1filelib(3) Erlang Module Definition filelib(3)
2
6 filelib - File utilities, such as wildcard matching of filenames.
7
10 This module contains utilities on a higher level than the file module.
11 This module does not support "raw" filenames (that is, files whose
13 names do not comply with the expected encoding). Such files are ignored
14 by the functions in this module.
15 For more information about raw filenames, see the file module.
17 Note:
19 Functionality in this module generally assumes valid input and does not
20 necessarily fail on input that does not use a valid encoding, but may
21 instead very likely produce invalid output.
22 File operations used to accept filenames containing null characters
24 (integer value zero). This caused the name to be truncated and in some
25 cases arguments to primitive operations to be mixed up. Filenames con‐
26 taining null characters inside the filename are now rejected and will
27 cause primitive file operations to fail.
28 Warning:
31 Currently null characters at the end of the filename will be accepted
32 by primitive file operations. Such filenames are however still docu‐
33 mented as invalid. The implementation will also change in the future
34 and reject such filenames.
35
38 filename() = file:name()
39 dirname() = filename()
41 dirname_all() = filename_all()
43 filename_all() = file:name_all()
45 find_file_rule() =
47 {ObjDirSuffix :: string(), SrcDirSuffix :: string()}
48 find_source_rule() =
50 {ObjExtension :: string(),
51 SrcExtension :: string(),
52 [find_file_rule()]}
53
55 ensure_dir(Name) -> ok | {error, Reason}
56 Types:
58 Name = filename_all() | dirname_all()
60 Reason = file:posix()
61 Ensures that all parent directories for the specified file or
63 directory name Name exist, trying to create them if necessary.
64 Returns ok if all parent directories already exist or can be
66 created. Returns {error, Reason} if some parent directory does
67 not exist and cannot be created.
68 ensure_path(Path) -> ok | {error, Reason}
70 Types:
72 Path = dirname_all()
74 Reason = file:posix()
75 Ensures that all parent directories for the specified path Path
77 exist, trying to create them if necessary.
78 Unlike ensure_dir/1, this function will attempt to create all
80 path segments as a directory, including the last segment.
81 Returns ok if all parent directories already exist or can be
83 created. Returns {error, Reason} if some parent directory does
84 not exist and cannot be created.
85 file_size(Filename) -> integer() >= 0
87 Types:
89 Filename = filename_all()
91 Returns the size of the specified file.
93 fold_files(Dir, RegExp, Recursive, Fun, AccIn) -> AccOut
95 Types:
97 Dir = dirname()
99 RegExp = string()
100 Recursive = boolean()
101 Fun = fun((F :: file:filename(), AccIn) -> AccOut)
102 AccIn = AccOut = term()
103 Folds function Fun over all (regular) files F in directory Dir
105 whose basename (for example, just "baz.erl" in
106 "foo/bar/baz.erl") matches the regular expression RegExp (for a
107 description of the allowed regular expressions, see the re mod‐
108 ule). If Recursive is true, all subdirectories to Dir are pro‐
109 cessed. The regular expression matching is only done on the
110 filename without the directory part.
111 If Unicode filename translation is in effect and the file system
113 is transparent, filenames that cannot be interpreted as Unicode
114 can be encountered, in which case the fun() must be prepared to
115 handle raw filenames (that is, binaries). If the regular expres‐
116 sion contains codepoints > 255, it does not match filenames that
117 do not conform to the expected character encoding (that is, are
118 not encoded in valid UTF-8).
119 For more information about raw filenames, see the file module.
121 is_dir(Name) -> boolean()
123 Types:
125 Name = filename_all() | dirname_all()
127 Returns true if Name refers to a directory, otherwise false.
129 is_file(Name) -> boolean()
131 Types:
133 Name = filename_all() | dirname_all()
135 Returns true if Name refers to a file or a directory, otherwise
137 false.
138 is_regular(Name) -> boolean()
140 Types:
142 Name = filename_all()
144 Returns true if Name refers to a (regular) file, otherwise
146 false.
147 last_modified(Name) -> file:date_time() | 0
149 Types:
151 Name = filename_all() | dirname_all()
153 Returns the date and time the specified file or directory was
155 last modified, or 0 if the file does not exist.
156 wildcard(Wildcard) -> [file:filename()]
158 Types:
160 Wildcard = filename() | dirname()
162 Returns a list of all files that match Unix-style wildcard
164 string Wildcard.
165 The wildcard string looks like an ordinary filename, except that
167 the following "wildcard characters" are interpreted in a special
168 way:
169 ?:
171 Matches one character.
172 *:
174 Matches any number of characters up to the end of the file‐
175 name, the next dot, or the next slash.
176 **:
178 Two adjacent * used as a single pattern match all files and
179 zero or more directories and subdirectories.
180 [Character1,Character2,...]:
182 Matches any of the characters listed. Two characters sepa‐
183 rated by a hyphen match a range of characters. Example: [A-
184 Z] matches any uppercase letter.
185 {Item,...}:
187 Alternation. Matches one of the alternatives.
188 Other characters represent themselves. Only filenames that have
190 exactly the same character in the same position match. Matching
191 is case-sensitive, for example, "a" does not match "A".
192 Directory separators must always be written as /, even on Win‐
194 dows.
195 A character preceded by \ loses its special meaning. Note that \
197 must be written as \\ in a string literal. For example, "\\?*"
198 will match any filename starting with ?.
199 Notice that multiple "*" characters are allowed (as in Unix
201 wildcards, but opposed to Windows/DOS wildcards).
202 Examples:
204 The following examples assume that the current directory is the
206 top of an Erlang/OTP installation.
207 To find all .beam files in all applications, use the following
209 line:
210 filelib:wildcard("lib/*/ebin/*.beam").
212 To find .erl or .hrl in all applications src directories, use
214 either of the following lines:
215 filelib:wildcard("lib/*/src/*.?rl")
217 filelib:wildcard("lib/*/src/*.{erl,hrl}")
219 To find all .hrl files in src or include directories:
221 filelib:wildcard("lib/*/{src,include}/*.hrl").
223 To find all .erl or .hrl files in either src or include directo‐
225 ries:
226 filelib:wildcard("lib/*/{src,include}/*.{erl,hrl}")
228 To find all .erl or .hrl files in any subdirectory:
230 filelib:wildcard("lib/**/*.{erl,hrl}")
232 wildcard(Wildcard, Cwd) -> [file:filename()]
234 Types:
236 Wildcard = filename() | dirname()
238 Cwd = dirname()
239 Same as wildcard/1, except that Cwd is used instead of the work‐
241 ing directory.
242 find_file(Filename :: filename(), Dir :: filename()) ->
244 {ok, filename()} | {error, not_found}
245 find_file(Filename :: filename(),
247 Dir :: filename(),
248 Rules :: [find_file_rule()]) ->
249 {ok, filename()} | {error, not_found}
250 Looks for a file of the given name by applying suffix rules to
252 the given directory path. For example, a rule {"ebin", "src"}
253 means that if the directory path ends with "ebin", the corre‐
254 sponding path ending in "src" should be searched.
255 If Rules is left out or is an empty list, the default system
257 rules are used. See also the Kernel application parameter
258 source_search_rules.
259 find_source(FilePath :: filename()) ->
261 {ok, filename()} | {error, not_found}
262 Equivalent to find_source(Base, Dir), where Dir is file‐
264 name:dirname(FilePath) and Base is filename:basename(FilePath).
265 find_source(Filename :: filename(), Dir :: filename()) ->
267 {ok, filename()} | {error, not_found}
268 find_source(Filename :: filename(),
270 Dir :: filename(),
271 Rules :: [find_source_rule()]) ->
272 {ok, filename()} | {error, not_found}
273 Applies file extension specific rules to find the source file
275 for a given object file relative to the object directory. For
276 example, for a file with the extension .beam, the default rule
277 is to look for a file with a corresponding extension .erl by re‐
278 placing the suffix "ebin" of the object directory path with
279 "src" or "src/*". The file search is done through find_file/3.
280 The directory of the object file is always tried before any
281 other directory specified by the rules.
282 If Rules is left out or is an empty list, the default system
284 rules are used. See also the Kernel application parameter
285 source_search_rules.
286 safe_relative_path(Filename, Cwd) -> unsafe | SafeFilename
288 Types:
290 Filename = Cwd = SafeFilename = filename_all()
292 Sanitizes the relative path by eliminating ".." and "." compo‐
294 nents to protect against directory traversal attacks. Either re‐
295 turns the sanitized path name, or the atom unsafe if the path is
296 unsafe. The path is considered unsafe in the following circum‐
297 stances:
298 * The path is not relative.
300 * A ".." component would climb up above the root of the rela‐
302 tive path.
303 * A symbolic link in the path points above the root of the
305 relative path.
306 Examples:
308 1> {ok, Cwd} = file:get_cwd().
310 2> filelib:safe_relative_path("dir/sub_dir/..", Cwd).
311 "dir"
312 3> filelib:safe_relative_path("dir/..", Cwd).
313 []
314 4> filelib:safe_relative_path("dir/../..", Cwd).
315 unsafe
316 5> filelib:safe_relative_path("/abs/path", Cwd).
317 unsafe
318Ericsson AB stdlib 4.3.1.3 filelib(3)