File.open
open
, go back to File module for more information.
Specs
open(Path.t(), [mode() | :ram]) :: {:ok, io_device()} | {:error, posix()}
open(Path.t(), (io_device() -> res)) :: {:ok, res} | {:error, posix()} when res: var
Opens the given path
.
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.
modes_or_function
can either be a list of modes or a function. If it's a
list, it's considered to be a list of modes (that are documented below). If
it's a function, then it's equivalent to calling open(path, [], modes_or_function)
. See the documentation for open/3
for more information
on this function.
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 monitors the process that originally opened the file (the owner process). If the owner process terminates, the file is closed and the process itself terminates too. If any process to which theio_device
is linked terminates, the file will be closed and the process itself will be terminated. Anio_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)
Specs
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.
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)
See open/2
for the list of available modes
.