From 5a485461a1157fef1bb3ce8426bfd1ad57b5ca52 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Fri, 6 May 2011 16:01:56 +0200 Subject: Use Erlang specs and types for documentation --- lib/kernel/doc/src/file.xml | 895 +++++++++++++++++--------------------------- 1 file changed, 339 insertions(+), 556 deletions(-) (limited to 'lib/kernel/doc/src/file.xml') diff --git a/lib/kernel/doc/src/file.xml b/lib/kernel/doc/src/file.xml index 36fce464c5..e0feaf6ee7 100644 --- a/lib/kernel/doc/src/file.xml +++ b/lib/kernel/doc/src/file.xml @@ -4,7 +4,7 @@
- 19962010 + 19962011 Ericsson AB. All Rights Reserved. @@ -93,47 +93,76 @@ is UTF-8...

-
- DATA TYPES - -iodata() = iolist() | binary() - iolist() = [char() | binary() | iolist()] - -io_device() - as returned by file:open/2, a process handling IO protocols - -name() = string() | atom() | DeepList | RawFilename - DeepList = [char() | atom() | DeepList] - RawFilename = binary() - If VM is in unicode filename mode, string() and char() 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 - filesystem (i.e. non-UTF-8 characters although the VM is started in Unicode - filename mode). - -posix() - an atom which is named from the POSIX error codes used in - Unix, and in the runtime libraries of most C compilers - -ext_posix() = posix() | badarg + + + + + + + + + + + + + + + + +

As returned by + file:open/2, + a process handling IO protocols.

+ + + + + +

If VM is in Unicode filename mode, string() and char() + 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 filesystem + (i.e. non-UTF-8 characters although the VM is started + in Unicode filename mode). +

+ + + + + +

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

+ + + + + + + + + + + +

Must denote a valid date and time.

+ + + + + + + + + + + + -time() = {{Year, Month, Day}, {Hour, Minute, Second}} - Year = Month = Day = Hour = Minute = Second = int() - Must denote a valid date and time -
- advise(IoDevice, Offset, Length, Advise) -> ok | {error, Reason} + Predeclare an access pattern for file data - - IoDevice = io_device() - Offset = int() - Length = int() - Advise = posix_file_advise() - posix_file_advise() = normal | sequential | random | no_reuse - | will_need | dont_need - Reason = ext_posix() - +

advise/4 can be used to announce an intention to access file data in a specific pattern in the future, thus allowing the @@ -142,93 +171,58 @@ time() = {{Year, Month, Day}, {Hour, Minute, Second}} - change_group(Filename, Gid) -> ok | {error, Reason} + Change group of a file - - Filename = name() - Gid = int() - Reason = ext_posix() -

Changes group of a file. See write_file_info/2.

 - change_mode(Filename, Mode) -> ok | {error, Reason} + Change permissions of a file - - Filename = name() - Mode = int() - Reason = ext_posix() -

Changes permissions of a file. See write_file_info/2.

 - change_owner(Filename, Uid) -> ok | {error, Reason} + Change owner of a file - - Filename = name() - Uid = int() - Reason = ext_posix() -

Changes owner of a file. See write_file_info/2.

 - change_owner(Filename, Uid, Gid) -> ok | {error, Reason} + Change owner and group of a file - - Filename = name() - Uid = int() - Gid = int() - Reason = ext_posix() -

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

 - change_time(Filename, Mtime) -> ok | {error, Reason} + Change the modification time of a file - - Filename = name() - Mtime = time() - Reason = ext_posix() -

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

 - change_time(Filename, Mtime, Atime) -> ok | {error, Reason} + Change the modification and last access time of a file - - Filename = name() - Mtime = Atime = time() - Reason = ext_posix() -

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

 - close(IoDevice) -> ok | {error, Reason} + Close a file - - IoDevice = io_device() - Reason = ext_posix() | terminated - -

Closes the file referenced by IoDevice. It mostly +

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 @@ -238,20 +232,13 @@ time() = {{Year, Month, Day}, {Hour, Minute, Second}} - consult(Filename) -> {ok, Terms} | {error, Reason} + Read Erlang terms from a file - - Filename = name() - Terms = [term()] - Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term} -  Line, Mod, Term -- see below - -

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

+

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

- {ok, Terms} + {ok, Terms}

The file was successfully read.

 @@ -261,7 +248,8 @@ time() = {{Year, Month, Day}, {Hour, Minute, Second}} See open/2 for a list of typical error codes.

- {error, {Line, Mod, Term}} + {error, {Line, Mod, + Term}}

An error occurred when interpreting the Erlang terms in the file. Use format_error/1 to convert @@ -279,53 +267,46 @@ f.txt: {person, "kalle", 25}. - copy(Source, Destination) -> - copy(Source, Destination, ByteCount) -> {ok, BytesCopied} | {error, Reason} + + Copy file contents - - Source = Destination = io_device() | Filename | {Filename, Modes} -  Filename = name() -  Modes = [Mode] -- see open/2 - ByteCount = int() >= 0 | infinity - BytesCopied = int() - -

Copies ByteCount bytes from Source to - Destination. Source and Destination refer +

Copies ByteCount bytes from + Source to Destination. + Source and Destination refer to either filenames or IO devices from e.g. open/2. - ByteCount defaults infinity, denoting an + 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 +

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

-

If both Source and Destination refer 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 +

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 +

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 +

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.

+ 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} + Delete a directory - - Dir = name() - Reason = ext_posix() - -

Tries to delete the directory Dir. The directory must +

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

Typical error reasons are:

@@ -333,7 +314,7 @@ f.txt: {person, "kalle", 25}. eacces

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

+ directories of Dir.

 eexist @@ -345,8 +326,8 @@ f.txt: {person, "kalle", 25}. enotdir -

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

+

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

 einval @@ -357,15 +338,11 @@ f.txt: {person, "kalle", 25}. - delete(Filename) -> ok | {error, Reason} + Delete a file - - Filename = name() - Reason = ext_posix() - -

Tries to delete the file Filename. Returns ok - if successful.

+

Tries to delete the file Filename. + Returns ok if successful.

Typical error reasons are:

enoent @@ -387,30 +364,25 @@ f.txt: {person, "kalle", 25}. einval -

Filename had an improper type, such as tuple.

+

Filename had an improper type, such as tuple.

 -

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

+

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

 - eval(Filename) -> ok | {error, Reason} + Evaluate Erlang expressions in a file - - Filename = name() - Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term} -  Line, Mod, Term -- see below -

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 + 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 @@ -422,7 +394,8 @@ f.txt: {person, "kalle", 25}.

An error occurred when opening the file or reading it. See open/2 for a list of typical error codes.

- {error, {Line, Mod, Term}} + {error, {Line, Mod, + Term}}

An error occurred when interpreting the Erlang expressions in the file. Use format_error/1 to @@ -433,18 +406,11 @@ f.txt: {person, "kalle", 25}. - eval(Filename, Bindings) -> ok | {error, Reason} + Evaluate Erlang expressions in a file - - Filename = name() - Bindings -- see erl_eval(3) - Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term} -  Line, Mod, Term -- see eval/1 -

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

 @@ -458,27 +424,19 @@ f.txt: {person, "kalle", 25}. - format_error(Reason) -> Chars + Return a descriptive string for an error reason - - Reason = atom() | {Line, Mod, Term} -  Line, Mod, Term -- see eval/1 - Chars = [char() | Chars] -

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} + Get the current working directory - - Dir = string() - Reason = posix() - -

Returns {ok, Dir}, where Dir is the current +

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

In rare circumstances, this function can fail on Unix. @@ -496,17 +454,14 @@ f.txt: {person, "kalle", 25}. - get_cwd(Drive) -> {ok, Dir} | {error, Reason} + Get the current working directory for the drive specified - - Drive = string() -- see below - Dir = string() - Reason = ext_posix() - -

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

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

@@ -514,7 +469,7 @@ f.txt: {person, "kalle", 25}. enotsup -

The operating system have no concept of drives.

+

The operating system has no concept of drives.

 eacces @@ -522,32 +477,27 @@ f.txt: {person, "kalle", 25}. einval -

The format of Drive is invalid.

+

The format of Drive is invalid.

 - list_dir(Dir) -> {ok, Filenames} | {error, Reason} + List files in a directory - - Dir = name() - Filenames = [Filename] -  Filename = string() - Reason = ext_posix() -

Lists all the files in a directory. Returns - {ok, Filenames} if successful. Otherwise, it returns - {error, Reason}. Filenames is a list of + {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.

+

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

 enoent @@ -557,14 +507,10 @@ f.txt: {person, "kalle", 25}. - make_dir(Dir) -> ok | {error, Reason} + Make a directory - - Dir = name() - Reason = ext_posix() - -

Tries to create the directory Dir. Missing parent +

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

Typical error reasons are:

@@ -572,15 +518,15 @@ f.txt: {person, "kalle", 25}. eacces

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

+ directories of Dir.

 eexist -

There is already a file or directory named Dir.

+

There is already a file or directory named Dir.

 enoent -

A component of Dir does not exist.

+

A component of Dir does not exist.

 enospc @@ -588,35 +534,33 @@ f.txt: {person, "kalle", 25}. enotdir -

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

+

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

 - make_link(Existing, New) -> ok | {error, Reason} + Make a hard link to a file - - Existing = New = name() - Reason = ext_posix() - -

Makes a hard link from Existing to New, on +

Makes a hard link from Existing to + New, on platforms that support links (Unix). This function returns ok if the link was successfully created, or - {error, Reason}. On platforms that do not support + {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.

+ directories of Existing or + New.

 eexist -

New already exists.

+

New already exists.

 enotsup @@ -626,30 +570,28 @@ f.txt: {person, "kalle", 25}. - make_symlink(Name1, Name2) -> ok | {error, Reason} + Make a symbolic link to a file or directory - - Name1 = Name2 = name() - Reason = ext_posix() - -

This function creates a symbolic link Name2 to - the file or directory Name1, on platforms that support - symbolic links (most Unix systems). Name1 need not +

This function creates a symbolic link Name2 to + the file or directory Name1, on platforms that + support + symbolic links (most Unix systems). Name1 need not exist. This function returns ok if the link was - successfully created, or {error, Reason}. On platforms + 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 Name1 or Name2.

+

Missing read or write permissions for the parent directories + of Name1 or Name2.

 eexist -

Name2 already exists.

+

Name2 already exists.

 enotsup @@ -668,22 +610,12 @@ f.txt: {person, "kalle", 25}. - open(Filename, Modes) -> {ok, IoDevice} | {error, Reason} + Open a file - - Filename = name() - Modes = [Mode] -  Mode = read | write | append | exclusive | raw | binary | {delayed_write, Size, Delay} | delayed_write | {read_ahead, Size} | read_ahead | compressed | {encoding, Encoding} -   Size = Delay = int() -   Encoding = latin1 | unicode | utf8 | utf16 | {utf16, Endian} | utf32 | {utf32, Endian} -     Endian = big | little - IoDevice = io_device() - Reason = ext_posix() | system_limit - -

Opens the file Filename in the mode determined by - Modes, which may contain one or more of the following - items:

+

Opens the file Filename in the mode determined + by Modes, which may contain one or more of the + following items:

read @@ -841,23 +773,23 @@ f.txt: {person, "kalle", 25}.

Returns:

- {ok, IoDevice} + {ok, IoDevice}

The file has been opened in the requested mode. - IoDevice is a reference to the file.

+ IoDevice is a reference to the file.

 - {error, Reason} + {error, Reason}

The file could not be opened.

 -

IoDevice is really the pid of the process which +

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 + 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(3)).

In previous versions of file, modes were given @@ -897,34 +829,25 @@ f.txt: {person, "kalle", 25}. - path_consult(Path, Filename) -> {ok, Terms, FullName} | {error, Reason} + Read Erlang terms from a file - - Path = [Dir] -  Dir = name() - Filename = name() - Terms = [term()] - FullName = string() - Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term} -  Line, Mod, Term -- see below - -

Searches the path Path (a list of directory names) - until the file Filename is found. If Filename - is an absolute filename, Path is ignored. +

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} + {ok, Terms, FullName} -

The file was successfully read. FullName is +

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.

+ Path.

 {error, atom()} @@ -932,7 +855,8 @@ f.txt: {person, "kalle", 25}. See open/2 for a list of typical error codes.

 - {error, {Line, Mod, Term}} + {error, {Line, Mod, + Term}}

An error occurred when interpreting the Erlang terms in the file. Use format_error/1 to convert @@ -943,36 +867,28 @@ f.txt: {person, "kalle", 25}. - path_eval(Path, Filename) -> {ok, FullName} | {error, Reason} + Evaluate Erlang expressions in a file - - Path = [Dir] -  Dir = name() - Filename = name() - FullName = string() - Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term} -  Line, Mod, Term -- see below - -

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 +

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} + {ok, FullName} -

The file was read and evaluated. FullName is +

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.

+ Path.

 {error, atom()} @@ -980,7 +896,8 @@ f.txt: {person, "kalle", 25}. See open/2 for a list of typical error codes.

 - {error, {Line, Mod, Term}} + {error, {Line, Mod, + Term}}

An error occurred when interpreting the Erlang expressions in the file. Use format_error/1 to @@ -991,34 +908,26 @@ f.txt: {person, "kalle", 25}. - path_open(Path, Filename, Modes) -> {ok, IoDevice, FullName} | {error, Reason} + Open a file - - Path = [Dir] -  Dir = name() - Filename = name() - Modes = [Mode] -- see open/2 - IoDevice = io_device() - FullName = string() - Reason = ext_posix() | 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. +

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

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

+ Path.

 {error, atom()} @@ -1028,36 +937,27 @@ f.txt: {person, "kalle", 25}. - path_script(Path, Filename) -> {ok, Value, FullName} | {error, Reason} + Evaluate and return the value of Erlang expressions in a file - - Path = [Dir] -  Dir = name() - Filename = name() - Value = term() - FullName = string() - Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term} -  Line, Mod, Term -- see below - -

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 +

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} + {ok, Value, FullName} -

The file was read and evaluated. FullName is - the full name of the file and Value the value of +

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.

+ Path.

 {error, atom()} @@ -1065,7 +965,8 @@ f.txt: {person, "kalle", 25}. See open/2 for a list of typical error codes.

 - {error, {Line, Mod, Term}} + {error, {Line, Mod, + Term}}

An error occurred when interpreting the Erlang expressions in the file. Use format_error/1 to @@ -1076,42 +977,28 @@ f.txt: {person, "kalle", 25}. - path_script(Path, Filename, Bindings) -> {ok, Value, FullName} | {error, Reason} + Evaluate and return the value of Erlang expressions in a file - - Path = [Dir] -  Dir = name() - Filename = name() - Bindings -- see erl_eval(3) - Value = term() - FullName = string() - Reason = posix() | terminated | system_limit - | {Line, Mod, Term} -  Line, Mod, Term -- see path_script/2 -

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

 - pid2name(Pid) -> string() | undefined + Return the name of the file handled by a pid - - Pid = pid() - -

If Pid is an IO device, that is, a pid returned from +

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

- {ok, Filename} + {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 + Pid must be a local pid) and the file is not + closed. Filename is the filename in flat string format.

 undefined @@ -1125,21 +1012,15 @@ f.txt: {person, "kalle", 25}. - position(IoDevice, Location) -> {ok, NewPosition} | {error, Reason} + Set position in a file - - IoDevice = io_device() - Location = Offset | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof -  Offset = int() - NewPosition = int() - Reason = ext_posix() | terminated - -

Sets the position of the file referenced by IoDevice - to Location. Returns {ok, NewPosition} (as +

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:

+ {error, Reason}. Location is + one of the following:

Offset @@ -1167,7 +1048,8 @@ f.txt: {person, "kalle", 25}. einval -

Either Location was illegal, or it evaluated to a +

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.

@@ -1176,22 +1058,14 @@ f.txt: {person, "kalle", 25}. - pread(IoDevice, LocNums) -> {ok, DataL} | eof | {error, Reason} + Read from a file at certain positions - - IoDevice = io_device() - LocNums = [{Location, Number}] -  Location -- see position/2 -  Number = int() - DataL = [Data] -  Data = [char()] | binary() - Reason = ext_posix() | 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 + 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 beyond end of file.

@@ -1199,76 +1073,53 @@ f.txt: {person, "kalle", 25}. - pread(IoDevice, Location, Number) -> {ok, Data} | eof | {error, Reason} + Read from a file at a certain position - - IoDevice = io_device() - Location -- see position/2 - Number = int() - Data = [char()] | binary() - Reason = ext_posix() | 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 + 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}} + Write to a file at certain positions - - IoDevice = io_device() - LocBytes = [{Location, Bytes}] -  Location -- see position/2 -  Bytes = iodata() - N = int() - Reason = ext_posix() | 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 + 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, caution must be taken to set the position on a correct character boundary, see position/2 for details.

 - pwrite(IoDevice, Location, Bytes) -> ok | {error, Reason} + Write to a file at a certain position - - IoDevice = io_device() - Location -- see position/2 - Bytes = iodata() - Reason = ext_posix() | 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 + 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, caution 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} + Read from a file - - IoDevice = io_device() - Number = int() - Data = [char()] | binary() - Reason = ext_posix() | terminated - -

Reads Number bytes/characters from the file referenced by - IoDevice. The functions read/2, pread/3 +

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

@@ -1276,7 +1127,7 @@ f.txt: {person, "kalle", 25}.

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(3) module is to be preferred when reading such a file.

The function returns:

- {ok, Data} + {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 @@ -1285,10 +1136,10 @@ f.txt: {person, "kalle", 25}. eof -

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

+

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

 - {error, Reason} + {error, Reason}

An error occurred.

 @@ -1307,17 +1158,14 @@ f.txt: {person, "kalle", 25}. - read_file(Filename) -> {ok, Binary} | {error, Reason} + Read a file - - Filename = name() - Binary = binary() - Reason = ext_posix() | 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.

+

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 @@ -1346,17 +1194,13 @@ f.txt: {person, "kalle", 25}. - read_file_info(Filename) -> {ok, FileInfo} | {error, Reason} + Get information about a file - - Filename = name() - FileInfo = #file_info{} - Reason = ext_posix() -

Retrieves information about a file. Returns - {ok, FileInfo} if successful, otherwise - {error, Reason}. FileInfo is a record + {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:

@@ -1364,7 +1208,7 @@ f.txt: {person, "kalle", 25}. -include_lib("kernel/include/file.hrl").

The record file_info contains the following fields.

- size = int() + size = integer()

Size of file in bytes.

 @@ -1391,7 +1235,7 @@ f.txt: {person, "kalle", 25}. the file or the inode was changed. In Windows, it is the create time.

- mode = int() + mode = integer()

The file permissions as the sum of the following bit values:

@@ -1422,33 +1266,33 @@ f.txt: {person, "kalle", 25}.

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

 - links = int() + links = integer()

Number of links to the file (this will always be 1 for file systems which have no concept of links).

 - major_device = int() + major_device = integer()

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 = int() + minor_device = integer()

Only valid for character devices on Unix. In all other cases, this field is zero.

 - inode = int() + inode = integer()

Gives the inode number. On non-Unix file systems, this field will be zero.

 - uid = int() + uid = integer()

Indicates the owner of the file. Will be zero for non-Unix file systems.

 - gid = int() + gid = integer()

Gives the group that the owner of the file belongs to. Will be zero for non-Unix file systems.

@@ -1474,21 +1318,16 @@ f.txt: {person, "kalle", 25}. - read_line(IoDevice) -> {ok, Data} | eof | {error, Reason} + Read a line from a file - - IoDevice = io_device() - Data = [char()] | binary() - Reason = ext_posix() | terminated -

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

+ 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 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. It is however inefficient to use it on raw files if the file is not opened with the option {read_ahead, Size} specified, why 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 will fail if the data contains characters larger than 255, why the io(3) module is to be preferred when reading such a file.

The function returns:

- {ok, Data} + {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 @@ -1499,7 +1338,7 @@ f.txt: {person, "kalle", 25}.

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

 - {error, Reason} + {error, Reason}

An error occurred.

 @@ -1518,23 +1357,19 @@ f.txt: {person, "kalle", 25}. - read_link(Name) -> {ok, Filename} | {error, Reason} + See what a link is pointing to - - Name = name() - Filename = string() - Reason = ext_posix() - -

This function returns {ok, Filename} if Name - refers to a symbolic link or {error, Reason} otherwise. +

This function 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 will be {error,enotsup}.

Typical error reasons:

einval -

Linkname does not refer to a symbolic link.

+

Name does not refer to a symbolic link.

 enoent @@ -1548,34 +1383,26 @@ f.txt: {person, "kalle", 25}. - read_link_info(Name) -> {ok, FileInfo} | {error, Reason} + Get information about a link or file - - Name = name() - FileInfo = #file_info{}, see read_file_info/1 - Reason = ext_posix() -

This function works like read_file_info/1, except that - if Name is a symbolic link, information about the link - will be returned in the file_info record and + 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 +

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} + Rename a file - - Source = Destination = name() - Reason = ext_posix() - -

Tries to rename the file Source to Destination. +

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 @@ -1593,25 +1420,28 @@ f.txt: {person, "kalle", 25}. eacces

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

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

+

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-directory of Source.

+

Source is a root directory, or + Destination + is a sub-directory of Source.

 eisdir -

Destination is a directory, but Source is - not.

+

Destination is a directory, but + Source is not.

 enoent @@ -1619,35 +1449,28 @@ f.txt: {person, "kalle", 25}. enotdir -

Source is a directory, but Destination is - not.

+

Source is a directory, but + Destination is not.

 exdev -

Source and Destination are on different - file systems.

+

Source and Destination + are on different file systems.

 - script(Filename) -> {ok, Value} | {error, Reason} + Evaluate and return the value of Erlang expressions in a file - - Filename = name() - Value = term() - Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term} -  Line, Mod, Term -- see below -

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} + {ok, Value} -

The file was read and evaluated. Value is +

The file was read and evaluated. Value is the value of the last expression.

 {error, atom()} @@ -1656,7 +1479,8 @@ f.txt: {person, "kalle", 25}. See open/2 for a list of typical error codes.

- {error, {Line, Mod, Term}} + {error, {Line, Mod, + Term}}

An error occurred when interpreting the Erlang expressions in the file. Use format_error/1 to @@ -1667,33 +1491,21 @@ f.txt: {person, "kalle", 25}. - script(Filename, Bindings) -> {ok, Value} | {error, Reason} + Evaluate and return the value of Erlang expressions in a file - - Filename = name() - Bindings -- see erl_eval(3) - Value = term() - Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term} -  Line, Mod, Term -- see below -

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

 - set_cwd(Dir) -> ok | {error,Reason} + Set the current working directory - - Dir = name() - Reason = ext_posix() -

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

+ Dir. Returns ok if successful.

Typical error reasons are:

enoent @@ -1702,8 +1514,8 @@ f.txt: {person, "kalle", 25}. enotdir -

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

+

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

 eacces @@ -1712,23 +1524,21 @@ f.txt: {person, "kalle", 25}. badarg -

Filename had an improper type, such as tuple.

+

Dir had an improper type, + such as tuple.

 -

In a future release, a bad type for the Filename +

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

 - sync(IoDevice) -> ok | {error, Reason} + Synchronizes the in-memory state of a file with that on the physical medium - - IoDevice = io_device() - Reason = ext_posix() | terminated -

Makes sure that any buffers kept by the operating system (not by the Erlang runtime system) are written to disk. On @@ -1743,12 +1553,8 @@ f.txt: {person, "kalle", 25}. - datasync(IoDevice) -> ok | {error, Reason} + Synchronizes the in-memory data of a file, ignoring most of its metadata, with that on the physical medium - - IoDevice = io_device() - Reason = ext_posix() | terminated -

Makes sure that any buffers kept by the operating system (not by the Erlang runtime system) are written to disk. In @@ -1770,32 +1576,23 @@ f.txt: {person, "kalle", 25}. - truncate(IoDevice) -> ok | {error, Reason} + Truncate a file - - IoDevice = io_device() - Reason = ext_posix() | terminated - -

Truncates the file referenced by IoDevice at +

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

+ otherwise {error, Reason}.

 - write(IoDevice, Bytes) -> ok | {error, Reason} + Write to a file - - IoDevice = io_device() - Bytes = iodata() - Reason = ext_posix() | terminated - -

Writes Bytes to the file referenced by - IoDevice. This function is the only way to write to a +

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.

+ {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 represent anything between one and four bytes depending on value and UTF encoding type.

Typical error reasons are:

@@ -1811,18 +1608,14 @@ f.txt: {person, "kalle", 25}. - write_file(Filename, Bytes) -> ok | {error, Reason} + Write a file - - Filename = name() - Bytes = iodata() - Reason = ext_posix() | terminated | system_limit - -

Writes the contents of the iodata term Bytes to the - file Filename. The file is created if it does not +

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

+ overwritten. Returns ok, or {error, Reason}.

Typical error reasons are:

enoent @@ -1851,33 +1644,23 @@ f.txt: {person, "kalle", 25}. - write_file(Filename, Bytes, Modes) -> ok | {error, Reason} + Write a file - - Filename = name() - Bytes = iodata() - Modes = [Mode] -- see open/2 - Reason = ext_posix() | terminated | system_limit -

Same as write_file/2, but takes a third argument - Modes, a list of possible modes, see + 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} + Change information about a file - - Filename = name() - FileInfo = #file_info{} -- see also read_file_info/1 - Reason = ext_posix() -

Change file information. Returns ok if successful, - otherwise {error, Reason}. FileInfo is a record + 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:

@@ -1901,7 +1684,7 @@ f.txt: {person, "kalle", 25}. time). On Windows, this field is the new creation time to set for the file.

- mode = int() + mode = integer()

The file permissions as the sum of the following bit values:

@@ -1932,12 +1715,12 @@ f.txt: {person, "kalle", 25}.

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

 - uid = int() + uid = integer()

Indicates the owner of the file. Ignored for non-Unix file systems.

 - gid = int() + gid = integer()

Gives the group that the owner of the file belongs to. Ignored non-Unix file systems.

-- cgit v1.2.3