.TH filelib 3erl "stdlib 4.3.1.4" "Ericsson AB" "Erlang Module Definition"
.SH NAME
filelib \- File utilities, such as wildcard matching of filenames.
  
.SH DESCRIPTION
.LP
This module contains utilities on a higher level than the \fIfile\fR\& module\&.
.LP
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\&.
.LP
For more information about raw filenames, see the \fIfile\fR\& module\&.
.LP

.RS -4
.B
Note:
.RE
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\&.
.LP
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 \fIrejected\fR\& and will cause primitive file operations to fail\&.

.LP

.RS -4
.B
Warning:
.RE
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\&.

.SH DATA TYPES
.nf

\fBfilename()\fR\& = file:name()
.br
.fi
.nf

\fBdirname()\fR\& = filename()
.br
.fi
.nf

\fBdirname_all()\fR\& = filename_all()
.br
.fi
.nf

\fBfilename_all()\fR\& = file:name_all()
.br
.fi
.nf

\fBfind_file_rule()\fR\& = 
.br
    {ObjDirSuffix :: string(), SrcDirSuffix :: string()}
.br
.fi
.nf

\fBfind_source_rule()\fR\& = 
.br
    {ObjExtension :: string(),
.br
     SrcExtension :: string(),
.br
     [find_file_rule()]}
.br
.fi
.SH EXPORTS
.LP
.nf

.B
ensure_dir(Name) -> ok | {error, Reason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = filename_all() | dirname_all()
.br
Reason = file:posix()
.br
.RE
.RE
.RS
.LP
Ensures that all parent directories for the specified file or directory name \fIName\fR\& exist, trying to create them if necessary\&.
.LP
Returns \fIok\fR\& if all parent directories already exist or can be created\&. Returns \fI{error, Reason}\fR\& if some parent directory does not exist and cannot be created\&.
.RE

.LP
.nf

.B
ensure_path(Path) -> ok | {error, Reason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Path = dirname_all()
.br
Reason = file:posix()
.br
.RE
.RE
.RS
.LP
Ensures that all parent directories for the specified path \fIPath\fR\& exist, trying to create them if necessary\&.
.LP
Unlike \fIensure_dir/1\fR\&, this function will attempt to create all path segments as a directory, including the last segment\&.
.LP
Returns \fIok\fR\& if all parent directories already exist or can be created\&. Returns \fI{error, Reason}\fR\& if some parent directory does not exist and cannot be created\&.
.RE

.LP
.nf

.B
file_size(Filename) -> integer() >= 0
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Filename = filename_all()
.br
.RE
.RE
.RS
.LP
Returns the size of the specified file\&.
.RE

.LP
.nf

.B
fold_files(Dir, RegExp, Recursive, Fun, AccIn) -> AccOut
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Dir = dirname()
.br
RegExp = string()
.br
Recursive = boolean()
.br
Fun = fun((F :: file:filename(), AccIn) -> AccOut)
.br
AccIn = AccOut = term()
.br
.RE
.RE
.RS
.LP
Folds function \fIFun\fR\& over all (regular) files \fIF\fR\& in directory \fIDir\fR\& whose basename (for example, just \fI"baz\&.erl"\fR\& in \fI"foo/bar/baz\&.erl"\fR\&) matches the regular expression \fIRegExp\fR\& (for a description of the allowed regular expressions, see the \fIre\fR\& module)\&. If \fIRecursive\fR\& is \fItrue\fR\&, all subdirectories to \fIDir\fR\& are processed\&. The regular expression matching is only done on the filename without the directory part\&.
.LP
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 \fIfun()\fR\& 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)\&.
.LP
For more information about raw filenames, see the \fIfile\fR\& module\&.
.RE

.LP
.nf

.B
is_dir(Name) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = filename_all() | dirname_all()
.br
.RE
.RE
.RS
.LP
Returns \fItrue\fR\& if \fIName\fR\& refers to a directory, otherwise \fIfalse\fR\&\&.
.RE

.LP
.nf

.B
is_file(Name) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = filename_all() | dirname_all()
.br
.RE
.RE
.RS
.LP
Returns \fItrue\fR\& if \fIName\fR\& refers to a file or a directory, otherwise \fIfalse\fR\&\&.
.RE

.LP
.nf

.B
is_regular(Name) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = filename_all()
.br
.RE
.RE
.RS
.LP
Returns \fItrue\fR\& if \fIName\fR\& refers to a (regular) file, otherwise \fIfalse\fR\&\&.
.RE

.LP
.nf

.B
last_modified(Name) -> file:date_time() | 0
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = filename_all() | dirname_all()
.br
.RE
.RE
.RS
.LP
Returns the date and time the specified file or directory was last modified, or \fI0\fR\& if the file does not exist\&.
.RE

.LP
.nf

.B
wildcard(Wildcard) -> [file:filename()]
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Wildcard = filename() | dirname()
.br
.RE
.RE
.RS
.LP
Returns a list of all files that match Unix-style wildcard string \fIWildcard\fR\&\&.
.LP
The wildcard string looks like an ordinary filename, except that the following "wildcard characters" are interpreted in a special way:
.RS 2
.TP 2
.B
?:
Matches one character\&.
.TP 2
.B
*:
Matches any number of characters up to the end of the filename, the next dot, or the next slash\&.
.TP 2
.B
**:
Two adjacent \fI*\fR\& used as a single pattern match all files and zero or more directories and subdirectories\&.
.TP 2
.B
[Character1,Character2,\&.\&.\&.]:
Matches any of the characters listed\&. Two characters separated by a hyphen match a range of characters\&. Example: \fI[A-Z]\fR\& matches any uppercase letter\&.
.TP 2
.B
{Item,\&.\&.\&.}:
Alternation\&. Matches one of the alternatives\&.
.RE
.LP
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"\&.
.LP
Directory separators must always be written as \fI/\fR\&, even on Windows\&.
.LP
A character preceded by \fI\\\fR\& loses its special meaning\&. Note that \fI\\\fR\& must be written as \fI\\\\\fR\& in a string literal\&. For example, "\\\\?*" will match any filename starting with \fI?\fR\&\&.
.LP
Notice that multiple "*" characters are allowed (as in Unix wildcards, but opposed to Windows/DOS wildcards)\&.
.LP
\fIExamples:\fR\&
.LP
The following examples assume that the current directory is the top of an Erlang/OTP installation\&.
.LP
To find all \fI\&.beam\fR\& files in all applications, use the following line:
.LP
.nf

filelib:wildcard("lib/*/ebin/*.beam").
.fi
.LP
To find \fI\&.erl\fR\& or \fI\&.hrl\fR\& in all applications \fIsrc\fR\& directories, use either of the following lines:
.LP
.nf

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

filelib:wildcard("lib/*/src/*.{erl,hrl}")
.fi
.LP
To find all \fI\&.hrl\fR\& files in \fIsrc\fR\& or \fIinclude\fR\& directories:
.LP
.nf

filelib:wildcard("lib/*/{src,include}/*.hrl").
.fi
.LP
To find all \fI\&.erl\fR\& or \fI\&.hrl\fR\& files in either \fIsrc\fR\& or \fIinclude\fR\& directories:
.LP
.nf

filelib:wildcard("lib/*/{src,include}/*.{erl,hrl}")
.fi
.LP
To find all \fI\&.erl\fR\& or \fI\&.hrl\fR\& files in any subdirectory:
.LP
.nf

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

.LP
.nf

.B
wildcard(Wildcard, Cwd) -> [file:filename()]
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Wildcard = filename() | dirname()
.br
Cwd = dirname()
.br
.RE
.RE
.RS
.LP
Same as \fIwildcard/1\fR\&, except that \fICwd\fR\& is used instead of the working directory\&.
.RE

.LP
.nf

.B
find_file(Filename :: filename(), Dir :: filename()) ->
.B
             {ok, filename()} | {error, not_found}
.br
.fi
.br
.nf

.B
find_file(Filename :: filename(),
.B
          Dir :: filename(),
.B
          Rules :: [find_file_rule()]) ->
.B
             {ok, filename()} | {error, not_found}
.br
.fi
.br
.RS
.LP
Looks for a file of the given name by applying suffix rules to the given directory path\&. For example, a rule \fI{"ebin", "src"}\fR\& means that if the directory path ends with \fI"ebin"\fR\&, the corresponding path ending in \fI"src"\fR\& should be searched\&.
.LP
If \fIRules\fR\& is left out or is an empty list, the default system rules are used\&. See also the Kernel application parameter \fIsource_search_rules\fR\&\&.
.RE

.LP
.nf

.B
find_source(FilePath :: filename()) ->
.B
               {ok, filename()} | {error, not_found}
.br
.fi
.br
.RS
.LP
Equivalent to \fIfind_source(Base, Dir)\fR\&, where \fIDir\fR\& is \fIfilename:dirname(FilePath)\fR\& and \fIBase\fR\& is \fIfilename:basename(FilePath)\fR\&\&.
.RE

.LP
.nf

.B
find_source(Filename :: filename(), Dir :: filename()) ->
.B
               {ok, filename()} | {error, not_found}
.br
.fi
.br
.nf

.B
find_source(Filename :: filename(),
.B
            Dir :: filename(),
.B
            Rules :: [find_source_rule()]) ->
.B
               {ok, filename()} | {error, not_found}
.br
.fi
.br
.RS
.LP
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 \fI\&.beam\fR\&, the default rule is to look for a file with a corresponding extension \fI\&.erl\fR\& by replacing the suffix \fI"ebin"\fR\& of the object directory path with \fI"src"\fR\& or \fI"src/*"\fR\&\&. The file search is done through \fIfind_file/3\fR\&\&. The directory of the object file is always tried before any other directory specified by the rules\&.
.LP
If \fIRules\fR\& is left out or is an empty list, the default system rules are used\&. See also the Kernel application parameter \fIsource_search_rules\fR\&\&.
.RE

.LP
.nf

.B
safe_relative_path(Filename, Cwd) -> unsafe | SafeFilename
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Filename = Cwd = SafeFilename = filename_all()
.br
.RE
.RE
.RS
.LP
Sanitizes the relative path by eliminating "\&.\&." and "\&." components to protect against directory traversal attacks\&. Either returns the sanitized path name, or the atom \fIunsafe\fR\& if the path is unsafe\&. The path is considered unsafe in the following circumstances:
.RS 2
.TP 2
*
The path is not relative\&.
.LP
.TP 2
*
A "\&.\&." component would climb up above the root of the relative path\&.
.LP
.TP 2
*
A symbolic link in the path points above the root of the relative path\&.
.LP
.RE

.LP
\fIExamples:\fR\&
.LP
.nf

1> {ok, Cwd} = file:get_cwd()\&.
\&...
2> filelib:safe_relative_path("dir/sub_dir/\&.\&.", Cwd)\&.
"dir"
3> filelib:safe_relative_path("dir/\&.\&.", Cwd)\&.
[]
4> filelib:safe_relative_path("dir/\&.\&./\&.\&.", Cwd)\&.
unsafe
5> filelib:safe_relative_path("/abs/path", Cwd)\&.
unsafe
.fi
.RE