diff options
Diffstat (limited to 'lib/kernel/doc/src/file.xml')
| -rw-r--r-- | lib/kernel/doc/src/file.xml | 992 |
1 files changed, 453 insertions, 539 deletions
diff --git a/lib/kernel/doc/src/file.xml b/lib/kernel/doc/src/file.xml index f9f5443f68..7db20e6343 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>2009</year> + <year>1996</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -13,12 +13,12 @@ compliance with the License. You should have received a copy of the Erlang Public License along with this software. If not, it can be retrieved online at http://www.erlang.org/. - + Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. - + </legalnotice> <title>file</title> @@ -36,106 +36,186 @@ other Erlang processes to continue executing in parallel with the file operations. See the command line flag <c>+A</c> in <seealso marker="erts:erl">erl(1)</seealso>.</p> - </description> - <section> - <title>DATA TYPES</title> - <code type="none"> -iodata() = iolist() | binary() - iolist() = [char() | binary() | iolist()] + <p>The Erlang VM supports file names in Unicode to a limited + extent. Depending on how the VM is started (with the parameter + <c>+fnu</c> or <c>+fnl</c>), file names given can contain + characters > 255 and the VM system will convert file names + back and forth to the native file name encoding.</p> -io_device() - as returned by file:open/2, a process handling IO protocols + <p>The default behavior for Unicode character translation depends + on to what extent the underlying OS/filesystem enforces consistent + naming. On OSes where all file names are ensured to be in one or + another encoding, Unicode is the default (currently this holds for + Windows and MacOSX). On OSes with completely transparent file + naming (i.e. all Unixes except MacOSX), ISO-latin-1 file naming is + the default. The reason for the ISO-latin-1 default is that + file names are not guaranteed to be possible to interpret according to + the Unicode encoding expected (i.e. UTF-8), and file names that + cannot be decoded will only be accessible by using "raw + file names", in other word file names given as binaries.</p> + + <p>As file names are traditionally not binaries in Erlang, + applications that need to handle raw file names need to be + converted, why the Unicode mode for file names is not default on + systems having completely transparent file naming.</p> -name() = string() | atom() | DeepList - DeepList = [char() | atom() | DeepList] + <note> + <p>As of R14B01, the most basic file handling modules + (<c>file</c>, <c>prim_file</c>, <c>filelib</c> and + <c>filename</c>) accept raw file names, but the rest of OTP is not + guaranteed to handle them, why Unicode file naming on systems + where it is not default is still considered experimental.</p> + </note> -posix() - an atom which is named from the POSIX error codes used in - Unix, and in the runtime libraries of most C compilers + <p>Raw file names is a new feature in OTP R14B01, which allows the + user to supply completely uninterpreted file names to the + underlying OS/filesystem. They are supplied as binaries, where it + is up to the user to supply a correct encoding for the + environment. The function <c>file:native_name_encoding()</c> can + be used to check what encoding the VM is working in. If the + function returns <c>latin1</c> file names are not in any way + converted to Unicode, if it is <c>utf8</c>, raw file names should + be encoded as UTF-8 if they are to follow the convention of the VM + (and usually the convention of the OS as well). Using raw + file names is useful if you have a filesystem with inconsistent + file naming, where some files are named in UTF-8 encoding while + others are not. A file:list_dir on such mixed file name systems + when the VM is in Unicode file name mode might return file names as + raw binaries as they cannot be interpreted as Unicode + file names. Raw file names can also be used to give UTF-8 encoded + file names even though the VM is not started in Unicode file name + translation mode.</p> -ext_posix() = posix() | badarg + <p>Note that on Windows, <c>file:native_name_encoding()</c> + returns <c>utf8</c> per default, which is the format for raw + file names even on Windows, although the underlying OS specific + code works in a limited version of little endian UTF16. As far as + the Erlang programmer is concerned, Windows native Unicode format + is UTF-8...</p> + </description> + + <datatypes> + <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_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>change_group(Filename, Gid) -> ok | {error, Reason}</name> + <name name="advise" arity="4"/> + <fsummary>Predeclare an access pattern for file data</fsummary> + <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 + operating system to perform appropriate optimizations.</p> + <p>On some platforms, this function might have no effect.</p> + </desc> + </func> + <func> + <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_owner(Filename, Uid) -> ok | {error, Reason}</name> + <name name="change_mode" arity="2"/> + <fsummary>Change permissions of a file</fsummary> + <desc> + <p>Changes permissions of a file. See + <seealso marker="#write_file_info/2">write_file_info/2</seealso>.</p> + </desc> + </func> + <func> + <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 @@ -145,20 +225,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> @@ -168,7 +241,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 @@ -177,62 +251,53 @@ time() = {{Year, Month, Day}, {Hour, Minute, Second}} </item> </taglist> <p>Example:</p> - <code type="none"> -f.txt: {person, "kalle", 25}. +<code type="none">f.txt: {person, "kalle", 25}. {person, "pelle", 30}.</code> - <pre> -1> <input>file:consult("f.txt").</input> +<pre>1> <input>file:consult("f.txt").</input> {ok,[{person,"kalle",25},{person,"pelle",30}]}</pre> </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> @@ -240,7 +305,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> @@ -252,8 +317,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> @@ -264,15 +329,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> @@ -294,30 +355,24 @@ 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></p> + <p>In a future release, a bad type for the + <c><anno>Filename</anno></c> argument will probably generate + an exception.</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> @@ -329,7 +384,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 @@ -340,18 +396,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> @@ -365,27 +414,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. @@ -403,17 +444,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> @@ -421,7 +459,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> @@ -429,32 +467,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> @@ -464,14 +497,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> @@ -479,15 +508,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> @@ -495,35 +524,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> @@ -533,30 +560,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> @@ -566,20 +591,21 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>open(Filename, Modes) -> {ok, IoDevice} | {error, Reason}</name> + <name>native_name_encoding() -> latin1 | utf8</name> + <fsummary>Return the VM's configured filename encoding.</fsummary> + <desc> + <p>This function returns the configured default file name encoding to use for raw file names. Generally an application supplying file names raw (as binaries), should obey the character encoding returned by this function.</p> + <p>By default, the VM uses ISO-latin-1 file name encoding on filesystems and/or OSes that use completely transparent file naming. This includes all Unix versions except MacOSX, where the vfs layer enforces UTF-8 file naming. By giving the experimental option <c>+fnu</c> when starting Erlang, UTF-8 translation of file names can be turned on even for those systems. If Unicode file name translation is in effect, the system behaves as usual as long as file names conform to the encoding, but will return file names that are not properly encoded in UTF-8 as raw file names (i.e. binaries).</p> + <p>On Windows, this function also returns <c>utf8</c> by default. The OS uses a pure Unicode naming scheme and file names are always possible to interpret as valid Unicode. The fact that the underlying Windows OS actually encodes file names using little endian UTF-16 can be ignored by the Erlang programmer. Windows and MacOSX are the only operating systems where the VM operates in Unicode file name mode by default.</p> + </desc> + </func> + <func> + <name name="open" arity="2"/> <fsummary>Open a file</fsummary> - <type> - <v>Filename = name()</v> - <v>Modes = [Mode]</v> - <v> Mode = read | write | append | raw | binary | {delayed_write, Size, Delay} | delayed_write | {read_ahead, Size} | read_ahead | compressed</v> - <v> Size = Delay = int()</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> @@ -598,6 +624,17 @@ f.txt: {person, "kalle", 25}. file opened with <c>append</c> will take place at the end of the file.</p> </item> + <tag><c>exclusive</c></tag> + <item> + <p>The file, when opened for writing, is created if it + does not exist. If the file exists, open will return + <c>{error, eexist}</c>.</p> + <warning><p>This option does not guarantee exclusiveness on + file systems that do not support O_EXCL properly, + such as NFS. Do not depend on this option unless you + know that the file system supports it (in general, local + file systems should be safe).</p></warning> + </item> <tag><c>raw</c></tag> <item> <p>The <c>raw</c> option allows faster access to a file, @@ -726,23 +763,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 @@ -782,34 +819,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> @@ -817,7 +845,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 @@ -828,36 +857,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> @@ -865,7 +886,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 @@ -876,34 +898,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> @@ -913,36 +927,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> @@ -950,7 +955,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 @@ -961,42 +967,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> @@ -1010,21 +1002,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> @@ -1052,7 +1038,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> @@ -1061,22 +1048,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> @@ -1084,76 +1063,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> @@ -1161,7 +1117,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 @@ -1170,10 +1126,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> @@ -1186,23 +1142,20 @@ f.txt: {person, "kalle", 25}. </item> <tag><c>{no_translation, unicode, latin1}</c></tag> <item> - <p>The file is was opened with another <c>encoding</c> than <c>latin1</c> and the data on the file can not be translated to the byte-oriented data that this function returns.</p> + <p>The file was opened with another <c>encoding</c> than <c>latin1</c> and the data in the file can not be translated to the byte-oriented data that this function returns.</p> </item> </taglist> </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> @@ -1231,17 +1184,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> @@ -1249,7 +1198,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> @@ -1261,22 +1210,22 @@ f.txt: {person, "kalle", 25}. <item> <p>The current system access to the file.</p> </item> - <tag><c>atime = time()</c></tag> + <tag><c>atime = <seealso marker="#type-date_time">date_time()</seealso></c></tag> <item> <p>The last (local) time the file was read.</p> </item> - <tag><c>mtime = time()</c></tag> + <tag><c>mtime = <seealso marker="#type-date_time">date_time()</seealso></c></tag> <item> <p>The last (local) time the file was written.</p> </item> - <tag><c>ctime = time()</c></tag> + <tag><c>ctime = <seealso marker="#type-date_time">date_time()</seealso></c></tag> <item> <p>The interpretation of this time field depends on the operating system. On Unix, it is the last time the file or the inode was changed. In Windows, it is the create time.</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> @@ -1307,33 +1256,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> @@ -1359,21 +1308,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 @@ -1384,7 +1328,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> @@ -1403,23 +1347,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> @@ -1433,34 +1373,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 @@ -1478,25 +1410,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> @@ -1504,35 +1439,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> @@ -1541,7 +1469,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 @@ -1552,33 +1481,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> @@ -1587,8 +1504,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> @@ -1597,23 +1514,20 @@ 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 @@ -1628,32 +1542,46 @@ f.txt: {person, "kalle", 25}. </desc> </func> <func> - <name>truncate(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> + <desc> + <p>Makes sure that any buffers kept by the operating system + (not by the Erlang runtime system) are written to disk. In + many ways it's resembles fsync but it not requires to update + some of file's metadata such as the access time. On + some platforms, this function might have no effect.</p> + <p>Applications that access databases or log files often write + a tiny data fragment (e.g., one line in a log file) and then + call fsync() immediately in order to ensure that the written + data is physically stored on the harddisk. Unfortunately, fsync() + will always initiate two write operations: one for the newly + written data and another one in order to update the modification + time stored in the inode. If the modification time is not a part + of the transaction concept fdatasync() can be used to avoid + unnecessary inode disk write operations.</p> + <p>Available only in some POSIX systems. This call results in a + call to fsync(), or has no effect, in systems not implementing + the fdatasync syscall.</p> + </desc> + </func> + <func> + <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> @@ -1669,18 +1597,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> @@ -1709,33 +1633,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> @@ -1744,22 +1658,22 @@ f.txt: {person, "kalle", 25}. <p>The following fields are used from the record, if they are given.</p> <taglist> - <tag><c>atime = time()</c></tag> + <tag><c>atime = <seealso marker="#type-date_time">date_time()</seealso></c></tag> <item> <p>The last (local) time the file was read.</p> </item> - <tag><c>mtime = time()</c></tag> + <tag><c>mtime = <seealso marker="#type-date_time">date_time()</seealso></c></tag> <item> <p>The last (local) time the file was written.</p> </item> - <tag><c>ctime = time()</c></tag> + <tag><c>ctime = <seealso marker="#type-date_time">date_time()</seealso></c></tag> <item> <p>On Unix, any value give for this field will be ignored (the "ctime" for the file will be set to the current time). On Windows, this field is the new creation time to set for the file.</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> @@ -1790,12 +1704,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> |