Файлы

Этот модуль содержит функции для работы с файлами.

Некоторые из этих функций являются низкоуровневыми, позволяя пользователю взаимодействовать с файлами или устройствами ввода-вывода, такими как open/2, copy/3 и другие. Этот модуль также предоставляет функции более высокого уровня, работающие с именами файлов и имеющие именование, основанное на вариантах UNIX. Например, можно скопировать файл с помощью cp/3 и удалить файлы и каталоги рекурсивно с помощью rm_rf/1.

Кодировка

Для записи и чтения файлов необходимо использовать функции в модуле IO. По умолчанию файл открывается в двоичном режиме, что требует использования функций IO.binread/2 и IO.binwrite/2 для взаимодействия с файлом. Разработчик может передать :utf8 в качестве параметра при открытии файла, тогда медленные функции IO.read/2 и IO.write/2 должны быть использованы, так как они отвечают за правильные преобразования и гарантируют правильность данных.

Обратите внимание, что имена файлов, заданные в виде списков символов в Elixir, всегда обрабатываются как UTF-8. В частности, ожидается, что оболочка и операционная система настроены для использования кодировки UTF-8. Двоичные имена файлов считаются сырыми и передаются в ОС как есть.

API

Большинство функций в этом модуле возвращают :ok или {:ok, result} в случае успеха, {:error, reason} в противном случае. Эти функции также имеют вариант, заканчивающийся на !, который возвращает результат (вместо кортежа {:ok, result} ) в случае успеха или вызывает исключение в случае неудачи. Например:

File.read("hello.txt")
#=> {:ok, "World"}

File.read("invalid.txt")
#=> {:error, :enoent}

File.read!("hello.txt")
#=> "World"

File.read!("invalid.txt")
#=> raises File.Error

В целом, разработчик должен использовать первый вариант, если хочет реагировать, если файл не существует. Второй вариант следует использовать, если разработчик ожидает, что его программное обеспечение завершится ошибкой, если файл не может быть прочитан (т.е. это буквальное исключение).

Процессы и сырые файлы

Каждый раз, когда открывается файл, Elixir запускает новый процесс. Запись в файл эквивалентна отправке сообщений процессу, который записывает в дескриптор файла.

Это означает, что файлы могут передаваться между узлами, и гарантии передачи сообщений обеспечивают возможность записи в один и тот же файл в сети.

Однако, вы не всегда хотите платить за эту абстракцию. В таких случаях файл можно открыть в :raw режиме. Параметры :read_ahead и :delayed_write также полезны при работе с большими файлами или работе с файлами в тесных циклах.

См. :file.open/2 для получения дополнительной информации об этих параметрах и других соображениях по производительности.

Резюме

Типы

io_device()

режим()

posix()

опции_статистики()

Функции

cd(path)

Устанавливает текущую рабочую директорию

cd!(path)

То же, что и cd/1, но генерирует исключение при неудаче

cd!(path, function)

Изменяет текущую директорию на указанную path, выполняет заданную функцию, а затем возвращает предыдущий путь независимо от того, было ли исключение

chgrp(path, gid)

Изменяет группу, заданную идентификатором группы gid для данного file. Возвращает :ok при успехе или {:error, reason} при ошибке

chgrp!(path, gid)

То же, что и chgrp/2, но генерирует исключение в случае неудачи. В противном случае :ok

chmod(path, mode)

Изменяет mode для данного file

chmod!(path, mode)

То же, что и chmod/2, но генерирует исключение в случае неудачи. В противном случае :ok

chown(path, uid)

Изменяет владельца, заданного идентификатором пользователя uid для данного file. Возвращает :ok при успехе или {:error, reason} при ошибке

chown!(path, uid)

То же, что и chown/2, но генерирует исключение в случае неудачи. В противном случае :ok

close(io_device)

Закрывает файл, на который ссылается io_device. В основном возвращает :ok, за исключением некоторых серьезных ошибок, таких как недостаток памяти

copy(source, destination, bytes_count \\ :infinity)

Копирует содержимое source в destination

copy!(source, destination, bytes_count \\ :infinity)

То же, что и copy/3, но генерирует File.CopyError при неудаче. Возвращает bytes_copied в противном случае

cp(source, destination, callback \\ fn _, _ -> true end)

Копирует содержимое source в destination с сохранением его режима

cp!(source, destination, callback \\ fn _, _ -> true end)

То же, что и cp/3, но генерирует File.CopyError при неудаче. Возвращает :ok в противном случае

cp_r(source, destination, callback \\ fn _, _ -> true end)

Копирует содержимое в источник в пункт назначения

cp_r!(source, destination, callback \\ fn _, _ -> true end)

То же, что и cp_r/3, но генерирует File.CopyError при неудаче. В противном случае возвращает список скопированных файлов

cwd()

Получает текущую рабочую директорию

cwd!()

То же, что и cwd/0, но генерирует исключение при неудаче

dir?(path)

Возвращает true если путь является директорией

exists?(path)

Возвращает true если указанный путь существует. Это может быть обычный файл, директория, сокет, символическая ссылка, именованная трубка или устройство

ln_s(existing, new)

Создаёт символическую ссылку new на файл или директорию existing

ls(path \\ ".")

Возвращает список файлов в данной директории

ls!(path \\ ".")

То же, что и ls/1, но генерирует File.Error в случае ошибки

lstat(path, opts \\ [])

Возвращает информацию о path. Если файл является символической ссылкой, устанавливает type на :symlink и возвращает структуру File.Stat для ссылки. Для любого другого файла возвращает точно такие же значения, как stat/2

lstat!(path, opts \\ [])

То же, что и lstat/2, но возвращает структуру File.Stat напрямую и выбрасывает File.Error, если возвращена ошибка

mkdir(path)

Пытается создать директорию path. Отсутствующие родительские директории не создаются. Возвращает :ok при успехе или {:error, reason} при возникновении ошибки

mkdir!(path)

То же, что и mkdir/1, но генерирует исключение в случае неудачи. В противном случае :ok

mkdir_p(path)

Пытается создать директорию path. Отсутствующие родительские директории создаются. Возвращает :ok при успехе или {:error, reason} при возникновении ошибки

mkdir_p!(path)

То же, что и mkdir_p/1, но генерирует исключение в случае неудачи. В противном случае :ok

open(path, modes_or_function \\ [])

Открывает данный path

open(path, modes, function)

Аналогично open/2, но ожидает функцию в качестве последнего аргумента

open!(path, modes_or_function \\ [])

Аналогично open/2, но генерирует ошибку, если файл не может быть открыт

open!(path, modes, function)

Аналогично open/3, но генерирует ошибку, если файл не может быть открыт

read(path)

Возвращает {:ok, binary}, где binary это двоичный объект данных, содержащий содержимое path, или {:error, reason} в случае ошибки

read!(path)

Возвращает двоичный объект с содержимым заданного файла или генерирует File.Error в случае ошибки

regular?(path)

Возвращает true если путь является обычным файлом

rename(source, destination)

Переименовывает файл source в файл destination. Может использоваться для перемещения файлов (и директорий) между директориями. При перемещении файла необходимо полностью указать имя файла destination, просто указание его директории недостаточно

rm(path)

Пытается удалить файл path

rm!(path)

То же, что и rm/1, но генерирует исключение в случае неудачи. В противном случае :ok

rm_rf(path)

Рекурсивно удаляет файлы и директории в указанном path. Символические ссылки не отслеживаются, а просто удаляются, несуществующие файлы просто игнорируются (т.е. не делают эту функцию неудачной)

rm_rf!(path)

То же, что и rm_rf/1, но генерирует File.Error в случае неудачи, в противном случае список удаленных файлов или директорий

rmdir(path)

Пытается удалить директорию по пути path. Возвращает :ok при успехе или {:error, reason} при возникновении ошибки

rmdir!(path)

То же, что и rmdir/1, но генерирует исключение в случае неудачи. В противном случае :ok

stat(path, opts \\ [])

Возвращает информацию о path. Если существует, возвращает кортеж {:ok, info}, где info — структура File.Stat. Возвращает {:error, reason} по тем же причинам, что и read/1, если произошла ошибка

stat!(path, opts \\ [])

То же самое, что и stat/2, но возвращает File.Stat напрямую и выбрасывает File.Error, если возвращено сообщение об ошибке

stream!(path, modes \\ [], line_or_bytes \\ :line)

Возвращает File.Stream для заданного path с заданными modes

touch(path, time \\ :calendar.universal_time())

Обновляет время изменения (mtime) и время доступа (atime) заданного файла

touch!(path, time \\ :calendar.universal_time())

То же самое, что и touch/2, но генерирует исключение, если операция завершится неудачно

write(path, content, modes \\ [])

Записывает content в файл path

write!(path, content, modes \\ [])

То же самое, что и write/3, но генерирует исключение, если операция завершится неудачно, иначе возвращает :ok

write_stat(path, stat, opts \\ [])

Записывает заданный File.Stat обратно в файловую систему по заданному пути. Возвращает :ok или {:error, reason}

write_stat!(path, stat, opts \\ [])

То же самое, что и write_stat/3, но генерирует исключение, если операция завершится неудачно. В противном случае возвращает :ok

Типы

io_device()

io_device() :: :file.io_device()

mode()

mode() ::
  :append |
  :binary |
  :charlist |
  :compressed |
  :delayed_write |
  :exclusive |
  :raw |
  :read |
  :read_ahead |
  :sync |
  :utf8 |
  :write |
  {:encoding, :latin1 | :unicode | :utf8 | :utf16 | :utf32 | {:utf16, :big | :little} | {:utf32, :big | :little}} |
  {:read_ahead, pos_integer()} |
  {:delayed_write, non_neg_integer(), non_neg_integer()}

posix()

posix() :: :file.posix()

stat_options()

stat_options() :: [{:time, :local | :universal | :posix}]

Функции

cd(path)

cd(Path.t()) :: :ok | {:error, posix()}

Устанавливает текущую рабочую директорию.

Возвращает :ok при успехе, {:error, reason} в противном случае.

cd!(path)

cd!(Path.t()) :: :ok | no_return()

Аналогично cd/1, но генерирует исключение при неудаче.

cd!(path, function)

cd!(Path.t(), (() -> res)) :: res | no_return() when res: var

Изменяет текущую директорию на указанную path, выполняет заданную функцию и затем возвращает предыдущий путь независимо от возникновения исключений.

Генерирует ошибку, если получение или изменение текущей директории завершается неудачно.

chgrp(path, gid)

chgrp(Path.t(), non_neg_integer()) :: :ok | {:error, posix()}

Изменяет группу, заданную идентификатором группы gid для заданного file. Возвращает :ok при успехе или {:error, reason} при неудаче.

chgrp!(path, gid)

chgrp!(Path.t(), non_neg_integer()) :: :ok | no_return()

То же самое, что и chgrp/2, но генерирует исключение в случае неудачи. В противном случае :ok.

chmod(path, mode)

chmod(Path.t(), non_neg_integer()) :: :ok | {:error, posix()}

Изменяет mode для заданного file.

Возвращает :ok при успехе или {:error, reason} при неудаче.

Разрешения

• 0o400 - право чтения: владелец

• 0o200 - право записи: владелец

• 0o100 - право выполнения: владелец

• 0o040 - право чтения: группа

• 0o020 - право записи: группа

• 0o010 - право выполнения: группа

• 0o004 - право чтения: другие

• 0o002 - право записи: другие

• 0o001 - право выполнения: другие

Например, установка режима 0o755 предоставляет права на запись, чтение и выполнение владельцу и права на чтение и выполнение группе и другим пользователям.

chmod!(path, mode)

chmod!(Path.t(), non_neg_integer()) :: :ok | no_return()

То же самое, что и chmod/2, но генерирует исключение в случае неудачи. В противном случае :ok.

chown(path, uid)

chown(Path.t(), non_neg_integer()) :: :ok | {:error, posix()}

Изменяет владельца, заданного идентификатором пользователя uid для заданного file. Возвращает :ok при успехе или {:error, reason} при неудаче.

chown!(path, uid)

chown!(Path.t(), non_neg_integer()) :: :ok | no_return()

То же самое, что и chown/2, но генерирует исключение в случае неудачи. В противном случае :ok.

close(io_device)

close(io_device()) :: :ok | {:error, posix() | :badarg | :terminated}

Закрывает файл, на который ссылается io_device. В основном возвращает :ok, за исключением некоторых серьезных ошибок, таких как недостаток памяти.

Обратите внимание, что если при открытии файла использовался параметр :delayed_write, close/1 может вернуть старую ошибку записи и даже не пытаться закрыть файл. Подробнее см. open/2.

copy(source, destination, bytes_count \\ :infinity)

copy(Path.t() | io_device(), Path.t() | io_device(), pos_integer() | :infinity) ::
  {:ok, non_neg_integer()} |
  {:error, posix()}

Копирует содержимое source в destination.

Оба параметра могут быть именем файла или устройством ввода-вывода, открытым с помощью open/2. bytes_count задаёт количество копируемых байтов, по умолчанию — :infinity.

Если файл destination уже существует, он перезаписывается содержимым из source.

Возвращает {:ok, bytes_copied} при успехе, {:error, reason} в противном случае.

По сравнению с cp/3, эта функция более низкого уровня, позволяя копировать данные между устройствами ввода-вывода, ограниченными количеством байтов. С другой стороны, cp/3 выполняет более тщательную проверку источника и назначения, а также сохраняет права доступа файла после копирования.

Типичные причины ошибок такие же, как и в open/2, read/1 и write/3.

copy!(source, destination, bytes_count \\ :infinity)

copy!(Path.t() | io_device(), Path.t() | io_device(), pos_integer() | :infinity) ::
  non_neg_integer() |
  no_return()

Аналогично copy/3, но генерирует File.CopyError при неудаче. Возвращает bytes_copied в противном случае.

cp(source, destination, callback \\ fn _, _ -> true end)

cp(Path.t(), Path.t(), (Path.t(), Path.t() -> boolean())) ::
  :ok |
  {:error, posix()}

Копирует содержимое source в destination, сохраняя его права доступа.

Если файл уже существует в месте назначения, вызывается обратный вызов, который должен вернуть true для перезаписи существующего файла, false в противном случае. Обратный вызов по умолчанию возвращает true.

Функция возвращает :ok в случае успеха, {:error, reason} в противном случае.

Если требуется скопировать содержимое из устройства ввода-вывода на другое устройство или выполнить прямое копирование без сохранения прав доступа, используйте copy/3.

Примечание: команда cp в системах Unix ведет себя по-разному в зависимости от того, является ли destination существующей директорией или нет. Мы решили явно запретить такое поведение. Если место назначения — директория, будет возвращена ошибка.

cp!(source, destination, callback \\ fn _, _ -> true end)

cp!(Path.t(), Path.t(), (Path.t(), Path.t() -> boolean())) ::
  :ok |
  no_return()

Аналогично cp/3, но генерирует File.CopyError при неудаче. Возвращает :ok в противном случае.

cp_r(source, destination, callback \\ fn _, _ -> true end)

cp_r(Path.t(), Path.t(), (Path.t(), Path.t() -> boolean())) ::
  {:ok, [binary()]} |
  {:error, posix(), binary()}

Копирует содержимое из источника в место назначения.

Если источник — файл, копирует source в destination. Если источник — директория, копирует содержимое директории в место назначения.

Если файл уже существует в месте назначения, вызывается обратный вызов, который должен вернуть true для перезаписи существующего файла, false в противном случае. Обратный вызов по умолчанию возвращает true.

Если директория уже существует в месте назначения, куда должен быть скопирован файл (или наоборот), эта функция завершится неудачно.

Эта функция может завершиться неудачей при копировании файлов, в этом случае она оставит директорию назначения в некорректном состоянии, где скопированные файлы не будут удалены.

Функция возвращает {:ok, files_and_directories} в случае успеха, files_and_directories — список скопированных файлов в произвольном порядке. Возвращает {:error, reason, file} в противном случае.

Примечание: команда cp в системах Unix ведет себя по-разному в зависимости от того, является ли destination существующей директорией или нет. Мы решили явно запретить такое поведение.

Примеры

# Copies file "a.txt" to "b.txt"
File.cp_r "a.txt", "b.txt"

# Copies all files in "samples" to "tmp"
File.cp_r "samples", "tmp"

# Same as before, but asks the user how to proceed in case of conflicts
File.cp_r "samples", "tmp", fn(source, destination) ->
  IO.gets("Overwriting #{destination} by #{source}. Type y to confirm. ") == "y\n"
end

cp_r!(source, destination, callback \\ fn _, _ -> true end)

cp_r!(Path.t(), Path.t(), (Path.t(), Path.t() -> boolean())) ::
  [binary()] |
  no_return()

Аналогично cp_r/3, но генерирует File.CopyError при неудаче. Возвращает список скопированных файлов в противном случае.

cwd()

cwd() :: {:ok, binary()} | {:error, posix()}

Получает текущую рабочую директорию.

В редких случаях эта функция может завершиться неудачей в Unix. Это может произойти, если права чтения отсутствуют для родительских каталогов текущей директории. По этой причине возвращает {:ok, cwd} в случае успеха и {:error, reason} в противном случае.

cwd!()

cwd!() :: binary() | no_return()

То же самое, что и cwd/0, но генерирует исключение в случае неудачи.

dir?(path)

dir?(Path.t()) :: boolean()

Возвращает true , если путь является каталогом.

exists?(path)

exists?(Path.t()) :: boolean()

Возвращает true , если указанный путь существует. Он может быть обычным файлом, каталогом, сокетом, символической ссылкой, именованной очередью или файлом устройства.

Примеры

File.exists?("test/")
#=> true

File.exists?("missing.txt")
#=> false

File.exists?("/dev/null")
#=> true

ln_s(existing, new)

Создаёт символическую ссылку new на файл или каталог existing.

Возвращает :ok в случае успеха, {:error, reason} в противном случае. Если операционная система не поддерживает символические ссылки, возвращает {:error, :enotsup}.

ls(path \\ ".")

ls(Path.t()) :: {:ok, [binary()]} | {:error, posix()}

Возвращает список файлов в заданной директории.

Возвращает {:ok, [files]} в случае успеха, {:error, reason} в противном случае.

ls!(path \\ ".")

ls!(Path.t()) :: [binary()] | no_return()

То же самое, что и ls/1, но генерирует исключение File.Error в случае ошибки.

lstat(path, opts \\ [])

lstat(Path.t(), stat_options()) ::
  {:ok, File.Stat.t()} |
  {:error, posix()}

Возвращает информацию о path. Если файл является символической ссылкой, устанавливает type в :symlink и возвращает структуру File.Stat для ссылки. Для любого другого файла возвращает точно такие же значения, как и stat/2.

Для более подробной информации см. :file.read_link_info/2.

Параметры

Допустимые параметры:

• :time - настраивает, как возвращаются временные метки файла

Значения для :time могут быть:

• :universal - возвращает кортеж {date, time} в формате UTC (по умолчанию)
• :local - возвращает кортеж {date, time} с использованием машинного времени
• :posix - возвращает время как целое число секунд с момента эпохи

lstat!(path, opts \\ [])

lstat!(Path.t(), stat_options()) :: File.Stat.t() | no_return()

Аналогично lstat/2, но возвращает структуру File.Stat напрямую и генерирует исключение File.Error в случае ошибки.

mkdir(path)

mkdir(Path.t()) :: :ok | {:error, posix()}

Пытается создать директорию path . Отсутствующие родительские директории не создаются. Возвращает :ok в случае успеха или {:error, reason} в случае ошибки.

Типичные причины ошибок:

• :eacces - отсутствуют права поиска или записи для родительских каталогов path
• :eexist - уже существует файл или директория с именем path
• :enoent - компонент path не существует
• :enospc - закончилось место на устройстве
• :enotdir - компонент path не является директорией; на некоторых платформах вместо этого возвращается :enoent

mkdir!(path)

mkdir!(Path.t()) :: :ok | no_return()

То же, что и mkdir/1, но генерирует исключение в случае неудачи. В противном случае :ok.

mkdir_p(path)

mkdir_p(Path.t()) :: :ok | {:error, posix()}

Пытается создать директорию path . Отсутствующие родительские директории создаются. Возвращает :ok в случае успеха или {:error, reason} в случае ошибки.

Типичные причины ошибок:

• :eacces - отсутствуют права поиска или записи для родительских каталогов path
• :enospc - закончилось место на устройстве
• :enotdir - компонент path не является директорией

mkdir_p!(path)

mkdir_p!(Path.t()) :: :ok | no_return()

То же, что и mkdir_p/1, но генерирует исключение в случае неудачи. В противном случае :ok.

open(path, modes_or_function \\ [])

open(Path.t(), [mode() | :ram]) ::
  {:ok, io_device()} |
  {:error, posix()}

open(Path.t(), (io_device() -> res)) ::
  {:ok, res} |
  {:error, posix()} when res: var

Открывает заданный path.

Для чтения и записи файлов необходимо использовать функции модуля IO. По умолчанию файл открывается в режиме :binary , который требует функций IO.binread/2 и IO.binwrite/2 для взаимодействия с файлом. Разработчик может передать :utf8 в качестве параметра при открытии файла, и тогда все остальные функции из IO будут доступны, так как они работают напрямую с данными Unicode.

modes_or_function может быть списком режимов или функцией. Если это список, он рассматривается как список режимов (которые документированы ниже). Если это функция, то она эквивалентна вызову open(path, [], modes_or_function). Более подробная информация об этой функции содержится в документации по open/3.

Допустимые режимы:

• :binary - открывает файл в двоичном режиме, отключая специальную обработку последовательностей Unicode (режим по умолчанию).

• :read - файл, который должен существовать, открывается для чтения.

• :write - файл открывается для записи. Он создаётся, если не существует.

  Если файл существует, и запись не сочетается с чтением, файл будет обрезан.

• :append - файл будет открыт для записи и будет создан, если не существует. Если файл существует, open вернёт {:error, :eexist}.

• :exclusive - когда этот термин задан, операции чтения из файла вернут списки символов вместо двоичных данных.

• :compressed - позволяет читать или записывать сжатые gzip файлы.

  Параметр compressed должен быть объединён либо с чтением, либо с записью, но не с тем и другим. Обратите внимание, что размер файла, полученный с помощью stat/1, скорее всего, не будет совпадать с количеством байтов, которые можно считать из сжатого файла.

• :utf8 - этот параметр определяет, как данные фактически хранятся в файле на диске, и делает файл выполняющим автоматическое преобразование символов в UTF-8 и обратно.

  Если данные отправляются в файл в формате, который нельзя преобразовать в UTF-8, или если данные считываются функцией, которая возвращает данные в формате, не поддерживающем диапазон символов данных, возникает ошибка, и файл будет закрыт.

• :delayed_write, :raw, :ram, :read_ahead, :sync, {:encoding, ...}, {:read_ahead, pos_integer}, {:delayed_write, non_neg_integer, non_neg_integer} - для получения более подробной информации об этих параметрах, см. :file.open/2.

Функция возвращает:

• {:ok, io_device} - файл был открыт в запрошенном режиме.

  io_device фактически является PID процесса, который обрабатывает файл. Этот процесс связан с процессом, который первоначально открыл файл. Если любой процесс, к которому привязан io_device, завершается, файл будет закрыт, а сам процесс будет завершён.

  Полученный от этого вызова io_device может быть использован в качестве аргумента для функций модуля IO.

• {:error, reason} - файл не удалось открыть.

Примеры

{:ok, file} = File.open("foo.tar.gz", [:read, :compressed])
IO.read(file, :line)
File.close(file)

open(path, modes, function)

open(Path.t(), [mode() | :ram], (io_device() -> res)) ::
  {:ok, res} |
  {:error, posix()} when res: var

Аналогично open/2, но в качестве последнего аргумента принимает функцию.

Файл открывается, передаётся функции в качестве аргумента и автоматически закрывается после возврата функции, независимо от того, была ли ошибка при выполнении функции.

Возвращает {:ok, function_result} в случае успеха, {:error, reason} в противном случае.

Функция ожидает успешного закрытия файла, что обычно имеет место, если не задан параметр :delayed_write . По этой причине не рекомендуется передавать :delayed_write в эту функцию.

Примеры

File.open("file.txt", [:read, :write], fn(file) ->
  IO.read(file, :line)
end)

См. open/2 для списка доступных modes.

open!(path, modes_or_function \\ [])

open!(Path.t(), [mode() | :ram]) :: io_device() | no_return()

open!(Path.t(), (io_device() -> res)) ::
  res |
  no_return() when res: var

Аналогично open/2, но генерирует ошибку, если файл не удалось открыть.

В противном случае возвращает устройство ввода-вывода.

См. open/2 для списка доступных режимов.

open!(path, modes, function)

open!(Path.t(), [mode() | :ram], (io_device() -> res)) ::
  res |
  no_return() when res: var

Аналогично open/3, но генерирует ошибку, если файл не удалось открыть.

Если открытие файла успешно, то возвращает результат function на устройстве ввода-вывода.

См. open/2 для списка доступных modes.

read(path)

read(Path.t()) :: {:ok, binary()} | {:error, posix()}

Возвращает {:ok, binary}, где binary — это объект двоичных данных, содержащий содержимое path, или {:error, reason} в случае возникновения ошибки.

Типичные причины ошибок:

• :enoent — файл не существует
• :eacces — недостаточно разрешений для чтения файла или поиска одного из родительских каталогов
• :eisdir — указанное имя — это каталог
• :enotdir — компонент имени файла не является каталогом; на некоторых платформах вместо этого возвращается :enoent
• :enomem — недостаточно памяти для содержимого файла

Вы можете использовать :file.format_error/1, чтобы получить описательную строку ошибки.

read!(path)

read!(Path.t()) :: binary() | no_return()

Возвращает двоичный объект с содержимым указанного файла или вызывает File.Error в случае ошибки.

regular?(path)

regular?(Path.t()) :: boolean()

Возвращает true, если путь указывает на обычный файл.

Примеры

File.regular? __ENV__.file #=> true

rename(source, destination)

rename(Path.t(), Path.t()) :: :ok | {:error, posix()}

Переименовывает файл source в файл destination. Может использоваться для перемещения файлов (и каталогов) между каталогами. При перемещении файла необходимо полностью указать имя файла destination, недостаточно просто указать каталог.

Возвращает :ok в случае успеха, {:error, reason} в противном случае.

Примечание: команда mv в системах Unix ведет себя по-разному в зависимости от того, является ли source файлом, и является ли destination существующим каталогом. Мы решили явно запретить такое поведение.

Примеры

# Rename file "a.txt" to "b.txt"
File.rename "a.txt", "b.txt"

# Rename directory "samples" to "tmp"
File.rename "samples", "tmp"

rm(path)

rm(Path.t()) :: :ok | {:error, posix()}

Пытается удалить файл path.

Возвращает :ok при успехе или {:error, reason} в случае ошибки.

Обратите внимание, что файл удаляется даже если он имеет атрибут «только для чтения».

Типичные причины ошибок:

• :enoent — файл не существует
• :eacces — недостаточно разрешений для файла или одного из его родительских каталогов
• :eperm — файл является каталогом, и пользователь не суперпользователь
• :enotdir — компонент имени файла не является каталогом; на некоторых платформах вместо этого возвращается :enoent
• :einval — имя файла имеет неверный тип, например, кортеж

Примеры

File.rm("file.txt")
#=> :ok

File.rm("tmp_dir/")
#=> {:error, :eperm}

rm!(path)

rm!(Path.t()) :: :ok | no_return()

Аналогично rm/1, но генерирует исключение в случае неудачи. В противном случае :ok.

rm_rf(path)

rm_rf(Path.t()) :: {:ok, [binary()]} | {:error, posix(), binary()}

Рекурсивно удаляет файлы и каталоги по заданному path. Символические ссылки не отслеживаются, а просто удаляются; не существующие файлы просто игнорируются (то есть эта функция не завершается ошибкой).

Возвращает {:ok, files_and_directories} со всеми удалёнными файлами и каталогами в произвольном порядке, {:error, reason, file} в противном случае.

Примеры

File.rm_rf "samples"
#=> {:ok, ["samples", "samples/1.txt"]}

File.rm_rf "unknown"
#=> {:ok, []}

rm_rf!(path)

rm_rf!(Path.t()) :: [binary()] | no_return()

Аналогично rm_rf/1, но вызывает File.Error в случае неудачи; в противном случае возвращает список удалённых файлов или каталогов.

rmdir(path)

rmdir(Path.t()) :: :ok | {:error, posix()}

Пытается удалить каталог по пути path. Возвращает :ok в случае успеха или {:error, reason} в случае ошибки.

Примеры

File.rmdir('tmp_dir')
#=> :ok

File.rmdir('file.txt')
#=> {:error, :enotdir}

rmdir!(path)

rmdir!(Path.t()) :: :ok | {:error, posix()}

Аналогично rmdir/1, но вызывает исключение в случае неудачи. В противном случае :ok.

stat(path, opts \\ [])

stat(Path.t(), stat_options()) ::
  {:ok, File.Stat.t()} |
  {:error, posix()}

Возвращает информацию о path. Если он существует, возвращает кортеж {:ok, info}, где info — это структура File.Stat. Возвращает {:error, reason} по тем же причинам, что и read/1, если произошла ошибка.

Параметры

Допустимые параметры:

• :time — настраивает способ возврата временных меток файла

Значения для :time могут быть:

• :universal — возвращает кортеж {date, time} в UTC (по умолчанию)
• :local — возвращает кортеж {date, time}, используя часовой пояс машины
• :posix — возвращает время в виде целого числа — секунд с эпохи

stat!(path, opts \\ [])

stat!(Path.t(), stat_options()) :: File.Stat.t() | no_return()

Аналогично stat/2, но возвращает структуру File.Stat напрямую и генерирует File.Error в случае ошибки.

stream!(path, modes \\ [], line_or_bytes \\ :line)

Возвращает File.Stream для заданного path с заданными modes.

Поток реализует протоколы Enumerable и Collectable, что означает, что его можно использовать как для чтения, так и для записи.

Аргумент line_or_bytes настраивает способ чтения файла при потоковой передаче, по строкам (по умолчанию) или по заданному количеству байтов.

Работа с потоком может завершиться ошибкой при открытии по тем же причинам, что и File.open!/2. Обратите внимание, что файл автоматически открывается каждый раз при начале потоковой передачи. Нет необходимости передавать параметры :read и :write режимов, так как они автоматически устанавливаются Elixir.

Необработанные файлы

Так как Elixir управляет временем открытия потокового файла, базовое устройство не может быть совместно использовано, и для повышения производительности удобно открыть файл в необработанном режиме. Поэтому Elixir будет открывать потоки в режиме :raw с опцией :read_ahead если кодировка не указана. Это означает, что любые данные, передаваемые в файл потоком, должны быть преобразованы в тип iodata/0. Если вы передадите [:utf8] в параметр modes, базовый поток будет использовать IO.write/2 и протокол String.Chars для преобразования данных. См. IO.binwrite/2 и IO.write/2.

Можно также рассмотреть передачу опции :delayed_write если поток предназначен для записи в условиях интенсивной обработки.

Примеры

# Read in 2048 byte chunks rather than lines
File.stream!("./test/test.data", [], 2048)
#=> %File.Stream{line_or_bytes: 2048, modes: [:raw, :read_ahead, :binary],
#=> path: "./test/test.data", raw: true}

См. Stream.run/1 для примера потоковой записи в файл.

touch(path, time \\ :calendar.universal_time())

touch(Path.t(), :calendar.datetime()) :: :ok | {:error, posix()}

Обновляет время изменения (mtime) и время доступа (atime) указанного файла.

Файл создается, если он не существует. Требуется дата и время в UTC.

touch!(path, time \\ :calendar.universal_time())

touch!(Path.t(), :calendar.datetime()) :: :ok | no_return()

Аналогично touch/2, но генерирует исключение при ошибке.

Возвращает :ok в противном случае. Требуется дата и время в UTC.

write(path, content, modes \\ [])

write(Path.t(), iodata(), [mode()]) :: :ok | {:error, posix()}

Записывает content в файл path.

Файл создаётся, если он не существует. Если он существует, предыдущее содержимое перезаписывается. Возвращает :ok при успехе или {:error, reason} в случае ошибки.

content должно быть iodata (список байтов или двоичное значение). Установка кодировки для этой функции не имеет эффекта.

Предупреждение: каждый раз при вызове этой функции открывается дескриптор файла и запускается новый процесс для записи в файл. По этой причине, если вы выполняете несколько записей в цикле, открытие файла через File.open/2 и использование функций в IO для записи в файл обеспечит значительно лучшую производительность, чем многократный вызов данной функции.

Типичные причины ошибок:

• :enoent — компонент имени файла не существует
• :enotdir — компонент имени файла не является каталогом; на некоторых платформах вместо этого возвращается :enoent
• :enospc — недостаточно места на устройстве
• :eacces — недостаточно разрешений для записи в файл или поиска одного из родительских каталогов
• :eisdir — указанное имя — это каталог

Проверьте File.open/2 для получения других доступных параметров.

write!(path, content, modes \\ [])

write!(Path.t(), iodata(), [mode()]) :: :ok | no_return()

Аналогично write/3, но генерирует исключение при ошибке; возвращает :ok в противном случае.

write_stat(path, stat, opts \\ [])

write_stat(Path.t(), File.Stat.t(), stat_options()) ::
  :ok |
  {:error, posix()}

Записывает заданную File.Stat обратно в файловую систему по заданному пути. Возвращает :ok или {:error, reason}.

write_stat!(path, stat, opts \\ [])

write_stat!(Path.t(), File.Stat.t(), stat_options()) ::
  :ok |
  no_return()

То же самое, что и write_stat/3, но вызывает исключение, если не удаётся. В противном случае возвращает :ok.