%% %CopyrightBegin%
%%
%% SPDX-License-Identifier: Apache-2.0
%%
%% Copyright Ericsson AB 2021-2025. All Rights Reserved.
%%
%% %CopyrightEnd%

[;1m  open(File, Modes)[0m

  Opens file [;;4mFile[0m in the mode determined by [;;4mModes[0m, which can
  contain one or more of the following options:

   • [;;4mread[0m - The file, which must exist, is opened for reading.

   • [;;4mwrite[0m - The file is opened for writing. It is created if it
     does not exist. If the file exists and [;;4mwrite[0m is not
     combined with [;;4mread[0m, the file is truncated.

   • [;;4mappend[0m - The file is opened for writing. It is created if
     it does not exist. Every write operation to a file opened
     with [;;4mappend[0m takes place at the end of the file.

   • [;;4mexclusive[0m - The file is opened for writing. It is created
     if it does not exist. If the file exists, [;;4m{error, eexist}[0m
     is returned.

  [;;4mWarning[0m

       This option does not guarantee exclusiveness on file
       systems not supporting [;;4mO_EXCL[0m properly, such as NFS.
       Do not depend on this option unless you know that the
       file system supports it (in general, local file systems
       are safe).

   • [;;4mraw[0m - Allows faster access to a file, as no Erlang process
     is needed to handle the file. However, a file opened in this
     way has the following limitations:

      ￮ The functions in the [;;4mio[0m module cannot be used, as
        they can only talk to an Erlang process. Instead, use
        functions [;;4mread/2[0m, [;;4mread_line/1[0m, and [;;4mwrite/2[0m.

      ￮ Especially if [;;4mread_line/1[0m is to be used on a [;;4mraw[0m
        file, it is recommended to combine this option with
        option [;;4m{read_ahead, Size}[0m as line-oriented I/O is
        inefficient without buffering.

      ￮ Only the Erlang process that opened the file can use
        it.

      ￮ remote Erlang file server cannot be used. The computer
        on which the Erlang node is running must have access
        to the file system (directly or through NFS).

   • [;;4mbinary[0m - Read operations on the file return binaries rather
     than lists.

   • [;;4m{delayed_write, Size, Delay}[0m - Data in subsequent [;;4mwrite/2[0m
     calls is buffered until at least [;;4mSize[0m bytes are buffered,
     or until the oldest buffered data is [;;4mDelay[0m milliseconds
     old. Then all buffered data is written in one operating
     system call. The buffered data is also flushed before some
     other file operation than [;;4mwrite/2[0m is executed.

     The purpose of this option is to increase performance by
     reducing the number of operating system calls. Thus, the [;;4m[0m
     [;;4mwrite/2[0m calls must be for sizes significantly less than [;;4m[0m
     [;;4mSize[0m, and not interspersed by too many other file
     operations.

     When this option is used, the result of [;;4mwrite/2[0m calls can
     prematurely be reported as successful, and if a write error
     occurs, the error is reported as the result of the next file
     operation, which is not executed.

     For example, when [;;4mdelayed_write[0m is used, after a number of [;;4m[0m
     [;;4mwrite/2[0m calls, [;;4mclose/1[0m can return [;;4m{error, enospc}[0m, as
     there is not enough space on the disc for previously written
     data. [;;4mclose/1[0m must probably be called again, as the file
     is still open.

   • [;;4mdelayed_write[0m - The same as [;;4m{delayed_write, Size, Delay}[0m
     with reasonable default values for [;;4mSize[0m and [;;4mDelay[0m
     (roughly some 64 KB, 2 seconds).

   • [;;4m{read_ahead, Size}[0m - Activates read data buffering. If [;;4m[0m
     [;;4mread/2[0m calls are for significantly less than [;;4mSize[0m bytes,
     read operations to the operating system are still performed
     for blocks of [;;4mSize[0m bytes. The extra data is buffered and
     returned in subsequent [;;4mread/2[0m calls, giving a performance
     gain as the number of operating system calls is reduced.

     The [;;4mread_ahead[0m buffer is also highly used by function [;;4m[0m
     [;;4mread_line/1[0m in [;;4mraw[0m mode, therefore this option is
     recommended (for performance reasons) when accessing raw
     files using that function.

     If [;;4mread/2[0m calls are for sizes not significantly less than,
     or even greater than [;;4mSize[0m bytes, no performance gain can
     be expected.

   • [;;4mread_ahead[0m - The same as [;;4m{read_ahead, Size}[0m with a
     reasonable default value for [;;4mSize[0m (roughly some 64 KB).

   • [;;4mcompressed[0m - Makes it possible to read or write gzip
     compressed files. Option [;;4mcompressed[0m must be combined with [;;4m[0m
     [;;4mread[0m or [;;4mwrite[0m, but not both. Notice that the file size
     obtained with [;;4mread_file_info/1[0m does probably not match the
     number of bytes that can be read from a compressed file.

   • [;;4mcompressed_one[0m - Read one member of a gzip compressed file.
     Option [;;4mcompressed_one[0m can only be combined with [;;4mread[0m.

   • [;;4m{encoding, Encoding}[0m - Makes the file perform automatic
     translation of characters to and from a specific (Unicode)
     encoding. Notice that the data supplied to [;;4mwrite/2[0m or
     returned by [;;4mread/2[0m still is byte-oriented; this option
     denotes only how data is stored in the disk file.

     Depending on the encoding, different methods of reading and
     writing data is preferred. The default encoding of [;;4mlatin1[0m
     implies using this module ([;;4mfile[0m) for reading and writing
     data as the interfaces provided here work with byte-oriented
     data. Using other (Unicode) encodings makes the [;;4mio[0m
     functions [;;4mget_chars[0m, [;;4mget_line[0m, and [;;4mput_chars[0m more
     suitable, as they can work with the full Unicode range.

     If data is sent to an [;;4mio_device/0[0m in a format that cannot
     be converted to the specified encoding, 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 is closed.

     Allowed values for [;;4mEncoding[0m:

      ￮ [;;4mlatin1[0m - The default encoding. Bytes supplied to the
        file, that is, [;;4mwrite/2[0m are written "as is" on the
        file. Likewise, bytes read from the file, that is, [;;4m[0m
        [;;4mread/2[0m are returned "as is". If module [;;4mio[0m is used
        for writing, the file can only cope with Unicode
        characters up to code point 255 (the ISO Latin-1
        range).

      ￮ [;;4municode or utf8[0m - Characters are translated to and
        from UTF-8 encoding before they are written to or read
        from the file. A file opened in this way can be
        readable using function [;;4mread/2[0m, as long as no data
        stored on the file lies beyond the ISO Latin-1 range
        (0..255), but failure occurs if the data contains
        Unicode code points beyond that range. The file is
        best read with the functions in the Unicode aware
        module [;;4mio[0m.

        Bytes written to the file by any means are translated
        to UTF-8 encoding before being stored on the disk
        file.

      ￮ [;;4mutf16 or {utf16,big}[0m - Works like [;;4municode[0m, but
        translation is done to and from big endian UTF-16
        instead of UTF-8.

      ￮ [;;4m{utf16,little}[0m - Works like [;;4municode[0m, but
        translation is done to and from little endian UTF-16
        instead of UTF-8.

      ￮ [;;4mutf32 or {utf32,big}[0m - Works like [;;4municode[0m, but
        translation is done to and from big endian UTF-32
        instead of UTF-8.

      ￮ [;;4m{utf32,little}[0m - Works like [;;4municode[0m, but
        translation is done to and from little endian UTF-32
        instead of UTF-8.

     The Encoding can be changed for a file "on the fly" by using
     function [;;4mio:setopts/2[0m. So a file can be analyzed in latin1
     encoding for, for example, a BOM, positioned beyond the BOM
     and then be set for the right encoding before further
     reading. For functions identifying BOMs, see module [;;4municode[0m.

     This option is not allowed on [;;4mraw[0m files.

   • [;;4mram[0m - [;;4mFile[0m must be [;;4miodata/0[0m. Returns an [;;4mfd/0[0m, which
     lets module [;;4mfile[0m operate on the data in-memory as if it is
     a file.

   • [;;4msync[0m - On platforms supporting it, enables the POSIX [;;4m[0m
     [;;4mO_SYNC[0m synchronous I/O flag or its platform-dependent
     equivalent (for example, [;;4mFILE_FLAG_WRITE_THROUGH[0m on
     Windows) so that writes to the file block until the data is
     physically written to disk. However, be aware that the exact
     semantics of this flag differ from platform to platform. For
     example, none of Linux or Windows guarantees that all file
     metadata are also written before the call returns. For
     precise semantics, check the details of your platform
     documentation. On platforms with no support for POSIX [;;4m[0m
     [;;4mO_SYNC[0m or equivalent, use of the [;;4msync[0m flag causes [;;4mopen[0m
     to return [;;4m{error, enotsup}[0m.

   • [;;4mdirectory[0m - Allows [;;4mopen[0m to work on directories.

  Returns:

   • [;;4m{ok, IoDevice}[0m - The file is opened in the requested mode. [;;4m[0m
     [;;4mIoDevice[0m is a reference to the file.

   • [;;4m{error, Reason}[0m - The file cannot be opened.

  [;;4mIoDevice[0m is really the pid of the process that 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. An [;;4mIoDevice[0m
  returned from this call can be used as an argument to the I/O
  functions (see [;;4mio[0m).

  [;;4mWarning[0m

    While this function can be used to open any file, we recommend
    against using it for NFS-mounted files, FIFOs, devices, or
    similar since they can cause IO threads to hang forever. If
    your application needs to interact with these kinds of files
    we recommend breaking out those parts to a port program
    instead.

  [;;4mNote[0m

    In previous versions of [;;4mfile[0m, modes were specified as one of
    the atoms [;;4mread[0m, [;;4mwrite[0m, or [;;4mread_write[0m instead of a list.
    This is still allowed for reasons of backwards compatibility,
    but is not to be used for new code. Also note that [;;4mread_write[0m
    is not allowed in a mode list.

  Typical error reasons:

   • [;;4menoent[0m - The file does not exist.

   • [;;4meacces[0m - Missing permission for reading the file or
     searching one of the parent directories.

   • [;;4meisdir[0m - The named file is a directory.

   • [;;4menotdir[0m - A component of the filename is not a directory,
     or the filename itself is not a directory if [;;4mdirectory[0m
     mode was specified. On some platforms, [;;4menoent[0m is returned
     instead.

   • [;;4menospc[0m - There is no space left on the device (if [;;4mwrite[0m
     access was specified).
