Merge tag 'OTP-19.0' into sverker/19/binary_to_atom-utf8-crash/ERL-474/OTP-14590

1 files changed, 114 insertions, 101 deletions

diff --git a/lib/stdlib/doc/src/filelib.xml b/lib/stdlib/doc/src/filelib.xml
index bd780b2b2f..7c6380ce28 100644
--- a/lib/stdlib/doc/src/filelib.xml
+++ b/lib/stdlib/doc/src/filelib.xml
@@ -1,23 +1,24 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
 <!DOCTYPE erlref SYSTEM "erlref.dtd">
 
 <erlref>
   <header>
     <copyright>
-      <year>2003</year><year>2013</year>
+      <year>2003</year><year>2016</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
-      The contents of this file are subject to the Erlang Public License,
-      Version 1.1, (the "License"); you may not use this file except in
-      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.
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+ 
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.
     
     </legalnotice>
 
@@ -27,19 +28,23 @@
     <docno>1</docno>
     <approved>Kenneth Lundin</approved>
     <checked></checked>
-    <date>03-01-21</date>
+    <date>2003-01-21</date>
     <rev>A</rev>
-    <file>filelib.sgml</file>
+    <file>filelib.xml</file>
   </header>
   <module>filelib</module>
-  <modulesummary>File utilities, such as wildcard matching of filenames</modulesummary>
+  <modulesummary>File utilities, such as wildcard matching of filenames.
+  </modulesummary>
   <description>
-    <p>This module contains utilities on a higher level than the <c>file</c>
-      module.</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>
+    <p>This module contains utilities on a higher level than the
+      <seealso marker="kernel:file"><c>file</c></seealso> module.</p>
+
+    <p>This module does not support "raw" filenames (that is, files whose
+      names do not comply with the expected encoding). Such files are ignored
+      by the functions in this module.</p>
+
+    <p>For more information about raw filenames, see the
+      <seealso marker="kernel:file"><c>file</c></seealso> module.</p>
   </description>
 
   <datatypes>
@@ -49,98 +54,110 @@
     <datatype>
       <name name="dirname"/>
     </datatype>
+    <datatype>
+      <name name="dirname_all"/>
+    </datatype>
+    <datatype>
+      <name name="filename_all"/>
+    </datatype>
   </datatypes>
 
   <funcs>
     <func>
       <name name="ensure_dir" arity="1"/>
-      <fsummary>Ensure that all parent directories for a file or directory exist.</fsummary>
+      <fsummary>Ensure that all parent directories for a file or directory
+        exist.</fsummary>
       <desc>
-        <p>The <c>ensure_dir/1</c> function ensures that all parent
-          directories for the given file or directory name <c><anno>Name</anno></c>
+        <p>Ensures that all parent directories for the specified file or
+          directory name <c><anno>Name</anno></c>
           exist, trying to create them if necessary.</p>
         <p>Returns <c>ok</c> if all parent directories already exist
-          or could be created, or <c>{error, <anno>Reason</anno>}</c> if some parent
-          directory does not exist and could not be created for some
-          reason.</p>
+          or can be created. Returns <c>{error, <anno>Reason</anno>}</c> if
+          some parent directory does not exist and cannot be created.</p>
       </desc>
     </func>
+
     <func>
       <name name="file_size" arity="1"/>
-      <fsummary>Return the size in bytes of the file.</fsummary>
+      <fsummary>Return the size in bytes of a file.</fsummary>
       <desc>
-        <p>The <c>file_size</c> function returns the size of the given file.</p>
+        <p>Returns the size of the specified file.</p>
       </desc>
     </func>
+
     <func>
       <name name="fold_files" arity="5"/>
       <fsummary>Fold over all files matching a regular expression.</fsummary>
       <desc>
-        <p>The <c>fold_files/5</c> function folds the function
-          <c><anno>Fun</anno></c> over all (regular) files <c><anno>F</anno></c> in the
-          directory <c><anno>Dir</anno></c> that match the regular expression <c><anno>RegExp</anno></c>
-	  (see the <seealso marker="re">re</seealso> module for a description
-	  of the allowed regular expressions).
-          If <c><anno>Recursive</anno></c> is true all sub-directories to <c>Dir</c>
-          are processed. The regular expression matching is done on just
-	  the filename without the directory part.</p>
-
-	  <p>If Unicode file name translation is in effect and the file
-	  system is completely transparent, file names that cannot be
-	  interpreted as Unicode may be encountered, in which case the
-	  <c>fun()</c> must be prepared to handle raw file names
-	  (i.e. binaries). If the regular expression contains
-	  codepoints beyond 255, it will not match file names that do
-	  not conform to the expected character encoding (i.e. are not
-	  encoded in valid UTF-8).</p>
-
-	  <p>For more information about raw file names, see the 
-          <seealso marker="kernel:file">file</seealso> module.</p>
+        <p>Folds function <c><anno>Fun</anno></c> over all (regular) files
+          <c><anno>F</anno></c> in directory <c><anno>Dir</anno></c> that match
+          the regular expression <c><anno>RegExp</anno></c> (for a description
+          of the allowed regular expressions,
+          see the <seealso marker="re"><c>re</c></seealso> module).
+          If <c><anno>Recursive</anno></c> is <c>true</c>, all subdirectories
+          to <c>Dir</c>
+          are processed. The regular expression matching is only done on
+          the filename without the directory part.</p>
+        <p>If Unicode filename translation is in effect and the file
+          system is transparent, filenames that cannot be
+          interpreted as Unicode can be encountered, in which case the
+          <c>fun()</c> must be prepared to handle raw filenames
+          (that is, binaries). If the regular expression contains
+          codepoints &gt; 255, it does not match filenames that do
+          not conform to the expected character encoding (that is, are not
+          encoded in valid UTF-8).</p>
+        <p>For more information about raw filenames, see the
+          <seealso marker="kernel:file"><c>file</c></seealso> module.</p>
       </desc>
     </func>
+
     <func>
       <name name="is_dir" arity="1"/>
-      <fsummary>Test whether Name refer to a directory or not</fsummary>
+      <fsummary>Test whether <c>Name</c> refers to a directory.</fsummary>
       <desc>
-        <p>The <c>is_dir/1</c> function returns <c>true</c> if <c><anno>Name</anno></c>
-          refers to a directory, and <c>false</c> otherwise.</p>
+        <p>Returns <c>true</c> if <c><anno>Name</anno></c>
+          refers to a directory, otherwise <c>false</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="is_file" arity="1"/>
-      <fsummary>Test whether Name refer to a file or directory.</fsummary>
+      <fsummary>Test whether <c>Name</c> refers to a file or directory.
+      </fsummary>
       <desc>
-        <p>The <c>is_file/1</c> function returns <c>true</c> if <c><anno>Name</anno></c>
-          refers to a file or a directory, and <c>false</c> otherwise.</p>
+        <p>Returns <c>true</c> if <c><anno>Name</anno></c>
+          refers to a file or a directory, otherwise <c>false</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="is_regular" arity="1"/>
-      <fsummary>Test whether Name refer to a (regular) file.</fsummary>
+      <fsummary>Test whether <c>Name</c> refers to a (regular) file.</fsummary>
       <desc>
-        <p>The <c>is_regular/1</c> function returns <c>true</c> if <c><anno>Name</anno></c>
-          refers to a file (regular file), and <c>false</c> otherwise.</p>
+        <p>Returns <c>true</c> if <c><anno>Name</anno></c>
+          refers to a (regular) file, otherwise <c>false</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="last_modified" arity="1"/>
-      <fsummary>Return the local date and time when a file was last modified.</fsummary>
+      <fsummary>Return the local date and time when a file was last modified.
+      </fsummary>
       <desc>
-        <p>The <c>last_modified/1</c> function returns the date and time the
-          given file or directory was last modified, or 0 if the file
-	  does not exist.</p>
+        <p>Returns the date and time the specified file or directory was last
+          modified, or <c>0</c> if the file does not exist.</p>
       </desc>
     </func>
+
     <func>
       <name name="wildcard" arity="1"/>
       <fsummary>Match filenames using Unix-style wildcards.</fsummary>
       <desc>
-        <p>The <c>wildcard/1</c> function returns a list of all files
-          that match Unix-style wildcard-string <c><anno>Wildcard</anno></c>.</p>
+        <p>Returns a list of all files that match Unix-style wildcard string
+          <c><anno>Wildcard</anno></c>.</p>
         <p>The wildcard string looks like an ordinary filename, except
-          that certain "wildcard characters" are interpreted in a special
-          way. The following characters are special:
-          </p>
+          that the following "wildcard characters" are interpreted in a special
+          way:</p>
         <taglist>
           <tag>?</tag>
           <item>
@@ -153,14 +170,14 @@
           </item>
           <tag>**</tag>
           <item>
-            <p>Two adjacent <c>*</c>'s used as a single pattern will
-        match all files and zero or more directories and subdirectories.</p>
+            <p>Two adjacent <c>*</c> used as a single pattern match
+              all files and zero or more directories and subdirectories.</p>
           </item>
           <tag>[Character1,Character2,...]</tag>
           <item>
             <p>Matches any of the characters listed. Two characters
-	    separated by a hyphen will match a range of characters.
-	    Example: <c>[A-Z]</c> will match any uppercase letter.</p>
+              separated by a hyphen match a range of characters.
+              Example: <c>[A-Z]</c> matches any uppercase letter.</p>
           </item>
           <tag>{Item,...}</tag>
           <item>
@@ -168,49 +185,45 @@
           </item>
         </taglist>
         <p>Other characters represent themselves. Only filenames that
-          have exactly the same character in the same position will match.
-          (Matching is case-sensitive; i.e. "a" will not match "A").
-          </p>
-        <p>Note that multiple "*" characters are allowed
-          (as in Unix wildcards, but opposed to Windows/DOS wildcards).
-          </p>
-        <p>Examples:</p>
+          have exactly the same character in the same position match.
+          Matching is case-sensitive, for example, "a" does not match "A".</p>
+        <p>Notice that multiple "*" characters are allowed
+          (as in Unix wildcards, but opposed to Windows/DOS wildcards).</p>
+        <p><em>Examples:</em></p>
         <p>The following examples assume that the current directory is the
-          top of an Erlang/OTP installation.
-          </p>
-        <p>To find all <c>.beam</c> files in all applications, the following
-          line can be used:</p>
+          top of an Erlang/OTP installation.</p>
+        <p>To find all <c>.beam</c> files in all applications, use the
+          following line:</p>
         <code type="none">
-    filelib:wildcard("lib/*/ebin/*.beam").        </code>
-        <p>To find either <c>.erl</c> or <c>.hrl</c> in all applications
-          <c>src</c> directories, the following</p>
+filelib:wildcard("lib/*/ebin/*.beam").</code>
+        <p>To find <c>.erl</c> or <c>.hrl</c> in all applications <c>src</c>
+          directories, use either of the following lines:</p>
         <code type="none">
-    filelib:wildcard("lib/*/src/*.?rl")        </code>
-        <p>or the following line</p>
+filelib:wildcard("lib/*/src/*.?rl")</code>
         <code type="none">
-    filelib:wildcard("lib/*/src/*.{erl,hrl}")        </code>
-        <p>can be used.</p>
-        <p>To find all <c>.hrl</c> files in either <c>src</c> or <c>include</c>
-          directories, use:</p>
+filelib:wildcard("lib/*/src/*.{erl,hrl}")</code>
+        <p>To find all <c>.hrl</c> files in <c>src</c> or <c>include</c>
+          directories:</p>
         <code type="none">
-    filelib:wildcard("lib/*/{src,include}/*.hrl").        </code>
+filelib:wildcard("lib/*/{src,include}/*.hrl").</code>
         <p>To find all <c>.erl</c> or <c>.hrl</c> files in either
-          <c>src</c> or <c>include</c> directories, use:</p>
+          <c>src</c> or <c>include</c> directories:</p>
         <code type="none">
-    filelib:wildcard("lib/*/{src,include}/*.{erl,hrl}")        </code>
-        <p>To find all <c>.erl</c> or <c>.hrl</c> files in any
-          subdirectory, use:</p>
+filelib:wildcard("lib/*/{src,include}/*.{erl,hrl}")</code>
+        <p>To find all <c>.erl</c> or <c>.hrl</c> files in any subdirectory:</p>
         <code type="none">
-    filelib:wildcard("lib/**/*.{erl,hrl}")        </code>
+filelib:wildcard("lib/**/*.{erl,hrl}")</code>
       </desc>
     </func>
+
     <func>
       <name name="wildcard" arity="2"/>
-      <fsummary>Match filenames using Unix-style wildcards starting at a specified directory.</fsummary>
+      <fsummary>Match filenames using Unix-style wildcards starting at a
+        specified directory.</fsummary>
       <desc>
-        <p>The <c>wildcard/2</c> function works like <c>wildcard/1</c>,
-          except that instead of the actual working directory, <c><anno>Cwd</anno></c>
-          will be used.</p>
+        <p>Same as <seealso marker="#wildcard/1"><c>wildcard/1</c></seealso>,
+          except that <c><anno>Cwd</anno></c> is used instead of the working
+          directory.</p>
       </desc>
     </func>
   </funcs>