Файл

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

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

Краткое описание

Функции

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

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

Если данные отправляются в файл в формате, который не может быть преобразован в UTF-8, или если данные читаются функцией, которая возвращает данные в формате, не поддерживающем диапазон символов, произойдёт ошибка, и файл будет закрыт.
:delayed_write, :raw, :ram, :read_ahead, :sync, {:encoding, ...}, {:read_ahead, pos_integer}, {:delayed_write, non_neg_integer, non_neg_integer} - для получения дополнительной информации об этих параметрах см. :file.open/2.

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

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

io_device фактически является PID процесса, который обрабатывает файл. Этот процесс контролирует процесс, который изначально открыл файл (процесс-владелец). Если процесс-владелец завершается, файл закрывается, и сам процесс также завершается. Если завершается любой процесс, к которому связан io_device, файл будет закрыт, и сам процесс будет завершён. io_device результат данного вызова может использоваться в качестве аргумента для функций модуля IO.
{:error, reason} - файл не удалось открыть.

Примеры

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

open(path, modes, function)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, если файл не удалось открыть. В противном случае возвращает устройство ввода-вывода.

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

См. 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. Может использоваться для перемещения файлов (и каталогов) между директориями. При перемещении файла необходимо указать полный путь к целевому файлу; указание только каталога недостаточно.

Возвращает :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.