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       file_size(Filename) -> integer() >= 0
70
71              Types:
72
73                 Filename = filename_all()
74
75              Returns the size of the specified file.
76
77       fold_files(Dir, RegExp, Recursive, Fun, AccIn) -> AccOut
78
79              Types:
80
81                 Dir = dirname()
82                 RegExp = string()
83                 Recursive = boolean()
84                 Fun = fun((F :: file:filename(), AccIn) -> AccOut)
85                 AccIn = AccOut = term()
86
87              Folds  function  Fun over all (regular) files F in directory Dir
88              that match the regular expression RegExp (for a  description  of
89              the  allowed  regular expressions, see the re module). If Recur‐
90              sive is true, all subdirectories to Dir are processed. The regu‐
91              lar expression matching is only done on the filename without the
92              directory part.
93
94              If Unicode filename translation is in effect and the file system
95              is  transparent, filenames that cannot be interpreted as Unicode
96              can be encountered, in which case the fun() must be prepared  to
97              handle raw filenames (that is, binaries). If the regular expres‐
98              sion contains codepoints > 255, it does not match filenames that
99              do  not conform to the expected character encoding (that is, are
100              not encoded in valid UTF-8).
101
102              For more information about raw filenames, see the file module.
103
104       is_dir(Name) -> boolean()
105
106              Types:
107
108                 Name = filename_all() | dirname_all()
109
110              Returns true if Name refers to a directory, otherwise false.
111
112       is_file(Name) -> boolean()
113
114              Types:
115
116                 Name = filename_all() | dirname_all()
117
118              Returns true if Name refers to a file or a directory,  otherwise
119              false.
120
121       is_regular(Name) -> boolean()
122
123              Types:
124
125                 Name = filename_all()
126
127              Returns  true  if  Name  refers  to  a (regular) file, otherwise
128              false.
129
130       last_modified(Name) -> file:date_time() | 0
131
132              Types:
133
134                 Name = filename_all() | dirname_all()
135
136              Returns the date and time the specified file  or  directory  was
137              last modified, or 0 if the file does not exist.
138
139       wildcard(Wildcard) -> [file:filename()]
140
141              Types:
142
143                 Wildcard = filename() | dirname()
144
145              Returns  a  list  of  all  files  that match Unix-style wildcard
146              string Wildcard.
147
148              The wildcard string looks like an ordinary filename, except that
149              the following "wildcard characters" are interpreted in a special
150              way:
151
152                ?:
153                  Matches one character.
154
155                *:
156                  Matches any number of characters up to the end of the  file‐
157                  name, the next dot, or the next slash.
158
159                **:
160                  Two  adjacent * used as a single pattern match all files and
161                  zero or more directories and subdirectories.
162
163                [Character1,Character2,...]:
164                  Matches any of the characters listed. Two  characters  sepa‐
165                  rated  by a hyphen match a range of characters. Example: [A-
166                  Z] matches any uppercase letter.
167
168                {Item,...}:
169                  Alternation. Matches one of the alternatives.
170
171              Other characters represent themselves. Only filenames that  have
172              exactly  the same character in the same position match. Matching
173              is case-sensitive, for example, "a" does not match "A".
174
175              Directory separators must always be written as /, even  on  Win‐
176              dows.
177
178              A character preceded by \ loses its special meaning. Note that \
179              must be written as \\ in a string literal. For  example,  "\\?*"
180              will match any filename starting with ?.
181
182              Notice  that  multiple  "*"  characters  are allowed (as in Unix
183              wildcards, but opposed to Windows/DOS wildcards).
184
185              Examples:
186
187              The following examples assume that the current directory is  the
188              top of an Erlang/OTP installation.
189
190              To  find  all .beam files in all applications, use the following
191              line:
192
193              filelib:wildcard("lib/*/ebin/*.beam").
194
195              To find .erl or .hrl in all applications  src  directories,  use
196              either of the following lines:
197
198              filelib:wildcard("lib/*/src/*.?rl")
199
200              filelib:wildcard("lib/*/src/*.{erl,hrl}")
201
202              To find all .hrl files in src or include directories:
203
204              filelib:wildcard("lib/*/{src,include}/*.hrl").
205
206              To find all .erl or .hrl files in either src or include directo‐
207              ries:
208
209              filelib:wildcard("lib/*/{src,include}/*.{erl,hrl}")
210
211              To find all .erl or .hrl files in any subdirectory:
212
213              filelib:wildcard("lib/**/*.{erl,hrl}")
214
215       wildcard(Wildcard, Cwd) -> [file:filename()]
216
217              Types:
218
219                 Wildcard = filename() | dirname()
220                 Cwd = dirname()
221
222              Same as wildcard/1, except that Cwd is used instead of the work‐
223              ing directory.
224
225       find_file(Filename :: filename(), Dir :: filename()) ->
226                    {ok, filename()} | {error, not_found}
227
228       find_file(Filename :: filename(),
229                 Dir :: filename(),
230                 Rules :: [find_file_rule()]) ->
231                    {ok, filename()} | {error, not_found}
232
233              Looks  for  a file of the given name by applying suffix rules to
234              the given directory path. For example, a  rule  {"ebin",  "src"}
235              means  that  if  the directory path ends with "ebin", the corre‐
236              sponding path ending in "src" should be searched.
237
238              If Rules is left out or is an empty  list,  the  default  system
239              rules  are  used.  See  also  the  Kernel  application parameter
240              source_search_rules.
241
242       find_source(FilePath :: filename()) ->
243                      {ok, filename()} | {error, not_found}
244
245              Equivalent  to  find_source(Base,  Dir),  where  Dir  is   file‐
246              name:dirname(FilePath) and Base is filename:basename(FilePath).
247
248       find_source(Filename :: filename(), Dir :: filename()) ->
249                      {ok, filename()} | {error, not_found}
250
251       find_source(Filename :: filename(),
252                   Dir :: filename(),
253                   Rules :: [find_source_rule()]) ->
254                      {ok, filename()} | {error, not_found}
255
256              Applies  file  extension  specific rules to find the source file
257              for a given object file relative to the  object  directory.  For
258              example,  for  a file with the extension .beam, the default rule
259              is to look for a file with a corresponding extension .erl by re‐
260              placing  the  suffix  "ebin"  of  the object directory path with
261              "src" or "src/*". The file search is done  through  find_file/3.
262              The  directory  of  the  object  file is always tried before any
263              other directory specified by the rules.
264
265              If Rules is left out or is an empty  list,  the  default  system
266              rules  are  used.  See  also  the  Kernel  application parameter
267              source_search_rules.
268
269       safe_relative_path(Filename, Cwd) -> unsafe | SafeFilename
270
271              Types:
272
273                 Filename = Cwd = SafeFilename = filename_all()
274
275              Sanitizes the relative path by eliminating ".." and  "."  compo‐
276              nents to protect against directory traversal attacks. Either re‐
277              turns the sanitized path name, or the atom unsafe if the path is
278              unsafe.  The  path is considered unsafe in the following circum‐
279              stances:
280
281                * The path is not relative.
282
283                * A ".." component would climb up above the root of the  rela‐
284                  tive path.
285
286                * A  symbolic  link  in  the path points above the root of the
287                  relative path.
288
289              Examples:
290
291              1> {ok, Cwd} = file:get_cwd().
292              2> filelib:safe_relative_path("dir/sub_dir/..", Cwd).
293              "dir"
294              3> filelib:safe_relative_path("dir/..", Cwd).
295              []
296              4> filelib:safe_relative_path("dir/../..", Cwd).
297              unsafe
298              5> filelib:safe_relative_path("/abs/path", Cwd).
299              unsafe
300
301
302
303Ericsson AB                     stdlib 3.14.2.1                     filelib(3)