aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorBjörn Gustavsson <bjorn@erlang.org>2013-02-22 11:03:43 +0100
committerBjörn Gustavsson <bjorn@erlang.org>2013-02-22 11:03:43 +0100
commitb9a21d85d17b74fcec78565082d30a613c1fe192 (patch)
treee1f2b0bdaa38522ffa3eae8f381052e59b4866f9
parentcd312a8ed8742705d3af46df09017619827b30e3 (diff)
parent9dd60c47d4e91f39933edc97840bbd68f10c55d8 (diff)
downloadotp-b9a21d85d17b74fcec78565082d30a613c1fe192.tar.gz
otp-b9a21d85d17b74fcec78565082d30a613c1fe192.tar.bz2
otp-b9a21d85d17b74fcec78565082d30a613c1fe192.zip
Merge branch 'bjorn/unicode-doc/OTP-10852'
* bjorn/unicode-doc/OTP-10852: file: Document list_dir_all/1 and read_link_all/1 file: Remove note about Unicode handling being experimental filelib: Update documentation
-rw-r--r--lib/kernel/doc/src/file.xml67
-rw-r--r--lib/stdlib/doc/src/filelib.xml5
2 files changed, 61 insertions, 11 deletions
diff --git a/lib/kernel/doc/src/file.xml b/lib/kernel/doc/src/file.xml
index 069b13eacf..22a04c6c13 100644
--- a/lib/kernel/doc/src/file.xml
+++ b/lib/kernel/doc/src/file.xml
@@ -60,14 +60,6 @@
converted, why the Unicode mode for file names is not default on
systems having completely transparent file naming.</p>
- <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>
-
<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
@@ -504,7 +496,8 @@
<name name="list_dir" arity="1"/>
<fsummary>List files in a directory</fsummary>
<desc>
- <p>Lists all the files in a directory. Returns
+ <p>Lists all files in a directory, <b>except</b> files
+ with "raw" names. Returns
<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
@@ -525,6 +518,31 @@
</desc>
</func>
<func>
+ <name name="list_dir_all" arity="1"/>
+ <fsummary>List all files in a directory</fsummary>
+ <desc>
+ <p>Lists all the files in a directory, including files with
+ "raw" names.
+ Returns <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><anno>Dir</anno></c>
+ or one of its parent directories.</p>
+ </item>
+ <tag><c>enoent</c></tag>
+ <item>
+ <p>The directory does not exist.</p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
<name name="make_dir" arity="1"/>
<fsummary>Make a directory</fsummary>
<desc>
@@ -1409,10 +1427,41 @@
<fsummary>See what a link is pointing to</fsummary>
<desc>
<p>This function returns <c>{ok, <anno>Filename</anno>}</c> if
+ <c><anno>Name</anno></c> refers to a symbolic link that is
+ not a "raw" file name, 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><anno>Name</anno></c> does not refer to a symbolic link
+ or the name of the file that it refers to does not conform
+ to the expected encoding.</p>
+ </item>
+ <tag><c>enoent</c></tag>
+ <item>
+ <p>The file does not exist.</p>
+ </item>
+ <tag><c>enotsup</c></tag>
+ <item>
+ <p>Symbolic links are not supported on this platform.</p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name name="read_link_all" arity="1"/>
+ <fsummary>See what a link is pointing to</fsummary>
+ <desc>
+ <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>Note that <c><anno>Filename</anno></c> can be either a list
+ or a binary.</p>
<p>Typical error reasons:</p>
<taglist>
<tag><c>einval</c></tag>
diff --git a/lib/stdlib/doc/src/filelib.xml b/lib/stdlib/doc/src/filelib.xml
index ac67596f3c..bd780b2b2f 100644
--- a/lib/stdlib/doc/src/filelib.xml
+++ b/lib/stdlib/doc/src/filelib.xml
@@ -36,8 +36,9 @@
<description>
<p>This module contains utilities on a higher level than the <c>file</c>
module.</p>
- <p>The module supports Unicode file names, so that it will match against regular expressions given in Unicode and that it will find and process raw file names (i.e. files named in a way that does not confirm to the expected encoding).</p>
- <p>If the VM operates in Unicode file naming mode on a machine with transparent file naming, the <c>fun()</c> provided to <c>fold_files/5</c> needs to be prepared to handle binary file names.</p>
+ <p>This module does not support "raw" file names (i.e. files whose names
+ do not comply with the expected encoding). Such files will be ignored
+ by the functions in this module.</p>
<p>For more information about raw file names, see the <seealso marker="kernel:file">file</seealso> module.</p>
</description>