Provided by: erlang-manpages_22.0.5+dfsg-2_all bug

NAME

       filelib - File utilities, such as wildcard matching of filenames.

DESCRIPTION

       This module contains utilities on a higher level than the file module.

       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.

       For more information about raw filenames, see the file module.

   Note:
       Functionality in this module generally assumes valid input and does not  necessarily  fail
       on  input  that does not use a valid encoding, but may instead very likely produce invalid
       output.

       File operations used to accept filenames containing null characters (integer value  zero).
       This  caused  the name to be truncated and in some cases arguments to primitive operations
       to be mixed up. Filenames containing null characters inside the filename are now  rejected
       and will cause primitive file operations to fail.

   Warning:
       Currently  null  characters  at the end of the filename will be accepted by primitive file
       operations. Such filenames are however still documented  as  invalid.  The  implementation
       will also change in the future and reject such filenames.

DATA TYPES

       filename() = file:name()

       dirname() = filename()

       dirname_all() = filename_all()

       filename_all() = file:name_all()

       find_file_rule() =
           {ObjDirSuffix :: string(), SrcDirSuffix :: string()}

       find_source_rule() =
           {ObjExtension :: string(),
            SrcExtension :: string(),
            [find_file_rule()]}

EXPORTS

       ensure_dir(Name) -> ok | {error, Reason}

              Types:

                 Name = filename_all() | dirname_all()
                 Reason = file:posix()

              Ensures  that  all parent directories for the specified file or directory name Name
              exist, trying to create them if necessary.

              Returns ok if all parent directories already  exist  or  can  be  created.  Returns
              {error, Reason} if some parent directory does not exist and cannot be created.

       file_size(Filename) -> integer() >= 0

              Types:

                 Filename = filename_all()

              Returns the size of the specified file.

       fold_files(Dir, RegExp, Recursive, Fun, AccIn) -> AccOut

              Types:

                 Dir = dirname()
                 RegExp = string()
                 Recursive = boolean()
                 Fun = fun((F :: file:filename(), AccIn) -> AccOut)
                 AccIn = AccOut = term()

              Folds  function  Fun  over  all  (regular)  files F in directory Dir that match the
              regular expression RegExp (for a description of the  allowed  regular  expressions,
              see  the re module). If Recursive is true, all subdirectories to Dir are processed.
              The regular expression matching is only done on the filename without the  directory
              part.

              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  fun()  must  be  prepared  to handle raw filenames (that is, binaries). If the
              regular expression contains codepoints > 255, it does not match filenames  that  do
              not  conform  to the expected character encoding (that is, are not encoded in valid
              UTF-8).

              For more information about raw filenames, see the file module.

       is_dir(Name) -> boolean()

              Types:

                 Name = filename_all() | dirname_all()

              Returns true if Name refers to a directory, otherwise false.

       is_file(Name) -> boolean()

              Types:

                 Name = filename_all() | dirname_all()

              Returns true if Name refers to a file or a directory, otherwise false.

       is_regular(Name) -> boolean()

              Types:

                 Name = filename_all()

              Returns true if Name refers to a (regular) file, otherwise false.

       last_modified(Name) -> file:date_time() | 0

              Types:

                 Name = filename_all() | dirname_all()

              Returns the date and time the specified file or directory was last modified,  or  0
              if the file does not exist.

       wildcard(Wildcard) -> [file:filename()]

              Types:

                 Wildcard = filename() | dirname()

              Returns a list of all files that match Unix-style wildcard string Wildcard.

              The  wildcard  string  looks  like  an ordinary filename, except that the following
              "wildcard characters" are interpreted in a special way:

                ?:
                  Matches one character.

                *:
                  Matches any number of characters up to the end of the filename, the  next  dot,
                  or the next slash.

                **:
                  Two  adjacent  *  used  as  a  single  pattern match all files and zero or more
                  directories and subdirectories.

                [Character1,Character2,...]:
                  Matches any of the characters listed. Two  characters  separated  by  a  hyphen
                  match a range of characters. Example: [A-Z] matches any uppercase letter.

                {Item,...}:
                  Alternation. Matches one of the alternatives.

              Other  characters  represent  themselves. Only filenames that have exactly the same
              character in the same position match. Matching is case-sensitive, for example,  "a"
              does not match "A".

              Directory separators must always be written as /, even on Windows.

              A character preceded by \ loses its special meaning. Note that \ must be written as
              \\ in a string literal. For example, "\\?*" will match any filename  starting  with
              ?.

              Notice  that multiple "*" characters are allowed (as in Unix wildcards, but opposed
              to Windows/DOS wildcards).

              Examples:

              The following examples  assume  that  the  current  directory  is  the  top  of  an
              Erlang/OTP installation.

              To find all .beam files in all applications, use the following line:

              filelib:wildcard("lib/*/ebin/*.beam").

              To  find  .erl  or  .hrl  in  all  applications  src directories, use either of the
              following lines:

              filelib:wildcard("lib/*/src/*.?rl")

              filelib:wildcard("lib/*/src/*.{erl,hrl}")

              To find all .hrl files in src or include directories:

              filelib:wildcard("lib/*/{src,include}/*.hrl").

              To find all .erl or .hrl files in either src or include directories:

              filelib:wildcard("lib/*/{src,include}/*.{erl,hrl}")

              To find all .erl or .hrl files in any subdirectory:

              filelib:wildcard("lib/**/*.{erl,hrl}")

       wildcard(Wildcard, Cwd) -> [file:filename()]

              Types:

                 Wildcard = filename() | dirname()
                 Cwd = dirname()

              Same as wildcard/1, except that Cwd is used instead of the working directory.

       find_file(Filename :: filename(), Dir :: filename()) ->
                    {ok, filename()} | {error, not_found}

       find_file(Filename :: filename(),
                 Dir :: filename(),
                 Rules :: [find_file_rule()]) ->
                    {ok, filename()} | {error, not_found}

              Looks for a file of the given name by applying suffix rules to the given  directory
              path.  For  example,  a  rule {"ebin", "src"} means that if the directory path ends
              with "ebin", the corresponding path ending in "src" should be searched.

              If Rules is left out or is an empty list, the default system rules  are  used.  See
              also the Kernel application parameter source_search_rules.

       find_source(FilePath :: filename()) ->
                      {ok, filename()} | {error, not_found}

              Equivalent  to  find_source(Base, Dir), where Dir is filename:dirname(FilePath) and
              Base is filename:basename(FilePath).

       find_source(Filename :: filename(), Dir :: filename()) ->
                      {ok, filename()} | {error, not_found}

       find_source(Filename :: filename(),
                   Dir :: filename(),
                   Rules :: [find_source_rule()]) ->
                      {ok, filename()} | {error, not_found}

              Applies file extension specific rules to find the source file for  a  given  object
              file  relative  to the object directory. For example, for a file with the extension
              .beam, the default rule is to look for a file with a corresponding  extension  .erl
              by  replacing the suffix "ebin" of the object directory path with "src" or "src/*".
              The file search is done through find_file/3. The directory of the  object  file  is
              always tried before any other directory specified by the rules.

              If  Rules  is  left out or is an empty list, the default system rules are used. See
              also the Kernel application parameter source_search_rules.