Файл

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

Некоторые из этих функций являются низкоуровневыми, позволяя пользователю взаимодействовать с файлами или устройствами ввода-вывода, например, 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, options \\ []): Копирует содержимое source_file в destination_file сохраняя его режимы.
cp!(source_file, destination_file, options \\ []): То же самое, что и cp/3, но если операция завершается неудачно, генерирует исключение File.CopyError. В противном случае возвращает :ok.
cp_r(source, destination, options \\ []): Рекурсивно копирует содержимое source в destination, сохраняя структуру каталогов и режимы источника.
cp_r!(source, destination, options \\ []): То же самое, что и 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.
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()Source

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

erlang_time()Source

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

io_device()Source

@type io_device() :: :file.io_device()

mode()Source

@type 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()

on_conflict_callback()Source

@type on_conflict_callback() :: (Path.t(), Path.t() -> boolean())

posix()Source

@type posix() :: :file.posix()

posix_time()Source

@type posix_time() :: integer()

stat_options()Source

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

stream_mode()Source

@type stream_mode() ::
  encoding_mode()
  | :append
  | :compressed
  | :delayed_write
  | :trim_bom
  | {:read_ahead, pos_integer() | false}
  | {:delayed_write, non_neg_integer(), non_neg_integer()}

END_OF_DOCUMENT_MARKER

cd(path)Source

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

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

Текущий рабочий каталог устанавливается для BEAM глобально. Это может привести к гонкам, если несколько процессов одновременно изменяют текущий рабочий каталог. Чтобы запустить внешнюю команду в заданном каталоге без изменения глобального текущего рабочего каталога, используйте параметр :cd функции System.cmd/3 и Port.open/2.

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

cd!(path)Source

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

То же, что и cd/1, но вызывает исключение File.Error, если операция завершается неудачно.

cd!(path, function)Source

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

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

Текущий рабочий каталог временно устанавливается для BEAM глобально. Это может привести к гонкам, если несколько процессов одновременно изменяют текущий рабочий каталог. Чтобы запустить внешнюю команду в заданном каталоге без изменения глобального текущего рабочего каталога, используйте параметр :cd функции System.cmd/3 и Port.open/2.

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

chgrp(path, gid)Source

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

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

chgrp!(path, gid)Source

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

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

chmod(path, mode)Source

@spec 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)Source

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

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

chown(path, uid)Source

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

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

chown!(path, uid)Source

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

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

close(io_device)Source

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

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

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

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

@spec 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)Source

@spec 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, options \\ [])Source

@spec cp(Path.t(), Path.t(), [{:on_conflict, on_conflict_callback()}]) ::
  :ok | {:error, posix()}

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

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

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

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

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

Параметры

:on_conflict - (с версии v1.14.0) Вызывается, когда файл уже существует в месте назначения. Функция получает аргументы для source_file и destination_file. Она должна возвращать true если существующий файл должен быть перезаписан, false в противном случае. По умолчанию вызывается функция true. В более ранних версиях эта функция могла быть передана в качестве третьего аргумента, но такое поведение теперь устарело.

cp!(source_file, destination_file, options \\ [])Source

@spec cp!(Path.t(), Path.t(), [{:on_conflict, on_conflict_callback()}]) :: :ok

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

END_OF_DOCUMENT_MARKER

cp_r(source, destination, options \\ [])Source

@spec cp_r(Path.t(), Path.t(),
  on_conflict: on_conflict_callback(),
  dereference_symlinks: boolean()
) ::
  {:ok, [binary()]} | {:error, posix(), binary()}

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

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

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

Если исходный объект является файлом, он копирует source в destination. Если исходный объект является каталогом, он копирует содержимое внутри исходного каталога в каталог destination.

Если файл уже существует в пункте назначения, вызывается необязательный обратный вызов on_conflict , заданный как параметр. См. "Параметры" для получения дополнительной информации.

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

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

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

Параметры

:on_conflict - (с версии v1.14.0) Вызывается, когда файл уже существует в пункте назначения. Функция получает аргументы для source и destination. Она должна возвращать true если существующий файл должен быть перезаписан, false в противном случае. По умолчанию обратный вызов возвращает true. В более ранних версиях этот обратный вызов можно было передать в качестве третьего аргумента, но такое поведение устарело.
:dereference_symlinks - (с версии v1.14.0) По умолчанию эта функция копирует символические ссылки, создавая символические ссылки, указывающие на то же местоположение. Этот параметр принудительно приводит к делению символических ссылок и копированию их содержимого вместо этого, если значение равно true. Если дереференцированные файлы не существуют, операция завершается ошибкой. Значение по умолчанию - false.

Примеры

# 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", on_conflict: fn source, destination ->
  IO.gets("Overwriting #{destination} by #{source}. Type y to confirm. ") == "y\n"
end)

cp_r!(source, destination, options \\ [])Source

@spec cp_r!(Path.t(), Path.t(),
  on_conflict: on_conflict_callback(),
  dereference_symlinks: boolean()
) ::
  [binary()]

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

cwd()Source

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

Получает текущий рабочий каталог.

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

cwd!()Source

@spec cwd!() :: binary()

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

dir?(path, opts \\ [])Source

@spec 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 \\ [])Source

@spec 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)Source

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

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

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

ln!(existing, new)Source

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

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

ln_s(existing, new)Source

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

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

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

ln_s!(existing, new)Source

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

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

ls(path \\ ".")Source

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

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

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

ls!(path \\ ".")Source

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

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

lstat(path, opts \\ [])Source

@spec 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 в большинстве операционных систем, получение информации о файлах с помощью параметра time: :posix быстрее.

lstat!(path, opts \\ [])Source

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

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

mkdir(path)Source

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

Пытается создать директорию path.

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

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

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

mkdir!(path)Source

@spec mkdir!(Path.t()) :: :ok

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

mkdir_p(path)Source

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

Пытается создать директорию path.

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

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

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

mkdir_p!(path)Source

@spec mkdir_p!(Path.t()) :: :ok

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

open(path, modes_or_function \\ [])Source

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

@spec 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.

Если данные отправляются в файл в формате, который не может быть преобразован в 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)Source

@spec 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 \\ [])Source

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

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

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

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

open!(path, modes, function)Source

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

Аналогично open/3, но вызывает исключение File.Error, если файл не может быть открыт.

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

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

read(path)Source

@spec 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)Source

@spec read!(Path.t()) :: binary()

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

read_link(path)Source

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

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

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

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

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

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

read_link!(path)Source

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

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

regular?(path, opts \\ [])Source

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

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

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

Параметры

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

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

Примеры

File.regular?(__ENV__.file)
#=> true

rename(source, destination)Source

@spec 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)Source

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

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

rm(path)Source

@spec 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)Source

@spec rm!(Path.t()) :: :ok

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

rm_rf(path)Source

@spec 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)Source

@spec rm_rf!(Path.t()) :: [binary()]

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

rmdir(path)Source

@spec 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)Source

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

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

stat(path, opts \\ [])Source

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

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

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

@spec stat!(Path.t(), stat_options()) :: File.Stat.t()

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

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

@spec stream!(Path.t(), [stream_mode()], :line | pos_integer()) :: File.Stream.t()

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

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

Аргумент line_or_bytes определяет способ чтения файла при потоковой передаче, по :line (по умолчанию) или по заданному числу байтов. При использовании опции :line, символы новой строки CRLF ("\r\n") нормализуются до LF ("\n").

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

Операции с потоком могут завершиться ошибкой при открытии по тем же причинам, что и 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))Source

@spec 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))Source

@spec 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 \\ [])Source

@spec 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 \\ [])Source

@spec write!(Path.t(), iodata(), [mode()]) :: :ok

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

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

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

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

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

@spec write_stat!(Path.t(), File.Stat.t(), stat_options()) :: :ok

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