Provided by: erlang-manpages_22.0.7+dfsg-1build1_all bug

NAME

       file - File interface module.

DESCRIPTION

       This module provides an interface to the file system.

   Warning:
       File  operations  are  only  guaranteed  to appear atomic when going through the same file
       server. A NIF or other OS process may observe intermediate steps on certain operations  on
       some  operating systems, eg. renaming an existing file on Windows, or write_file_info/2 on
       any OS at the time of writing.

       Regarding filename encoding, the Erlang VM can operate in two modes. The current mode  can
       be queried using function native_name_encoding/0. It returns latin1 or utf8.

       In  latin1  mode,  the  Erlang VM does not change the encoding of filenames. In utf8 mode,
       filenames can contain Unicode characters greater than 255 and the  VM  converts  filenames
       back and forth to the native filename encoding (usually UTF-8, but UTF-16 on Windows).

       The  default  mode depends on the operating system. Windows and MacOS X enforce consistent
       filename encoding and therefore the VM uses utf8 mode.

       On operating systems with transparent naming (for example, all Unix systems  except  MacOS
       X),  default  is utf8 if the terminal supports UTF-8, otherwise latin1. The default can be
       overridden using +fnl (to force latin1 mode) or +fnu (to force utf8  mode)  when  starting
       erl.

       On  operating  systems  with  transparent  naming,  files can be inconsistently named, for
       example, some files are encoded in UTF-8 while others are  encoded  in  ISO  Latin-1.  The
       concept  of  raw  filenames  is introduced to handle file systems with inconsistent naming
       when running in utf8 mode.

       A raw filename is a filename specified as a binary. The Erlang VM  does  not  translate  a
       filename specified as a binary on systems with transparent naming.

       When  running  in  utf8  mode,  functions  list_dir/1  and  read_link/1  never  return raw
       filenames. To return all filenames including raw filenames, use  functions  list_dir_all/1
       and read_link_all/1.

       See also section Notes About Raw Filenames in the STDLIB User's Guide.

   Note:
       File  operations used to accept filenames containing null characters (integer value zero).
       This caused the name to be truncated and in some cases arguments to  primitive  operations
       to  be mixed up. Filenames containing null characters inside the filename are now rejected
       and will cause primitive file operations fail.

DATA TYPES

       deep_list() = [char() | atom() | deep_list()]

       fd()

              A file descriptor representing a file opened in raw mode.

       filename() = string()

              See also the documentation of the name_all() type.

       filename_all() = string() | binary()

              See also the documentation of the name_all() type.

       io_device() = pid() | fd()

              As returned by open/2; pid() is a process handling I/O-protocols.

       name() = string() | atom() | deep_list()

              If VM is in Unicode filename mode, string() and char() are allowed to be > 255. See
              also the documentation of the name_all() type.

       name_all() =
           string() | atom() | deep_list() | (RawFilename :: binary())

              If  VM is in Unicode filename mode, characters are allowed to be > 255. RawFilename
              is a filename not subject to Unicode  translation,  meaning  that  it  can  contain
              characters  not  conforming  to  the Unicode encoding expected from the file system
              (that is, non-UTF-8 characters although the  VM  is  started  in  Unicode  filename
              mode).  Null characters (integer value zero) are not allowed in filenames (not even
              at the end).

       posix() =
           eacces | eagain | ebadf | ebadmsg | ebusy | edeadlk |
           edeadlock | edquot | eexist | efault | efbig | eftype |
           eintr | einval | eio | eisdir | eloop | emfile | emlink |
           emultihop | enametoolong | enfile | enobufs | enodev |
           enolck | enolink | enoent | enomem | enospc | enosr | enostr |
           enosys | enotblk | enotdir | enotsup | enxio | eopnotsupp |
           eoverflow | eperm | epipe | erange | erofs | espipe | esrch |
           estale | etxtbsy | exdev

              An atom that is named from the POSIX error codes used in Unix, and in  the  runtime
              libraries of most C compilers.

       date_time() = calendar:datetime()

              Must denote a valid date and time.

       file_info() =
           #file_info{size = integer() >= 0 | undefined,
                      type =
                          device | directory | other | regular |
                          symlink | undefined,
                      access =
                          read | write | read_write | none | undefined,
                      atime =
                          file:date_time() |
                          integer() >= 0 |
                          undefined,
                      mtime =
                          file:date_time() |
                          integer() >= 0 |
                          undefined,
                      ctime =
                          file:date_time() |
                          integer() >= 0 |
                          undefined,
                      mode = integer() >= 0 | undefined,
                      links = integer() >= 0 | undefined,
                      major_device = integer() >= 0 | undefined,
                      minor_device = integer() >= 0 | undefined,
                      inode = integer() >= 0 | undefined,
                      uid = integer() >= 0 | undefined,
                      gid = integer() >= 0 | undefined}

       location() =
           integer() |
           {bof, Offset :: integer()} |
           {cur, Offset :: integer()} |
           {eof, Offset :: integer()} |
           bof | cur | eof

       mode() =
           read | write | append | exclusive | raw | binary |
           {delayed_write,
            Size :: integer() >= 0,
            Delay :: integer() >= 0} |
           delayed_write |
           {read_ahead, Size :: integer() >= 1} |
           read_ahead | compressed |
           {encoding, unicode:encoding()} |
           sync

       file_info_option() =
           {time, local} | {time, universal} | {time, posix} | raw

EXPORTS

       advise(IoDevice, Offset, Length, Advise) -> ok | {error, Reason}

              Types:

                 IoDevice = io_device()
                 Offset = Length = integer()
                 Advise = posix_file_advise()
                 Reason = posix() | badarg
                 posix_file_advise() =
                     normal | sequential | random | no_reuse | will_need |
                     dont_need

              advise/4  can  be  used  to announce an intention to access file data in a specific
              pattern in the future, thus allowing the operating system  to  perform  appropriate
              optimizations.

              On some platforms, this function might have no effect.

       allocate(File, Offset, Length) -> ok | {error, posix()}

              Types:

                 File = io_device()
                 Offset = Length = integer() >= 0

              allocate/3 can be used to preallocate space for a file.

              This  function  only  succeeds  in  platforms  that  provide  this feature. When it
              succeeds, space is preallocated for the  file  but  the  file  size  might  not  be
              updated.  This  behaviour depends on the preallocation implementation. To guarantee
              that the file size is updated, truncate the file to the new size.

       change_group(Filename, Gid) -> ok | {error, Reason}

              Types:

                 Filename = name_all()
                 Gid = integer()
                 Reason = posix() | badarg

              Changes group of a file. See write_file_info/2.

       change_mode(Filename, Mode) -> ok | {error, Reason}

              Types:

                 Filename = name_all()
                 Mode = integer()
                 Reason = posix() | badarg

              Changes permissions of a file. See write_file_info/2.

       change_owner(Filename, Uid) -> ok | {error, Reason}

              Types:

                 Filename = name_all()
                 Uid = integer()
                 Reason = posix() | badarg

              Changes owner of a file. See write_file_info/2.

       change_owner(Filename, Uid, Gid) -> ok | {error, Reason}

              Types:

                 Filename = name_all()
                 Uid = Gid = integer()
                 Reason = posix() | badarg

              Changes owner and group of a file. See write_file_info/2.

       change_time(Filename, Mtime) -> ok | {error, Reason}

              Types:

                 Filename = name_all()
                 Mtime = date_time()
                 Reason = posix() | badarg

              Changes the modification and access times of a file. See write_file_info/2.

       change_time(Filename, Atime, Mtime) -> ok | {error, Reason}

              Types:

                 Filename = name_all()
                 Atime = Mtime = date_time()
                 Reason = posix() | badarg

              Changes the modification and last access times of a file. See write_file_info/2.

       close(IoDevice) -> ok | {error, Reason}

              Types:

                 IoDevice = io_device()
                 Reason = posix() | badarg | terminated

              Closes the file referenced by IoDevice. It  mostly  returns  ok,  except  for  some
              severe errors such as out of memory.

              Notice  that  if  option  delayed_write was used when opening the file, close/1 can
              return an old write error and not even try to close the file. See open/2.

       consult(Filename) -> {ok, Terms} | {error, Reason}

              Types:

                 Filename = name_all()
                 Terms = [term()]
                 Reason =
                     posix() |
                     badarg | terminated | system_limit |
                     {Line :: integer(), Mod :: module(), Term :: term()}

              Reads Erlang terms, separated by '.', from Filename. Returns one of the following:

                {ok, Terms}:
                  The file was successfully read.

                {error, atom()}:
                  An error occurred when opening the file or reading it. For a  list  of  typical
                  error codes, see open/2.

                {error, {Line, Mod, Term}}:
                  An  error  occurred  when interpreting the Erlang terms in the file. To convert
                  the  three-element  tuple  to  an  English  description  of  the   error,   use
                  format_error/1.

              Example:

              f.txt:  {person, "kalle", 25}.
                      {person, "pelle", 30}.

              1> file:consult("f.txt").
              {ok,[{person,"kalle",25},{person,"pelle",30}]}

              The encoding of Filename can be set by a comment, as described in epp(3erl).

       copy(Source, Destination) -> {ok, BytesCopied} | {error, Reason}

       copy(Source, Destination, ByteCount) ->
               {ok, BytesCopied} | {error, Reason}

              Types:

                 Source = Destination = io_device() | Filename | {Filename, Modes}
                 Filename = name_all()
                 Modes = [mode()]
                 ByteCount = integer() >= 0 | infinity
                 BytesCopied = integer() >= 0
                 Reason = posix() | badarg | terminated

              Copies  ByteCount bytes from Source to Destination. Source and Destination refer to
              either filenames or IO devices from, for example,  open/2.  ByteCount  defaults  to
              infinity, denoting an infinite number of bytes.

              Argument Modes is a list of possible modes, see open/2, and defaults to [].

              If both Source and Destination refer to filenames, the files are opened with [read,
              binary] and [write,  binary]  prepended  to  their  mode  lists,  respectively,  to
              optimize the copy.

              If  Source  refers to a filename, it is opened with read mode prepended to the mode
              list before the copy, and closed when done.

              If Destination refers to a filename, it is opened with write mode prepended to  the
              mode list before the copy, and closed when done.

              Returns  {ok,  BytesCopied},  where  BytesCopied  is  the  number of bytes that was
              copied, which can be less than ByteCount if end of  file  was  encountered  on  the
              source. If the operation fails, {error, Reason} is returned.

              Typical  error reasons: as for open/2 if a file had to be opened, and as for read/2
              and write/2.

       datasync(IoDevice) -> ok | {error, Reason}

              Types:

                 IoDevice = io_device()
                 Reason = posix() | badarg | terminated

              Ensures that any buffers kept by the operating system (not by  the  Erlang  runtime
              system) are written to disk. In many ways it resembles fsync but it does not update
              some of the metadata of the file, such as the access time. On some  platforms  this
              function has no effect.

              Applications  that  access  databases or log files often write a tiny data fragment
              (for example, one line in a log file) and then call fsync() immediately  to  ensure
              that the written data is physically stored on the hard disk. Unfortunately, fsync()
              always initiates two write operations: one for the newly written data  and  another
              one  to  update the modification time stored in the inode. If the modification time
              is not a part of  the  transaction  concept,  fdatasync()  can  be  used  to  avoid
              unnecessary inode disk write operations.

              Available  only  in  some POSIX systems, this call results in a call to fsync(), or
              has no effect in systems not providing the fdatasync() syscall.

       del_dir(Dir) -> ok | {error, Reason}

              Types:

                 Dir = name_all()
                 Reason = posix() | badarg

              Tries to delete directory Dir. The  directory  must  be  empty  before  it  can  be
              deleted. Returns ok if successful.

              Typical error reasons:

                eacces:
                  Missing search or write permissions for the parent directories of Dir.

                eexist:
                  The directory is not empty.

                enoent:
                  The directory does not exist.

                enotdir:
                  A  component  of  Dir is not a directory. On some platforms, enoent is returned
                  instead.

                einval:
                  Attempt to delete the current directory. On some platforms, eacces is  returned
                  instead.

       delete(Filename) -> ok | {error, Reason}

              Types:

                 Filename = name_all()
                 Reason = posix() | badarg

              Tries to delete file Filename. Returns ok if successful.

              Typical error reasons:

                enoent:
                  The file does not exist.

                eacces:
                  Missing permission for the file or one of its parents.

                eperm:
                  The file is a directory and the user is not superuser.

                enotdir:
                  A  component  of  the filename is not a directory. On some platforms, enoent is
                  returned instead.

                einval:
                  Filename has an improper type, such as tuple.

          Warning:
              In a future release, a bad type for argument Filename  will  probably  generate  an
              exception.

       eval(Filename) -> ok | {error, Reason}

              Types:

                 Filename = name_all()
                 Reason =
                     posix() |
                     badarg | terminated | system_limit |
                     {Line :: integer(), Mod :: module(), Term :: term()}

              Reads  and  evaluates  Erlang  expressions, separated by '.' (or ',', a sequence of
              expressions is also an expression) from Filename. The result of the  evaluation  is
              not  returned;  any  expression  sequence  in  the  file must be there for its side
              effect. Returns one of the following:

                ok:
                  The file was read and evaluated.

                {error, atom()}:
                  An error occurred when opening the file or reading it. For a  list  of  typical
                  error codes, see open/2.

                {error, {Line, Mod, Term}}:
                  An  error  occurred  when  interpreting  the Erlang expressions in the file. To
                  convert the three-element tuple to an English description  of  the  error,  use
                  format_error/1.

              The encoding of Filename can be set by a comment, as described in epp(3erl).

       eval(Filename, Bindings) -> ok | {error, Reason}

              Types:

                 Filename = name_all()
                 Bindings = erl_eval:binding_struct()
                 Reason =
                     posix() |
                     badarg | terminated | system_limit |
                     {Line :: integer(), Mod :: module(), Term :: term()}

              The  same as eval/1, but the variable bindings Bindings are used in the evaluation.
              For information about the variable bindings, see erl_eval(3erl).

       format_error(Reason) -> Chars

              Types:

                 Reason =
                     posix() |
                     badarg | terminated | system_limit |
                     {Line :: integer(), Mod :: module(), Term :: term()}
                 Chars = string()

              Given the error  reason  returned  by  any  function  in  this  module,  returns  a
              descriptive string of the error in English.

       get_cwd() -> {ok, Dir} | {error, Reason}

              Types:

                 Dir = filename()
                 Reason = posix()

              Returns {ok, Dir}, where Dir is the current working directory of the file server.

          Note:
              In  rare  circumstances,  this  function  can  fail  on  Unix. It can occur if read
              permission does not exist for the parent directories of the current directory.

              A typical error reason:

                eacces:
                  Missing read permission for one of the parents of the current directory.

       get_cwd(Drive) -> {ok, Dir} | {error, Reason}

              Types:

                 Drive = string()
                 Dir = filename()
                 Reason = posix() | badarg

              Returns {ok, Dir} or {error, Reason}, where Dir is the current working directory of
              the specified drive.

              Drive is to be of the form "Letter:", for example, "c:".

              Returns  {error, enotsup} on platforms that have no concept of current drive (Unix,
              for example).

              Typical error reasons:

                enotsup:
                  The operating system has no concept of drives.

                eacces:
                  The drive does not exist.

                einval:
                  The format of Drive is invalid.

       list_dir(Dir) -> {ok, Filenames} | {error, Reason}

              Types:

                 Dir = name_all()
                 Filenames = [filename()]
                 Reason =
                     posix() |
                     badarg |
                     {no_translation, Filename :: unicode:latin1_binary()}

              Lists all files in a directory, except  files  with  raw  filenames.  Returns  {ok,
              Filenames}  if  successful,  otherwise  {error, Reason}. Filenames is a list of the
              names of all the files in the directory. The names are not sorted.

              Typical error reasons:

                eacces:
                  Missing search or write permissions for Dir or one of its parent directories.

                enoent:
                  The directory does not exist.

                {no_translation, Filename}:
                  Filename is a binary() with characters coded in ISO  Latin-1  and  the  VM  was
                  started with parameter +fnue.

       list_dir_all(Dir) -> {ok, Filenames} | {error, Reason}

              Types:

                 Dir = name_all()
                 Filenames = [filename_all()]
                 Reason = posix() | badarg

              Lists  all  the  files  in a directory, including files with raw filenames. Returns
              {ok, Filenames} if successful, otherwise {error, Reason}. Filenames is  a  list  of
              the names of all the files in the directory. The names are not sorted.

              Typical error reasons:

                eacces:
                  Missing search or write permissions for Dir or one of its parent directories.

                enoent:
                  The directory does not exist.

       make_dir(Dir) -> ok | {error, Reason}

              Types:

                 Dir = name_all()
                 Reason = posix() | badarg

              Tries  to create directory Dir. Missing parent directories are not created. Returns
              ok if successful.

              Typical error reasons:

                eacces:
                  Missing search or write permissions for the parent directories of Dir.

                eexist:
                  A file or directory named Dir exists already.

                enoent:
                  A component of Dir does not exist.

                enospc:
                  No space is left on the device.

                enotdir:
                  A component of Dir is not a directory. On some platforms,  enoent  is  returned
                  instead.

       make_link(Existing, New) -> ok | {error, Reason}

              Types:

                 Existing = New = name_all()
                 Reason = posix() | badarg

              Makes  a  hard  link  from  Existing to New on platforms supporting links (Unix and
              Windows). This function returns ok if the link was successfully created,  otherwise
              {error, Reason}. On platforms not supporting links, {error,enotsup} is returned.

              Typical error reasons:

                eacces:
                  Missing  read  or  write  permissions for the parent directories of Existing or
                  New.

                eexist:
                  New already exists.

                enotsup:
                  Hard links are not supported on this platform.

       make_symlink(Existing, New) -> ok | {error, Reason}

              Types:

                 Existing = New = name_all()
                 Reason = posix() | badarg

              Creates a symbolic link  New  to  the  file  or  directory  Existing  on  platforms
              supporting  symbolic  links  (most Unix systems and Windows, beginning with Vista).
              Existing does not need to exist. Returns ok if the link  is  successfully  created,
              otherwise  {error,  Reason}.  On  platforms  not supporting symbolic links, {error,
              enotsup} is returned.

              Typical error reasons:

                eacces:
                  Missing read or write permissions for the parent  directories  of  Existing  or
                  New.

                eexist:
                  New already exists.

                enotsup:
                  Symbolic links are not supported on this platform.

                eperm:
                  User     does    not    have    privileges    to    create    symbolic    links
                  (SeCreateSymbolicLinkPrivilege on Windows).

       native_name_encoding() -> latin1 | utf8

              Returns the filename encoding mode. If it  is  latin1,  the  system  translates  no
              filenames.  If  it  is  utf8,  filenames are converted back and forth to the native
              filename encoding (usually UTF-8, but UTF-16 on Windows).

       open(File, Modes) -> {ok, IoDevice} | {error, Reason}

              Types:

                 File = Filename | iodata()
                 Filename = name_all()
                 Modes = [mode() | ram]
                 IoDevice = io_device()
                 Reason = posix() | badarg | system_limit

              Opens file File in the mode determined by Modes, which can contain one or  more  of
              the following options:

                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
                  exists and write is not combined with read, the file is truncated.

                append:
                  The file is opened for writing. It is created if it does not exist. Every write
                  operation to a file opened with append takes place at the end of the file.

                exclusive:
                  The file is opened for writing. It is created if it does not exist. If the file
                  exists, {error, eexist} is returned.

            Warning:
                This option does not guarantee  exclusiveness  on  file  systems  not  supporting
                O_EXCL  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).

                raw:
                  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 io module cannot be used, as they can only talk to an
                    Erlang process. Instead, use functions read/2, read_line/1, and write/2.

                  * Especially if read_line/1 is to be used on a raw file, it is  recommended  to
                    combine  this  option  with option {read_ahead, Size} as line-oriented I/O is
                    inefficient without buffering.

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

                  * A 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).

                binary:
                  Read operations on the file return binaries rather than lists.

                {delayed_write, Size, Delay}:
                  Data in subsequent write/2 calls is buffered until  at  least  Size  bytes  are
                  buffered, or until the oldest buffered data is Delay 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 write/2 is executed.

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

                  When  this  option  is  used,  the  result  of write/2 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  delayed_write  is  used,  after a number of write/2 calls,
                  close/1 can return {error, enospc}, as there is not enough space  on  the  disc
                  for previously written data. close/1 must probably be called again, as the file
                  is still open.

                delayed_write:
                  The same as {delayed_write, Size, Delay} with  reasonable  default  values  for
                  Size and Delay (roughly some 64 KB, 2 seconds).

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

                  The  read_ahead buffer is also highly used by function read_line/1 in raw mode,
                  therefore this option is recommended (for performance reasons)  when  accessing
                  raw files using that function.

                  If read/2 calls are for sizes not significantly less than, or even greater than
                  Size bytes, no performance gain can be expected.

                read_ahead:
                  The same as {read_ahead,  Size}  with  a  reasonable  default  value  for  Size
                  (roughly some 64 KB).

                compressed:
                  Makes  it  possible  to  read or write gzip compressed files. Option compressed
                  must be combined with read or write, but not both. Notice that  the  file  size
                  obtained with read_file_info/1 does probably not match the number of bytes that
                  can be read from a compressed file.

                {encoding, Encoding}:
                  Makes the file perform automatic  translation  of  characters  to  and  from  a
                  specific  (Unicode)  encoding.  Notice  that  the  data  supplied to write/2 or
                  returned by read/2 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 latin1 implies using this module (file)  for
                  reading  and  writing  data  as  the  interfaces  provided here work with byte-
                  oriented data. Using other (Unicode) encodings  makes  the  io(3erl)  functions
                  get_chars,  get_line,  and  put_chars  more suitable, as they can work with the
                  full Unicode range.

                  If data is sent to an io_device() 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 Encoding:

                  latin1:
                    The  default  encoding.  Bytes  supplied  to  the  file, that is, write/2 are
                    written "as is" on the file. Likewise, bytes read from  the  file,  that  is,
                    read/2 are returned "as is". If module io(3erl) is used for writing, the file
                    can only cope with Unicode characters up to code point 255 (the  ISO  Latin-1
                    range).

                  unicode or utf8:
                    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  read/2,  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 io(3erl).

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

                  utf16 or {utf16,big}:
                    Works  like  unicode,  but  translation is done to and from big endian UTF-16
                    instead of UTF-8.

                  {utf16,little}:
                    Works like unicode, but translation is done to and from little endian  UTF-16
                    instead of UTF-8.

                  utf32 or {utf32,big}:
                    Works  like  unicode,  but  translation is done to and from big endian UTF-32
                    instead of UTF-8.

                  {utf32,little}:
                    Works like unicode, 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
                  io:setopts/2. 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 unicode(3erl).

                  This option is not allowed on raw files.

                ram:
                  File must be iodata(). Returns an fd(), which lets module file operate  on  the
                  data in-memory as if it is a file.

                sync:
                  On  platforms  supporting  it, enables the POSIX O_SYNC synchronous I/O flag or
                  its platform-dependent  equivalent  (for  example,  FILE_FLAG_WRITE_THROUGH  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 O_SYNC or equivalent, use of the sync  flag  causes  open  to  return
                  {error, enotsup}.

              Returns:

                {ok, IoDevice}:
                  The file is opened in the requested mode. IoDevice is a reference to the file.

                {error, Reason}:
                  The file cannot be opened.

              IoDevice  is  really  the pid of the process that handles the file. This process is
              linked to the process that originally opened the file. If any process to which  the
              IoDevice  is  linked  terminates,  the  file  is  closed  and the process itself is
              terminated. An IoDevice returned from this call can be used as an argument  to  the
              I/O functions (see io(3erl)).

          Note:
              In previous versions of file, modes were specified as one of the atoms read, write,
              or read_write 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 read_write is not
              allowed in a mode list.

              Typical error reasons:

                enoent:
                  The file does not exist.

                eacces:
                  Missing permission for  reading  the  file  or  searching  one  of  the  parent
                  directories.

                eisdir:
                  The named file is a directory.

                enotdir:
                  A  component  of  the filename is not a directory. On some platforms, enoent is
                  returned instead.

                enospc:
                  There is no space left on the device (if write access was specified).

       path_consult(Path, Filename) ->
                       {ok, Terms, FullName} | {error, Reason}

              Types:

                 Path = [Dir]
                 Dir = Filename = name_all()
                 Terms = [term()]
                 FullName = filename_all()
                 Reason =
                     posix() |
                     badarg | terminated | system_limit |
                     {Line :: integer(), Mod :: module(), Term :: term()}

              Searches the path Path (a list of directory  names)  until  the  file  Filename  is
              found.  If  Filename  is  an  absolute filename, Path is ignored. Then reads Erlang
              terms, separated by '.', from the file.

              Returns one of the following:

                {ok, Terms, FullName}:
                  The file is successfully read. FullName is the full name of the file.

                {error, enoent}:
                  The file cannot be found in any of the directories in Path.

                {error, atom()}:
                  An error occurred when opening the file or reading it. For a  list  of  typical
                  error codes, see open/2.

                {error, {Line, Mod, Term}}:
                  An  error  occurred  when  interpreting  the  Erlang  terms  in  the  file. Use
                  format_error/1 to convert the three-element tuple to an English description  of
                  the error.

              The encoding of Filename can be set by a comment as described in epp(3erl).

       path_eval(Path, Filename) -> {ok, FullName} | {error, Reason}

              Types:

                 Path = [Dir :: name_all()]
                 Filename = name_all()
                 FullName = filename_all()
                 Reason =
                     posix() |
                     badarg | terminated | system_limit |
                     {Line :: integer(), Mod :: module(), Term :: term()}

              Searches  the  path  Path  (a  list  of directory names) until the file Filename is
              found. If Filename is an  absolute  filename,  Path  is  ignored.  Then  reads  and
              evaluates  Erlang  expressions, separated by '.' (or ',', a sequence of expressions
              is also an expression), from the file. The result of evaluation  is  not  returned;
              any expression sequence in the file must be there for its side effect.

              Returns one of the following:

                {ok, FullName}:
                  The file is read and evaluated. FullName is the full name of the file.

                {error, enoent}:
                  The file cannot be found in any of the directories in Path.

                {error, atom()}:
                  An  error  occurred  when opening the file or reading it. For a list of typical
                  error codes, see open/2.

                {error, {Line, Mod, Term}}:
                  An error occurred when interpreting the Erlang expressions  in  the  file.  Use
                  format_error/1  to convert the three-element tuple to an English description of
                  the error.

              The encoding of Filename can be set by a comment as described in epp(3erl).

       path_open(Path, Filename, Modes) ->
                    {ok, IoDevice, FullName} | {error, Reason}

              Types:

                 Path = [Dir :: name_all()]
                 Filename = name_all()
                 Modes = [mode()]
                 IoDevice = io_device()
                 FullName = filename_all()
                 Reason = posix() | badarg | system_limit

              Searches the path Path (a list of directory  names)  until  the  file  Filename  is
              found. If Filename is an absolute filename, Path is ignored. Then opens the file in
              the mode determined by Modes.

              Returns one of the following:

                {ok, IoDevice, FullName}:
                  The file is opened in the requested mode. IoDevice is a reference to  the  file
                  and FullName is the full name of the file.

                {error, enoent}:
                  The file cannot be found in any of the directories in Path.

                {error, atom()}:
                  The file cannot be opened.

       path_script(Path, Filename) ->
                      {ok, Value, FullName} | {error, Reason}

              Types:

                 Path = [Dir :: name_all()]
                 Filename = name_all()
                 Value = term()
                 FullName = filename_all()
                 Reason =
                     posix() |
                     badarg | terminated | system_limit |
                     {Line :: integer(), Mod :: module(), Term :: term()}

              Searches  the  path  Path  (a  list  of directory names) until the file Filename is
              found. If Filename is an  absolute  filename,  Path  is  ignored.  Then  reads  and
              evaluates  Erlang  expressions, separated by '.' (or ',', a sequence of expressions
              is also an expression), from the file.

              Returns one of the following:

                {ok, Value, FullName}:
                  The file is read and evaluated. FullName is the full name of the file and Value
                  the value of the last expression.

                {error, enoent}:
                  The file cannot be found in any of the directories in Path.

                {error, atom()}:
                  An  error  occurred  when opening the file or reading it. For a list of typical
                  error codes, see open/2.

                {error, {Line, Mod, Term}}:
                  An error occurred when interpreting the Erlang expressions  in  the  file.  Use
                  format_error/1  to convert the three-element tuple to an English description of
                  the error.

              The encoding of Filename can be set by a comment as described in epp(3erl).

       path_script(Path, Filename, Bindings) ->
                      {ok, Value, FullName} | {error, Reason}

              Types:

                 Path = [Dir :: name_all()]
                 Filename = name_all()
                 Bindings = erl_eval:binding_struct()
                 Value = term()
                 FullName = filename_all()
                 Reason =
                     posix() |
                     badarg | terminated | system_limit |
                     {Line :: integer(), Mod :: module(), Term :: term()}

              The same as path_script/2 but the  variable  bindings  Bindings  are  used  in  the
              evaluation. See erl_eval(3erl) about variable bindings.

       pid2name(Pid) -> {ok, Filename} | undefined

              Types:

                 Filename = filename_all()
                 Pid = pid()

              If Pid is an I/O device, that is, a pid returned from open/2, this function returns
              the filename, or rather:

                {ok, Filename}:
                  If the file server of this node is not a slave, the file was opened by the file
                  server of this node (this implies that Pid must be a local pid) and the file is
                  not closed. Filename is the filename in flat string format.

                undefined:
                  In all other cases.

          Warning:
              This function is intended for debugging only.

       position(IoDevice, Location) ->
                   {ok, NewPosition} | {error, Reason}

              Types:

                 IoDevice = io_device()
                 Location = location()
                 NewPosition = integer()
                 Reason = posix() | badarg | terminated

              Sets the position of the file referenced by  IoDevice  to  Location.  Returns  {ok,
              NewPosition}  (as  absolute  offset)  if  successful,  otherwise  {error,  Reason}.
              Location is one of the following:

                Offset:
                  The same as {bof, Offset}.

                {bof, Offset}:
                  Absolute offset.

                {cur, Offset}:
                  Offset from the current position.

                {eof, Offset}:
                  Offset from the end of file.

                bof | cur | eof:
                  The same as above with Offset 0.

              Notice that offsets are counted in bytes, not in characters. If the file is  opened
              using  some  other  encoding  than  latin1,  one  byte  does  not correspond to one
              character. Positioning in  such  a  file  can  only  be  done  to  known  character
              boundaries. That is, to a position earlier retrieved by getting a current position,
              to the beginning/end of the file or to some other position known to be on a correct
              character  boundary  by some other means (typically beyond a byte order mark in the
              file, which has a known byte-size).

              A typical error reason is:

                einval:
                  Either Location is illegal, or it is evaluated to  a  negative  offset  in  the
                  file.  Notice that if the resulting position is a negative value, the result is
                  an error, and after the call the file position is undefined.

       pread(IoDevice, LocNums) -> {ok, DataL} | eof | {error, Reason}

              Types:

                 IoDevice = io_device()
                 LocNums =
                     [{Location :: location(), Number :: integer() >= 0}]
                 DataL = [Data]
                 Data = string() | binary() | eof
                 Reason = posix() | badarg | terminated

              Performs a sequence of pread/3 in one  operation,  which  is  more  efficient  than
              calling  them  one  at  a time. Returns {ok, [Data, ...]} or {error, Reason}, where
              each Data, the result of the corresponding pread, is either  a  list  or  a  binary
              depending  on  the mode of the file, or eof if the requested position is beyond end
              of file.

              As the position is specified as a byte-offset, take special  caution  when  working
              with  files  where encoding is set to something else than latin1, as not every byte
              position is a valid character boundary on such a file.

       pread(IoDevice, Location, Number) ->
                {ok, Data} | eof | {error, Reason}

              Types:

                 IoDevice = io_device()
                 Location = location()
                 Number = integer() >= 0
                 Data = string() | binary()
                 Reason = posix() | badarg | terminated

              Combines position/2 and read/2 in one  operation,  which  is  more  efficient  than
              calling  them  one  at a time. If IoDevice is opened in raw mode, some restrictions
              apply:

                * Location is only allowed to be an integer.

                * The current position of the file is undefined after the operation.

              As the position is specified as a byte-offset, take special  caution  when  working
              with  files  where encoding is set to something else than latin1, as not every byte
              position is a valid character boundary on such a file.

       pwrite(IoDevice, LocBytes) -> ok | {error, {N, Reason}}

              Types:

                 IoDevice = io_device()
                 LocBytes = [{Location :: location(), Bytes :: iodata()}]
                 N = integer() >= 0
                 Reason = posix() | badarg | terminated

              Performs a sequence of pwrite/3 in one operation,  which  is  more  efficient  than
              calling  them  one  at  a  time. Returns ok or {error, {N, Reason}}, where N is the
              number of successful writes done before the failure.

              When positioning in a file with other encoding than latin1, caution must  be  taken
              to set the position on a correct character boundary. For details, see position/2.

       pwrite(IoDevice, Location, Bytes) -> ok | {error, Reason}

              Types:

                 IoDevice = io_device()
                 Location = location()
                 Bytes = iodata()
                 Reason = posix() | badarg | terminated

              Combines  position/2  and  write/2  in  one operation, which is more efficient than
              calling them one at a  time.  If  IoDevice  has  been  opened  in  raw  mode,  some
              restrictions apply:

                * Location is only allowed to be an integer.

                * The current position of the file is undefined after the operation.

              When  positioning  in a file with other encoding than latin1, caution must be taken
              to set the position on a correct character boundary. For details, see position/2.

       read(IoDevice, Number) -> {ok, Data} | eof | {error, Reason}

              Types:

                 IoDevice = io_device() | atom()
                 Number = integer() >= 0
                 Data = string() | binary()
                 Reason =
                     posix() |
                     badarg | terminated |
                     {no_translation, unicode, latin1}

              Reads Number bytes/characters from the file referenced by IoDevice.  The  functions
              read/2,  pread/3,  and  read_line/1 are the only ways to read from a file opened in
              raw mode (although they work for normally opened files, too).

              For files where encoding is set to something else than latin1, one character can be
              represented  by more than one byte on the file. The parameter Number always denotes
              the number of characters read from the file, while the position in the file can  be
              moved much more than this number when reading a Unicode file.

              Also,  if  encoding  is set to something else than latin1, the read/3 call fails if
              the data contains characters larger than 255, which is why module io(3erl) is to be
              preferred when reading such a file.

              The function returns:

                {ok, Data}:
                  If the file was opened in binary mode, the read bytes are returned in a binary,
                  otherwise in a list. The list or binary is shorter than  the  number  of  bytes
                  requested if end of file was reached.

                eof:
                  Returned  if  Number>0 and end of file was reached before anything at all could
                  be read.

                {error, Reason}:
                  An error occurred.

              Typical error reasons:

                ebadf:
                  The file is not opened for reading.

                {no_translation, unicode, latin1}:
                  The file is opened with another encoding than latin1 and the data in  the  file
                  cannot be translated to the byte-oriented data that this function returns.

       read_file(Filename) -> {ok, Binary} | {error, Reason}

              Types:

                 Filename = name_all()
                 Binary = binary()
                 Reason = posix() | badarg | terminated | system_limit

              Returns  {ok,  Binary},  where  Binary  is  a  binary data object that contains the
              contents of Filename, 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 filename is not a directory. On some platforms, enoent is
                  returned instead.

                enomem:
                  There is not enough memory for the contents of the file.

       read_file_info(Filename) -> {ok, FileInfo} | {error, Reason}

       read_file_info(Filename, Opts) -> {ok, FileInfo} | {error, Reason}

              Types:

                 Filename = name_all()
                 Opts = [file_info_option()]
                 FileInfo = file_info()
                 Reason = posix() | badarg

              Retrieves information about a file. Returns {ok, FileInfo} if successful, otherwise
              {error, Reason}. FileInfo is a record file_info, defined in the Kernel include file
              file.hrl. Include the following directive in the module from which the function  is
              called:

               -include_lib("kernel/include/file.hrl").

              The time type returned in atime, mtime, and ctime is dependent on the time type set
              in Opts :: {time, Type} as follows:

                local:
                  Returns local time.

                universal:
                  Returns universal time.

                posix:
                  Returns seconds since or before Unix time epoch, which is 1970-01-01 00:00 UTC.

              Default is {time, local}.

              If the option raw is set, the file server is not called and only information  about
              local  files  is  returned.  Note  that  this  will  break  this module's atomicity
              guarantees as it can race with a concurrent call to write_file_info/1,2

          Note:
              As file times are stored in POSIX time on most OS,  it  is  faster  to  query  file
              information with option posix.

              The record file_info contains the following fields:

                size = integer() >= 0:
                  Size of file in bytes.

                type = device | directory | other | regular | symlink:
                  The type of the file.

                access = read | write | read_write | none:
                  The current system access to the file.

                atime = date_time() | integer() >= 0:
                  The last time the file was read.

                mtime = date_time() | integer() >= 0:
                  The last time the file was written.

                ctime = date_time() | integer() >=0:
                  The interpretation of this time field depends on the operating system. On Unix,
                  it is the last time the file or the inode was changed. In Windows,  it  is  the
                  create time.

                mode = integer() >= 0:
                  The file permissions as the sum of the following bit values:

                  8#00400:
                    read permission: owner

                  8#00200:
                    write permission: owner

                  8#00100:
                    execute permission: owner

                  8#00040:
                    read permission: group

                  8#00020:
                    write permission: group

                  8#00010:
                    execute permission: group

                  8#00004:
                    read permission: other

                  8#00002:
                    write permission: other

                  8#00001:
                    execute permission: other

                  16#800:
                    set user id on execution

                  16#400:
                    set group id on execution

                  On Unix platforms, other bits than those listed above may be set.

                links = integer() >= 0:
                  Number  of  links  to  the file (this is always 1 for file systems that have no
                  concept of links).

                major_device = integer() >= 0:
                  Identifies the file system where the file is located. In  Windows,  the  number
                  indicates a drive as follows: 0 means A:, 1 means B:, and so on.

                minor_device = integer() >= 0:
                  Only  valid  for  character  devices on Unix. In all other cases, this field is
                  zero.

                inode = integer() >= 0:
                  Gives the inode number. On non-Unix file systems, this field is zero.

                uid = integer() >= 0:
                  Indicates the owner of the file. On non-Unix file systems, this field is zero.

                gid = integer() >= 0:
                  Gives the group that the owner  of  the  file  belongs  to.  On  non-Unix  file
                  systems, this field is zero.

              Typical error reasons:

                eacces:
                  Missing search permission for one of the parent directories of the file.

                enoent:
                  The file does not exist.

                enotdir:
                  A  component  of  the filename is not a directory. On some platforms, enoent is
                  returned instead.

       read_line(IoDevice) -> {ok, Data} | eof | {error, Reason}

              Types:

                 IoDevice = io_device() | atom()
                 Data = string() | binary()
                 Reason =
                     posix() |
                     badarg | terminated |
                     {no_translation, unicode, latin1}

              Reads a line of bytes/characters from the file referenced by  IoDevice.  Lines  are
              defined to be delimited by the linefeed (LF, \n) character, but any carriage return
              (CR, \r) followed by a newline is also  treated  as  a  single  LF  character  (the
              carriage  return  is  silently ignored). The line is returned including the LF, but
              excluding any CR immediately followed by an LF. This behaviour is  consistent  with
              the behaviour of io:get_line/2. If end of file is reached without any LF ending the
              last line, a line with no trailing LF is returned.

              The function can be used on files opened in raw mode. However, it is inefficient to
              use  it  on  raw  files  if  the  file is not opened with option {read_ahead, Size}
              specified. Thus, combining raw and {read_ahead, Size} is  highly  recommended  when
              opening a text file for raw line-oriented reading.

              If encoding is set to something else than latin1, the read_line/1 call fails if the
              data contains characters larger than 255, why module io(3erl) is  to  be  preferred
              when reading such a file.

              The function returns:

                {ok, Data}:
                  One  line  from  the file is returned, including the trailing LF, but with CRLF
                  sequences replaced by a single LF (see above).

                  If the file is opened in binary mode, the read bytes are returned in a  binary,
                  otherwise in a list.

                eof:
                  Returned if end of file was reached before anything at all could be read.

                {error, Reason}:
                  An error occurred.

              Typical error reasons:

                ebadf:
                  The file is not opened for reading.

                {no_translation, unicode, latin1}:
                  The  file  is opened with another encoding than latin1 and the data on the file
                  cannot be translated to the byte-oriented data that this function returns.

       read_link(Name) -> {ok, Filename} | {error, Reason}

              Types:

                 Name = name_all()
                 Filename = filename()
                 Reason = posix() | badarg

              Returns {ok, Filename} if Name refers  to  a  symbolic  link  that  is  not  a  raw
              filename,  or  {error, Reason} otherwise. On platforms that do not support symbolic
              links, the return value is {error,enotsup}.

              Typical error reasons:

                einval:
                  Name does not refer to a symbolic link or the name of the file that  it  refers
                  to does not conform to the expected encoding.

                enoent:
                  The file does not exist.

                enotsup:
                  Symbolic links are not supported on this platform.

       read_link_all(Name) -> {ok, Filename} | {error, Reason}

              Types:

                 Name = name_all()
                 Filename = filename_all()
                 Reason = posix() | badarg

              Returns  {ok,  Filename}  if  Name  refers  to  a  symbolic link or {error, Reason}
              otherwise. On platforms that do not support symbolic links,  the  return  value  is
              {error,enotsup}.

              Notice that Filename can be either a list or a binary.

              Typical error reasons:

                einval:
                  Name does not refer to a symbolic link.

                enoent:
                  The file does not exist.

                enotsup:
                  Symbolic links are not supported on this platform.

       read_link_info(Name) -> {ok, FileInfo} | {error, Reason}

       read_link_info(Name, Opts) -> {ok, FileInfo} | {error, Reason}

              Types:

                 Name = name_all()
                 Opts = [file_info_option()]
                 FileInfo = file_info()
                 Reason = posix() | badarg

              Works  like  read_file_info/1,2 except that if Name is a symbolic link, information
              about the link is returned in the file_info record and the type field of the record
              is set to symlink.

              If  the option raw is set, the file server is not called and only information about
              local files is  returned.  Note  that  this  will  break  this  module's  atomicity
              guarantees as it can race with a concurrent call to write_file_info/1,2

              If  Name  is  not  a  symbolic  link,  this  function  returns  the  same result as
              read_file_info/1. On platforms that do not support symbolic links, this function is
              always equivalent to read_file_info/1.

       rename(Source, Destination) -> ok | {error, Reason}

              Types:

                 Source = Destination = name_all()
                 Reason = posix() | badarg

              Tries  to  rename the file Source to Destination. It can be used to move files (and
              directories)  between  directories,  but  it  is  not  sufficient  to  specify  the
              destination  only. The destination filename must also be specified. For example, if
              bar is a normal file and foo and  baz  are  directories,  rename("foo/bar",  "baz")
              returns  an  error,  but rename("foo/bar", "baz/bar") succeeds. Returns ok if it is
              successful.

          Note:
              Renaming of open files is not allowed on most platforms (see eacces below).

              Typical error reasons:

                eacces:
                  Missing read or write permissions for  the  parent  directories  of  Source  or
                  Destination.  On  some  platforms,  this  error  is  given  if either Source or
                  Destination is open.

                eexist:
                  Destination is not an empty directory.  On  some  platforms,  also  given  when
                  Source and Destination are not of the same type.

                einval:
                  Source is a root directory, or Destination is a subdirectory of Source.

                eisdir:
                  Destination is a directory, but Source is not.

                enoent:
                  Source does not exist.

                enotdir:
                  Source is a directory, but Destination is not.

                exdev:
                  Source and Destination are on different file systems.

       script(Filename) -> {ok, Value} | {error, Reason}

              Types:

                 Filename = name_all()
                 Value = term()
                 Reason =
                     posix() |
                     badarg | terminated | system_limit |
                     {Line :: integer(), Mod :: module(), Term :: term()}

              Reads  and  evaluates  Erlang  expressions, separated by '.' (or ',', a sequence of
              expressions is also an expression), from the file.

              Returns one of the following:

                {ok, Value}:
                  The file is read and evaluated. Value is the value of the last expression.

                {error, atom()}:
                  An error occurred when opening the file or reading it. For a  list  of  typical
                  error codes, see open/2.

                {error, {Line, Mod, Term}}:
                  An  error  occurred  when  interpreting the Erlang expressions in the file. Use
                  format_error/1 to convert the three-element tuple to an English description  of
                  the error.

              The encoding of Filename can be set by a comment as described in epp(3erl).

       script(Filename, Bindings) -> {ok, Value} | {error, Reason}

              Types:

                 Filename = name_all()
                 Bindings = erl_eval:binding_struct()
                 Value = term()
                 Reason =
                     posix() |
                     badarg | terminated | system_limit |
                     {Line :: integer(), Mod :: module(), Term :: term()}

              The same as script/1 but the variable bindings Bindings are used in the evaluation.
              See erl_eval(3erl) about variable bindings.

       sendfile(Filename, Socket) ->
                   {ok, integer() >= 0} |
                   {error, inet:posix() | closed | badarg | not_owner}

              Types:

                 Filename = name_all()
                 Socket = inet:socket()

              Sends the file Filename to Socket. Returns {ok, BytesSent} if successful, otherwise
              {error, Reason}.

       sendfile(RawFile, Socket, Offset, Bytes, Opts) ->
                   {ok, integer() >= 0} |
                   {error, inet:posix() | closed | badarg | not_owner}

              Types:

                 RawFile = fd()
                 Socket = inet:socket()
                 Offset = Bytes = integer() >= 0
                 Opts = [sendfile_option()]
                 sendfile_option() =
                     {chunk_size, integer() >= 0} | {use_threads, boolean()}

              Sends  Bytes  from  the  file  referenced by RawFile beginning at Offset to Socket.
              Returns {ok, BytesSent} if successful, otherwise {error, Reason}. If Bytes  is  set
              to 0 all data after the specified Offset is sent.

              The  file  used must be opened using the raw flag, and the process calling sendfile
              must be the controlling process of the socket. See gen_tcp:controlling_process/2.

              If the OS used does not support non-blocking sendfile,  an  Erlang  fallback  using
              read/2 and gen_tcp:send/2 is used.

              The option list can contain the following options:

                chunk_size:
                  The chunk size used by the Erlang fallback to send data. If using the fallback,
                  set this to a value that comfortably fits in the systems memory. Default is  20
                  MB.

       set_cwd(Dir) -> ok | {error, Reason}

              Types:

                 Dir = name() | EncodedBinary
                 EncodedBinary = binary()
                 Reason = posix() | badarg | no_translation

              Sets  the  current  working  directory  of  the  file  server to Dir. Returns ok if
              successful.

              The functions in the module file usually treat binaries as raw filenames, that  is,
              they  are  passed  "as is" even when the encoding of the binary does not agree with
              native_name_encoding(). However, this  function  expects  binaries  to  be  encoded
              according to the value returned by native_name_encoding().

              Typical error reasons are:

                enoent:
                  The directory does not exist.

                enotdir:
                  A component of Dir is not a directory. On some platforms, enoent is returned.

                eacces:
                  Missing permission for the directory or one of its parents.

                badarg:
                  Dir has an improper type, such as tuple.

                no_translation:
                  Dir  is a binary() with characters coded in ISO-latin-1 and the VM is operating
                  with unicode filename encoding.

          Warning:
              In a future release, a  bad  type  for  argument  Dir  will  probably  generate  an
              exception.

       sync(IoDevice) -> ok | {error, Reason}

              Types:

                 IoDevice = io_device()
                 Reason = posix() | badarg | terminated

              Ensures  that  any  buffers kept by the operating system (not by the Erlang runtime
              system) are written to disk. On some platforms, this function might have no effect.

              A typical error reason is:

                enospc:
                  Not enough space left to write the file.

       truncate(IoDevice) -> ok | {error, Reason}

              Types:

                 IoDevice = io_device()
                 Reason = posix() | badarg | terminated

              Truncates the file referenced by IoDevice at the current position.  Returns  ok  if
              successful, otherwise {error, Reason}.

       write(IoDevice, Bytes) -> ok | {error, Reason}

              Types:

                 IoDevice = io_device() | atom()
                 Bytes = iodata()
                 Reason = posix() | badarg | terminated

              Writes  Bytes  to the file referenced by IoDevice. This function is the only way to
              write to a file opened in raw mode (although it works  for  normally  opened  files
              too). Returns ok if successful, and {error, Reason} otherwise.

              If  the  file  is opened with encoding set to something else than latin1, each byte
              written can result in many bytes being written to  the  file,  as  the  byte  range
              0..255 can represent anything between one and four bytes depending on value and UTF
              encoding type.

              Typical error reasons:

                ebadf:
                  The file is not opened for writing.

                enospc:
                  No space is left on the device.

       write_file(Filename, Bytes) -> ok | {error, Reason}

              Types:

                 Filename = name_all()
                 Bytes = iodata()
                 Reason = posix() | badarg | terminated | system_limit

              Writes the contents of the iodata term Bytes to file Filename. The file is  created
              if  it does not exist. If it exists, the previous contents are overwritten. Returns
              ok if successful, otherwise {error, Reason}.

              Typical error reasons:

                enoent:
                  A component of the filename does not exist.

                enotdir:
                  A component of the filename is not a directory. On some  platforms,  enoent  is
                  returned instead.

                enospc:
                  No space is 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.

       write_file(Filename, Bytes, Modes) -> ok | {error, Reason}

              Types:

                 Filename = name_all()
                 Bytes = iodata()
                 Modes = [mode()]
                 Reason = posix() | badarg | terminated | system_limit

              Same as write_file/2, but takes a third argument Modes, a list of  possible  modes,
              see  open/2.  The  mode  flags binary and write are implicit, so they are not to be
              used.

       write_file_info(Filename, FileInfo) -> ok | {error, Reason}

       write_file_info(Filename, FileInfo, Opts) -> ok | {error, Reason}

              Types:

                 Filename = name_all()
                 Opts = [file_info_option()]
                 FileInfo = file_info()
                 Reason = posix() | badarg

              Changes file information. Returns ok  if  successful,  otherwise  {error,  Reason}.
              FileInfo  is  a  record  file_info,  defined  in  the Kernel include file file.hrl.
              Include the following directive in the module from which the function is called:

               -include_lib("kernel/include/file.hrl").

              The time type set in atime, mtime, and ctime depends on the time type set  in  Opts
              :: {time, Type} as follows:

                local:
                  Interprets the time set as local.

                universal:
                  Interprets it as universal time.

                posix:
                  Must be seconds since or before Unix time epoch, which is 1970-01-01 00:00 UTC.

              Default is {time, local}.

              If  the option raw is set, the file server is not called and only information about
              local files is returned.

              The following fields are used from the record, if they are specified:

                atime = date_time() | integer() >= 0:
                  The last time the file was read.

                mtime = date_time() | integer() >= 0:
                  The last time the file was written.

                ctime = date_time() | integer() >= 0:
                  On Unix, any value specified for this field is ignored  (the  "ctime"  for  the
                  file  is  set  to the current time). On Windows, this field is the new creation
                  time to set for the file.

                mode = integer() >= 0:
                  The file permissions as the sum of the following bit values:

                  8#00400:
                    Read permission: owner

                  8#00200:
                    Write permission: owner

                  8#00100:
                    Execute permission: owner

                  8#00040:
                    Read permission: group

                  8#00020:
                    Write permission: group

                  8#00010:
                    Execute permission: group

                  8#00004:
                    Read permission: other

                  8#00002:
                    Write permission: other

                  8#00001:
                    Execute permission: other

                  16#800:
                    Set user id on execution

                  16#400:
                    Set group id on execution

                  On Unix platforms, other bits than those listed above may be set.

                uid = integer() >= 0:
                  Indicates the file owner. Ignored for non-Unix file systems.

                gid = integer() >= 0:
                  Gives the group that the file owner  belongs  to.  Ignored  for  non-Unix  file
                  systems.

              Typical error reasons:

                eacces:
                  Missing search permission for one of the parent directories of the file.

                enoent:
                  The file does not exist.

                enotdir:
                  A  component  of  the filename is not a directory. On some platforms, enoent is
                  returned instead.

POSIX ERROR CODES

         * eacces - Permission denied

         * eagain - Resource temporarily unavailable

         * ebadf - Bad file number

         * ebusy - File busy

         * edquot - Disk quota exceeded

         * eexist - File already exists

         * efault - Bad address in system call argument

         * efbig - File too large

         * eintr - Interrupted system call

         * einval - Invalid argument

         * eio - I/O error

         * eisdir - Illegal operation on a directory

         * eloop - Too many levels of symbolic links

         * emfile - Too many open files

         * emlink - Too many links

         * enametoolong - Filename too long

         * enfile - File table overflow

         * enodev - No such device

         * enoent - No such file or directory

         * enomem - Not enough memory

         * enospc - No space left on device

         * enotblk - Block device required

         * enotdir - Not a directory

         * enotsup - Operation not supported

         * enxio - No such device or address

         * eperm - Not owner

         * epipe - Broken pipe

         * erofs - Read-only file system

         * espipe - Invalid seek

         * esrch - No such process

         * estale - Stale remote file handle

         * exdev - Cross-domain link

PERFORMANCE

       For increased performance, raw files are recommended.

       A normal file is really a process so it can be used as an I/O device (see io).  Therefore,
       when data is written to a normal file, the sending of the data to the file process, copies
       all data that are not binaries. Opening the file in binary mode and  writing  binaries  is
       therefore  recommended.  If the file is opened on another node, or if the file server runs
       as slave to the file server of another node, also binaries are copied.

   Note:
       Raw files use the file system of the host machine of the node. For normal files (non-raw),
       the  file  server is used to find the files, and if the node is running its file server as
       slave to the file server of another node, and the other  node  runs  on  some  other  host
       machine, they can have different file systems. However, this is seldom a problem.

       open/2  can  be  given  the options delayed_write and read_ahead to turn on caching, which
       will reduce the number of operating system calls and greatly improve performance for small
       reads  and  writes. However, the overhead won't disappear completely and it's best to keep
       the number of file operations to a minimum. As a contrived example, the following function
       writes 4MB in 2.5 seconds when tested:

       create_file_slow(Name) ->
           {ok, Fd} = file:open(Name, [raw, write, delayed_write, binary]),
           create_file_slow_1(Fd, 4 bsl 20),
           file:close(Fd).

       create_file_slow_1(_Fd, 0) ->
           ok;
       create_file_slow_1(Fd, M) ->
           ok = file:write(Fd, <<0>>),
           create_file_slow_1(Fd, M - 1).

       The  following  functionally  equivalent  code writes 128 bytes per call to write/2 and so
       does the same work in 0.08 seconds, which is roughly 30 times faster:

       create_file(Name) ->
           {ok, Fd} = file:open(Name, [raw, write, delayed_write, binary]),
           create_file_1(Fd, 4 bsl 20),
           file:close(Fd),
           ok.

       create_file_1(_Fd, 0) ->
           ok;
       create_file_1(Fd, M) when M >= 128 ->
           ok = file:write(Fd, <<0:(128)/unit:8>>),
           create_file_1(Fd, M - 128);
       create_file_1(Fd, M) ->
           ok = file:write(Fd, <<0:(M)/unit:8>>),
           create_file_1(Fd, M - 1).

       When writing data it's generally more efficient to write a list of binaries rather than  a
       list  of  integers. It is not needed to flatten a deep list before writing. On Unix hosts,
       scatter output, which writes a set of buffers in one operation, is used when possible.  In
       this  way  write(FD,  [Bin1,  Bin2  |  Bin3])  writes the contents of the binaries without
       copying the data at all, except for perhaps deep down in the operating system kernel.

   Warning:
       If an error occurs when accessing an open file with module io, the  process  handling  the
       file  exits.  The  dead  file process can hang if a process tries to access it later. This
       will be fixed in a future release.

SEE ALSO

       filename(3erl)