Файл

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

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

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

Кодирование

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

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

API

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

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

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

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

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

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

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

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

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

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

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

Сводка

Функции

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

Возвращает информацию о path. Если она существует, возвращает кортеж {:ok, info}, где info — структура File.Stat. Возвращает {:error, reason} по тем же причинам, что и read/1, если произошла ошибка
stat!(path, opts \\ []): То же, что и stat/2, но возвращает структуру File.Stat напрямую или вызывает исключение File.Error, если произошла ошибка
stream!(path, modes \\ [], line_or_bytes \\ :line): Возвращает объект File.Stream для данного path с заданными modes
touch(path, time \\ :calendar.universal_time()): Обновляет время модификации (mtime) и время доступа (atime) данного файла
touch!(path, time \\ :calendar.universal_time()): То же, что и touch/2, но вызывает исключение, если произошла ошибка
write(path, content, modes \\ []): Записывает content в файл path
write!(path, content, modes \\ []): То же, что и write/3, но вызывает исключение, если произошла ошибка; в противном случае возвращает :ok
write_stat(path, stat, opts \\ []): Записывает заданную структуру File.Stat обратно в файловую систему по заданному пути. Возвращает :ok или {:error, reason}
write_stat!(path, stat, opts \\ []): То же, что и write_stat/3, но вызывает исключение, если произошла ошибка. В противном случае возвращает :ok

Типы

io_device()

io_device() :: :file.io_device()

mode()

mode() ::
  :append |
  :binary |
  :charlist |
  :compressed |
  :delayed_write |
  :exclusive |
  :raw |
  :read |
  :read_ahead |
  :sync |
  :utf8 |
  :write |
  {:encoding, :latin1 | :unicode | :utf8 | :utf16 | :utf32 | {:utf16, :big | :little} | {:utf32, :big | :little}} |
  {:read_ahead, pos_integer()} |
  {:delayed_write, non_neg_integer(), non_neg_integer()}

posix()

posix() :: :file.posix()

stat_options()

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

Функции

cd(path)

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

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

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

cd!(path)

cd!(Path.t()) :: :ok | no_return()

Аналогично cd/1, но вызывает исключение при ошибке.

cd!(path, function)

cd!(Path.t(), (() -> res)) :: res when res: var

Изменяет текущий каталог на указанный path, выполняет заданную функцию и затем возвращает в предыдущий путь независимо от наличия исключений.

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

chgrp(path, gid)

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

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

chgrp!(path, gid)

chgrp!(Path.t(), non_neg_integer()) :: :ok | no_return()

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

chmod(path, mode)

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

Изменяет mode для заданного file.

Возвращает :ok при успехе, или {:error, reason} при ошибке.

Разрешения

Права доступа к файлам задаются путем сложения следующих восьмеричных флагов:

0o400 - право чтения: владелец
0o200 - право записи: владелец
0o100 - право выполнения: владелец
0o040 - право чтения: группа
0o020 - право записи: группа
0o010 - право выполнения: группа
0o004 - право чтения: другие
0o002 - право записи: другие
0o001 - право выполнения: другие

Например, установка режима 0o755 предоставляет права на запись, чтение и выполнение владельцу, а также права на чтение и выполнение группе и другим.

chmod!(path, mode)

chmod!(Path.t(), non_neg_integer()) :: :ok | no_return()

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

chown(path, uid)

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

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

chown!(path, uid)

chown!(Path.t(), non_neg_integer()) :: :ok | no_return()

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

close(io_device)

close(io_device()) :: :ok | {:error, posix() | :badarg | :terminated}

Закрывает файл, на который ссылается io_device. В основном возвращает :ok, за исключением некоторых серьезных ошибок, таких как недостаток памяти.

Обратите внимание, что если при открытии файла был использован параметр :delayed_write, close/1 может вернуть старую ошибку записи и даже не попытаться закрыть файл. Смотрите open/2 для получения дополнительной информации.

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

copy(Path.t() | io_device(), Path.t() | io_device(), pos_integer() | :infinity) ::
  {:ok, non_neg_integer()} |
  {:error, posix()}

Копирует содержимое source в destination.

Оба параметра могут быть именем файла или устройством ввода-вывода, открытым с помощью open/2. bytes_count указывает количество байтов для копирования, по умолчанию оно равно :infinity.

Если файл destination уже существует, он перезаписывается содержимым из source.

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

По сравнению с cp/3, эта функция более низкого уровня, позволяя копирование с устройства на устройство, ограниченное количеством байтов. С другой стороны, cp/3 выполняет более тщательную проверку источника и назначения, а также сохраняет режим файла после копирования.

Типичные причины ошибок такие же, как и в open/2, read/1 и write/3.

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

copy!(Path.t() | io_device(), Path.t() | io_device(), pos_integer() | :infinity) ::
  non_neg_integer() |
  no_return()

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

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

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

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

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

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

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

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

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

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

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

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

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

Копирует содержимое в источник в назначение.

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

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

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

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

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

Примеры

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

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

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

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

cp_r!(Path.t(), Path.t(), (Path.t(), Path.t() -> boolean())) ::
  [binary()] |
  no_return()

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

cwd()

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

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

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

cwd!()

cwd!() :: binary() | no_return()

То же, что и cwd/0, но вызывает исключение, если произошла ошибка.

dir?(path)

dir?(Path.t()) :: boolean()

Возвращает true если указанный путь является каталогом.

Эта функция следует за символическими ссылками, поэтому, если символическая ссылка указывает на каталог, возвращается true.

Примеры

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)

exists?(Path.t()) :: boolean()

Возвращает true если указанный путь существует. Он может быть обычным файлом, каталогом, сокетом, символической ссылкой, именованной трубой или устройством.

Примеры

File.exists?("test/")
#=> true

File.exists?("missing.txt")
#=> false

File.exists?("/dev/null")
#=> true

ln(existing, new)

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

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

ln!(existing, new)

Аналогично ln/2, но вызывает исключение, если произошла ошибка.

В противном случае возвращает :ok

ln_s(existing, new)

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

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

ln_s!(existing, new)

Аналогично ln_s/2, но вызывает исключение, если произошла ошибка.

В противном случае возвращает :ok.

ls(path \\ ".")

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

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

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

ls!(path \\ ".")

ls!(Path.t()) :: [binary()] | no_return()

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

lstat(path, opts \\ [])

lstat(Path.t(), stat_options()) ::
  {:ok, File.Stat.t()} |
  {:error, posix()}

Возвращает информацию о path. Если файл является символической ссылкой, устанавливает type в :symlink и возвращает структуру File.Stat для ссылки. Для любого другого файла возвращает точно такие же значения, как и stat/2.

Для более подробной информации см. :file.read_link_info/2.

Параметры

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

:time - настраивает способ возврата временных меток файла

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

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

lstat!(path, opts \\ [])

lstat!(Path.t(), stat_options()) :: File.Stat.t() | no_return()

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

mkdir(path)

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

Попытка создать каталог path. Родительские каталоги, которых нет, не создаются. Возвращает :ok при успехе или {:error, reason} в случае ошибки.

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

:eacces - отсутствуют права поиска или записи для родительских каталогов path
:eexist - файл или каталог с именем path уже существует
:enoent - какой-либо компонент пути path не существует
:enospc - на устройстве закончилось место
:enotdir - какой-либо компонент пути path не является каталогом; на некоторых платформах, :enoent возвращается вместо этого

mkdir!(path)

mkdir!(Path.t()) :: :ok | no_return()

Аналогично mkdir/1, но вызывает исключение в случае неудачи. В противном случае возвращает :ok.

mkdir_p(path)

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

Попытка создать каталог path. Родительские каталоги, которых нет, создаются. Возвращает :ok при успехе или {:error, reason} в случае ошибки.

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

:eacces - отсутствуют права поиска или записи для родительских каталогов path
:enospc - на устройстве закончилось место
:enotdir - какой-либо компонент пути path не является каталогом

mkdir_p!(path)

mkdir_p!(Path.t()) :: :ok | no_return()

Аналогично mkdir_p/1, но вызывает исключение в случае неудачи. В противном случае возвращает :ok.

open(path, modes_or_function \\ [])

open(Path.t(), [mode() | :ram]) ::
  {:ok, io_device()} |
  {:error, posix()}

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

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

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

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

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

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

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

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

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

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

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

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

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

Примеры

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

open(path, modes, function)

open(Path.t(), [mode() | :ram], (io_device() -> res)) ::
  {:ok, res} |
  {:error, posix()} when res: var

Аналогично open/2, но в качестве последнего аргумента ожидает функцию.

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

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

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

Примеры

File.open("file.txt", [:read, :write], fn(file) ->
  IO.read(file, :line)
end)

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

open!(path, modes_or_function \\ [])

open!(Path.t(), [mode() | :ram]) :: io_device() | no_return()

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

Аналогично open/2, но вызывает ошибку, если файл не удалось открыть.

В противном случае возвращает устройство ввода-вывода.

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

open!(path, modes, function)

open!(Path.t(), [mode() | :ram], (io_device() -> res)) ::
  res |
  no_return() when res: var

Аналогично open/3, но вызывает ошибку, если файл не удалось открыть.

Если открытие файла успешно, возвращает результат function на устройстве ввода-вывода.

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

read(path)

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

Возвращает {:ok, binary}, где binary — это двоичный объект данных, содержащий содержимое path, или {:error, reason} в случае возникновения ошибки.

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

:enoent — файл не существует
:eacces — отсутствуют права для чтения файла или поиска в одной из родительских директорий
:eisdir — указанное имя файла — это директория
:enotdir — компонент имени файла не является директорией; на некоторых платформах вместо этого возвращается :enoent
:enomem — недостаточно памяти для содержимого файла

Вы можете использовать :file.format_error/1, чтобы получить описательную строку ошибки.

read!(path)

read!(Path.t()) :: binary() | no_return()

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

read_link(path)

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

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

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

Для получения более подробной информации, см. :file.read_link/1.

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

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

read_link!(path)

read_link!(Path.t()) :: binary() | no_return()

То же, что и read_link/1, но возвращает целевой объект напрямую или вызывает File.Error в случае возникновения ошибки.

regular?(path)

regular?(Path.t()) :: boolean()

Возвращает true если путь является обычным файлом.

Эта функция следует за символическими ссылками, поэтому если символическая ссылка указывает на обычный файл, возвращается true.

Примеры

File.regular? __ENV__.file #=> true

rename(source, destination)

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

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

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

Примечание: команда mv в системах Unix ведет себя по-разному в зависимости от того, является ли source файлом, а destination — существующей директорией. Мы выбрали явное запрещение такого поведения.

Примеры

# Rename file "a.txt" to "b.txt"
File.rename "a.txt", "b.txt"

# Rename directory "samples" to "tmp"
File.rename "samples", "tmp"

rm(path)

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

Попытка удалить файл path.

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

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

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

:enoent — файл не существует
:eacces — отсутствуют права на файл или одну из его родительских директорий
:eperm — файл является директорией, а пользователь не суперпользователь
:enotdir — компонент имени файла не является директорией; на некоторых платформах вместо этого возвращается :enoent
:einval — имя файла имеет неправильный тип, например, кортеж

Примеры

File.rm("file.txt")
#=> :ok

File.rm("tmp_dir/")
#=> {:error, :eperm}

rm!(path)

rm!(Path.t()) :: :ok | no_return()

То же, что и rm/1, но генерирует исключение в случае неудачи. В противном случае :ok.

rm_rf(path)

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

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

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

Примеры

File.rm_rf "samples"
#=> {:ok, ["samples", "samples/1.txt"]}

File.rm_rf "unknown"
#=> {:ok, []}

rm_rf!(path)

rm_rf!(Path.t()) :: [binary()] | no_return()

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

rmdir(path)

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

Попытка удалить директорию по адресу path. Возвращает :ok в случае успеха или {:error, reason} в случае возникновения ошибки.

Примеры

File.rmdir('tmp_dir')
#=> :ok

File.rmdir('file.txt')
#=> {:error, :enotdir}

rmdir!(path)

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

То же, что и rmdir/1, но вызывает исключение в случае неудачи. В противном случае :ok.

stat(path, opts \\ [])

stat(Path.t(), stat_options()) ::
  {:ok, File.Stat.t()} |
  {:error, posix()}

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

Параметры

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

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

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

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

stat!(path, opts \\ [])

stat!(Path.t(), stat_options()) :: File.Stat.t() | no_return()

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

stream!(path, modes \\ [], line_or_bytes \\ :line)

Возвращает File.Stream для данного path с заданными modes.

Поток реализует протоколы Enumerable и Collectable, что означает, что он может использоваться как для чтения, так и для записи.

Аргумент line_or_bytes настраивает способ чтения файла при потоковой передаче, по :line (по умолчанию) или по заданному числу байт.

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

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

Поскольку Elixir контролирует время открытия потокового файла, используемый подлежащий прибор не может быть совместно использован, и поэтому удобно открыть файл в необработанном режиме для повышения производительности. Поэтому Elixir будет открывать потоки в :raw режиме с :read_ahead параметром, если не указан кодировочный формат. Это означает, что любые данные, передаваемые в файл, должны быть преобразованы в тип iodata/0. Если вы передаете [:utf8] в параметре режимов, подлежащий поток будет использовать IO.write/2 и протокол String.Chars для преобразования данных. См. IO.binwrite/2 и IO.write/2.

Также можно рассмотреть передачу параметра :delayed_write если поток предназначен для записи в условиях высокой нагрузки.

Маркеры порядка байт

Если вы передаете :trim_bom в параметре режимов, поток будет обрезать метки порядка байтов UTF-8, UTF-16 и UTF-32 при чтении из файла.

Примеры

# 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 \\ :calendar.universal_time())

touch(Path.t(), :calendar.datetime()) :: :ok | {:error, posix()}

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

Файл создаётся, если он не существует. Требуется время в UTC.

touch!(path, time \\ :calendar.universal_time())

touch!(Path.t(), :calendar.datetime()) :: :ok | no_return()

То же, что и touch/2, но вызывает исключение, если произошла ошибка.

В противном случае возвращает :ok. Требуется время в UTC.

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

write(Path.t(), iodata(), [mode()]) :: :ok | {:error, posix()}

Записывает content в файл path.

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

content должен быть iodata (списком байтов или двоичным объектом). Установка кодирования для этой функции не оказывает влияния.

Предупреждение: Каждый раз при вызове этой функции открывается дескриптор файла и запускается новый процесс для записи в файл. По этой причине, если вы выполняете несколько записей в цикле, открытие файла с помощью File.open/2 и использование функций в IO для записи в файл обеспечит гораздо лучшую производительность, чем вызов этой функции несколько раз.

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

:enoent — компонент имени файла не существует
:enotdir — компонент имени файла не является директорией; на некоторых платформах вместо этого возвращается :enoent
:enospc — на устройстве закончилось место
:eacces — отсутствуют права для записи в файл или поиска в одной из родительских директорий
:eisdir — указанное имя файла — это директория

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

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

write!(Path.t(), iodata(), [mode()]) :: :ok | no_return()

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

write_stat(path, stat, opts \\ [])

write_stat(Path.t(), File.Stat.t(), stat_options()) ::
  :ok |
  {:error, posix()}

Записывает заданный File.Stat обратно в файловую систему по заданному пути. Возвращает :ok или {:error, reason}.

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

write_stat!(Path.t(), File.Stat.t(), stat_options()) ::
  :ok |
  no_return()

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