Файл

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

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

Пути, передаваемые функциям в этом модуле, могут быть относительными к текущему рабочему каталогу (как возвращает File.cwd/0), или абсолютными путями. Оболочки конвенции, такие как ~, не расширяются автоматически. Для использования путей, таких как ~/Downloads, можно использовать Path.expand/1 или Path.expand/2 для расширения пути до абсолютного пути.

Кодировка

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

Обратите внимание, что имена файлов, заданные в Elixir как charlists, всегда обрабатываются как 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 для получения дополнительной информации об этих параметрах и других соображениях по производительности.

Сводка

Функции

END_OF_DOCUMENT_MARKER

cd(path): Устанавливает текущий рабочий каталог.
cd!(path): То же, что и cd/1, но генерирует исключение File.Error, если операция завершается неудачно.
cd!(path, function): Изменяет текущий каталог на указанный path, выполняет заданную функцию, а затем возвращается к предыдущему пути независимо от возникновения исключения.
chgrp(path, gid): Изменяет группу, заданную идентификатором группы gid для указанного file. Возвращает :ok при успешном выполнении или {:error, reason} при ошибке.
chgrp!(path, gid): То же, что и chgrp/2, но генерирует исключение File.Error в случае ошибки. В противном случае :ok.
chmod(path, mode): Изменяет mode для указанного file.
chmod!(path, mode): То же, что и chmod/2, но генерирует исключение File.Error в случае ошибки. В противном случае :ok.
chown(path, uid): Изменяет владельца, заданного идентификатором пользователя uid для указанного file. Возвращает :ok при успешном выполнении или {:error, reason} при ошибке.
chown!(path, uid): То же, что и chown/2, но генерирует исключение File.Error в случае ошибки. В противном случае :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_file, destination_file, callback \\ fn _, _ -> true end): Копирует содержимое source_file в destination_file, сохраняя его атрибуты.
cp!(source_file, destination_file, callback \\ fn _, _ -> true end): То же, что и cp/3, но генерирует исключение File.CopyError в случае ошибки. В противном случае возвращает :ok.
cp_r(source, destination, callback \\ fn _, _ -> true end): Рекурсивно копирует содержимое source в destination, сохраняя структуру каталогов и атрибуты исходного каталога.
cp_r!(source, destination, callback \\ fn _, _ -> true end): То же, что и cp_r/3, но генерирует исключение File.CopyError в случае ошибки. В противном случае возвращает список скопированных файлов.
cwd(): Получает текущий рабочий каталог.
cwd!(): То же, что и cwd/0, но генерирует исключение File.Error в случае ошибки.
dir?(path, opts \\ []): Возвращает true если указанный путь является каталогом.
exists?(path, opts \\ []): Возвращает true если указанный путь существует.
ln(existing, new): Создает жёсткую ссылку new на файл existing.
ln!(existing, new): То же, что и ln/2, но генерирует исключение File.LinkError в случае ошибки. Возвращает :ok в противном случае.
ln_s(existing, new): Создаёт символическую ссылку new на файл или каталог existing.
ln_s!(existing, new): То же, что и ln_s/2, но генерирует исключение File.LinkError в случае ошибки. Возвращает :ok в противном случае.
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.
mkdir!(path): То же, что и mkdir/1, но генерирует исключение File.Error в случае ошибки. В противном случае :ok.
mkdir_p(path): Пытается создать каталог path.
mkdir_p!(path): То же, что и mkdir_p/1, но генерирует исключение File.Error в случае ошибки. В противном случае :ok.
open(path, modes_or_function \\ []): Открывает указанный path.
open(path, modes, function): Аналогично open/2, но ожидает функцию в качестве последнего аргумента.
open!(path, modes_or_function \\ []): Аналогично open/2, но генерирует исключение File.Error если файл не удалось открыть. В противном случае возвращает устройство ввода/вывода.
open!(path, modes, function): Аналогично open/3, но генерирует исключение File.Error если файл не удалось открыть.
read(path): Возвращает {:ok, binary}, где binary — это объект двоичных данных, содержащий содержимое path, или {:error, reason} в случае ошибки.
read!(path): Возвращает двоичные данные с содержимым указанного файла или генерирует исключение File.Error в случае ошибки.
read_link(path): Считывает символическую ссылку по адресу path.

END_OF_DOCUMENT_MARKER

read_link!(path): То же, что и read_link/1, но возвращает целевой объект напрямую или поднимает исключение File.Error, если произошла ошибка.
regular?(path, opts \\ []): Возвращает true, если путь — обычный файл.
rename(source, destination): Переименовывает файл source в файл destination. Может использоваться для перемещения файлов (и каталогов) между каталогами. При перемещении файла необходимо полностью указать имя файла destination, недостаточно указать только его каталог.
rename!(source, destination): То же, что и rename/2, но поднимает исключение File.RenameError, если произошел сбой. В противном случае возвращает :ok.
rm(path): Пытается удалить файл path.
rm!(path): То же, что и rm/1, но поднимает исключение File.Error в случае неудачи. В противном случае :ok.
rm_rf(path): Рекурсивно удаляет файлы и каталоги по заданному path. Символические ссылки не отслеживаются, а просто удаляются, несуществующие файлы просто игнорируются (т.е. эта функция не терпит неудачи).
rm_rf!(path): То же, что и rm_rf/1, но поднимает исключение File.Error в случае ошибок, иначе список удаленных файлов или каталогов.
rmdir(path): Пытается удалить каталог по path.
rmdir!(path): То же, что и rmdir/1, но поднимает исключение File.Error в случае неудачи. В противном случае :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 \\ System.os_time(:second)): Обновляет время модификации (mtime) и время доступа (atime) указанного файла.
touch!(path, time \\ System.os_time(:second)): То же, что и touch/2, но поднимает исключение File.Error в случае неудачи. В противном случае :ok.
write(path, content, modes \\ []): Записывает content в файл path.
write!(path, content, modes \\ []): То же, что и write/3, но поднимает исключение File.Error в случае неудачи. В противном случае :ok.
write_stat(path, stat, opts \\ []): Записывает заданную File.Stat обратно в файловую систему по указанному пути. Возвращает :ok или {:error, reason}.
write_stat!(path, stat, opts \\ []): То же, что и write_stat/3, но поднимает исключение File.Error в случае неудачи. В противном случае :ok.

Типы

encoding_mode()

Спецификации

encoding_mode() ::
  :utf8
  | {:encoding,
     :latin1
     | :unicode
     | :utf8
     | :utf16
     | :utf32
     | {:utf16, :big | :little}
     | {:utf32, :big | :little}}

erlang_time()

Спецификации

erlang_time() ::
  {{year :: non_neg_integer(), month :: 1..12, day :: 1..31},
   {hour :: 0..23, minute :: 0..59, second :: 0..59}}

io_device()

Спецификации

io_device() :: :file.io_device()

mode()

Спецификации

mode() ::
  :append
  | :binary
  | :charlist
  | :compressed
  | :delayed_write
  | :exclusive
  | :raw
  | :read
  | :read_ahead
  | :sync
  | :write
  | {:read_ahead, pos_integer()}
  | {:delayed_write, non_neg_integer(), non_neg_integer()}
  | encoding_mode()

posix()

Спецификации

posix() :: :file.posix()

posix_time()

Спецификации

posix_time() :: integer()

stat_options()

Спецификации

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

stream_mode()

Спецификации

stream_mode() ::
  encoding_mode()
  | :trim_bom
  | {:read_ahead, pos_integer() | false}
  | {:delayed_write, non_neg_integer(), non_neg_integer()}

END_OF_DOCUMENT_MARKER

Функции

cd(path)

Specs

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

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

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

cd!(path)

Specs

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

То же самое, что и cd/1, но вызывает исключение File.Error, если происходит сбой.

cd!(path, function)

Specs

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

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

Вызывает ошибку, если произошел сбой при извлечении или изменении текущего каталога.

chgrp(path, gid)

Specs

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

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

chgrp!(path, gid)

Specs

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

То же самое, что и chgrp/2, но вызывает исключение File.Error в случае сбоя. В противном случае :ok.

chmod(path, mode)

Specs

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)

Specs

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

То же самое, что и chmod/2, но вызывает исключение File.Error в случае сбоя. В противном случае :ok.

chown(path, uid)

Specs

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

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

chown!(path, uid)

Specs

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

То же самое, что и chown/2, но вызывает исключение File.Error в случае сбоя. В противном случае :ok.

close(io_device)

Specs

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

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

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

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

Specs

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)

Specs

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

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

cp(source_file, destination_file, callback \\ fn _, _ -> true end)

Specs

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

Копирует содержимое из source_file в destination_file, сохраняя его режимы.

source_file и destination_file должны быть файлом или символической ссылкой на него, или в случае назначения — путем к несуществующему файлу. Если один из них является каталогом, будет возвращено {:error, :eisdir}.

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

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

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

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

cp!(source_file, destination_file, callback \\ fn _, _ -> true end)

Specs

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

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

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

Specs

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

Рекурсивно копирует содержимое из source в destination, сохраняя структуру и режимы исходного каталога.

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

Если source является каталогом или символической ссылкой на него, то destination должен быть существующим directory или символической ссылкой на него, или путем к несуществующему каталогу.

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

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

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

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

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

Примеры

# 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)

Specs

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

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

cwd()

Характеристики

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

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

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

cwd!()

Характеристики

cwd!() :: binary()

То же, что и cwd/0, но вызывает исключение File.Error, если произошла ошибка.

dir?(path, opts \\ [])

Характеристики

dir?(Path.t(), [dir_option]) :: boolean() when dir_option: :raw

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

Эта функция следует за символическими ссылками, поэтому если символическая ссылка указывает на директорию, возвращается true.

Параметры

Поддерживаемые параметры:

:raw - одно атомарное значение, чтобы обойти файловый сервер и проверить существование файла только локально

Примеры

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

File.dir?("test")
#=> true

File.dir?("/usr/bin")
#=> true

File.dir?("~/Downloads")
#=> false

"~/Downloads" |> Path.expand() |> File.dir?()
#=> true

exists?(path, opts \\ [])

Характеристики

exists?(Path.t(), [exists_option]) :: boolean() when exists_option: :raw

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

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

Параметры

Поддерживаемые параметры:

:raw - одно атомарное значение, чтобы обойти файловый сервер и проверить существование файла только локально

Примеры

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

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

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

ln(existing, new)

Характеристики

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

Создаёт жёсткую ссылку new на файл existing.

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

ln!(existing, new)

Характеристики

ln!(Path.t(), Path.t()) :: :ok

Аналогично ln/2, но вызывает исключение File.LinkError при ошибке. Возвращает :ok в противном случае.

ln_s(existing, new)

Характеристики

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

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

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

ln_s!(existing, new)

Характеристики

ln_s!(Path.t(), Path.t()) :: :ok

Аналогично ln_s/2, но вызывает исключение File.LinkError при ошибке. Возвращает :ok в противном случае.

ls(path \\ ".")

Характеристики

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

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

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

ls!(path \\ ".")

Характеристики

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

Аналогично 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 - возвращает время как целое число секунд с эпохи

Примечание: Поскольку временные метки файлов хранятся в формате POSIX на большинстве операционных систем, получение информации о файлах с параметром time: :posix быстрее.

lstat!(path, opts \\ [])

Характеристики

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

Аналогично 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

Аналогично mkdir/1, но вызывает исключение File.Error при неудаче. В противном случае :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

Аналогично mkdir_p/1, но вызывает исключение File.Error при неудаче. В противном случае :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 — файл будет открыт для записи, и он будет создан, если не существует. Каждая операция записи в файл, открытый для добавления, будет происходить в конце файла.
:exclusive — файл, при открытии для записи, создаётся, если не существует. Если файл существует, open вернёт {:error, :eexist}.
:charlist — при указании этого параметра операции чтения файла будут возвращать списки символов, а не двоичные данные.
:compressed — позволяет читать или записывать сжатые gzip файлы.

Параметр сжатия должен быть объединён либо с чтением, либо с записью, но не с обоими. Обратите внимание, что размер файла, полученный с помощью 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()

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

Аналогично open/2, но генерирует исключение File.Error, если файл не удалось открыть. В противном случае возвращает устройство ввода-вывода.

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

open!(path, modes, function)

Характеристики

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

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

В случае успеха, возвращает результат 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()

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

read_link(path)

Характеристики

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

Читает символическую ссылку по пути path.

Если path существует и является символической ссылкой, возвращает {:ok, target}, в противном случае возвращает {:error, reason}.

Для получения более подробной информации см. :file.read_link/1.

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

:einval — путь не является символической ссылкой
:enoent — путь не существует
:enotsup — символические ссылки не поддерживаются на текущей платформе

read_link!(path)

Характеристики

read_link!(Path.t()) :: binary()

То же, что и read_link/1, но возвращает целевой путь непосредственно или генерирует исключение File.Error в случае ошибки.

regular?(path, opts \\ [])

Характеристики

regular?(Path.t(), [regular_option]) :: boolean() when regular_option: :raw

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

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

Опции

Поддерживаемые опции:

:raw — единственный атом для обхода сервера файлов и проверки наличия файла только локально

Примеры

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")

rename!(source, destination)

Характеристики

rename!(Path.t(), Path.t()) :: :ok

То же, что и rename/2, но генерирует исключение File.RenameError, если операция провалилась. В противном случае возвращает :ok.

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

Аналогично rm/1, но при ошибке генерирует исключение File.Error. В противном случае :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()]

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

rmdir(path)

Характеристики

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

Пытается удалить каталог по пути path.

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

Примеры

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

File.rmdir("non_empty_dir")
#=> {:error, :eexist}

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

rmdir!(path)

Характеристики

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

Аналогично rmdir/1, но при ошибке генерирует исключение File.Error. В противном случае :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()

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

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

Характеристики

stream!(Path.t(), stream_mode(), :line | pos_integer()) :: File.Stream.t()

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

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

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

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

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

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

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

Маркеры порядка байтов

Если вы передаёте :trim_bom в параметре modes, поток обрежет маркеры порядка байтов UTF-8, UTF-16 и UTF-32 при чтении из файла.

Обратите внимание, что эта функция не пытается определить кодировку файла на основе BOM.

Примеры

# 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 \\ System.os_time(:second))

Характеристики

touch(Path.t(), erlang_time() | posix_time()) :: :ok | {:error, posix()}

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

Файл создаётся, если он не существует. Требуется дата и время в UTC (как возвращает :erlang.universaltime()) или целое число, представляющее временную метку POSIX (как возвращает System.os_time(:second)).

В системах Unix-подобных системах изменение времени изменения может потребовать от вас быть либо root , либо владельцем файла. Разрешения на запись могут быть недостаточно. В таких случаях касание файла в первый раз (для создания) будет успешным, но касание существующего файла завершится с ошибкой {:error, :eperm}.

Примеры

File.touch("/tmp/a.txt", {{2018, 1, 30}, {13, 59, 59}})
#=> :ok
File.touch("/fakedir/b.txt", {{2018, 1, 30}, {13, 59, 59}})
{:error, :enoent}

File.touch("/tmp/a.txt", 1544519753)
#=> :ok

touch!(path, time \\ System.os_time(:second))

Характеристики

touch!(Path.t(), erlang_time() | posix_time()) :: :ok

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

Примеры

File.touch!("/tmp/a.txt", {{2018, 1, 30}, {13, 59, 59}})
#=> :ok
File.touch!("/fakedir/b.txt", {{2018, 1, 30}, {13, 59, 59}})
#=> ** (File.Error) could not touch "/fakedir/b.txt": no such file or directory

File.touch!("/tmp/a.txt", 1544519753)

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

Аналогично write/3, но при ошибке генерирует исключение File.Error. В противном случае :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

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