Файл

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

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

Резюме

Функции

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)

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

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

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

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

cd!(path)

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

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

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

cd!(path, function)

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

cd!(Path.t(), (() -> res)) :: res 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

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

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

То же, что и chown/2, но вызывает исключение File.Error при неудаче. В противном случае :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()

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

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

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

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)

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

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

То же, что и 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, сохраняя структуру каталогов и режимы источника.

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

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

Если источник является файлом, он копирует source в destination. Если source является каталогом, он копирует содержимое внутри каталога 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)

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

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

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

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 на устройстве ввода-вывода.

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

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

Примечание: Поскольку временные метки файлов хранятся в формате POSIX на большинстве операционных систем, извлечение информации о файлах с помощью параметра 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.

END_OF_DOCUMENT_MARKER

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.