Источник Файл

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

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

Пути, передаваемые функциям в этом модуле, могут быть либо относительными к текущей рабочей директории (как возвращает File.cwd/0), либо абсолютными путями. Оболочки Unix, такие как ~ не расширяются автоматически. Для использования путей, таких как ~/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 для получения дополнительной информации о таких параметрах и других соображениях производительности.

Поиск внутри файла

Вы также можете использовать любые функции из модуля :file для взаимодействия с файлами, возвращаемыми Elixir. Например, чтобы читать из определенной позиции в файле, используйте :file.pread/3:

File.write!("example.txt", "Eats, Shoots & Leaves")
file = File.open!("example.txt")
:file.pread(file, 15, 6)
#=> {:ok, "Leaves"}

В качестве альтернативы, если вам нужно отслеживать текущую позицию, используйте :file.position/2 и :file.read/2:

:file.position(file, 6)
#=> {:ok, 6}
:file.read(file, 6)
#=> {:ok, "Shoots"}
:file.position(file, {:cur, -12})
#=> {:ok, 0}
:file.read(file, 4)
#=> {:ok, "Eats"}

Резюме

Функции

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

END_OF_DOCUMENT_MARKER

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, line_or_bytes_modes \\ []): Сокращение для File.stream!/3.
stream!(path, line_or_bytes, modes): Возвращает поток 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}}

file_descriptor()Source

@type file_descriptor() :: :file.fd()

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

read_offset_mode()Source

@type read_offset_mode() :: {:read_offset, non_neg_integer()}

stat_options()Source

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

stream_mode()Source

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

Функции

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

END_OF_DOCUMENT_MARKER

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() | file_descriptor()} | {:error, posix()}

@spec open(Path.t(), (io_device() | file_descriptor() -> res)) ::
  {:ok, res} | {:error, posix()}
when res: var

Открывает заданный path.

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

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

:binary - открывает файл в бинарном режиме, отключая специальную обработку последовательностей Unicode (режим по умолчанию).
:read - файл, который должен существовать, открывается для чтения.
:write - файл открывается для записи. Он создается, если его не существует.

Если файл существует, и если запись не объединена с чтением, файл будет усечен.
:append - файл будет открыт для записи, и он будет создан, если его не существует. Каждая операция записи в файл, открытый с добавлением, будет происходить в конце файла.
:exclusive - файл, при открытии для записи, создается, если он не существует. Если файл существует, open вернет {:error, :eexist}.
:charlist - когда этот термин задан, операции чтения из файла будут возвращать списки символов, а не бинарные данные.
:compressed - позволяет читать или записывать сжатые gzip файлы.

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

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

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

{:ok, io_device | file_descriptor} - файл был открыт в запрошенном режиме. Мы рассмотрим различия между этими двумя результатами в следующем разделе
{:error, reason} - файл не может быть открыт из-за reason.

Устройства ввода-вывода

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

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

Дескрипторы файлов

Когда заданы режимы :raw или :ram, эта функция возвращает низкоуровневые дескрипторы файлов. Это позволяет избежать создания процесса, но требует использования функций в модуле :file для взаимодействия с ним.

Примеры

{: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() | file_descriptor() -> 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() | file_descriptor()

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

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

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

open!(path, modes, function)Source

@spec open!(Path.t(), [mode() | :ram], (io_device() | file_descriptor() -> 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. Может использоваться для перемещения файлов (и каталогов) между каталогами. При перемещении файла, необходимо полностью указать имя файла 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: :posix для получения информации о файлах является более быстрым.

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

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

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

stream!(path, line_or_bytes_modes \\ [])Source

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

Сокращение для File.stream!/3.

stream!(path, line_or_bytes, modes)Source

@spec stream!(Path.t(), :line | pos_integer(), [stream_mode()]) :: 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. С Elixir v1.16.0 вы также можете передать :read_offset, который пропускается при перечислении потока (если оба :read_offset и :trim_bom указаны, смещение пропускается после BOM).

Примеры

# Read a utf8 text file which may include BOM
File.stream!("./test/test.txt", [:trim_bom, encoding: :utf8])

# Read in 2048 byte chunks rather than lines
File.stream!("./test/test.data", 2048)

См. 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.