Исходный код Файл

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

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

Поиск в файле

Вы также можете использовать любые функции из модуля :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"}

Резюме

Функции

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, но в качестве последнего аргумента принимает функцию.

END_OF_DOCUMENT_MARKER

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

END_OF_DOCUMENT_MARKER

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.

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

END_OF_DOCUMENT_MARKER

read(path)Source

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

Возвращает {data, nil}, где data — это двоичный объект данных, содержащий содержимое файла, или {nil, error} в случае ошибки.

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

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

Для получения более подробной информации см. :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 в противном случае.

Примечание: команда rename в системах 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 в случае ошибки.

Обратите внимание, что файл удаляется даже если он находится в режиме только для чтения.

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

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

Рекурсивно удаляет файлы и каталоги по заданному пути. Символические ссылки не отслеживаются, а просто удаляются, несуществующие файлы игнорируются (т. е. эта функция не терпит неудачу).

Возвращает список удаленных файлов и каталогов в произвольном порядке; :error в противном случае.

Примеры

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 при ошибке. Возвращает :error, если каталог не пуст.

Примеры

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

Возвращает информацию о файле. Если он существует, возвращает кортеж {ok, info}, где info — структура File.Stat. Возвращает {error, reason} по тем же причинам, что и read/1, если произошла ошибка.

Параметры

Принятые параметры:

:time — настраивает то, как возвращаются временные метки файла

Значения для opts могут быть:

:universal — возвращает кортеж {ok, info} в формате UTC (по умолчанию)
:local — возвращает кортеж {ok, info}, используя часовой пояс машины
:posix — возвращает время в виде целого числа — секунд с начала эпохи

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

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, символы перевода строки CRLF ("\r\n") нормализуются до LF ("\n").

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

Работа с потоком может завершиться ошибкой при открытии по тем же причинам, что и File.open!/2. Обратите внимание, что файл автоматически открывается каждый раз при начале потоковой передачи. Нет необходимости передавать :read и :write режимы, так как они автоматически устанавливаются Elixir.

Необработанные файлы

Поскольку Elixir управляет моментом открытия потокового файла, базовый девайс не может быть совместно использован, и поэтому для повышения производительности удобно открыть файл в режиме raw. Поэтому 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.