Файл

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

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

Пути, передаваемые функциям в этом модуле, могут быть относительными к текущей рабочей директории (как возвращается File.cwd/0), или абсолютными путями. Оболочки соглашения, такие как ~, не расширяются автоматически. Для использования путей, таких как ~/Downloads, можно использовать Path.expand/1 или Path.expand/2 для расширения пути до абсолютного пути.

Кодировка

Для записи и чтения файлов необходимо использовать функции в модуле IO. По умолчанию файл открывается в двоичном режиме, что требует функций IO.binread/2 и IO.binwrite/2 для взаимодействия с файлом. Разработчик может передать :utf8 в качестве опции при открытии файла, тогда должны использоваться более медленные функции IO.read/2 и IO.write/2, так как они отвечают за правильные преобразования и предоставление гарантий данных.

Обратите внимание, что имена файлов, заданные в Elixir как списки символов, всегда обрабатываются как UTF-8. В частности, ожидается, что оболочка и операционная система настроены на использование кодировки UTF-8. Двоичные имена файлов считаются сырыми и передаются операционной системе как есть.

API

Большинство функций в этом модуле возвращают :ok или {:ok, result} в случае успеха, {:error, reason} в противном случае. Эти функции также имеют вариант, заканчивающийся !, который возвращает результат (вместо кортежа {:ok, result} ) в случае успеха или вызывает исключение в случае сбоя. Например:

File.read("hello.txt")
#=> {:ok, "World"}

File.read("invalid.txt")
#=> {:error, :enoent}

File.read!("hello.txt")
#=> "World"

File.read!("invalid.txt")
#=> raises File.Error

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

Процессы и сырые файлы

Каждый раз, когда файл открывается, Elixir запускает новый процесс. Запись в файл эквивалентна отправке сообщений в процесс, который записывает в дескриптор файла.

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

Однако, вы не всегда хотите платить за эту абстракцию. В таких случаях файл можно открыть в :raw режиме. Опции :read_ahead и :delayed_write также полезны при работе с большими файлами или работе с файлами в узких циклах.

См. :file.open/2 для получения дополнительной информации об этих опциях и других соображениях по производительности.

Сводка

Функции

cd!(path): То же самое, что и cd/1, но при неудачном выполнении генерирует исключение File.Error.
cd!(path, function): Изменяет текущую директорию на указанную path, выполняет заданную функцию, а затем возвращается к предыдущему пути, независимо от наличия исключения.
cd(path): Устанавливает текущую рабочую директорию.
chgrp!(path, gid): То же, что и chgrp/2, но генерирует исключение File.Error в случае ошибки. В противном случае :ok.
chgrp(path, gid): Изменяет группу, заданную идентификатором группы gid для указанного file. Возвращает :ok при успехе или {:error, reason} при ошибке.
chmod!(path, mode): То же самое, что и chmod/2, но генерирует исключение File.Error в случае ошибки. В противном случае :ok.
chmod(path, mode): Изменяет mode для заданного file.
chown!(path, uid): То же самое, что и chown/2, но генерирует исключение File.Error при ошибке. В противном случае :ok.
chown(path, uid): Изменяет владельца, заданного идентификатором пользователя uid для заданного file. Возвращает :ok при успехе или {:error, reason} при ошибке.
close(io_device): Закрывает файл, на который ссылается io_device. В основном возвращает :ok, за исключением некоторых серьезных ошибок, таких как недостаток памяти.
copy!(source, destination, bytes_count \\ :infinity): То же самое, что и copy/3, но при неудаче генерирует исключение File.CopyError. В противном случае возвращает bytes_copied.
copy(source, destination, bytes_count \\ :infinity): Копирует содержимое source в destination.
cp!(source_file, destination_file, callback \\ fn _, _ -> true end): То же самое, что и cp/3, но при неудаче генерирует исключение File.CopyError. В противном случае возвращает :ok.
cp(source_file, destination_file, callback \\ fn _, _ -> true end): Копирует содержимое source_file в destination_file, сохраняя его режимы.
cp_r!(source, destination, callback \\ fn _, _ -> true end): То же самое, что и cp_r/3, но при неудаче генерирует исключение File.CopyError. В противном случае возвращает список скопированных файлов.
cp_r(source, destination, callback \\ fn _, _ -> true end): Рекурсивно копирует содержимое source в destination, сохраняя структуру каталога и режимы исходного каталога.
cwd!(): То же самое, что и cwd/0, но при неудаче генерирует исключение File.Error.
cwd(): Получает текущую рабочую директорию.
dir?(path, opts \\ []): Возвращает true если указанный путь является каталогом.
exists?(path, opts \\ []): Возвращает true если указанный путь существует.
ln!(existing, new): То же, что и ln/2, но генерирует исключение File.LinkError при неудаче. В противном случае возвращает :ok.
ln(existing, new): Создаёт жёсткую ссылку new на файл existing.
ln_s!(existing, new): То же самое, что и ln_s/2, но генерирует исключение File.LinkError при неудаче. В противном случае возвращает :ok.
ln_s(existing, new): Создаёт символическую ссылку new на файл или директорию existing.
ls!(path \\ "."): То же, что и ls/1, но генерирует исключение File.Error в случае ошибки.
ls(path \\ "."): Возвращает список файлов в заданной директории.
lstat!(path, opts \\ []): То же самое, что и lstat/2, но возвращает структуру File.Stat напрямую или генерирует исключение File.Error в случае ошибки.
lstat(path, opts \\ []): Возвращает информацию о path. Если файл является символической ссылкой, устанавливает type на :symlink и возвращает структуру File.Stat для ссылки. В любом другом случае возвращает точно такие же значения, как stat/2.
mkdir!(path): То же самое, что и mkdir/1, но генерирует исключение File.Error в случае ошибки. В противном случае :ok.
mkdir(path): Попытка создать директорию path.
mkdir_p!(path): То же самое, что и mkdir_p/1, но генерирует исключение File.Error при ошибке. В противном случае :ok.
mkdir_p(path): Попытка создать директорию path.
open!(path, modes_or_function \\ []): Аналогично open/2, но генерирует исключение File.Error, если файл не может быть открыт. В противном случае возвращает устройство ввода-вывода.
open!(path, modes, function): Аналогично open/3, но генерирует исключение File.Error, если файл не может быть открыт.
open(path, modes_or_function \\ []): Открывает указанный path.
open(path, modes, function): Аналогично open/2, но в качестве последнего аргумента ожидает функцию.
read!(path): Возвращает бинарное представление содержимого заданного файла или генерирует исключение File.Error в случае ошибки.

END_OF_DOCUMENT_MARKER

read(path): Возвращает {:ok, binary}, где binary — это двоичный объект данных, содержащий содержимое path, или {:error, reason} в случае возникновения ошибки.
read_link!(path): То же, что и read_link/1, но возвращает целевой объект напрямую или вызывает исключение File.Error, если произошла ошибка.
read_link(path): Читает символическую ссылку по адресу path.
regular?(path, opts \\ []): Возвращает true если путь указывает на обычный файл.
rename!(source, destination): То же, что и rename/2, но вызывает исключение File.RenameError в случае неудачи. В противном случае возвращает :ok.
rename(source, destination): Переименовывает файл source в файл destination. Может использоваться для перемещения файлов (и каталогов) между каталогами. При перемещении файла необходимо полностью указать имя файла destination, указания только каталога недостаточно.
rm!(path): То же, что и rm/1, но вызывает исключение File.Error в случае неудачи. В противном случае :ok.
rm(path): Попытка удалить файл path.
rm_rf!(path): То же, что и rm_rf/1, но вызывает исключение File.Error в случае неудачи, в противном случае возвращает список удаленных файлов или каталогов.
rm_rf(path): Рекурсивно удаляет файлы и каталоги по заданному path. Символические ссылки не отслеживаются, а просто удаляются, несуществующие файлы просто игнорируются (т.е. эта функция не завершается ошибкой).
rmdir!(path): То же, что и rmdir/1, но вызывает исключение File.Error в случае неудачи. В противном случае :ok.
rmdir(path): Попытка удалить каталог по адресу path.
stat!(path, opts \\ []): То же, что и stat/2, но возвращает File.Stat напрямую или вызывает исключение File.Error в случае ошибки.
stat(path, opts \\ []): Возвращает информацию о path. Если он существует, возвращает кортеж {:ok, info}, где info — структура File.Stat. Возвращает {:error, reason} по тем же причинам, что и read/1, в случае ошибки.
stream!(path, modes \\ [], line_or_bytes \\ :line): Возвращает File.Stream для указанного path с заданными modes.
touch!(path, time \\ System.os_time(:second)): То же, что и touch/2, но вызывает исключение File.Error при ошибке. В противном случае возвращает :ok.
touch(path, time \\ System.os_time(:second)): Обновляет время изменения (mtime) и время доступа (atime) данного файла.
write!(path, content, modes \\ []): То же, что и write/3, но вызывает исключение File.Error при ошибке. В противном случае возвращает :ok.
write(path, content, modes \\ []): Записывает content в файл path.
write_stat!(path, stat, opts \\ []): То же, что и write_stat/3, но вызывает исключение File.Error при ошибке. В противном случае возвращает :ok.
write_stat(path, stat, opts \\ []): Записывает заданный File.Stat обратно в файловую систему по указанному пути. Возвращает :ok или {:error, reason}.

Типы

encoding_mode()Исходный код

@type encoding_mode() ::
  :utf8
  | {:encoding,
     :latin1
     | :unicode
     | :utf8
     | :utf16
     | :utf32
     | {:utf16, :big | :little}
     | {:utf32, :big | :little}}

erlang_time()Исходный код

@type erlang_time() ::
  {{year :: non_neg_integer(), month :: 1..12, day :: 1..31},
   {hour :: 0..23, minute :: 0..59, second :: 0..59}}

io_device()Исходный код

@type io_device() :: :file.io_device()

mode()Исходный код

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

posix()Исходный код

@type posix() :: :file.posix()

posix_time()Исходный код

@type posix_time() :: integer()

stat_options()Исходный код

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

stream_mode()Исходный код

@type stream_mode() ::
  encoding_mode()
  | :append
  | :compressed
  | :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

То же самое, что и 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.

Генерирует ошибку, если получение или изменение текущей директории завершилось неудачно.

cd(path)Source

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

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

Текущая рабочая директория устанавливается для BEAM глобально. Это может привести к гонкам, если несколько процессов одновременно изменяют текущую рабочую директорию. Чтобы запустить внешнюю команду в заданной директории без изменения глобальной текущей рабочей директории, используйте опцию :cd в System.cmd/3 и Port.open/2.

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

chgrp!(path, gid)Source

@spec chgrp!(Path.t(), non_neg_integer()) :: :ok

Аналогично chgrp/2, но генерирует исключение File.Error в случае ошибки. В противном случае :ok.

chgrp(path, gid)Source

@spec chgrp(Path.t(), non_neg_integer()) :: :ok | {:error, posix()}

Изменяет группу, заданную идентификатором группы gid для заданного file. Возвращает :ok при успехе или {:error, reason} при ошибке.

chmod!(path, mode)Source

@spec chmod!(Path.t(), non_neg_integer()) :: :ok

Аналогично chmod/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 предоставляет права на запись, чтение и выполнение владельцу, а также права на чтение и выполнение группе и другим.

chown!(path, uid)Source

@spec chown!(Path.t(), non_neg_integer()) :: :ok

Аналогично chown/2, но генерирует исключение File.Error в случае ошибки. В противном случае :ok.

chown(path, uid)Source

@spec chown(Path.t(), non_neg_integer()) :: :ok | {:error, posix()}

Изменяет владельца, заданного идентификатором пользователя uid для заданного file. Возвращает :ok при успехе или {:error, reason} при ошибке.

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

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

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.

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

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

То же самое, что и cp/3, но генерирует исключение File.CopyError в случае ошибки. В противном случае возвращает :ok.

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

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

Копирует содержимое source_file в destination_file с сохранением его режима.

source_file должен быть файлом или символической ссылкой на него. destination_file должен быть путем к несуществующему файлу. Если любой из них является каталогом, будет возвращено {:error, :eisdir}.

Функция callback вызывается, если destination_file уже существует. Функция получает аргументы для source_file и destination_file; она должна возвращать true если существующий файл должен быть перезаписан, false в противном случае. По умолчанию функция возвращает true.

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

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

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

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

@spec cp_r!(Path.t(), Path.t(), (Path.t(), Path.t() -> boolean())) :: [binary()]

То же самое, что и cp_r/3, но генерирует исключение File.CopyError в случае ошибки. В противном случае возвращает список скопированных файлов.

END_OF_DOCUMENT_MARKER

cp_r(source, destination, callback \\ fn _, _ -> true end)Source

@spec cp_r(Path.t(), Path.t(), (Path.t(), Path.t() -> boolean())) ::
  {:ok, [binary()]} | {:error, posix(), binary()}

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

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

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

Если источник является файлом, он копирует source в destination. Если source является каталогом, он копирует содержимое внутри каталога источника в каталог destination.

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

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

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

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

Примеры

# Copies file "a.txt" to "b.txt"
File.cp_r("a.txt", "b.txt")

# Copies all files in "samples" to "tmp"
File.cp_r("samples", "tmp")

# Same as before, but asks the user how to proceed in case of conflicts
File.cp_r("samples", "tmp", fn source, destination ->
  IO.gets("Overwriting #{destination} by #{source}. Type y to confirm. ") == "y\n"
end)

cwd!()Source

@spec cwd!() :: binary()

То же, что и cwd/0, но генерирует исключение File.Error, если произошла ошибка.

cwd()Source

@spec cwd() :: {:ok, binary()} | {:error, posix()}

Получает текущий рабочий каталог.

В редких случаях эта функция может завершиться ошибкой в системах Unix-подобных системах. Это может произойти, если разрешения на чтение отсутствуют для родительских каталогов текущего каталога. По этой причине возвращает {:ok, cwd} в случае успеха и {:error, reason} в противном случае.

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

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

ln(existing, new)Source

@spec ln(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.

ln_s(existing, new)Source

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

Создаёт символическую ссылку new на файл или каталог existing.

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

ls!(path \\ ".")Source

@spec ls!(Path.t()) :: [binary()]

То же, что и ls/1, но генерирует исключение File.Error в случае ошибки.

ls(path \\ ".")Source

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

Возвращает список файлов в заданном каталоге.

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

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

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

То же, что и lstat/2, но возвращает структуру File.Stat напрямую или генерирует исключение 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.

mkdir!(path)Source

@spec mkdir!(Path.t()) :: :ok

Аналогично mkdir/1, но генерирует исключение File.Error в случае ошибки. В противном случае :ok.

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_p!(path)Source

@spec mkdir_p!(Path.t()) :: :ok

Аналогично mkdir_p/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 не является директорией

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.

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

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

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

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

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

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

Примеры

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

open(path, modes, function)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.

read!(path)Source

@spec read!(Path.t()) :: binary()

Возвращает двоичные данные содержимого указанного файла или генерирует исключение File.Error при возникновении ошибки.

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_link!(path)Source

@spec read_link!(Path.t()) :: binary()

Аналогично read_link/1, но возвращает целевой объект непосредственно или генерирует исключение File.Error при ошибке.

END_OF_DOCUMENT_MARKER

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 - символические ссылки не поддерживаются на текущей платформе

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

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

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

rm!(path)Source

@spec rm!(Path.t()) :: :ok

Аналогично rm/1, но при ошибке генерирует исключение File.Error. В противном случае :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_rf!(path)Source

@spec rm_rf!(Path.t()) :: [binary()]

Аналогично rm_rf/1, но при ошибках генерирует исключение File.Error, в противном случае возвращает список удалённых файлов или каталогов.

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, []}

rmdir!(path)Source

@spec rmdir!(Path.t()) :: :ok | {:error, posix()}

Аналогично rmdir/1, но при ошибке генерирует исключение File.Error. В противном случае :ok.

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}

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

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

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

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 быстрее.

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 (" ") нормализуются до LF (" ").

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

Аналогично touch/2, но при неудаче генерирует исключение File.Error. В противном случае возвращает :ok.

Файл создается, если он не существует. Требуется дата и время в формате UTC (как возвращается :erlang.universaltime()) или целое число, представляющее метку времени POSIX (как возвращается System.os_time(:second)).

Примеры

File.touch!("/tmp/a.txt", {{2018, 1, 30}, {13, 59, 59}})
#=> :ok
File.touch!("/fakedir/b.txt", {{2018, 1, 30}, {13, 59, 59}})
** (File.Error) could not touch "/fakedir/b.txt": no such file or directory

File.touch!("/tmp/a.txt", 1544519753)

touch(path, time \\ System.os_time(:second))Source

@spec touch(Path.t(), erlang_time() | posix_time()) :: :ok | {:error, posix()}

Обновляет время изменения (mtime) и время доступа (atime) данного файла.

В системах 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

write!(path, content, modes \\ [])Source

@spec write!(Path.t(), iodata(), [mode()]) :: :ok

Аналогично write/3, но при неудаче генерирует исключение File.Error. В противном случае возвращает :ok.

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_stat!(path, stat, opts \\ [])Source

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

Аналогично write_stat/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}.

Настройки Файл

Кодировка

API

Процессы и сырые файлы

Сводка

Типы

Функции

Типы

encoding_mode()Исходный код

erlang_time()Исходный код

io_device()Исходный код

mode()Исходный код

posix()Исходный код

posix_time()Исходный код

stat_options()Исходный код

stream_mode()Исходный код

Функции

cd!(path)Source

cd!(path, function)Source

cd(path)Source

chgrp!(path, gid)Source

chgrp(path, gid)Source

chmod!(path, mode)Source

chmod(path, mode)Source

Разрешения

chown!(path, uid)Source

chown(path, uid)Source

close(io_device)Source

copy!(source, destination, bytes_count \\ :infinity)Source

copy(source, destination, bytes_count \\ :infinity)Source

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

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

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

cp_r(source, destination, callback \\ fn _, _ -> true end)Source

Примеры

cwd!()Source

cwd()Source

dir?(path, opts \\ [])Source

Параметры

Примеры

exists?(path, opts \\ [])Source

Параметры

Примеры

ln!(existing, new)Source

ln(existing, new)Source

ln_s!(existing, new)Source

ln_s(existing, new)Source

ls!(path \\ ".")Source

ls(path \\ ".")Source

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

lstat(path, opts \\ [])Source

Параметры

mkdir!(path)Source

mkdir(path)Source

mkdir_p!(path)Source

mkdir_p(path)Source

open!(path, modes_or_function \\ [])Source

open!(path, modes, function)Source

open(path, modes_or_function \\ [])Source

Примеры

open(path, modes, function)Source

Примеры

read!(path)Source

read(path)Source

read_link!(path)Source

read_link(path)Source

regular?(path, opts \\ [])Source

Параметры

Примеры

rename!(source, destination)Source

rename(source, destination)Source

Примеры

rm!(path)Source

rm(path)Source

Примеры

rm_rf!(path)Source

rm_rf(path)Source

Примеры

rmdir!(path)Source

rmdir(path)Source

Файл