1filelib(3)                 Erlang Module Definition                 filelib(3)
2
3
4

NAME

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

DESCRIPTION

10       This module contains utilities on a higher level than the file module.
11
12       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
16       For more information about raw filenames, see the file module.
17
18   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
23       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
29
30   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
36

DATA TYPES

38       filename() = file:name()
39
40       dirname() = filename()
41
42       dirname_all() = filename_all()
43
44       filename_all() = file:name_all()
45
46       find_file_rule() =
47           {ObjDirSuffix :: string(), SrcDirSuffix :: string()}
48
49       find_source_rule() =
50           {ObjExtension :: string(),
51            SrcExtension :: string(),
52            [find_file_rule()]}
53

EXPORTS

55       ensure_dir(Name) -> ok | {error, Reason}
56
57              Types:
58
59                 Name = filename_all() | dirname_all()
60                 Reason = file:posix()
61
62              Ensures that all parent directories for the  specified  file  or
63              directory name Name exist, trying to create them if necessary.
64
65              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
69       ensure_path(Path) -> ok | {error, Reason}
70
71              Types:
72
73                 Path = dirname_all()
74                 Reason = file:posix()
75
76              Ensures  that all parent directories for the specified path Path
77              exist, trying to create them if necessary.
78
79              Unlike ensure_dir/1, this function will attempt  to  create  all
80              path segments as a directory, including the last segment.
81
82              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
86       file_size(Filename) -> integer() >= 0
87
88              Types:
89
90                 Filename = filename_all()
91
92              Returns the size of the specified file.
93
94       fold_files(Dir, RegExp, Recursive, Fun, AccIn) -> AccOut
95
96              Types:
97
98                 Dir = dirname()
99                 RegExp = string()
100                 Recursive = boolean()
101                 Fun = fun((F :: file:filename(), AccIn) -> AccOut)
102                 AccIn = AccOut = term()
103
104              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
112              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
120              For more information about raw filenames, see the file module.
121
122       is_dir(Name) -> boolean()
123
124              Types:
125
126                 Name = filename_all() | dirname_all()
127
128              Returns true if Name refers to a directory, otherwise false.
129
130       is_file(Name) -> boolean()
131
132              Types:
133
134                 Name = filename_all() | dirname_all()
135
136              Returns  true if Name refers to a file or a directory, otherwise
137              false.
138
139       is_regular(Name) -> boolean()
140
141              Types:
142
143                 Name = filename_all()
144
145              Returns true if Name  refers  to  a  (regular)  file,  otherwise
146              false.
147
148       last_modified(Name) -> file:date_time() | 0
149
150              Types:
151
152                 Name = filename_all() | dirname_all()
153
154              Returns  the  date  and time the specified file or directory was
155              last modified, or 0 if the file does not exist.
156
157       wildcard(Wildcard) -> [file:filename()]
158
159              Types:
160
161                 Wildcard = filename() | dirname()
162
163              Returns a list of  all  files  that  match  Unix-style  wildcard
164              string Wildcard.
165
166              The wildcard string looks like an ordinary filename, except that
167              the following "wildcard characters" are interpreted in a special
168              way:
169
170                ?:
171                  Matches one character.
172
173                *:
174                  Matches  any number of characters up to the end of the file‐
175                  name, the next dot, or the next slash.
176
177                **:
178                  Two adjacent * used as a single pattern match all files  and
179                  zero or more directories and subdirectories.
180
181                [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
186                {Item,...}:
187                  Alternation. Matches one of the alternatives.
188
189              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
193              Directory  separators  must always be written as /, even on Win‐
194              dows.
195
196              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
200              Notice that multiple "*" characters  are  allowed  (as  in  Unix
201              wildcards, but opposed to Windows/DOS wildcards).
202
203              Examples:
204
205              The  following examples assume that the current directory is the
206              top of an Erlang/OTP installation.
207
208              To find all .beam files in all applications, use  the  following
209              line:
210
211              filelib:wildcard("lib/*/ebin/*.beam").
212
213              To  find  .erl  or .hrl in all applications src directories, use
214              either of the following lines:
215
216              filelib:wildcard("lib/*/src/*.?rl")
217
218              filelib:wildcard("lib/*/src/*.{erl,hrl}")
219
220              To find all .hrl files in src or include directories:
221
222              filelib:wildcard("lib/*/{src,include}/*.hrl").
223
224              To find all .erl or .hrl files in either src or include directo‐
225              ries:
226
227              filelib:wildcard("lib/*/{src,include}/*.{erl,hrl}")
228
229              To find all .erl or .hrl files in any subdirectory:
230
231              filelib:wildcard("lib/**/*.{erl,hrl}")
232
233       wildcard(Wildcard, Cwd) -> [file:filename()]
234
235              Types:
236
237                 Wildcard = filename() | dirname()
238                 Cwd = dirname()
239
240              Same as wildcard/1, except that Cwd is used instead of the work‐
241              ing directory.
242
243       find_file(Filename :: filename(), Dir :: filename()) ->
244                    {ok, filename()} | {error, not_found}
245
246       find_file(Filename :: filename(),
247                 Dir :: filename(),
248                 Rules :: [find_file_rule()]) ->
249                    {ok, filename()} | {error, not_found}
250
251              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
256              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
260       find_source(FilePath :: filename()) ->
261                      {ok, filename()} | {error, not_found}
262
263              Equivalent   to  find_source(Base,  Dir),  where  Dir  is  file‐
264              name:dirname(FilePath) and Base is filename:basename(FilePath).
265
266       find_source(Filename :: filename(), Dir :: filename()) ->
267                      {ok, filename()} | {error, not_found}
268
269       find_source(Filename :: filename(),
270                   Dir :: filename(),
271                   Rules :: [find_source_rule()]) ->
272                      {ok, filename()} | {error, not_found}
273
274              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
283              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
287       safe_relative_path(Filename, Cwd) -> unsafe | SafeFilename
288
289              Types:
290
291                 Filename = Cwd = SafeFilename = filename_all()
292
293              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
299                * The path is not relative.
300
301                * A  ".." component would climb up above the root of the rela‐
302                  tive path.
303
304                * A symbolic link in the path points above  the  root  of  the
305                  relative path.
306
307              Examples:
308
309              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
318
319
320
321Ericsson AB                     stdlib 4.3.1.3                      filelib(3)
Impressum