File.open

You're seeing just the function open, go back to File module for more information.
Link to this function

open(path, modes_or_function \\ [])

View Source

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 the io_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 the IO 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)
Link to this function

open(path, modes, function)

View Source

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.