Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
file(3erl)		   Erlang Module Definition		    file(3erl)

NAME
       file - File Interface Module

DESCRIPTION
       The module file provides	an interface to	the file system.

       On  operating  systems  with thread support, it is possible to let file
       operations be performed in threads of their own,	allowing other	Erlang
       processes  to  continue executing in parallel with the file operations.
       See the command line flag +A in erl(1).

       With regard to file name	encoding, the Erlang VM	 can  operate  in  two
       modes. The current mode can be queried using the	native_name_encoding/0
       function. It returns either latin1 or utf8.

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

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

       On operating systems with transparent naming (i.e. all Unix systems ex-
       cept MacOS X), the default will be utf8 if the terminal supports	UTF-8,
       otherwise  latin1.  The	default	 may  be overridden using the +fnl (to
       force latin1 mode) or +fnu (to force utf8 mode) when starting erl.

       On operating systems with transparent naming, files could be  inconsis-
       tently named, i.e. some files are encoded in UTF-8 while	others are en-
       coded in	(for example) iso-latin1. To be	able to	 handle	 file  systems
       with  inconsistent naming when running in the utf8 mode,	the concept of
       "raw file names"	has been introduced.

       A raw file name is a file name given as a binary. The  Erlang  VM  will
       perform no translation of a file	name given as a	binary on systems with
       transparent naming.

       When running in the utf8	mode, the file:list_dir/1 and file:read_link/1
       functions  will never return raw	file names. Use	the list_dir_all/1 and
       read_link_all/1 functions to return all file names including  raw  file
       names.

       Also see	Notes about raw	file names.

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

       fd()

	      A	file descriptor	representing a file opened in raw mode.

       filename() = string()

       filename_all() =	string() | binary()

       io_device() = pid() | fd()

	      As returned by file:open/2; pid()	is a process handling I/O-pro-
	      tocols.

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

	      If VM is in Unicode filename mode, string() and char()  are  al-
	      lowed to be > 255.

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

	      If  VM  is in Unicode filename mode, string() and	char() are al-
	      lowed to be > 255. RawFilename is	a filename not subject to Uni-
	      code  translation,  meaning  that	 it can	contain	characters not
	      conforming to the	Unicode	encoding expected from the  filesystem
	      (i.e. non-UTF-8 characters although the VM is started in Unicode
	      filename mode).

       posix() = eacces
	       | eagain
	       | ebadf
	       | ebusy
	       | edquot
	       | eexist
	       | efault
	       | efbig
	       | eintr
	       | einval
	       | eio
	       | eisdir
	       | eloop
	       | emfile
	       | emlink
	       | enametoolong
	       | enfile
	       | enodev
	       | enoent
	       | enomem
	       | enospc
	       | enotblk
	       | enotdir
	       | enotsup
	       | enxio
	       | eperm
	       | epipe
	       | erofs
	       | espipe
	       | esrch
	       | estale
	       | exdev

	      An atom which 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 = undefined | integer() >= 0,
		      type = undefined
			    | device
			    | directory
			    | other
			    | regular
			    | symlink,
		      access = undefined
			      |	read
			      |	write
			      |	read_write
			      |	none,
		      atime = undefined
			     | file:date_time()
			     | integer() >= 0,
		      mtime = undefined
			     | file:date_time()
			     | integer() >= 0,
		      ctime = undefined
			     | file:date_time()
			     | integer() >= 0,
		      mode = undefined | integer() >= 0,
		      links = undefined	| integer() >= 0,
		      major_device = undefined | integer() >= 0,
		      minor_device = undefined | integer() >= 0,
		      inode = undefined	| integer() >= 0,
		      uid = undefined |	integer() >= 0,
		      gid = undefined |	integer() >= 0}

       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}

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  op-
	      erating 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	implement 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	the file  size
	      is updated one must 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,
	      expect for some severe errors such as out	of memory.

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

       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. See
		  open/2 for a list of typical error codes.

		{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.

	      Example:

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

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

	      The encoding of 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 e.g.
	      open/2. ByteCount	defaults to  infinity,	denoting  an  infinite
	      number of	bytes.

	      The  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 actually was copied, which may	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.

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

	      Types:

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

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

	      Typical error reasons are:

		eacces:
		  Missing  search or write permissions for the parent directo-
		  ries 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 the file Filename. Returns ok if successful.

	      Typical error reasons are:

		enoent:
		  The file does	not exist.

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

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

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

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

	  Warning:
	      In  a  future release, a bad type	for the	Filename argument 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 actual 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.  See
		  open/2 for a list of typical error codes.

		{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 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. See erl_eval(3erl) about variable bindings.

       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 may
	      happen if	read permission	does not exist for the parent directo-
	      ries of the current directory.

	      Typical error reasons are:

		eacces:
		  Missing  read	 permission for	one of the parents of the cur-
		  rent directory.

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

	      Types:

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

	      Drive should be of the form "Letter:", for example "c:". Returns
	      {ok,  Dir}  or {error, Reason}, where Dir	is the current working
	      directory	of the drive specified.

	      This function returns {error, enotsup} on	platforms  which  have
	      no concept of current drive (Unix, for example).

	      Typical error reasons are:

		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_bi-
		 nary()}

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

	      Typical error reasons are:

		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 the 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"
	      names. Returns {ok, Filenames} if	successful. Otherwise, it  re-
	      turns  {error,  Reason}. Filenames is a list of the names	of all
	      the files	in the directory. The names are	not sorted.

	      Typical error reasons are:

		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	 the directory Dir. Missing parent directories
	      are not created. Returns ok if successful.

	      Typical error reasons are:

		eacces:
		  Missing search or write permissions for the parent  directo-
		  ries of Dir.

		eexist:
		  There	is already a file or directory named Dir.

		enoent:
		  A component of Dir does not exist.

		enospc:
		  There	is a no	space 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  that  sup-
	      port  links  (Unix and Windows). This function returns ok	if the
	      link was successfully created, or	{error,	Reason}. On  platforms
	      that do not support 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

	      This function creates a symbolic link New	to the file or	direc-
	      tory  Existing,  on  platforms that support symbolic links (most
	      Unix systems and Windows beginning with  Vista).	Existing  need
	      not exist. This function returns ok if the link was successfully
	      created, or {error, Reason}. On platforms	that  do  not  support
	      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  (Se-
		  CreateSymbolicLinkPrivilege on Windows).

       native_name_encoding() -> latin1	| utf8

	      This  function  returns  the  file  name encoding	mode. If it is
	      latin1, the system does no translation of	file names. If	it  is
	      utf8,  file names	will be	converted back and forth to the	native
	      file name	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 the	file File in the mode determined by Modes,  which  may
	      contain one or more of the following items:

		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 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}.

	    Warning:
		This option does not guarantee exclusiveness on	 file  systems
		that  do  not support O_EXCL properly, such as NFS. Do not de-
		pend on	this option unless you know that the file system  sup-
		ports it (in general, local file systems should	be safe).

		raw:
		  The  raw  option  allows faster access to a file, because 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, because
		    they can only talk to an Erlang process. Instead, use  the
		    read/2, read_line/1	and write/2 functions.

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

		  * Only the Erlang process which 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:
		  When this option has been given, read	operations on the file
		  will return binaries rather than lists.

		{delayed_write,	Size, Delay}:
		  If this option is used, the data in subsequent write/2 calls
		  is buffered until there are at least Size bytes 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 re-
		  ducing  the number of	operating system calls,	so the write/2
		  calls	should be for sizes significantly less than Size,  and
		  not  interspersed by to many other file operations, for this
		  to happen.

		  When this option is used, the	result of  write/2  calls  may
		  prematurely  be reported as successful, and if a write error
		  should actually occur	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 might return {error, enospc}  because
		  there	 was not enough	space on the disc for previously writ-
		  ten data, and	close/1	should probably	be called again	 since
		  the file is still open.

		delayed_write:
		  The same as {delayed_write, Size, Delay} with	reasonable de-
		  fault	values for Size	and Delay. (Roughly some 64 KBytes,  2
		  seconds)

		{read_ahead, Size}:
		  This	option	activates read data buffering. If read/2 calls
		  are for significantly	less than Size bytes, read  operations
		  towards  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 since the
		  number of operating system calls is reduced.

		  The  read_ahead  buffer  is  also  highly  utilized  by  the
		  read_line/1  function	in raw mode, why this option is	recom-
		  mended (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 KBytes)

		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
		  read_file_info/1  will most 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. Note that the
		  data supplied	to file:write or returned by  file:read	 still
		  is byte oriented, this option	only denotes how data is actu-
		  ally 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 (the file)	module for reading and writing
		  data,	 as  the  interfaces provided here work	with byte-ori-
		  ented	data, while using other	(Unicode) encodings makes  the
		  io(3erl)  module's  get_chars,  get_line and put_chars func-
		  tions	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 will be closed.

		  The allowed values for Encoding are:

		  latin1:
		    The	 default  encoding.  Bytes supplied to i.e. file:write
		    are	written	as is on the file, likewise  bytes  read  from
		    the	 file  are  returned  to  i.e. file:read as is.	If the
		    io(3erl) module is used for	writing,  the  file  can  only
		    cope with Unicode characters up to codepoint 255 (the ISO-
		    latin-1 range).

		  unicode or utf8:
		    Characters are translated to and from the  UTF-8  encoding
		    before  being  written  to	or  read from the file.	A file
		    opened in this way might be	readable using	the  file:read
		    function,  as  long	as no data stored on the file lies be-
		    yond the ISO-latin-1 range (0..255), but failure will  oc-
		    cur	 if  the  data contains	Unicode	codepoints beyond that
		    range. The file is best read with  the  functions  in  the
		    Unicode aware io(3erl) module.

		    Bytes  written  to the file	by any means are translated to
		    UTF-8 encoding before actually 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
		  the io:setopts/2 function, why a file	 can  be  analyzed  in
		  latin1  encoding  for	 i.e. a	BOM, positioned	beyond the BOM
		  and then be set for the right	encoding before	further	 read-
		  ing.See  the	unicode(3erl) module for functions identifying
		  BOM's.

		  This option is not allowed on	raw files.

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

		sync:
		  On  platforms	that support it, enables the POSIX O_SYNC syn-
		  chronous  I/O	 flag  or  its	platform-dependent  equivalent
		  (e.g., FILE_FLAG_WRITE_THROUGH on Windows) so	that writes to
		  the file block until the data	has been physically written to
		  disk.	 Be  aware,  though,  that the exact semantics of this
		  flag differ from platform to platform; for example,  neither
		  Linux	nor Windows guarantees that all	file metadata are also
		  written before the  call  returns.  For  precise  semantics,
		  check	the details of your platform's documentation. On plat-
		  forms	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 has	been opened in the requested mode. IoDevice is
		  a reference to the file.

		{error,	Reason}:
		  The file could not be	opened.

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

	  Note:
	      In  previous  versions  of  file,	modes were given as one	of the
	      atoms read, write, or read_write instead	of  a  list.  This  is
	      still allowed for	reasons	of backwards compatibility, but	should
	      not be used for new code.	Also note that read_write is  not  al-
	      lowed 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 not	a regular file.	It may be a directory,
		  a fifo, or a device.

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

		enospc:
		  There	is a no	space left on the device (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 was successfully read. FullName is the full name of
		  the file.

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

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

		{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 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 file name,
	      Path is ignored. Then reads and  evaluates  Erlang  expressions,
	      separated	 by  '.' (or ',', a sequence of	expressions is also an
	      expression), from	the file. The actual 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 was read and	evaluated. FullName is the  full  name
		  of the file.

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

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

		{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 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 file name,
	      Path is ignored. Then opens the file in the mode	determined  by
	      Modes. Returns one of the	following:

		{ok, IoDevice, FullName}:
		  The  file has	been 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  could  not	 be found in any of the	directories in
		  Path.

		{error,	atom()}:
		  The file could not 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 file name,
	      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 was read and	evaluated. FullName is the  full  name
		  of the file and Value	the value of the last expression.

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

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

		{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 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 bind-
	      ings.

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

	      Types:

		 Filename = filename_all()
		 Pid = pid()

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

		{ok, Filename}:
		  If  this  node's  file  server  is not a slave, the file was
		  opened by this node's	file server, (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	 Loca-
	      tion. Returns {ok, NewPosition} (as absolute offset) if success-
	      ful, otherwise {error, Reason}. Location is one of  the  follow-
	      ing:

		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.

	      Note  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, i.e.	 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).

	      Typical error reasons are:

		einval:
		  Either  Location  was	illegal, or it evaluated to a negative
		  offset in the	file. Note 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  was  be-
	      yond end of file.

	      As  the  position	is given as a byte-offset, special caution has
	      to be taken when working with files where	 encoding  is  set  to
	      something	else than latin1, as not every byte position will be 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 has been
	      opened in	raw mode, some restrictions apply:  Location  is  only
	      allowed  to  be an integer; and the current position of the file
	      is undefined after the operation.

	      As the position is given as a byte-offset, special  caution  has
	      to  be  taken  when  working with	files where encoding is	set to
	      something	else than latin1, as not every byte position will be 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 that
	      was done before the failure.

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

       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; and the current position of the file
	      is undefined after the operation.

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

       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	 IoDe-
	      vice. 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 might be represented by more than one byte on  the
	      file.  The parameter Number always denotes the number of charac-
	      ters read	from the file, why the position	in the file  might  be
	      moved a lot more than this number	when reading a Unicode file.

	      Also  if	encoding  is  set  to  something else than latin1, the
	      read/3 call will fail if the  data  contains  characters	larger
	      than  255, why the io(3erl) module is to be preferred when read-
	      ing 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 bi-
		  nary will be 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 any-
		  thing	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 was opened with another encoding  than  latin1  and
		  the  data in the file	can not	be translated to the byte-ori-
		  ented	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 er-
	      ror occurs.

	      Typical error reasons:

		enoent:
		  The file does	not exist.

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

		eisdir:
		  The named file is a directory.

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

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

       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}. Type	local will re-
	      turn local time, universal will return universal time and	 posix
	      will  return  seconds  since  or before unix time	epoch which is
	      1970-01-01 00:00 UTC. Default is {time, local}.

	  Note:
	      Since file times is stored in posix time on most OS it is	faster
	      to query file information	with the posix option.

	      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 operat-
		  ing system. On Unix, it is the last time the file or the in-
		  ode 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 will always	be 1 for  file
		  systems which	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
		  will be zero.

		uid = integer()	_= 0:
		  Indicates  the  owner	of the file. Will be zero for non-Unix
		  file systems.

		gid = integer()	_= 0:
		  Gives	the group that the owner of the	file belongs to.  Will
		  be zero 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 file name 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 a LF. This  be-
	      haviour  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. It is how-
	      ever inefficient to use it on raw	 files	if  the	 file  is  not
	      opened with the option {read_ahead, Size}	specified, why combin-
	      ing raw and {read_ahead, Size} is	highly recommended when	 open-
	      ing a text file for raw line oriented reading.

	      If   encoding   is  set  to  something  else  than  latin1,  the
	      read_line/1 call will  fail  if  the  data  contains  characters
	      larger than 255, why the io(3erl)	module 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 was 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 was opened with another encoding than latin1 and
		  the  data on the file	can not	be translated to the byte-ori-
		  ented	data that this function	returns.

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

	      Types:

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

	      This function returns {ok, Filename} if Name refers  to  a  sym-
	      bolic  link  that	 is  not a "raw" file name, or {error, Reason}
	      otherwise. On platforms that do not support symbolic links,  the
	      return value will	be {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  en-
		  coding.

		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

	      This  function  returns  {ok, Filename} if Name refers to	a sym-
	      bolic link or {error, Reason} otherwise. On  platforms  that  do
	      not  support  symbolic  links,  the  return  value  will be {er-
	      ror,enotsup}.

	      Note 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

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

	      If  Name	is  not	a symbolic link, this function returns exactly
	      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
	      file  name must also be specified. For example, if bar is	a nor-
	      mal file and foo	and  baz  are  directories,  rename("foo/bar",
	      "baz")  returns  an error, but rename("foo/bar", "baz/bar") suc-
	      ceeds. 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 sub-direc-
		  tory 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 was read and	evaluated. Value is the	value  of  the
		  last expression.

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

		{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 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.

       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 file module usually treat binaries	as raw
	      filenames, i.e. they are passed as is even when the encoding  of
	      the binary does not agree	with file:native_name_encoding(). This
	      function however expects binaries	to be encoded according	to the
	      value returned by	file: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 had 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 file	name encoding.

	  Warning:
	      In a future release, a bad type for the Dir argument will	proba-
	      bly generate an exception.

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

	      Types:

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

	      Makes sure that any buffers kept by the operating	system (not by
	      the  Erlang  runtime  system) are	written	to disk. On some plat-
	      forms, this function might have no effect.

	      Typical error reasons are:

		enospc:
		  Not enough space left	to write the file.

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

	      Types:

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

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

	      Applications that	access databases or log	files  often  write  a
	      tiny  data fragment (e.g., one line in a log file) and then call
	      fsync() immediately in order to ensure that the written data  is
	      physically  stored  on the harddisk. Unfortunately, fsync() will
	      always initiate two write	operations: one	for the	newly  written
	      data  and	 another  one in order 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	unnec-
	      essary 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 implementing
	      the fdatasync syscall.

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

	      Types:

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

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

       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,	other-
	      wise {error, Reason}. If Bytes is	set to 0 all  data  after  the
	      given 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 sendfile,	an Erlang fallback us-
	      ing file:read and	gen_tcp:send 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, this should be set to a value which com-
		  fortably fits	in the systems memory. Default is 20 MB.

		use_threads:
		  Instruct the emulator	to use the async thread	pool  for  the
		  sendfile  system  call.  This	could be usefull if the	OS you
		  are running on does not properly support non-blocking	 send-
		  file	calls.	Do  note  that using async threads potentially
		  makes	your system volnerable to slow client attacks. If  set
		  to  true  and	 no  async threads are available, the sendfile
		  call will return {error,einval}.  Introduced	in  Erlang/OTP
		  17.0.	Default	is false.

       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 success-
	      ful, and {error, Reason} otherwise.

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

	      Typical error reasons are:

		ebadf:
		  The file is not opened for writing.

		enospc:
		  There	is a no	space 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 the  file	 File-
	      name.  The  file	is created if it does not exist. If it exists,
	      the previous contents are	overwritten. Returns  ok,  or  {error,
	      Reason}.

	      Typical error reasons are:

		enoent:
		  A component of the file name does not	exist.

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

		enospc:
		  There	is a no	space left on the device.

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

		eisdir:
		  The named file is a directory.

       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 should not 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

	      Change  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 is dependent on  the
	      time type	set in Opts :: {time, Type}. Type local	will interpret
	      the time set as local, universal will interpret it as  universal
	      time  and	 posix must be seconds since or	before unix time epoch
	      which is 1970-01-01 00:00	UTC. Default is	{time, local}.

	      The following fields are used  from  the	record,	 if  they  are
	      given.

		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 give for this field will be ignored (the
		  "ctime" for the file will be 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  owner	of the file. Ignored for non-Unix file
		  systems.

		gid = integer()	_= 0:
		  Gives	the group that the owner of the	file belongs  to.  Ig-
		  nored	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 file name 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 - IO error

	 * eisdir - illegal operation on a directory

	 * eloop - too many levels of symbolic links

	 * emfile - too	many open files

	 * emlink - too	many links

	 * enametoolong	- file name 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
       Some  operating system file operations, for example a sync/1 or close/1
       on a huge file, may block their calling thread for seconds. If this be-
       falls  the  emulator main thread, the response time is no longer	in the
       order of	milliseconds, depending	on the definition of  "soft"  in  soft
       real-time system.

       If  the	device	driver thread pool is active, file operations are done
       through those threads instead, so the emulator can go on	executing  Er-
       lang  processes.	 Unfortunately,	 the time for serving a	file operation
       increases due to	the extra scheduling required from the operating  sys-
       tem.

       If  the	device driver thread pool is disabled or of size 0, large file
       reads and writes	are segmented into several smaller, which enables  the
       emulator	 so  server  other  processes  during the file operation. This
       gives the same effect as	when using the thread pool,  but  with	larger
       overhead.  Other	 file  operations,  for	example	sync/1 or close/1 on a
       huge file, still	are a problem.

       For increased performance, raw files are	recommended.  Raw  files  uses
       the file	system of the node's host machine. 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 another node's, and	the other node runs on
       some other host machine,	they may have different	file systems. This  is
       seldom a	problem, but you have now been warned.

       A  normal  file	is  really a process so	it can be used as an IO	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  rec-
       ommended.  If the file is opened	on another node, or if the file	server
       runs as slave to	another	node's,	also binaries are copied.

       Caching data to reduce the number of file  operations,  or  rather  the
       number  of  calls  to  the file driver, will generally increase perfor-
       mance. The following function  writes  4	 MBytes	 in  23	 seconds  when
       tested:

       create_file_slow(Name, N) when integer(N), N >= 0 ->
	   {ok,	FD} = file:open(Name, [raw, write, delayed_write, binary]),
	   ok =	create_file_slow(FD, 0,	N),
	   ok =	?FILE_MODULE:close(FD),
	   ok.

       create_file_slow(FD, M, M) ->
	   ok;
       create_file_slow(FD, M, N) ->
	   ok =	file:write(FD, <<M:32/unsigned>>),
	   create_file_slow(FD,	M+1, N).

       The  following, functionally equivalent,	function collects 1024 entries
       into a list of 128 32-byte binaries before each	call  to  file:write/2
       and so does the same work in 0.52 seconds, which	is 44 times faster.

       create_file(Name, N) when integer(N), N >= 0 ->
	   {ok,	FD} = file:open(Name, [raw, write, delayed_write, binary]),
	   ok =	create_file(FD,	0, N),
	   ok =	?FILE_MODULE:close(FD),
	   ok.

       create_file(FD, M, M) ->
	   ok;
       create_file(FD, M, N) when M + 1024 =&lt; N ->
	   create_file(FD, M, M	+ 1024,	[]),
	   create_file(FD, M + 1024, N);
       create_file(FD, M, N) ->
	   create_file(FD, M, N, []).

       create_file(FD, M, M, R)	->
	   ok =	file:write(FD, R);
       create_file(FD, M, N0, R) when M	+ 8 =&lt; N0 ->
	   N1  = N0-1,	N2  = N0-2,  N3	 = N0-3,  N4  =	N0-4,
	   N5  = N0-5,	N6  = N0-6,  N7	 = N0-7,  N8  =	N0-8,
	   create_file(FD, M, N8,
		       [<<N8:32/unsigned,  N7:32/unsigned,
			  N6:32/unsigned,  N5:32/unsigned,
			  N4:32/unsigned,  N3:32/unsigned,
			  N2:32/unsigned,  N1:32/unsigned>> | R]);
       create_file(FD, M, N0, R) ->
	   N1 =	N0-1,
	   create_file(FD, M, N1, [<<N1:32/unsigned>> |	R]).

   Note:
       Trust  only  your  own  benchmarks. If the list length in create_file/2
       above is	increased, it will run slightly	faster,	but consume more  mem-
       ory and cause more memory fragmentation.	How much this affects your ap-
       plication is something that this	simple benchmark can not predict.

       If the size of each binary is increased to 64 bytes, it will  also  run
       slightly	 faster,  but the code will be twice as	clumsy.	In the current
       implementation are binaries larger than 64 bytes	stored in memory  com-
       mon  to all processes and not copied when sent between processes, while
       these smaller binaries are stored on the	process	heap and  copied  when
       sent like any other term.

       So, with	a binary size of 68 bytes create_file/2	runs 30	percent	slower
       then with 64 bytes, and will cause much more memory fragmentation. Note
       that  if	 the binaries were to be sent between processes	(for example a
       non-raw file) the results would probably	be completely different.

       A raw file is really a port. When writing data to a port, it  is	 effi-
       cient  to  write	a list of binaries. There is no	need 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
       file:write(FD, [Bin1, Bin2 | Bin3]) will	write the contents of the  bi-
       naries  without copying the data	at all except for perhaps deep down in
       the operating system kernel.

       For raw files, pwrite/2 and pread/2 are	efficiently  implemented.  The
       file  driver  is	called only once for the whole operation, and the list
       iteration is done in the	file driver.

       The options delayed_write and read_ahead	to file:open/2 makes the  file
       driver  cache  data to reduce the number	of operating system calls. The
       function	create_file/2 in the example above takes  60  seconds  seconds
       without the delayed_write option, which is 2.6 times slower.

       And, as a really	bad example, create_file_slow/2	above without the raw,
       binary and delayed_write	options,  that	is  it	calls  file:open(Name,
       [write]), needs 1 min 20	seconds	for the	job, which is 3.5 times	slower
       than the	first example, and 150 times slower than  the  optimized  cre-
       ate_file/2.

WARNINGS
       If  an error occurs when	accessing an open file with the	io module, the
       process which handles the file will exit. The dead file	process	 might
       hang if a process tries to access it later. This	will be	fixed in a fu-
       ture release.

SEE ALSO
       filename(3erl)

Ericsson AB			 kernel	3.0.3			    file(3erl)

NAME | DESCRIPTION | DATA TYPES | EXPORTS | POSIX ERROR CODES | PERFORMANCE | WARNINGS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=file&sektion=3&manpath=Debian+8.1.0>

home | help