File
File
This module contains functions to manipulate files.
Some of those functions are low-level, allowing the user to interact with files or IO devices, like open/2
, copy/3
and others. This module also provides higher level functions that work with filenames and have their naming based on UNIX variants. For example, one can copy a file via cp/3
and remove files and directories recursively via rm_rf/1
.
Encoding
In order to write and read files, one must use the functions in the IO
module. By default, a file is opened in binary mode, which requires the functions IO.binread/2
and IO.binwrite/2
to interact with the file. A developer may pass :utf8
as an option when opening the file, then the slower IO.read/2
and IO.write/2
functions must be used as they are responsible for doing the proper conversions and providing the proper data guarantees.
Note that filenames when given as charlists in Elixir are always treated as UTF-8. In particular, we expect that the shell and the operating system are configured to use UTF-8 encoding. Binary filenames are considered raw and passed to the OS as is.
API
Most of the functions in this module return :ok
or {:ok, result}
in case of success, {:error, reason}
otherwise. Those functions also have a variant that ends with !
which returns the result (instead of the {:ok, result}
tuple) in case of success or raises an exception in case it fails. For example:
File.read("hello.txt")
#=> {:ok, "World"}
File.read("invalid.txt")
#=> {:error, :enoent}
File.read!("hello.txt")
#=> "World"
File.read!("invalid.txt")
#=> raises File.Error
In general, a developer should use the former in case they want to react if the file does not exist. The latter should be used when the developer expects their software to fail in case the file cannot be read (i.e. it is literally an exception).
Processes and raw files
Every time a file is opened, Elixir spawns a new process. Writing to a file is equivalent to sending messages to the process that writes to the file descriptor.
This means files can be passed between nodes and message passing guarantees they can write to the same file in a network.
However, you may not always want to pay the price for this abstraction. In such cases, a file can be opened in :raw
mode. The options :read_ahead
and :delayed_write
are also useful when operating on large files or working with files in tight loops.
Check :file.open/2
for more information about such options and other performance considerations.
Summary
Types
Functions
- cd(path)
-
Sets the current working directory
- cd!(path)
-
The same as
cd/1
, but raises an exception if it fails - cd!(path, function)
-
Changes the current directory to the given
path
, executes the given function and then reverts back to the previous path regardless of whether there is an exception - chgrp(path, gid)
-
Changes the group given by the group id
gid
for a givenfile
. Returns:ok
on success, or{:error, reason}
on failure - chgrp!(path, gid)
-
Same as
chgrp/2
, but raises an exception in case of failure. Otherwise:ok
- chmod(path, mode)
-
Changes the
mode
for a givenfile
- chmod!(path, mode)
-
Same as
chmod/2
, but raises an exception in case of failure. Otherwise:ok
- chown(path, uid)
-
Changes the owner given by the user id
uid
for a givenfile
. Returns:ok
on success, or{:error, reason}
on failure - chown!(path, uid)
-
Same as
chown/2
, but raises an exception in case of failure. Otherwise:ok
- close(io_device)
-
Closes the file referenced by
io_device
. It mostly returns:ok
, except for some severe errors such as out of memory - copy(source, destination, bytes_count \\ :infinity)
-
Copies the contents of
source
todestination
- copy!(source, destination, bytes_count \\ :infinity)
-
The same as
copy/3
but raises anFile.CopyError
if it fails. Returns thebytes_copied
otherwise - cp(source, destination, callback \\ fn _, _ -> true end)
-
Copies the contents in
source
todestination
preserving its mode - cp!(source, destination, callback \\ fn _, _ -> true end)
-
The same as
cp/3
, but raisesFile.CopyError
if it fails. Returns:ok
otherwise - cp_r(source, destination, callback \\ fn _, _ -> true end)
-
Copies the contents in source to destination
- cp_r!(source, destination, callback \\ fn _, _ -> true end)
-
The same as
cp_r/3
, but raisesFile.CopyError
if it fails. Returns the list of copied files otherwise - cwd()
-
Gets the current working directory
- cwd!()
-
The same as
cwd/0
, but raises an exception if it fails - dir?(path)
-
Returns
true
if the path is a directory - exists?(path)
-
Returns
true
if the given path exists. It can be regular file, directory, socket, symbolic link, named pipe or device file - ln_s(existing, new)
-
Creates a symbolic link
new
to the file or directoryexisting
- ls(path \\ ".")
-
Returns the list of files in the given directory
- ls!(path \\ ".")
-
The same as
ls/1
but raisesFile.Error
in case of an error - lstat(path, opts \\ [])
-
Returns information about the
path
. If the file is a symlink, sets thetype
to:symlink
and returns aFile.Stat
struct for the link. For any other file, returns exactly the same values asstat/2
- lstat!(path, opts \\ [])
-
Same as
lstat/2
but returns theFile.Stat
struct directly and throwsFile.Error
if an error is returned - mkdir(path)
-
Tries to create the directory
path
. Missing parent directories are not created. Returns:ok
if successful, or{:error, reason}
if an error occurs - mkdir!(path)
-
Same as
mkdir/1
, but raises an exception in case of failure. Otherwise:ok
- mkdir_p(path)
-
Tries to create the directory
path
. Missing parent directories are created. Returns:ok
if successful, or{:error, reason}
if an error occurs - mkdir_p!(path)
-
Same as
mkdir_p/1
, but raises an exception in case of failure. Otherwise:ok
- open(path, modes \\ [])
-
Opens the given
path
according to the given list ofmodes
- open(path, modes, function)
-
Similar to
open/2
but expects a function as its last argument - open!(path, modes \\ [])
-
Same as
open/2
but raises an error if file could not be opened - open!(path, modes, function)
-
Same as
open/3
but raises an error if file could not be opened - read(path)
-
Returns
{:ok, binary}
, wherebinary
is a binary data object that contains the contents ofpath
, or{:error, reason}
if an error occurs - read!(path)
-
Returns a binary with the contents of the given filename or raises
File.Error
if an error occurs - regular?(path)
-
Returns
true
if the path is a regular file - rename(source, destination)
-
Renames the
source
file todestination
file. It can be used to move files (and directories) between directories. If moving a file, you must fully specify thedestination
filename, it is not sufficient to simply specify its directory - rm(path)
-
Tries to delete the file
path
- rm!(path)
-
Same as
rm/1
, but raises an exception in case of failure. Otherwise:ok
- rm_rf(path)
-
Removes files and directories recursively at the given
path
. Symlinks are not followed but simply removed, non-existing files are simply ignored (i.e. doesn’t make this function fail) - rm_rf!(path)
-
Same as
rm_rf/1
but raisesFile.Error
in case of failures, otherwise the list of files or directories removed - rmdir(path)
-
Tries to delete the dir at
path
. Returns:ok
if successful, or{:error, reason}
if an error occurs - rmdir!(path)
-
Same as
rmdir/1
, but raises an exception in case of failure. Otherwise:ok
- stat(path, opts \\ [])
-
Returns information about the
path
. If it exists, it returns a{:ok, info}
tuple, where info is aFile.Stat
struct. Returns{:error, reason}
with the same reasons asread/1
if a failure occurs - stat!(path, opts \\ [])
-
Same as
stat/2
but returns theFile.Stat
directly and throwsFile.Error
if an error is returned - stream!(path, modes \\ [], line_or_bytes \\ :line)
-
Returns a
File.Stream
for the givenpath
with the givenmodes
- touch(path, time \\ :calendar.universal_time())
-
Updates modification time (mtime) and access time (atime) of the given file
- touch!(path, time \\ :calendar.universal_time())
-
Same as
touch/2
but raises an exception if it fails - write(path, content, modes \\ [])
-
Writes
content
to the filepath
- write!(path, content, modes \\ [])
-
Same as
write/3
but raises an exception if it fails, returns:ok
otherwise - write_stat(path, stat, opts \\ [])
-
Writes the given
File.Stat
back to the filesystem at the given path. Returns:ok
or{:error, reason}
- write_stat!(path, stat, opts \\ [])
-
Same as
write_stat/3
but raises an exception if it fails. Returns:ok
otherwise
Types
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}]
Functions
cd(path)
cd(Path.t) :: :ok | {:error, posix}
Sets the current working directory.
Returns :ok
if successful, {:error, reason}
otherwise.
cd!(path)
cd!(Path.t) :: :ok | no_return
The same as cd/1
, but raises an exception if it fails.
cd!(path, function)
cd!(Path.t, (() -> res)) :: res | no_return when res: var
Changes the current directory to the given path
, executes the given function and then reverts back to the previous path regardless of whether there is an exception.
Raises an error if retrieving or changing the current directory fails.
chgrp(path, gid)
chgrp(Path.t, non_neg_integer) :: :ok | {:error, posix}
Changes the group given by the group id gid
for a given file
. Returns :ok
on success, or {:error, reason}
on failure.
chgrp!(path, gid)
chgrp!(Path.t, non_neg_integer) :: :ok | no_return
Same as chgrp/2
, but raises an exception in case of failure. Otherwise :ok
.
chmod(path, mode)
chmod(Path.t, non_neg_integer) :: :ok | {:error, posix}
Changes the mode
for a given file
.
Returns :ok
on success, or {:error, reason}
on failure.
Permissions
- 0o400 - read permission: owner
- 0o200 - write permission: owner
-
0o100 - execute permission: owner
- 0o040 - read permission: group
- 0o020 - write permission: group
-
0o010 - execute permission: group
- 0o004 - read permission: other
- 0o002 - write permission: other
- 0o001 - execute permission: other
For example, setting the mode 0o755 gives it write, read and execute permission to the owner and both read and execute permission to group and others.
chmod!(path, mode)
chmod!(Path.t, non_neg_integer) :: :ok | no_return
Same as chmod/2
, but raises an exception in case of failure. Otherwise :ok
.
chown(path, uid)
chown(Path.t, non_neg_integer) :: :ok | {:error, posix}
Changes the owner given by the user id uid
for a given file
. Returns :ok
on success, or {:error, reason}
on failure.
chown!(path, uid)
chown!(Path.t, non_neg_integer) :: :ok | no_return
Same as chown/2
, but raises an exception in case of failure. Otherwise :ok
.
close(io_device)
close(io_device) :: :ok | {:error, posix | :badarg | :terminated}
Closes the file referenced by io_device
. It mostly returns :ok
, except for some severe errors such as out of memory.
Note that if the option :delayed_write
was used when opening the file, close/1
might return an old write error and not even try to close the file. See 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}
Copies the contents of source
to destination
.
Both parameters can be a filename or an IO device opened with open/2
. bytes_count
specifies the number of bytes to copy, the default being :infinity
.
If file destination
already exists, it is overwritten by the contents in source
.
Returns {:ok, bytes_copied}
if successful, {:error, reason}
otherwise.
Compared to the cp/3
, this function is more low-level, allowing a copy from device to device limited by a number of bytes. On the other hand, cp/3
performs more extensive checks on both source and destination and it also preserves the file mode after copy.
Typical error reasons are the same as in open/2
, read/1
and 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
The same as copy/3
but raises an File.CopyError
if it fails. Returns the bytes_copied
otherwise.
cp(source, destination, callback \\ fn _, _ -> true end)
cp(Path.t, Path.t, (Path.t, Path.t -> boolean)) :: :ok | {:error, posix}
Copies the contents in source
to destination
preserving its mode.
If a file already exists in the destination, it invokes a callback which should return true
if the existing file should be overwritten, false
otherwise. The callback defaults to return true
.
The function returns :ok
in case of success, returns {:error, reason}
otherwise.
If you want to copy contents from an IO device to another device or do a straight copy from a source to a destination without preserving modes, check copy/3
instead.
Note: The command cp
in Unix systems behaves differently depending if destination
is an existing directory or not. We have chosen to explicitly disallow this behaviour. If destination is a directory, an error will be returned.
cp!(source, destination, callback \\ fn _, _ -> true end)
cp!(Path.t, Path.t, (Path.t, Path.t -> boolean)) :: :ok | no_return
The same as cp/3
, but raises File.CopyError
if it fails. Returns :ok
otherwise.
cp_r(source, destination, callback \\ fn _, _ -> true end)
cp_r(Path.t, Path.t, (Path.t, Path.t -> boolean)) :: {:ok, [binary]} | {:error, posix, binary}
Copies the contents in source to destination.
If the source is a file, it copies source
to destination
. If the source is a directory, it copies the contents inside source into the destination.
If a file already exists in the destination, it invokes a callback which should return true
if the existing file should be overwritten, false
otherwise. The callback defaults to return true
.
If a directory already exists in the destination where a file is meant to be (or vice versa), this function will fail.
This function may fail while copying files, in such cases, it will leave the destination directory in a dirty state, where file which have already been copied won’t be removed.
The function returns {:ok, files_and_directories}
in case of success, files_and_directories
lists all files and directories copied in no specific order. It returns {:error, reason, file}
otherwise.
Note: The command cp
in Unix systems behaves differently depending if destination
is an existing directory or not. We have chosen to explicitly disallow this behaviour.
Examples
# 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
The same as cp_r/3
, but raises File.CopyError
if it fails. Returns the list of copied files otherwise.
cwd()
cwd() :: {:ok, binary} | {:error, posix}
Gets the current working directory.
In rare circumstances, this function can fail on Unix. It may happen if read permissions do not exist for the parent directories of the current directory. For this reason, returns {:ok, cwd}
in case of success, {:error, reason}
otherwise.
cwd!()
cwd!() :: binary | no_return
The same as cwd/0
, but raises an exception if it fails.
dir?(path)
dir?(Path.t) :: boolean
Returns true
if the path is a directory.
exists?(path)
exists?(Path.t) :: boolean
Returns true
if the given path exists. It can be regular file, directory, socket, symbolic link, named pipe or device file.
Examples
File.exists?("test/")
#=> true
File.exists?("missing.txt")
#=> false
File.exists?("/dev/null")
#=> true
ln_s(existing, new)
Creates a symbolic link new
to the file or directory existing
.
Returns :ok
if successful, {:error, reason}
otherwise. If the operating system does not support symlinks, returns {:error, :enotsup}
.
ls(path \\ ".")
ls(Path.t) :: {:ok, [binary]} | {:error, posix}
Returns the list of files in the given directory.
It returns {:ok, [files]}
in case of success, {:error, reason}
otherwise.
ls!(path \\ ".")
ls!(Path.t) :: [binary] | no_return
The same as ls/1
but raises File.Error
in case of an error.
lstat(path, opts \\ [])
lstat(Path.t, stat_options) :: {:ok, File.Stat.t} | {:error, posix}
Returns information about the path
. If the file is a symlink, sets the type
to :symlink
and returns a File.Stat
struct for the link. For any other file, returns exactly the same values as stat/2
.
For more details, see :file.read_link_info/2
.
Options
The accepted options are:
-
:time
- configures how the file timestamps are returned
The values for :time
can be:
-
:universal
- returns a{date, time}
tuple in UTC (default) -
:local
- returns a{date, time}
tuple using the machine time -
:posix
- returns the time as integer seconds since epoch
lstat!(path, opts \\ [])
lstat!(Path.t, stat_options) :: File.Stat.t | no_return
Same as lstat/2
but returns the File.Stat
struct directly and throws File.Error
if an error is returned.
mkdir(path)
mkdir(Path.t) :: :ok | {:error, posix}
Tries to create the directory path
. Missing parent directories are not created. Returns :ok
if successful, or {:error, reason}
if an error occurs.
Typical error reasons are:
-
:eacces
- missing search or write permissions for the parent directories ofpath
-
:eexist
- there is already a file or directory namedpath
-
:enoent
- a component ofpath
does not exist -
:enospc
- there is a no space left on the device -
:enotdir
- a component ofpath
is not a directory; on some platforms,:enoent
is returned instead
mkdir!(path)
mkdir!(Path.t) :: :ok | no_return
Same as mkdir/1
, but raises an exception in case of failure. Otherwise :ok
.
mkdir_p(path)
mkdir_p(Path.t) :: :ok | {:error, posix}
Tries to create the directory path
. Missing parent directories are created. Returns :ok
if successful, or {:error, reason}
if an error occurs.
Typical error reasons are:
-
:eacces
- missing search or write permissions for the parent directories ofpath
-
:enospc
- there is a no space left on the device -
:enotdir
- a component ofpath
is not a directory
mkdir_p!(path)
mkdir_p!(Path.t) :: :ok | no_return
Same as mkdir_p/1
, but raises an exception in case of failure. Otherwise :ok
.
open(path, modes \\ [])
open(Path.t, (io_device -> res)) :: {:ok, res} | {:error, posix} when res: var
open(Path.t, [mode | :ram]) :: {:ok, io_device} | {:error, posix}
Opens the given path
according to the given list of modes
.
In order to write and read files, one must use the functions in the IO
module. By default, a file is opened in :binary
mode, which requires the functions IO.binread/2
and IO.binwrite/2
to interact with the file. A developer may pass :utf8
as an option when opening the file and then all other functions from IO
are available, since they work directly with Unicode data.
The allowed modes:
-
:binary
- opens the file in binary mode, disabling special handling of unicode sequences (default mode). -
:read
- the file, which must exist, is opened for reading. -
:write
- the file is opened for writing. It is created if it does not exist.If the file does exists, and if write is not combined with read, the file will be truncated.
-
:append
- the file will be opened for writing, and it will be created if it does not exist. Every write operation to a file opened with append will take place at the end of the file. -
:exclusive
- the file, when opened for writing, is created if it does not exist. If the file exists, open will return{:error, :eexist}
. -
:charlist
- when this term is given, read operations on the file will return charlists rather than binaries. -
:compressed
- makes it possible to read or write gzip compressed files.The compressed option must be combined with either read or write, but not both. Note that the file size obtained with
stat/1
will most probably not match the number of bytes that can be read from a compressed file. -
:utf8
- this option denotes how data is actually stored in the disk file and makes the file perform automatic translation of characters to and from UTF-8.If data is sent to a file in a format that cannot be converted to the UTF-8 or if data is read by a function that returns data in a format that cannot cope with the character range of the data, an error occurs and the file will be closed.
-
:delayed_write
,:raw
,:ram
,:read_ahead
,:sync
,{:encoding, ...}
,{:read_ahead, pos_integer}
,{:delayed_write, non_neg_integer, non_neg_integer}
- for more information about these options see:file.open/2
.
This function returns:
-
{:ok, io_device}
- the file has been opened in the requested mode.io_device
is actually the pid of the process which handles the file. This process is linked to the process which originally opened the file. If any process to which theio_device
is linked terminates, the file will be closed and the process itself will be terminated.An
io_device
returned from this call can be used as an argument to theIO
module functions. -
{:error, reason}
- the file could not be opened.
Examples
{: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
Similar to open/2
but expects a function as its last argument.
The file is opened, given to the function as an argument and automatically closed after the function returns, regardless if there was an error when executing the function.
It returns {:ok, function_result}
in case of success, {:error, reason}
otherwise.
This function expects the file to be closed with success, which is usually the case unless the :delayed_write
option is given. For this reason, we do not recommend passing :delayed_write
to this function.
Examples
File.open("file.txt", [:read, :write], fn(file) ->
IO.read(file, :line)
end)
open!(path, modes \\ [])
open!(Path.t, [mode]) :: io_device | no_return
Same as open/2
but raises an error if file could not be opened.
Returns the io_device
otherwise.
open!(path, modes, function)
open!(Path.t, [mode | :ram], (io_device -> res)) :: res | no_return when res: var
Same as open/3
but raises an error if file could not be opened.
Returns the function result otherwise.
read(path)
read(Path.t) :: {:ok, binary} | {:error, posix}
Returns {:ok, binary}
, where binary
is a binary data object that contains the contents of path
, or {:error, reason}
if an error occurs.
Typical error reasons:
-
:enoent
- the file does not exist -
:eacces
- missing permission for reading the file, or for searching one of the parent directories -
:eisdir
- the named file is a directory -
:enotdir
- a component of the file name is not a directory; on some platforms,:enoent
is returned instead -
:enomem
- there is not enough memory for the contents of the file
You can use :file.format_error/1
to get a descriptive string of the error.
read!(path)
read!(Path.t) :: binary | no_return
Returns a binary with the contents of the given filename or raises File.Error
if an error occurs.
regular?(path)
regular?(Path.t) :: boolean
Returns true
if the path is a regular file.
Examples
File.regular? __ENV__.file #=> true
rename(source, destination)
rename(Path.t, Path.t) :: :ok | {:error, posix}
Renames the source
file to destination
file. It can be used to move files (and directories) between directories. If moving a file, you must fully specify the destination
filename, it is not sufficient to simply specify its directory.
It returns :ok
in case of success, returns {:error, reason}
otherwise.
Note: The command mv
in Unix systems behaves differently depending if source
is a file and the destination
is an existing directory. We have chosen to explicitly disallow this behaviour.
Examples
# 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}
Tries to delete the file path
.
Returns :ok
if successful, or {:error, reason}
if an error occurs.
Note the file is deleted even if in read-only mode.
Typical error reasons are:
-
:enoent
- the file does not exist -
:eacces
- missing permission for the file or one of its parents -
:eperm
- the file is a directory and user is not super-user -
:enotdir
- a component of the file name is not a directory; on some platforms,:enoent
is returned instead -
:einval
- filename had an improper type, such as tuple
Examples
File.rm("file.txt")
#=> :ok
File.rm("tmp_dir/")
#=> {:error, :eperm}
rm!(path)
rm!(Path.t) :: :ok | no_return
Same as rm/1
, but raises an exception in case of failure. Otherwise :ok
.
rm_rf(path)
rm_rf(Path.t) :: {:ok, [binary]} | {:error, posix, binary}
Removes files and directories recursively at the given path
. Symlinks are not followed but simply removed, non-existing files are simply ignored (i.e. doesn’t make this function fail).
Returns {:ok, files_and_directories}
with all files and directories removed in no specific order, {:error, reason, file}
otherwise.
Examples
File.rm_rf "samples"
#=> {:ok, ["samples", "samples/1.txt"]}
File.rm_rf "unknown"
#=> {:ok, []}
rm_rf!(path)
rm_rf!(Path.t) :: [binary] | no_return
Same as rm_rf/1
but raises File.Error
in case of failures, otherwise the list of files or directories removed.
rmdir(path)
rmdir(Path.t) :: :ok | {:error, posix}
Tries to delete the dir at path
. Returns :ok
if successful, or {:error, reason}
if an error occurs.
Examples
File.rmdir('tmp_dir')
#=> :ok
File.rmdir('file.txt')
#=> {:error, :enotdir}
rmdir!(path)
rmdir!(Path.t) :: :ok | {:error, posix}
Same as rmdir/1
, but raises an exception in case of failure. Otherwise :ok
.
stat(path, opts \\ [])
stat(Path.t, stat_options) :: {:ok, File.Stat.t} | {:error, posix}
Returns information about the path
. If it exists, it returns a {:ok, info}
tuple, where info is a File.Stat
struct. Returns {:error, reason}
with the same reasons as read/1
if a failure occurs.
Options
The accepted options are:
-
:time
- configures how the file timestamps are returned
The values for :time
can be:
-
:universal
- returns a{date, time}
tuple in UTC (default) -
:local
- returns a{date, time}
tuple using the same time zone as the machine -
:posix
- returns the time as integer seconds since epoch
stat!(path, opts \\ [])
stat!(Path.t, stat_options) :: File.Stat.t | no_return
Same as stat/2
but returns the File.Stat
directly and throws File.Error
if an error is returned.
stream!(path, modes \\ [], line_or_bytes \\ :line)
Returns a File.Stream
for the given path
with the given modes
.
The stream implements both Enumerable
and Collectable
protocols, which means it can be used both for read and write.
The line_or_byte
argument configures how the file is read when streaming, by :line
(default) or by a given number of bytes.
Operating the stream can fail on open for the same reasons as File.open!/2
. Note that the file is automatically opened each time streaming begins. There is no need to pass :read
and :write
modes, as those are automatically set by Elixir.
Raw files
Since Elixir controls when the streamed file is opened, the underlying device cannot be shared and as such it is convenient to open the file in raw mode for performance reasons. Therefore, Elixir will open streams in :raw
mode with the :read_ahead
option unless an encoding is specified. This means any data streamed into the file must be converted to iodata
type. If you pass [:utf8]
in the modes parameter, the underlying stream will use IO.write/2
and the String.Chars
protocol to convert the data. See IO.binwrite/2
and IO.write/2
.
One may also consider passing the :delayed_write
option if the stream is meant to be written to under a tight loop.
Examples
# 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}
See Stream.run/1
for an example of streaming into a file.
touch(path, time \\ :calendar.universal_time())
touch(Path.t, :calendar.datetime) :: :ok | {:error, posix}
Updates modification time (mtime) and access time (atime) of the given file.
The file is created if it doesn’t exist. Requires datetime in UTC.
touch!(path, time \\ :calendar.universal_time())
touch!(Path.t, :calendar.datetime) :: :ok | no_return
Same as touch/2
but raises an exception if it fails.
Returns :ok
otherwise. Requires datetime in UTC.
write(path, content, modes \\ [])
write(Path.t, iodata, [mode]) :: :ok | {:error, posix}
Writes content
to the file path
.
The file is created if it does not exist. If it exists, the previous contents are overwritten. Returns :ok
if successful, or {:error, reason}
if an error occurs.
Warning: Every time this function is invoked, a file descriptor is opened and a new process is spawned to write to the file. For this reason, if you are doing multiple writes in a loop, opening the file via File.open/2
and using the functions in IO
to write to the file will yield much better performance than calling this function multiple times.
Typical error reasons are:
-
:enoent
- a component of the file name does not exist -
:enotdir
- a component of the file name is not a directory; on some platforms,:enoent
is returned instead -
:enospc
- there is a no space left on the device -
:eacces
- missing permission for writing the file or searching one of the parent directories -
:eisdir
- the named file is a directory
Check File.open/2
for other available options.
write!(path, content, modes \\ [])
write!(Path.t, iodata, [mode]) :: :ok | no_return
Same as write/3
but raises an exception if it fails, returns :ok
otherwise.
write_stat(path, stat, opts \\ [])
write_stat(Path.t, File.Stat.t, stat_options) :: :ok | {:error, posix}
Writes the given File.Stat
back to the filesystem at the given path. Returns :ok
or {:error, reason}
.
write_stat!(path, stat, opts \\ [])
write_stat!(Path.t, File.Stat.t, stat_options) :: :ok | no_return
Same as write_stat/3
but raises an exception if it fails. Returns :ok
otherwise.
© 2012–2017 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.3.4/File.html