aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/file.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/kernel/doc/src/file.xml')
-rw-r--r--lib/kernel/doc/src/file.xml69
1 files changed, 49 insertions, 20 deletions
diff --git a/lib/kernel/doc/src/file.xml b/lib/kernel/doc/src/file.xml
index c6a1f25dd9..772eff13cc 100644
--- a/lib/kernel/doc/src/file.xml
+++ b/lib/kernel/doc/src/file.xml
@@ -150,6 +150,9 @@
<name name="mode"/>
</datatype>
<datatype>
+ <name name="file_info_option"/>
+ </datatype>
+ <datatype>
<name name="sendfile_option"/>
</datatype>
</datatypes>
@@ -412,7 +415,7 @@
<name>file_info(Filename) -> {ok, FileInfo} | {error, Reason}</name>
<fsummary>Get information about a file (deprecated)</fsummary>
<desc>
- <p>This function is obsolete. Use <c>read_file_info/1</c>
+ <p>This function is obsolete. Use <c>read_file_info/1,2</c>
instead.</p>
</desc>
</func>
@@ -539,7 +542,7 @@
<desc>
<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
+ platforms that support links (Unix and Windows). This function returns
<c>ok</c> if the link was successfully created, or
<c>{error, <anno>Reason</anno>}</c>. On platforms that do not support
links, <c>{error,enotsup}</c> is returned.</p>
@@ -566,11 +569,12 @@
<name name="make_symlink" arity="2"/>
<fsummary>Make a symbolic link to a file or directory</fsummary>
<desc>
- <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
+ <p>This function creates a symbolic link <c><anno>New</anno></c> to
+ the file or directory <c><anno>Existing</anno></c>, on platforms that
+ support symbolic links (most Unix systems and Windows beginning with
+ Vista).
+ <c><anno>Existing</anno></c> need not exist.
+ This function returns <c>ok</c> if the link was
successfully created, or <c>{error, <anno>Reason</anno>}</c>.
On platforms
that do not support symbolic links, <c>{error, enotsup}</c>
@@ -580,11 +584,11 @@
<tag><c>eacces</c></tag>
<item>
<p>Missing read or write permissions for the parent directories
- of <c><anno>Name1</anno></c> or <c><anno>Name2</anno></c>.</p>
+ of <c><anno>Existing</anno></c> or <c><anno>New</anno></c>.</p>
</item>
<tag><c>eexist</c></tag>
<item>
- <p><c><anno>Name2</anno></c> already exists.</p>
+ <p><c><anno>New</anno></c> already exists.</p>
</item>
<tag><c>enotsup</c></tag>
<item>
@@ -1188,6 +1192,7 @@
</func>
<func>
<name name="read_file_info" arity="1"/>
+ <name name="read_file_info" arity="2"/>
<fsummary>Get information about a file</fsummary>
<desc>
<p>Retrieves information about a file. Returns
@@ -1199,6 +1204,20 @@
from which the function is called:</p>
<code type="none">
-include_lib("kernel/include/file.hrl").</code>
+ <p>The time type returned in <c>atime</c>, <c>mtime</c> and <c>ctime</c>
+ is dependent on the time type set in <c>Opts :: {time, Type}</c>.
+ Type <c>local</c> will return local time, <c>universal</c> will
+ return universal time and <c>posix</c> will return seconds since
+ or before unix time epoch which is 1970-01-01 00:00 UTC.
+ Default is <c>{time, local}</c>.
+ </p>
+ <note>
+ <p>
+ Since file times is stored in posix time on most OS it is
+ faster to query file information with the <c>posix</c> option.
+ </p>
+ </note>
+
<p>The record <c>file_info</c> contains the following fields.</p>
<taglist>
<tag><c>size = integer()</c></tag>
@@ -1213,15 +1232,15 @@
<item>
<p>The current system access to the file.</p>
</item>
- <tag><c>atime = <seealso marker="#type-date_time">date_time()</seealso></c></tag>
+ <tag><c>atime = <seealso marker="#type-date_time">date_time()</seealso> | integer() </c></tag>
<item>
- <p>The last (local) time the file was read.</p>
+ <p>The last time the file was read.</p>
</item>
- <tag><c>mtime = <seealso marker="#type-date_time">date_time()</seealso></c></tag>
+ <tag><c>mtime = <seealso marker="#type-date_time">date_time()</seealso> | integer() </c></tag>
<item>
- <p>The last (local) time the file was written.</p>
+ <p>The last time the file was written.</p>
</item>
- <tag><c>ctime = <seealso marker="#type-date_time">date_time()</seealso></c></tag>
+ <tag><c>ctime = <seealso marker="#type-date_time">date_time()</seealso> | integer() </c></tag>
<item>
<p>The interpretation of this time field depends on
the operating system. On Unix, it is the last time
@@ -1377,9 +1396,11 @@
</func>
<func>
<name name="read_link_info" arity="1"/>
+ <name name="read_link_info" arity="2"/>
<fsummary>Get information about a link or file</fsummary>
<desc>
- <p>This function works like <c>read_file_info/1</c>, except that
+ <p>This function works like
+ <seealso marker="#read_file_info/2">read_file_info/1,2</seealso> except that
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
@@ -1690,6 +1711,7 @@
</func>
<func>
<name name="write_file_info" arity="2"/>
+ <name name="write_file_info" arity="3"/>
<fsummary>Change information about a file</fsummary>
<desc>
<p>Change file information. Returns <c>ok</c> if successful,
@@ -1700,18 +1722,25 @@
from which the function is called:</p>
<code type="none">
-include_lib("kernel/include/file.hrl").</code>
+ <p>The time type set in <c>atime</c>, <c>mtime</c> and <c>ctime</c>
+ is dependent on the time type set in <c>Opts :: {time, Type}</c>.
+ Type <c>local</c> will interpret the time set as local, <c>universal</c> will
+ interpret it as universal time and <c>posix</c> must be seconds since
+ or before unix time epoch which is 1970-01-01 00:00 UTC.
+ Default is <c>{time, local}</c>.
+ </p>
<p>The following fields are used from the record, if they are
given.</p>
<taglist>
- <tag><c>atime = <seealso marker="#type-date_time">date_time()</seealso></c></tag>
+ <tag><c>atime = <seealso marker="#type-date_time">date_time()</seealso> | integer()</c></tag>
<item>
- <p>The last (local) time the file was read.</p>
+ <p>The last time the file was read.</p>
</item>
- <tag><c>mtime = <seealso marker="#type-date_time">date_time()</seealso></c></tag>
+ <tag><c>mtime = <seealso marker="#type-date_time">date_time()</seealso> | integer()</c></tag>
<item>
- <p>The last (local) time the file was written.</p>
+ <p>The last time the file was written.</p>
</item>
- <tag><c>ctime = <seealso marker="#type-date_time">date_time()</seealso></c></tag>
+ <tag><c>ctime = <seealso marker="#type-date_time">date_time()</seealso> | integer()</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