Файл

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

Некоторые из этих функций являются низкоуровневыми, позволяя пользователю взаимодействовать с файлами или устройствами ввода-вывода, такими как 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, destination, callback \\ fn _, _ -> true end): Копирует содержимое source в destination, сохраняя его режим.
cp!(source, destination, callback \\ fn _, _ -> true end): То же, что и cp/3, но вызывает исключение File.CopyError в случае неудачи. В противном случае возвращает :ok.
cp_r(source, destination, callback \\ fn _, _ -> true end): Копирует содержимое из источника в место назначения.
cp_r!(source, destination, callback \\ fn _, _ -> true end): То же, что и cp_r/3, но вызывает исключение File.CopyError в случае неудачи. В противном случае возвращает список скопированных файлов.
cwd(): Возвращает текущую рабочую директорию.
cwd!(): То же, что и cwd/0, но вызывает исключение 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 имя файла, недостаточно просто указать его директорию.
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()}

Функции

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, destination, callback \\ fn _, _ -> true end)

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

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

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

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

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

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

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

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

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

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

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

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

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

Примеры

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

(since 1.5.0)

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

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

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

ln!(existing, new)

(since 1.5.0)

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

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

ln_s(existing, new)

(since 1.5.0)

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

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, поскольку они работают напрямую с данными Юникода.

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

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

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

Список доступных 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)

(since 1.5.0)

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

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

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

Дополнительную информацию см. в :file.read_link/1.

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

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

read_link!(path)

(since 1.5.0)

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

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

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

Примеры

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.