diff options
Diffstat (limited to 'lib/kernel/doc/src/file.xml')
| -rw-r--r-- | lib/kernel/doc/src/file.xml | 895 |
1 files changed, 339 insertions, 556 deletions
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 @@ <erlref> <header> <copyright> - <year>1996</year><year>2010</year> + <year>1996</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -93,47 +93,76 @@ is UTF-8...</p> </description> - <section> - <title>DATA TYPES</title> - <code type="none"> -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 + <datatypes> + <datatype> + <name name="bindings"/> + </datatype> + <datatype> + <name name="deep_list"/> + </datatype> + <datatype> + <name name="fd"/> + </datatype> + <datatype> + <name name="filename"/> + </datatype> + <datatype> + <name name="io_device"/> + <desc> + <p>As returned by + <seealso marker="#open/2">file:open/2</seealso>, + a process handling IO protocols.</p> + </desc> + </datatype> + <datatype> + <name name="name"/> + <desc> + <p>If VM is in Unicode filename mode, <c>string()</c> and <c>char()</c> + are allowed to be > 255. + <c><anno>RawFilename</anno></c> 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). + </p> + </desc> + </datatype> + <datatype> + <name name="posix"/> + <desc> + <p>An atom which is named from the POSIX error codes used in + Unix, and in the runtime libraries of most C compilers.</p> + </desc> + </datatype> + <datatype> + <name name="date"/> + </datatype> + <datatype> + <name name="time"/> + </datatype> + <datatype> + <name name="date_time"/> + <desc> + <p>Must denote a valid date and time.</p> + </desc> + </datatype> + <datatype> + <name name="file_info"/> + </datatype> + <datatype> + <name name="location"/> + </datatype> + <datatype> + <name name="mode"/> + </datatype> + </datatypes> -time() = {{Year, Month, Day}, {Hour, Minute, Second}} - Year = Month = Day = Hour = Minute = Second = int() - Must denote a valid date and time</code> - </section> <funcs> <func> - <name>advise(IoDevice, Offset, Length, Advise) -> ok | {error, Reason}</name> + <name name="advise" arity="4"/> <fsummary>Predeclare an access pattern for file data</fsummary> - <type> - <v>IoDevice = io_device()</v> - <v>Offset = int()</v> - <v>Length = int()</v> - <v>Advise = posix_file_advise()</v> - <v>posix_file_advise() = normal | sequential | random | no_reuse - | will_need | dont_need</v> - <v>Reason = ext_posix()</v> - </type> + <type name="posix_file_advise"/> <desc> <p><c>advise/4</c> 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}} </desc> </func> <func> - <name>change_group(Filename, Gid) -> ok | {error, Reason}</name> + <name name="change_group" arity="2"/> <fsummary>Change group of a file</fsummary> - <type> - <v>Filename = name()</v> - <v>Gid = int()</v> - <v>Reason = ext_posix()</v> - </type> <desc> <p>Changes group of a file. See <seealso marker="#write_file_info/2">write_file_info/2</seealso>.</p> </desc> </func> <func> - <name>change_mode(Filename, Mode) -> ok | {error, Reason}</name> + <name name="change_mode" arity="2"/> <fsummary>Change permissions of a file</fsummary> - <type> - <v>Filename = name()</v> - <v>Mode = int()</v> - <v>Reason = ext_posix()</v> - </type> <desc> <p>Changes permissions of a file. See <seealso marker="#write_file_info/2">write_file_info/2</seealso>.</p> </desc> </func> <func> - <name>change_owner(Filename, Uid) -> ok | {error, Reason}</name> + <name name="change_owner" arity="2"/> <fsummary>Change owner of a file</fsummary> - <type> - <v>Filename = name()</v> - <v>Uid = int()</v> - <v>Reason = ext_posix()</v> - </type> <desc> <p>Changes owner of a file. See <seealso marker="#write_file_info/2">write_file_info/2</seealso>.</p> </desc> </func> <func> - <name>change_owner(Filename, Uid, Gid) -> ok | {error, Reason}</name> + <name name="change_owner" arity="3"/> <fsummary>Change owner and group of a file</fsummary> - <type> - <v>Filename = name()</v> - <v>Uid = int()</v> - <v>Gid = int()</v> - <v>Reason = ext_posix()</v> - </type> <desc> <p>Changes owner and group of a file. See <seealso marker="#write_file_info/2">write_file_info/2</seealso>.</p> </desc> </func> <func> - <name>change_time(Filename, Mtime) -> ok | {error, Reason}</name> + <name name="change_time" arity="2"/> <fsummary>Change the modification time of a file</fsummary> - <type> - <v>Filename = name()</v> - <v>Mtime = time()</v> - <v>Reason = ext_posix()</v> - </type> <desc> <p>Changes the modification and access times of a file. See <seealso marker="#write_file_info/2">write_file_info/2</seealso>.</p> </desc> </func> <func> - <name>change_time(Filename, Mtime, Atime) -> ok | {error, Reason}</name> + <name name="change_time" arity="3"/> <fsummary>Change the modification and last access time of a file</fsummary> - <type> - <v>Filename = name()</v> - <v>Mtime = Atime = time()</v> - <v>Reason = ext_posix()</v> - </type> <desc> <p>Changes the modification and last access times of a file. See <seealso marker="#write_file_info/2">write_file_info/2</seealso>.</p> </desc> </func> <func> - <name>close(IoDevice) -> ok | {error, Reason}</name> + <name name="close" arity="1"/> <fsummary>Close a file</fsummary> - <type> - <v>IoDevice = io_device()</v> - <v>Reason = ext_posix() | terminated</v> - </type> <desc> - <p>Closes the file referenced by <c>IoDevice</c>. It mostly + <p>Closes the file referenced by <c><anno>IoDevice</anno></c>. It mostly returns <c>ok</c>, expect for some severe errors such as out of memory.</p> <p>Note that if the option <c>delayed_write</c> was @@ -238,20 +232,13 @@ time() = {{Year, Month, Day}, {Hour, Minute, Second}} </desc> </func> <func> - <name>consult(Filename) -> {ok, Terms} | {error, Reason}</name> + <name name="consult" arity="1"/> <fsummary>Read Erlang terms from a file</fsummary> - <type> - <v>Filename = name()</v> - <v>Terms = [term()]</v> - <v>Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term}</v> - <v> Line, Mod, Term -- see below</v> - </type> <desc> - <p>Reads Erlang terms, separated by '.', from <c>Filename</c>. - Returns one of the following:</p> + <p>Reads Erlang terms, separated by '.', from + <c><anno>Filename</anno></c>. Returns one of the following:</p> <taglist> - <tag><c>{ok, Terms}</c></tag> + <tag><c>{ok, <anno>Terms</anno>}</c></tag> <item> <p>The file was successfully read.</p> </item> @@ -261,7 +248,8 @@ time() = {{Year, Month, Day}, {Hour, Minute, Second}} See <seealso marker="#open/2">open/2</seealso> for a list of typical error codes.</p> </item> - <tag><c>{error, {Line, Mod, Term}}</c></tag> + <tag><c>{error, {<anno>Line</anno>, <anno>Mod</anno>, + <anno>Term</anno>}}</c></tag> <item> <p>An error occurred when interpreting the Erlang terms in the file. Use <c>format_error/1</c> to convert @@ -279,53 +267,46 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>copy(Source, Destination) -></name> - <name>copy(Source, Destination, ByteCount) -> {ok, BytesCopied} | {error, Reason}</name> + <name name="copy" arity="2"/> + <name name="copy" arity="3"/> <fsummary>Copy file contents</fsummary> - <type> - <v>Source = Destination = io_device() | Filename | {Filename, Modes}</v> - <v> Filename = name()</v> - <v> Modes = [Mode] -- see open/2</v> - <v>ByteCount = int() >= 0 | infinity</v> - <v>BytesCopied = int()</v> - </type> <desc> - <p>Copies <c>ByteCount</c> bytes from <c>Source</c> to - <c>Destination</c>. <c>Source</c> and <c>Destination</c> refer + <p>Copies <c><anno>ByteCount</anno></c> bytes from + <c><anno>Source</anno></c> to <c><anno>Destination</anno></c>. + <c><anno>Source</anno></c> and <c><anno>Destination</anno></c> refer to either filenames or IO devices from e.g. <c>open/2</c>. - <c>ByteCount</c> defaults <c>infinity</c>, denoting an + <c><anno>ByteCount</anno></c> defaults to <c>infinity</c>, denoting an infinite number of bytes.</p> - <p>The argument <c>Modes</c> is a list of possible modes, see - <seealso marker="#open/2">open/2</seealso>, and defaults to + <p>The argument <c><anno>Modes</anno></c> is a list of possible modes, + see <seealso marker="#open/2">open/2</seealso>, and defaults to [].</p> - <p>If both <c>Source</c> and <c>Destination</c> refer to + <p>If both <c><anno>Source</anno></c> and + <c><anno>Destination</anno></c> refer to filenames, the files are opened with <c>[read, binary]</c> and <c>[write, binary]</c> prepended to their mode lists, respectively, to optimize the copy.</p> - <p>If <c>Source</c> refers to a filename, it is opened with + <p>If <c><anno>Source</anno></c> refers to a filename, it is opened with <c>read</c> mode prepended to the mode list before the copy, and closed when done.</p> - <p>If <c>Destination</c> refers to a filename, it is opened + <p>If <c><anno>Destination</anno></c> refers to a filename, it is opened with <c>write</c> mode prepended to the mode list before the copy, and closed when done.</p> - <p>Returns <c>{ok, BytesCopied}</c> where <c>BytesCopied</c> is + <p>Returns <c>{ok, <anno>BytesCopied</anno>}</c> where + <c><anno>BytesCopied</anno></c> is the number of bytes that actually was copied, which may be - less than <c>ByteCount</c> if end of file was encountered on - the source. If the operation fails, <c>{error, Reason}</c> is - returned.</p> + less than <c><anno>ByteCount</anno></c> if end of file was + encountered on the source. If the operation fails, + <c>{error, <anno>Reason</anno>}</c> is returned.</p> <p>Typical error reasons: As for <c>open/2</c> if a file had to be opened, and as for <c>read/2</c> and <c>write/2</c>.</p> </desc> </func> <func> - <name>del_dir(Dir) -> ok | {error, Reason}</name> + <name name="del_dir" arity="1"/> <fsummary>Delete a directory</fsummary> - <type> - <v>Dir = name()</v> - <v>Reason = ext_posix()</v> - </type> <desc> - <p>Tries to delete the directory <c>Dir</c>. The directory must + <p>Tries to delete the directory <c><anno>Dir</anno></c>. + The directory must be empty before it can be deleted. Returns <c>ok</c> if successful.</p> <p>Typical error reasons are:</p> @@ -333,7 +314,7 @@ f.txt: {person, "kalle", 25}. <tag><c>eacces</c></tag> <item> <p>Missing search or write permissions for the parent - directories of <c>Dir</c>.</p> + directories of <c><anno>Dir</anno></c>.</p> </item> <tag><c>eexist</c></tag> <item> @@ -345,8 +326,8 @@ f.txt: {person, "kalle", 25}. </item> <tag><c>enotdir</c></tag> <item> - <p>A component of <c>Dir</c> is not a directory. On some - platforms, <c>enoent</c> is returned instead.</p> + <p>A component of <c><anno>Dir</anno></c> is not a directory. + On some platforms, <c>enoent</c> is returned instead.</p> </item> <tag><c>einval</c></tag> <item> @@ -357,15 +338,11 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>delete(Filename) -> ok | {error, Reason}</name> + <name name="delete" arity="1"/> <fsummary>Delete a file</fsummary> - <type> - <v>Filename = name()</v> - <v>Reason = ext_posix()</v> - </type> <desc> - <p>Tries to delete the file <c>Filename</c>. Returns <c>ok</c> - if successful.</p> + <p>Tries to delete the file <c><anno>Filename</anno></c>. + Returns <c>ok</c> if successful.</p> <p>Typical error reasons are:</p> <taglist> <tag><c>enoent</c></tag> @@ -387,30 +364,25 @@ f.txt: {person, "kalle", 25}. </item> <tag><c>einval</c></tag> <item> - <p><c>Filename</c> had an improper type, such as tuple.</p> + <p><c><anno>Filename</anno></c> had an improper type, such as tuple.</p> </item> </taglist> <warning> - <p>In a future release, a bad type for the <c>Filename</c> - argument will probably generate an exception.</p> + <p>In a future release, a bad type for the + <c><anno>Filename</anno></c> argument will probably generate + an exception.</p> <p></p> </warning> </desc> </func> <func> - <name>eval(Filename) -> ok | {error, Reason}</name> + <name name="eval" arity="1"/> <fsummary>Evaluate Erlang expressions in a file</fsummary> - <type> - <v>Filename = name()</v> - <v>Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term}</v> - <v> Line, Mod, Term -- see below</v> - </type> <desc> <p>Reads and evaluates Erlang expressions, separated by '.' (or ',', a sequence of expressions is also an expression), from - <c>Filename</c>. The actual result of the evaluation is not - returned; any expression sequence in the file must be there + <c><anno>Filename</anno></c>. 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:</p> <taglist> <tag><c>ok</c></tag> @@ -422,7 +394,8 @@ f.txt: {person, "kalle", 25}. <p>An error occurred when opening the file or reading it. See <c>open/2</c> for a list of typical error codes.</p> </item> - <tag><c>{error, {Line, Mod, Term}}</c></tag> + <tag><c>{error, {<anno>Line</anno>, <anno>Mod</anno>, + <anno>Term</anno>}}</c></tag> <item> <p>An error occurred when interpreting the Erlang expressions in the file. Use <c>format_error/1</c> to @@ -433,18 +406,11 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>eval(Filename, Bindings) -> ok | {error, Reason}</name> + <name name="eval" arity="2"/> <fsummary>Evaluate Erlang expressions in a file</fsummary> - <type> - <v>Filename = name()</v> - <v>Bindings -- see erl_eval(3)</v> - <v>Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term}</v> - <v> Line, Mod, Term -- see eval/1</v> - </type> <desc> <p>The same as <c>eval/1</c> but the variable bindings - <c>Bindings</c> are used in the evaluation. See + <c><anno>Bindings</anno></c> are used in the evaluation. See <seealso marker="stdlib:erl_eval">erl_eval(3)</seealso> about variable bindings.</p> </desc> @@ -458,27 +424,19 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>format_error(Reason) -> Chars</name> + <name name="format_error" arity="1"/> <fsummary>Return a descriptive string for an error reason</fsummary> - <type> - <v>Reason = atom() | {Line, Mod, Term}</v> - <v> Line, Mod, Term -- see eval/1</v> - <v>Chars = [char() | Chars]</v> - </type> <desc> <p>Given the error reason returned by any function in this module, returns a descriptive string of the error in English.</p> </desc> </func> <func> - <name>get_cwd() -> {ok, Dir} | {error, Reason}</name> + <name name="get_cwd" arity="0"/> <fsummary>Get the current working directory</fsummary> - <type> - <v>Dir = string()</v> - <v>Reason = posix()</v> - </type> <desc> - <p>Returns <c>{ok, Dir}</c>, where <c>Dir</c> is the current + <p>Returns <c>{ok, <anno>Dir</anno>}</c>, where <c><anno>Dir</anno></c> + is the current working directory of the file server.</p> <note> <p>In rare circumstances, this function can fail on Unix. @@ -496,17 +454,14 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>get_cwd(Drive) -> {ok, Dir} | {error, Reason}</name> + <name name="get_cwd" arity="1"/> <fsummary>Get the current working directory for the drive specified</fsummary> - <type> - <v>Drive = string() -- see below</v> - <v>Dir = string()</v> - <v>Reason = ext_posix()</v> - </type> <desc> - <p><c>Drive</c> should be of the form "<c>Letter</c><c>:</c>", - for example "c:". Returns <c>{ok, Dir}</c> or - <c>{error, Reason}</c>, where <c>Dir</c> is the current + <p><c><anno>Drive</anno></c> should be of the form + "<c>Letter</c><c>:</c>", + for example "c:". Returns <c>{ok, <anno>Dir</anno>}</c> or + <c>{error, <anno>Reason</anno>}</c>, where <c><anno>Dir</anno></c> + is the current working directory of the drive specified.</p> <p>This function returns <c>{error, enotsup}</c> on platforms which have no concept of current drive (Unix, for example).</p> @@ -514,7 +469,7 @@ f.txt: {person, "kalle", 25}. <taglist> <tag><c>enotsup</c></tag> <item> - <p>The operating system have no concept of drives.</p> + <p>The operating system has no concept of drives.</p> </item> <tag><c>eacces</c></tag> <item> @@ -522,32 +477,27 @@ f.txt: {person, "kalle", 25}. </item> <tag><c>einval</c></tag> <item> - <p>The format of <c>Drive</c> is invalid.</p> + <p>The format of <c><anno>Drive</anno></c> is invalid.</p> </item> </taglist> </desc> </func> <func> - <name>list_dir(Dir) -> {ok, Filenames} | {error, Reason}</name> + <name name="list_dir" arity="1"/> <fsummary>List files in a directory</fsummary> - <type> - <v>Dir = name()</v> - <v>Filenames = [Filename]</v> - <v> Filename = string()</v> - <v>Reason = ext_posix()</v> - </type> <desc> <p>Lists all the files in a directory. Returns - <c>{ok, Filenames}</c> if successful. Otherwise, it returns - <c>{error, Reason}</c>. <c>Filenames</c> is a list of + <c>{ok, <anno>Filenames</anno>}</c> if successful. + Otherwise, it returns <c>{error, <anno>Reason</anno>}</c>. + <c><anno>Filenames</anno></c> is a list of the names of all the files in the directory. The names are not sorted.</p> <p>Typical error reasons are:</p> <taglist> <tag><c>eacces</c></tag> <item> - <p>Missing search or write permissions for <c>Dir</c> or - one of its parent directories.</p> + <p>Missing search or write permissions for <c><anno>Dir</anno></c> + or one of its parent directories.</p> </item> <tag><c>enoent</c></tag> <item> @@ -557,14 +507,10 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>make_dir(Dir) -> ok | {error, Reason}</name> + <name name="make_dir" arity="1"/> <fsummary>Make a directory</fsummary> - <type> - <v>Dir = name()</v> - <v>Reason = ext_posix()</v> - </type> <desc> - <p>Tries to create the directory <c>Dir</c>. Missing parent + <p>Tries to create the directory <c><anno>Dir</anno></c>. Missing parent directories are <em>not</em> created. Returns <c>ok</c> if successful.</p> <p>Typical error reasons are:</p> @@ -572,15 +518,15 @@ f.txt: {person, "kalle", 25}. <tag><c>eacces</c></tag> <item> <p>Missing search or write permissions for the parent - directories of <c>Dir</c>.</p> + directories of <c><anno>Dir</anno></c>.</p> </item> <tag><c>eexist</c></tag> <item> - <p>There is already a file or directory named <c>Dir</c>.</p> + <p>There is already a file or directory named <c><anno>Dir</anno></c>.</p> </item> <tag><c>enoent</c></tag> <item> - <p>A component of <c>Dir</c> does not exist.</p> + <p>A component of <c><anno>Dir</anno></c> does not exist.</p> </item> <tag><c>enospc</c></tag> <item> @@ -588,35 +534,33 @@ f.txt: {person, "kalle", 25}. </item> <tag><c>enotdir</c></tag> <item> - <p>A component of <c>Dir</c> is not a directory. On some - platforms, <c>enoent</c> is returned instead.</p> + <p>A component of <c><anno>Dir</anno></c> is not a directory. + On some platforms, <c>enoent</c> is returned instead.</p> </item> </taglist> </desc> </func> <func> - <name>make_link(Existing, New) -> ok | {error, Reason}</name> + <name name="make_link" arity="2"/> <fsummary>Make a hard link to a file</fsummary> - <type> - <v>Existing = New = name()</v> - <v>Reason = ext_posix()</v> - </type> <desc> - <p>Makes a hard link from <c>Existing</c> to <c>New</c>, on + <p>Makes a hard link from <c><anno>Existing</anno></c> to + <c><anno>New</anno></c>, on platforms that support links (Unix). This function returns <c>ok</c> if the link was successfully created, or - <c>{error, Reason}</c>. On platforms that do not support + <c>{error, <anno>Reason</anno>}</c>. On platforms that do not support links, <c>{error,enotsup}</c> is returned.</p> <p>Typical error reasons:</p> <taglist> <tag><c>eacces</c></tag> <item> <p>Missing read or write permissions for the parent - directories of <c>Existing</c> or <c>New</c>.</p> + directories of <c><anno>Existing</anno></c> or + <c><anno>New</anno></c>.</p> </item> <tag><c>eexist</c></tag> <item> - <p><c>New</c> already exists.</p> + <p><c><anno>New</anno></c> already exists.</p> </item> <tag><c>enotsup</c></tag> <item> @@ -626,30 +570,28 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>make_symlink(Name1, Name2) -> ok | {error, Reason}</name> + <name name="make_symlink" arity="2"/> <fsummary>Make a symbolic link to a file or directory</fsummary> - <type> - <v>Name1 = Name2 = name()</v> - <v>Reason = ext_posix()</v> - </type> <desc> - <p>This function creates a symbolic link <c>Name2</c> to - the file or directory <c>Name1</c>, on platforms that support - symbolic links (most Unix systems). <c>Name1</c> need not + <p>This function creates a symbolic link <c><anno>Name2</anno></c> to + the file or directory <c><anno>Name1</anno></c>, on platforms that + support + symbolic links (most Unix systems). <c><anno>Name1</anno></c> need not exist. This function returns <c>ok</c> if the link was - successfully created, or <c>{error, Reason}</c>. On platforms + successfully created, or <c>{error, <anno>Reason</anno>}</c>. + On platforms that do not support symbolic links, <c>{error, enotsup}</c> is returned.</p> <p>Typical error reasons:</p> <taglist> <tag><c>eacces</c></tag> <item> - <p>Missing read or write permissions for the parent - directories of <c>Name1</c> or <c>Name2</c>.</p> + <p>Missing read or write permissions for the parent directories + of <c><anno>Name1</anno></c> or <c><anno>Name2</anno></c>.</p> </item> <tag><c>eexist</c></tag> <item> - <p><c>Name2</c> already exists.</p> + <p><c><anno>Name2</anno></c> already exists.</p> </item> <tag><c>enotsup</c></tag> <item> @@ -668,22 +610,12 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>open(Filename, Modes) -> {ok, IoDevice} | {error, Reason}</name> + <name name="open" arity="2"/> <fsummary>Open a file</fsummary> - <type> - <v>Filename = name()</v> - <v>Modes = [Mode]</v> - <v> Mode = read | write | append | exclusive | raw | binary | {delayed_write, Size, Delay} | delayed_write | {read_ahead, Size} | read_ahead | compressed | {encoding, Encoding}</v> - <v> Size = Delay = int()</v> - <v> Encoding = latin1 | unicode | utf8 | utf16 | {utf16, Endian} | utf32 | {utf32, Endian}</v> - <v> Endian = big | little</v> - <v>IoDevice = io_device()</v> - <v>Reason = ext_posix() | system_limit</v> - </type> <desc> - <p>Opens the file <c>Filename</c> in the mode determined by - <c>Modes</c>, which may contain one or more of the following - items:</p> + <p>Opens the file <c><anno>Filename</anno></c> in the mode determined + by <c><anno>Modes</anno></c>, which may contain one or more of the + following items:</p> <taglist> <tag><c>read</c></tag> <item> @@ -841,23 +773,23 @@ f.txt: {person, "kalle", 25}. </taglist> <p>Returns:</p> <taglist> - <tag><c>{ok, IoDevice}</c></tag> + <tag><c>{ok, <anno>IoDevice</anno>}</c></tag> <item> <p>The file has been opened in the requested mode. - <c>IoDevice</c> is a reference to the file.</p> + <c><anno>IoDevice</anno></c> is a reference to the file.</p> </item> - <tag><c>{error, Reason}</c></tag> + <tag><c>{error, <anno>Reason</anno>}</c></tag> <item> <p>The file could not be opened.</p> </item> </taglist> - <p><c>IoDevice</c> is really the pid of the process which + <p><c><anno>IoDevice</anno></c> 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 <c>IoDevice</c> is linked terminates, the file will be - closed and the process itself will be terminated. - An <c>IoDevice</c> returned from this call can be used as an - argument to the IO functions (see + the <c><anno>IoDevice</anno></c> is linked terminates, the file will + be closed and the process itself will be terminated. + An <c><anno>IoDevice</anno></c> returned from this call can be used + as an argument to the IO functions (see <seealso marker="stdlib:io">io(3)</seealso>).</p> <note> <p>In previous versions of <c>file</c>, modes were given @@ -897,34 +829,25 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>path_consult(Path, Filename) -> {ok, Terms, FullName} | {error, Reason}</name> + <name name="path_consult" arity="2"/> <fsummary>Read Erlang terms from a file</fsummary> - <type> - <v>Path = [Dir]</v> - <v> Dir = name()</v> - <v>Filename = name()</v> - <v>Terms = [term()]</v> - <v>FullName = string()</v> - <v>Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term}</v> - <v> Line, Mod, Term -- see below</v> - </type> <desc> - <p>Searches the path <c>Path</c> (a list of directory names) - until the file <c>Filename</c> is found. If <c>Filename</c> - is an absolute filename, <c>Path</c> is ignored. + <p>Searches the path <c><anno>Path</anno></c> (a list of directory + names) until the file <c><anno>Filename</anno></c> is found. + If <c><anno>Filename</anno></c> + is an absolute filename, <c><anno>Path</anno></c> is ignored. Then reads Erlang terms, separated by '.', from the file. Returns one of the following:</p> <taglist> - <tag><c>{ok, Terms, FullName}</c></tag> + <tag><c>{ok, <anno>Terms</anno>, <anno>FullName</anno>}</c></tag> <item> - <p>The file was successfully read. <c>FullName</c> is + <p>The file was successfully read. <c><anno>FullName</anno></c> is the full name of the file.</p> </item> <tag><c>{error, enoent}</c></tag> <item> <p>The file could not be found in any of the directories in - <c>Path</c>.</p> + <c><anno>Path</anno></c>.</p> </item> <tag><c>{error, atom()}</c></tag> <item> @@ -932,7 +855,8 @@ f.txt: {person, "kalle", 25}. See <seealso marker="#open/2">open/2</seealso> for a list of typical error codes.</p> </item> - <tag><c>{error, {Line, Mod, Term}}</c></tag> + <tag><c>{error, {<anno>Line</anno>, <anno>Mod</anno>, + <anno>Term</anno>}}</c></tag> <item> <p>An error occurred when interpreting the Erlang terms in the file. Use <c>format_error/1</c> to convert @@ -943,36 +867,28 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>path_eval(Path, Filename) -> {ok, FullName} | {error, Reason}</name> + <name name="path_eval" arity="2"/> <fsummary>Evaluate Erlang expressions in a file</fsummary> - <type> - <v>Path = [Dir]</v> - <v> Dir = name()</v> - <v>Filename = name()</v> - <v>FullName = string()</v> - <v>Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term}</v> - <v> Line, Mod, Term -- see below</v> - </type> <desc> - <p>Searches the path <c>Path</c> (a list of directory names) - until the file <c>Filename</c> is found. If <c>Filename</c> - is an absolute file name, <c>Path</c> is ignored. Then reads + <p>Searches the path <c><anno>Path</anno></c> (a list of directory + names) until the file <c><anno>Filename</anno></c> is found. + If <c><anno>Filename</anno></c> is an absolute file name, + <c><anno>Path</anno></c> 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:</p> <taglist> - <tag><c>{ok, FullName}</c></tag> + <tag><c>{ok, <anno>FullName</anno>}</c></tag> <item> - <p>The file was read and evaluated. <c>FullName</c> is + <p>The file was read and evaluated. <c><anno>FullName</anno></c> is the full name of the file.</p> </item> <tag><c>{error, enoent}</c></tag> <item> <p>The file could not be found in any of the directories in - <c>Path</c>.</p> + <c><anno>Path</anno></c>.</p> </item> <tag><c>{error, atom()}</c></tag> <item> @@ -980,7 +896,8 @@ f.txt: {person, "kalle", 25}. See <seealso marker="#open/2">open/2</seealso> for a list of typical error codes.</p> </item> - <tag><c>{error, {Line, Mod, Term}}</c></tag> + <tag><c>{error, {<anno>Line</anno>, <anno>Mod</anno>, + <anno>Term</anno>}}</c></tag> <item> <p>An error occurred when interpreting the Erlang expressions in the file. Use <c>format_error/1</c> to @@ -991,34 +908,26 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>path_open(Path, Filename, Modes) -> {ok, IoDevice, FullName} | {error, Reason}</name> + <name name="path_open" arity="3"/> <fsummary>Open a file</fsummary> - <type> - <v>Path = [Dir]</v> - <v> Dir = name()</v> - <v>Filename = name()</v> - <v>Modes = [Mode] -- see open/2</v> - <v>IoDevice = io_device()</v> - <v>FullName = string()</v> - <v>Reason = ext_posix() | system_limit</v> - </type> <desc> - <p>Searches the path <c>Path</c> (a list of directory names) - until the file <c>Filename</c> is found. If <c>Filename</c> - is an absolute file name, <c>Path</c> is ignored. - Then opens the file in the mode determined by <c>Modes</c>. + <p>Searches the path <c><anno>Path</anno></c> (a list of directory + names) until the file <c><anno>Filename</anno></c> is found. + If <c><anno>Filename</anno></c> + is an absolute file name, <c><anno>Path</anno></c> is ignored. + Then opens the file in the mode determined by <c><anno>Modes</anno></c>. Returns one of the following:</p> <taglist> - <tag><c>{ok, IoDevice, FullName}</c></tag> + <tag><c>{ok, <anno>IoDevice</anno>, <anno>FullName</anno>}</c></tag> <item> <p>The file has been opened in the requested mode. - <c>IoDevice</c> is a reference to the file and - <c>FullName</c> is the full name of the file.</p> + <c><anno>IoDevice</anno></c> is a reference to the file and + <c><anno>FullName</anno></c> is the full name of the file.</p> </item> <tag><c>{error, enoent}</c></tag> <item> <p>The file could not be found in any of the directories in - <c>Path</c>.</p> + <c><anno>Path</anno></c>.</p> </item> <tag><c>{error, atom()}</c></tag> <item> @@ -1028,36 +937,27 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>path_script(Path, Filename) -> {ok, Value, FullName} | {error, Reason}</name> + <name name="path_script" arity="2"/> <fsummary>Evaluate and return the value of Erlang expressions in a file</fsummary> - <type> - <v>Path = [Dir]</v> - <v> Dir = name()</v> - <v>Filename = name()</v> - <v>Value = term()</v> - <v>FullName = string()</v> - <v>Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term}</v> - <v> Line, Mod, Term -- see below</v> - </type> <desc> - <p>Searches the path <c>Path</c> (a list of directory names) - until the file <c>Filename</c> is found. If <c>Filename</c> - is an absolute file name, <c>Path</c> is ignored. Then reads + <p>Searches the path <c><anno>Path</anno></c> (a list of directory + names) until the file <c><anno>Filename</anno></c> is found. + If <c><anno>Filename</anno></c> is an absolute file name, + <c><anno>Path</anno></c> 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:</p> <taglist> - <tag><c>{ok, Value, FullName}</c></tag> + <tag><c>{ok, <anno>Value</anno>, <anno>FullName</anno>}</c></tag> <item> - <p>The file was read and evaluated. <c>FullName</c> is - the full name of the file and <c>Value</c> the value of + <p>The file was read and evaluated. <c><anno>FullName</anno></c> is + the full name of the file and <c><anno>Value</anno></c> the value of the last expression.</p> </item> <tag><c>{error, enoent}</c></tag> <item> <p>The file could not be found in any of the directories in - <c>Path</c>.</p> + <c><anno>Path</anno></c>.</p> </item> <tag><c>{error, atom()}</c></tag> <item> @@ -1065,7 +965,8 @@ f.txt: {person, "kalle", 25}. See <seealso marker="#open/2">open/2</seealso> for a list of typical error codes.</p> </item> - <tag><c>{error, {Line, Mod, Term}}</c></tag> + <tag><c>{error, {<anno>Line</anno>, <anno>Mod</anno>, + <anno>Term</anno>}}</c></tag> <item> <p>An error occurred when interpreting the Erlang expressions in the file. Use <c>format_error/1</c> to @@ -1076,42 +977,28 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>path_script(Path, Filename, Bindings) -> {ok, Value, FullName} | {error, Reason}</name> + <name name="path_script" arity="3"/> <fsummary>Evaluate and return the value of Erlang expressions in a file</fsummary> - <type> - <v>Path = [Dir]</v> - <v> Dir = name()</v> - <v>Filename = name()</v> - <v>Bindings -- see erl_eval(3)</v> - <v>Value = term()</v> - <v>FullName = string()</v> - <v>Reason = posix() | terminated | system_limit - | {Line, Mod, Term}</v> - <v> Line, Mod, Term -- see path_script/2</v> - </type> <desc> <p>The same as <c>path_script/2</c> but the variable bindings - <c>Bindings</c> are used in the evaluation. See + <c><anno>Bindings</anno></c> are used in the evaluation. See <seealso marker="stdlib:erl_eval">erl_eval(3)</seealso> about variable bindings.</p> </desc> </func> <func> - <name>pid2name(Pid) -> string() | undefined</name> + <name name="pid2name" arity="1"/> <fsummary>Return the name of the file handled by a pid</fsummary> - <type> - <v>Pid = pid()</v> - </type> <desc> - <p>If <c>Pid</c> is an IO device, that is, a pid returned from + <p>If <c><anno>Pid</anno></c> is an IO device, that is, a pid returned from <c>open/2</c>, this function returns the filename, or rather:</p> <taglist> - <tag><c>{ok, Filename}</c></tag> + <tag><c>{ok, <anno>Filename</anno>}</c></tag> <item> <p>If this node's file server is not a slave, the file was opened by this node's file server, (this implies that - <c>Pid</c> must be a local pid) and the file is not - closed. <c>Filename</c> is the filename in flat string + <c><anno>Pid</anno></c> must be a local pid) and the file is not + closed. <c><anno>Filename</anno></c> is the filename in flat string format.</p> </item> <tag><c>undefined</c></tag> @@ -1125,21 +1012,15 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>position(IoDevice, Location) -> {ok, NewPosition} | {error, Reason}</name> + <name name="position" arity="2"/> <fsummary>Set position in a file</fsummary> - <type> - <v>IoDevice = io_device()</v> - <v>Location = Offset | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof</v> - <v> Offset = int()</v> - <v>NewPosition = int()</v> - <v>Reason = ext_posix() | terminated</v> - </type> <desc> - <p>Sets the position of the file referenced by <c>IoDevice</c> - to <c>Location</c>. Returns <c>{ok, NewPosition}</c> (as + <p>Sets the position of the file referenced by <c><anno>IoDevice</anno></c> + to <c><anno>Location</anno></c>. Returns + <c>{ok, <anno>NewPosition</anno>}</c> (as absolute offset) if successful, otherwise - <c>{error, Reason}</c>. <c>Location</c> is one of - the following:</p> + <c>{error, <anno>Reason</anno>}</c>. <c><anno>Location</anno></c> is + one of the following:</p> <taglist> <tag><c>Offset</c></tag> <item> @@ -1167,7 +1048,8 @@ f.txt: {person, "kalle", 25}. <taglist> <tag><c>einval</c></tag> <item> - <p>Either <c>Location</c> was illegal, or it evaluated to a + <p>Either <c><anno>Location</anno></c> 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.</p> @@ -1176,22 +1058,14 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>pread(IoDevice, LocNums) -> {ok, DataL} | eof | {error, Reason}</name> + <name name="pread" arity="2"/> <fsummary>Read from a file at certain positions</fsummary> - <type> - <v>IoDevice = io_device()</v> - <v>LocNums = [{Location, Number}]</v> - <v> Location -- see position/2</v> - <v> Number = int()</v> - <v>DataL = [Data]</v> - <v> Data = [char()] | binary()</v> - <v>Reason = ext_posix() | terminated</v> - </type> <desc> <p>Performs a sequence of <c>pread/3</c> in one operation, which is more efficient than calling them one at a time. - Returns <c>{ok, [Data, ...]}</c> or <c>{error, Reason}</c>, - where each <c>Data</c>, the result of the corresponding + Returns <c>{ok, [<anno>Data</anno>, ...]}</c> or + <c>{error, <anno>Reason</anno>}</c>, + where each <c><anno>Data</anno></c>, the result of the corresponding <c>pread</c>, is either a list or a binary depending on the mode of the file, or <c>eof</c> if the requested position was beyond end of file.</p> @@ -1199,76 +1073,53 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>pread(IoDevice, Location, Number) -> {ok, Data} | eof | {error, Reason}</name> + <name name="pread" arity="3"/> <fsummary>Read from a file at a certain position</fsummary> - <type> - <v>IoDevice = io_device()</v> - <v>Location -- see position/2</v> - <v>Number = int()</v> - <v>Data = [char()] | binary()</v> - <v>Reason = ext_posix() | terminated</v> - </type> <desc> <p>Combines <c>position/2</c> and <c>read/2</c> in one operation, which is more efficient than calling them one at a - time. If <c>IoDevice</c> has been opened in raw mode, some - restrictions apply: <c>Location</c> is only allowed to be an + time. If <c><anno>IoDevice</anno></c> has been opened in raw mode, + some restrictions apply: <c><anno>Location</anno></c> is only allowed + to be an integer; and the current position of the file is undefined after the operation.</p> <p>As the position is given as a byte-offset, special caution has to be taken when working with files where <c>encoding</c> is set to something else than <c>latin1</c>, as not every byte position will be a valid character boundary on such a file.</p> </desc> </func> <func> - <name>pwrite(IoDevice, LocBytes) -> ok | {error, {N, Reason}}</name> + <name name="pwrite" arity="2"/> <fsummary>Write to a file at certain positions</fsummary> - <type> - <v>IoDevice = io_device()</v> - <v>LocBytes = [{Location, Bytes}]</v> - <v> Location -- see position/2</v> - <v> Bytes = iodata()</v> - <v>N = int()</v> - <v>Reason = ext_posix() | terminated</v> - </type> <desc> <p>Performs a sequence of <c>pwrite/3</c> in one operation, which is more efficient than calling them one at a time. - Returns <c>ok</c> or <c>{error, {N, Reason}}</c>, where - <c>N</c> is the number of successful writes that was done + Returns <c>ok</c> or <c>{error, {<anno>N</anno>, + <anno>Reason</anno>}}</c>, where + <c><anno>N</anno></c> is the number of successful writes that was done before the failure.</p> <p>When positioning in a file with other <c>encoding</c> than <c>latin1</c>, caution must be taken to set the position on a correct character boundary, see <seealso marker="#position/2">position/2</seealso> for details.</p> </desc> </func> <func> - <name>pwrite(IoDevice, Location, Bytes) -> ok | {error, Reason}</name> + <name name="pwrite" arity="3"/> <fsummary>Write to a file at a certain position</fsummary> - <type> - <v>IoDevice = io_device()</v> - <v>Location -- see position/2</v> - <v>Bytes = iodata()</v> - <v>Reason = ext_posix() | terminated</v> - </type> <desc> <p>Combines <c>position/2</c> and <c>write/2</c> in one operation, which is more efficient than calling them one at a - time. If <c>IoDevice</c> has been opened in raw mode, some - restrictions apply: <c>Location</c> is only allowed to be an + time. If <c><anno>IoDevice</anno></c> has been opened in raw mode, + some restrictions apply: <c><anno>Location</anno></c> is only allowed + to be an integer; and the current position of the file is undefined after the operation.</p> <p>When positioning in a file with other <c>encoding</c> than <c>latin1</c>, caution must be taken to set the position on a correct character boundary, see <seealso marker="#position/2">position/2</seealso> for details.</p> </desc> </func> <func> - <name>read(IoDevice, Number) -> {ok, Data} | eof | {error, Reason}</name> + <name name="read" arity="2"/> <fsummary>Read from a file</fsummary> - <type> - <v>IoDevice = io_device()</v> - <v>Number = int()</v> - <v>Data = [char()] | binary()</v> - <v>Reason = ext_posix() | terminated</v> - </type> <desc> - <p>Reads <c>Number</c> bytes/characters from the file referenced by - <c>IoDevice</c>. The functions <c>read/2</c>, <c>pread/3</c> + <p>Reads <c><anno>Number</anno></c> bytes/characters from the file + referenced by <c><anno>IoDevice</anno></c>. The functions + <c>read/2</c>, <c>pread/3</c> and <c>read_line/1</c> are the only ways to read from a file opened in raw mode (although they work for normally opened files, too).</p> @@ -1276,7 +1127,7 @@ f.txt: {person, "kalle", 25}. <p>Also if <c>encoding</c> is set to something else than <c>latin1</c>, the <c>read/3</c> call will fail if the data contains characters larger than 255, why the <seealso marker="stdlib:io">io(3)</seealso> module is to be preferred when reading such a file.</p> <p>The function returns:</p> <taglist> - <tag><c>{ok, Data}</c></tag> + <tag><c>{ok, <anno>Data</anno>}</c></tag> <item> <p>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}. </item> <tag><c>eof</c></tag> <item> - <p>Returned if <c>Number>0</c> and end of file was reached - before anything at all could be read.</p> + <p>Returned if <c><anno>Number</anno>>0</c> and end of file was + reached before anything at all could be read.</p> </item> - <tag><c>{error, Reason}</c></tag> + <tag><c>{error, <anno>Reason</anno>}</c></tag> <item> <p>An error occurred.</p> </item> @@ -1307,17 +1158,14 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>read_file(Filename) -> {ok, Binary} | {error, Reason}</name> + <name name="read_file" arity="1"/> <fsummary>Read a file</fsummary> - <type> - <v>Filename = name()</v> - <v>Binary = binary()</v> - <v>Reason = ext_posix() | terminated | system_limit</v> - </type> <desc> - <p>Returns <c>{ok, Binary}</c>, where <c>Binary</c> is a binary - data object that contains the contents of <c>Filename</c>, or - <c>{error, Reason}</c> if an error occurs.</p> + <p>Returns <c>{ok, <anno>Binary</anno>}</c>, where + <c><anno>Binary</anno></c> is a binary + data object that contains the contents of + <c><anno>Filename</anno></c>, or + <c>{error, <anno>Reason</anno>}</c> if an error occurs.</p> <p>Typical error reasons:</p> <taglist> <tag><c>enoent</c></tag> @@ -1346,17 +1194,13 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>read_file_info(Filename) -> {ok, FileInfo} | {error, Reason}</name> + <name name="read_file_info" arity="1"/> <fsummary>Get information about a file</fsummary> - <type> - <v>Filename = name()</v> - <v>FileInfo = #file_info{}</v> - <v>Reason = ext_posix()</v> - </type> <desc> <p>Retrieves information about a file. Returns - <c>{ok, FileInfo}</c> if successful, otherwise - <c>{error, Reason}</c>. <c>FileInfo</c> is a record + <c>{ok, <anno>FileInfo</anno>}</c> if successful, otherwise + <c>{error, <anno>Reason</anno>}</c>. <c><anno>FileInfo</anno></c> + is a record <c>file_info</c>, defined in the Kernel include file <c>file.hrl</c>. Include the following directive in the module from which the function is called:</p> @@ -1364,7 +1208,7 @@ f.txt: {person, "kalle", 25}. -include_lib("kernel/include/file.hrl").</code> <p>The record <c>file_info</c> contains the following fields.</p> <taglist> - <tag><c>size = int()</c></tag> + <tag><c>size = integer()</c></tag> <item> <p>Size of file in bytes.</p> </item> @@ -1391,7 +1235,7 @@ f.txt: {person, "kalle", 25}. the file or the inode was changed. In Windows, it is the create time.</p> </item> - <tag><c>mode = int()</c></tag> + <tag><c>mode = integer()</c></tag> <item> <p>The file permissions as the sum of the following bit values:</p> @@ -1422,33 +1266,33 @@ f.txt: {person, "kalle", 25}. <p>On Unix platforms, other bits than those listed above may be set.</p> </item> - <tag><c>links = int()</c></tag> + <tag><c>links = integer()</c></tag> <item> <p>Number of links to the file (this will always be 1 for file systems which have no concept of links).</p> </item> - <tag><c>major_device = int()</c></tag> + <tag><c>major_device = integer()</c></tag> <item> <p>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.</p> </item> - <tag><c>minor_device = int()</c></tag> + <tag><c>minor_device = integer()</c></tag> <item> <p>Only valid for character devices on Unix. In all other cases, this field is zero.</p> </item> - <tag><c>inode = int()</c></tag> + <tag><c>inode = integer()</c></tag> <item> <p>Gives the <c>inode</c> number. On non-Unix file systems, this field will be zero.</p> </item> - <tag><c>uid = int()</c></tag> + <tag><c>uid = integer()</c></tag> <item> <p>Indicates the owner of the file. Will be zero for non-Unix file systems.</p> </item> - <tag><c>gid = int()</c></tag> + <tag><c>gid = integer()</c></tag> <item> <p>Gives the group that the owner of the file belongs to. Will be zero for non-Unix file systems.</p> @@ -1474,21 +1318,16 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>read_line(IoDevice) -> {ok, Data} | eof | {error, Reason}</name> + <name name="read_line" arity="1"/> <fsummary>Read a line from a file</fsummary> - <type> - <v>IoDevice = io_device()</v> - <v>Data = [char()] | binary()</v> - <v>Reason = ext_posix() | terminated</v> - </type> <desc> <p>Reads a line of bytes/characters from the file referenced by - <c>IoDevice</c>. Lines are defined to be delimited by the linefeed (LF, <c>\n</c>) character, but any carriage return (CR, <c>\r</c>) followed by a newline is also treated as a single LF character (the carriage return is silently ignored). The line is returned <em>including</em> the LF, but excluding any CR immediately followed by a LF. This behaviour is consistent with the behaviour of <seealso marker="stdlib:io#get_line/2">io:get_line/2</seealso>. If end of file is reached without any LF ending the last line, a line with no trailing LF is returned.</p> + <c><anno>IoDevice</anno></c>. Lines are defined to be delimited by the linefeed (LF, <c>\n</c>) character, but any carriage return (CR, <c>\r</c>) followed by a newline is also treated as a single LF character (the carriage return is silently ignored). The line is returned <em>including</em> the LF, but excluding any CR immediately followed by a LF. This behaviour is consistent with the behaviour of <seealso marker="stdlib:io#get_line/2">io:get_line/2</seealso>. If end of file is reached without any LF ending the last line, a line with no trailing LF is returned.</p> <p>The function can be used on files opened in <c>raw</c> mode. It is however inefficient to use it on <c>raw</c> files if the file is not opened with the option <c>{read_ahead, Size}</c> specified, why combining <c>raw</c> and <c>{read_ahead, Size}</c> is highly recommended when opening a text file for raw line oriented reading.</p> <p>If <c>encoding</c> is set to something else than <c>latin1</c>, the <c>read_line/1</c> call will fail if the data contains characters larger than 255, why the <seealso marker="stdlib:io">io(3)</seealso> module is to be preferred when reading such a file.</p> <p>The function returns:</p> <taglist> - <tag><c>{ok, Data}</c></tag> + <tag><c>{ok, <anno>Data</anno>}</c></tag> <item> <p>One line from the file is returned, including the trailing LF, but with CRLF sequences replaced by a single LF (see above).</p> <p>If the file was opened in binary mode, the read bytes are @@ -1499,7 +1338,7 @@ f.txt: {person, "kalle", 25}. <p>Returned if end of file was reached before anything at all could be read.</p> </item> - <tag><c>{error, Reason}</c></tag> + <tag><c>{error, <anno>Reason</anno>}</c></tag> <item> <p>An error occurred.</p> </item> @@ -1518,23 +1357,19 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>read_link(Name) -> {ok, Filename} | {error, Reason}</name> + <name name="read_link" arity="1"/> <fsummary>See what a link is pointing to</fsummary> - <type> - <v>Name = name()</v> - <v>Filename = string()</v> - <v>Reason = ext_posix()</v> - </type> <desc> - <p>This function returns <c>{ok, Filename}</c> if <c>Name</c> - refers to a symbolic link or <c>{error, Reason}</c> otherwise. + <p>This function returns <c>{ok, <anno>Filename</anno>}</c> if + <c><anno>Name</anno></c> refers to a symbolic link or + <c>{error, <anno>Reason</anno>}</c> otherwise. On platforms that do not support symbolic links, the return value will be <c>{error,enotsup}</c>.</p> <p>Typical error reasons:</p> <taglist> <tag><c>einval</c></tag> <item> - <p><c>Linkname</c> does not refer to a symbolic link.</p> + <p><c><anno>Name</anno></c> does not refer to a symbolic link.</p> </item> <tag><c>enoent</c></tag> <item> @@ -1548,34 +1383,26 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>read_link_info(Name) -> {ok, FileInfo} | {error, Reason}</name> + <name name="read_link_info" arity="1"/> <fsummary>Get information about a link or file</fsummary> - <type> - <v>Name = name()</v> - <v>FileInfo = #file_info{}, see read_file_info/1</v> - <v>Reason = ext_posix()</v> - </type> <desc> <p>This function works like <c>read_file_info/1</c>, except that - if <c>Name</c> is a symbolic link, information about the link - will be returned in the <c>file_info</c> record and + if <c><anno>Name</anno></c> is a symbolic link, information about + the link will be returned in the <c>file_info</c> record and the <c>type</c> field of the record will be set to <c>symlink</c>.</p> - <p>If <c>Name</c> is not a symbolic link, this function returns + <p>If <c><anno>Name</anno></c> is not a symbolic link, this function returns exactly the same result as <c>read_file_info/1</c>. On platforms that do not support symbolic links, this function is always equivalent to <c>read_file_info/1</c>.</p> </desc> </func> <func> - <name>rename(Source, Destination) -> ok | {error, Reason}</name> + <name name="rename" arity="2"/> <fsummary>Rename a file</fsummary> - <type> - <v>Source = Destination = name()</v> - <v>Reason = ext_posix()</v> - </type> <desc> - <p>Tries to rename the file <c>Source</c> to <c>Destination</c>. + <p>Tries to rename the file <c><anno>Source</anno></c> to + <c><anno>Destination</anno></c>. 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}. <tag><c>eacces</c></tag> <item> <p>Missing read or write permissions for the parent - directories of <c>Source</c> or <c>Destination</c>. On + directories of <c><anno>Source</anno></c> or + <c><anno>Destination</anno></c>. On some platforms, this error is given if either - <c>Source</c> or <c>Destination</c> is open.</p> + <c><anno>Source</anno></c> or <c><anno>Destination</anno></c> + is open.</p> </item> <tag><c>eexist</c></tag> <item> - <p><c>Destination</c> is not an empty directory. On some - platforms, also given when <c>Source</c> and - <c>Destination</c> are not of the same type.</p> + <p><c><anno>Destination</anno></c> is not an empty directory. + On some platforms, also given when <c><anno>Source</anno></c> and + <c><anno>Destination</anno></c> are not of the same type.</p> </item> <tag><c>einval</c></tag> <item> - <p><c>Source</c> is a root directory, or <c>Destination</c> - is a sub-directory of <c>Source</c>.</p> + <p><c><anno>Source</anno></c> is a root directory, or + <c><anno>Destination</anno></c> + is a sub-directory of <c><anno>Source</anno></c>.</p> </item> <tag><c>eisdir</c></tag> <item> - <p><c>Destination</c> is a directory, but <c>Source</c> is - not.</p> + <p><c><anno>Destination</anno></c> is a directory, but + <c><anno>Source</anno></c> is not.</p> </item> <tag><c>enoent</c></tag> <item> @@ -1619,35 +1449,28 @@ f.txt: {person, "kalle", 25}. </item> <tag><c>enotdir</c></tag> <item> - <p><c>Source</c> is a directory, but <c>Destination</c> is - not.</p> + <p><c><anno>Source</anno></c> is a directory, but + <c><anno>Destination</anno></c> is not.</p> </item> <tag><c>exdev</c></tag> <item> - <p><c>Source</c> and <c>Destination</c> are on different - file systems.</p> + <p><c><anno>Source</anno></c> and <c><anno>Destination</anno></c> + are on different file systems.</p> </item> </taglist> </desc> </func> <func> - <name>script(Filename) -> {ok, Value} | {error, Reason}</name> + <name name="script" arity="1"/> <fsummary>Evaluate and return the value of Erlang expressions in a file</fsummary> - <type> - <v>Filename = name()</v> - <v>Value = term()</v> - <v>Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term}</v> - <v> Line, Mod, Term -- see below</v> - </type> <desc> <p>Reads and evaluates Erlang expressions, separated by '.' (or ',', a sequence of expressions is also an expression), from the file. Returns one of the following:</p> <taglist> - <tag><c>{ok, Value}</c></tag> + <tag><c>{ok, <anno>Value</anno>}</c></tag> <item> - <p>The file was read and evaluated. <c>Value</c> is + <p>The file was read and evaluated. <c><anno>Value</anno></c> is the value of the last expression.</p> </item> <tag><c>{error, atom()}</c></tag> @@ -1656,7 +1479,8 @@ f.txt: {person, "kalle", 25}. See <seealso marker="#open/2">open/2</seealso> for a list of typical error codes.</p> </item> - <tag><c>{error, {Line, Mod, Term}}</c></tag> + <tag><c>{error, {<anno>Line</anno>, <anno>Mod</anno>, + <anno>Term</anno>}}</c></tag> <item> <p>An error occurred when interpreting the Erlang expressions in the file. Use <c>format_error/1</c> to @@ -1667,33 +1491,21 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>script(Filename, Bindings) -> {ok, Value} | {error, Reason}</name> + <name name="script" arity="2"/> <fsummary>Evaluate and return the value of Erlang expressions in a file</fsummary> - <type> - <v>Filename = name()</v> - <v>Bindings -- see erl_eval(3)</v> - <v>Value = term()</v> - <v>Reason = ext_posix() | terminated | system_limit - | {Line, Mod, Term}</v> - <v> Line, Mod, Term -- see below</v> - </type> <desc> <p>The same as <c>script/1</c> but the variable bindings - <c>Bindings</c> are used in the evaluation. See + <c><anno>Bindings</anno></c> are used in the evaluation. See <seealso marker="stdlib:erl_eval">erl_eval(3)</seealso> about variable bindings.</p> </desc> </func> <func> - <name>set_cwd(Dir) -> ok | {error,Reason}</name> + <name name="set_cwd" arity="1"/> <fsummary>Set the current working directory</fsummary> - <type> - <v>Dir = name()</v> - <v>Reason = ext_posix()</v> - </type> <desc> <p>Sets the current working directory of the file server to - <c>Dir</c>. Returns <c>ok</c> if successful.</p> + <c><anno>Dir</anno></c>. Returns <c>ok</c> if successful.</p> <p>Typical error reasons are:</p> <taglist> <tag><c>enoent</c></tag> @@ -1702,8 +1514,8 @@ f.txt: {person, "kalle", 25}. </item> <tag><c>enotdir</c></tag> <item> - <p>A component of <c>Dir</c> is not a directory. On some - platforms, <c>enoent</c> is returned.</p> + <p>A component of <c><anno>Dir</anno></c> is not a directory. + On some platforms, <c>enoent</c> is returned.</p> </item> <tag><c>eacces</c></tag> <item> @@ -1712,23 +1524,21 @@ f.txt: {person, "kalle", 25}. </item> <tag><c>badarg</c></tag> <item> - <p><c>Filename</c> had an improper type, such as tuple.</p> + <p><c><anno>Dir</anno></c> had an improper type, + such as tuple.</p> </item> </taglist> <warning> - <p>In a future release, a bad type for the <c>Filename</c> + <p>In a future release, a bad type for the + <c><anno>Dir</anno></c> argument will probably generate an exception.</p> <p></p> </warning> </desc> </func> <func> - <name>sync(IoDevice) -> ok | {error, Reason}</name> + <name name="sync" arity="1"/> <fsummary>Synchronizes the in-memory state of a file with that on the physical medium</fsummary> - <type> - <v>IoDevice = io_device()</v> - <v>Reason = ext_posix() | terminated</v> - </type> <desc> <p>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}. </desc> </func> <func> - <name>datasync(IoDevice) -> ok | {error, Reason}</name> + <name name="datasync" arity="1"/> <fsummary>Synchronizes the in-memory data of a file, ignoring most of its metadata, with that on the physical medium</fsummary> - <type> - <v>IoDevice = io_device()</v> - <v>Reason = ext_posix() | terminated</v> - </type> <desc> <p>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}. </desc> </func> <func> - <name>truncate(IoDevice) -> ok | {error, Reason}</name> + <name name="truncate" arity="1"/> <fsummary>Truncate a file</fsummary> - <type> - <v>IoDevice = io_device()</v> - <v>Reason = ext_posix() | terminated</v> - </type> <desc> - <p>Truncates the file referenced by <c>IoDevice</c> at + <p>Truncates the file referenced by <c><anno>IoDevice</anno></c> at the current position. Returns <c>ok</c> if successful, - otherwise <c>{error, Reason}</c>.</p> + otherwise <c>{error, <anno>Reason</anno>}</c>.</p> </desc> </func> <func> - <name>write(IoDevice, Bytes) -> ok | {error, Reason}</name> + <name name="write" arity="2"/> <fsummary>Write to a file</fsummary> - <type> - <v>IoDevice = io_device()</v> - <v>Bytes = iodata()</v> - <v>Reason = ext_posix() | terminated</v> - </type> <desc> - <p>Writes <c>Bytes</c> to the file referenced by - <c>IoDevice</c>. This function is the only way to write to a + <p>Writes <c><anno>Bytes</anno></c> to the file referenced by + <c><anno>IoDevice</anno></c>. This function is the only way to write to a file opened in raw mode (although it works for normally opened files, too). Returns <c>ok</c> if successful, and - <c>{error, Reason}</c> otherwise.</p> + <c>{error, <anno>Reason</anno>}</c> otherwise.</p> <p>If the file is opened with <c>encoding</c> set to something else than <c>latin1</c>, 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.</p> <p>Typical error reasons are:</p> <taglist> @@ -1811,18 +1608,14 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>write_file(Filename, Bytes) -> ok | {error, Reason}</name> + <name name="write_file" arity="2"/> <fsummary>Write a file</fsummary> - <type> - <v>Filename = name()</v> - <v>Bytes = iodata()</v> - <v>Reason = ext_posix() | terminated | system_limit</v> - </type> <desc> - <p>Writes the contents of the iodata term <c>Bytes</c> to the - file <c>Filename</c>. The file is created if it does not + <p>Writes the contents of the iodata term <c><anno>Bytes</anno></c> + to the file <c><anno>Filename</anno></c>. + The file is created if it does not exist. If it exists, the previous contents are - overwritten. Returns <c>ok</c>, or <c>{error, Reason}</c>.</p> + overwritten. Returns <c>ok</c>, or <c>{error, <anno>Reason</anno>}</c>.</p> <p>Typical error reasons are:</p> <taglist> <tag><c>enoent</c></tag> @@ -1851,33 +1644,23 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>write_file(Filename, Bytes, Modes) -> ok | {error, Reason}</name> + <name name="write_file" arity="3"/> <fsummary>Write a file</fsummary> - <type> - <v>Filename = name()</v> - <v>Bytes = iodata()</v> - <v>Modes = [Mode] -- see open/2</v> - <v>Reason = ext_posix() | terminated | system_limit</v> - </type> <desc> <p>Same as <c>write_file/2</c>, but takes a third argument - <c>Modes</c>, a list of possible modes, see + <c><anno>Modes</anno></c>, a list of possible modes, see <seealso marker="#open/2">open/2</seealso>. The mode flags <c>binary</c> and <c>write</c> are implicit, so they should not be used.</p> </desc> </func> <func> - <name>write_file_info(Filename, FileInfo) -> ok | {error, Reason}</name> + <name name="write_file_info" arity="2"/> <fsummary>Change information about a file</fsummary> - <type> - <v>Filename = name()</v> - <v>FileInfo = #file_info{} -- see also read_file_info/1</v> - <v>Reason = ext_posix()</v> - </type> <desc> <p>Change file information. Returns <c>ok</c> if successful, - otherwise <c>{error, Reason}</c>. <c>FileInfo</c> is a record + otherwise <c>{error, <anno>Reason</anno>}</c>. + <c><anno>FileInfo</anno></c> is a record <c>file_info</c>, defined in the Kernel include file <c>file.hrl</c>. Include the following directive in the module from which the function is called:</p> @@ -1901,7 +1684,7 @@ f.txt: {person, "kalle", 25}. time). On Windows, this field is the new creation time to set for the file.</p> </item> - <tag><c>mode = int()</c></tag> + <tag><c>mode = integer()</c></tag> <item> <p>The file permissions as the sum of the following bit values:</p> @@ -1932,12 +1715,12 @@ f.txt: {person, "kalle", 25}. <p>On Unix platforms, other bits than those listed above may be set.</p> </item> - <tag><c>uid = int()</c></tag> + <tag><c>uid = integer()</c></tag> <item> <p>Indicates the owner of the file. Ignored for non-Unix file systems.</p> </item> - <tag><c>gid = int()</c></tag> + <tag><c>gid = integer()</c></tag> <item> <p>Gives the group that the owner of the file belongs to. Ignored non-Unix file systems.</p> |