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

DATA TYPES

19       filename() = file:name()
20
21       dirname() = filename()
22
23       dirname_all() = filename_all()
24
25       filename_all() = file:name_all()
26
27       find_file_rule() =
28           {ObjDirSuffix :: string(), SrcDirSuffix :: string()}
29
30       find_source_rule() =
31           {ObjExtension :: string(),
32            SrcExtension :: string(),
33            [find_file_rule()]}
34

EXPORTS

36       ensure_dir(Name) -> ok | {error, Reason}
37
38              Types:
39
40                 Name = filename_all() | dirname_all()
41                 Reason = file:posix()
42
43              Ensures  that  all  parent directories for the specified file or
44              directory name Name exist, trying to create them if necessary.
45
46              Returns ok if all parent directories already  exist  or  can  be
47              created.  Returns  {error, Reason} if some parent directory does
48              not exist and cannot be created.
49
50       file_size(Filename) -> integer() >= 0
51
52              Types:
53
54                 Filename = filename_all()
55
56              Returns the size of the specified file.
57
58       fold_files(Dir, RegExp, Recursive, Fun, AccIn) -> AccOut
59
60              Types:
61
62                 Dir = dirname()
63                 RegExp = string()
64                 Recursive = boolean()
65                 Fun = fun((F :: file:filename(), AccIn) -> AccOut)
66                 AccIn = AccOut = term()
67
68              Folds function Fun over all (regular) files F in  directory  Dir
69              that  match  the regular expression RegExp (for a description of
70              the allowed regular expressions, see the re module).  If  Recur‐
71              sive is true, all subdirectories to Dir are processed. The regu‐
72              lar expression matching is only done on the filename without the
73              directory part.
74
75              If Unicode filename translation is in effect and the file system
76              is transparent, filenames that cannot be interpreted as  Unicode
77              can  be encountered, in which case the fun() must be prepared to
78              handle raw filenames (that is, binaries). If the regular expres‐
79              sion contains codepoints > 255, it does not match filenames that
80              do not conform to the expected character encoding (that is,  are
81              not encoded in valid UTF-8).
82
83              For more information about raw filenames, see the file module.
84
85       is_dir(Name) -> boolean()
86
87              Types:
88
89                 Name = filename_all() | dirname_all()
90
91              Returns true if Name refers to a directory, otherwise false.
92
93       is_file(Name) -> boolean()
94
95              Types:
96
97                 Name = filename_all() | dirname_all()
98
99              Returns  true if Name refers to a file or a directory, otherwise
100              false.
101
102       is_regular(Name) -> boolean()
103
104              Types:
105
106                 Name = filename_all()
107
108              Returns true if Name  refers  to  a  (regular)  file,  otherwise
109              false.
110
111       last_modified(Name) -> file:date_time() | 0
112
113              Types:
114
115                 Name = filename_all() | dirname_all()
116
117              Returns  the  date  and time the specified file or directory was
118              last modified, or 0 if the file does not exist.
119
120       wildcard(Wildcard) -> [file:filename()]
121
122              Types:
123
124                 Wildcard = filename() | dirname()
125
126              Returns a list of  all  files  that  match  Unix-style  wildcard
127              string Wildcard.
128
129              The wildcard string looks like an ordinary filename, except that
130              the following "wildcard characters" are interpreted in a special
131              way:
132
133                ?:
134                  Matches one character.
135
136                *:
137                  Matches  any number of characters up to the end of the file‐
138                  name, the next dot, or the next slash.
139
140                **:
141                  Two adjacent * used as a single pattern match all files  and
142                  zero or more directories and subdirectories.
143
144                [Character1,Character2,...]:
145                  Matches  any  of the characters listed. Two characters sepa‐
146                  rated by a hyphen match a range of characters. Example:  [A-
147                  Z] matches any uppercase letter.
148
149                {Item,...}:
150                  Alternation. Matches one of the alternatives.
151
152              Other  characters represent themselves. Only filenames that have
153              exactly the same character in the same position match.  Matching
154              is case-sensitive, for example, "a" does not match "A".
155
156              Notice  that  multiple  "*"  characters  are allowed (as in Unix
157              wildcards, but opposed to Windows/DOS wildcards).
158
159              Examples:
160
161              The following examples assume that the current directory is  the
162              top of an Erlang/OTP installation.
163
164              To  find  all .beam files in all applications, use the following
165              line:
166
167              filelib:wildcard("lib/*/ebin/*.beam").
168
169              To find .erl or .hrl in all applications  src  directories,  use
170              either of the following lines:
171
172              filelib:wildcard("lib/*/src/*.?rl")
173
174              filelib:wildcard("lib/*/src/*.{erl,hrl}")
175
176              To find all .hrl files in src or include directories:
177
178              filelib:wildcard("lib/*/{src,include}/*.hrl").
179
180              To find all .erl or .hrl files in either src or include directo‐
181              ries:
182
183              filelib:wildcard("lib/*/{src,include}/*.{erl,hrl}")
184
185              To find all .erl or .hrl files in any subdirectory:
186
187              filelib:wildcard("lib/**/*.{erl,hrl}")
188
189       wildcard(Wildcard, Cwd) -> [file:filename()]
190
191              Types:
192
193                 Wildcard = filename() | dirname()
194                 Cwd = dirname()
195
196              Same as wildcard/1, except that Cwd is used instead of the work‐
197              ing directory.
198
199       find_file(Filename :: filename(), Dir :: filename()) ->
200                    {ok, filename()} | {error, not_found}
201
202       find_file(Filename :: filename(),
203                 Dir :: filename(),
204                 Rules :: [find_file_rule()]) ->
205                    {ok, filename()} | {error, not_found}
206
207              Looks  for  a file of the given name by applying suffix rules to
208              the given directory path. For example, a  rule  {"ebin",  "src"}
209              means  that  if  the directory path ends with "ebin", the corre‐
210              sponding path ending in "src" should be searched.
211
212              If Rules is left out or is an empty  list,  the  default  system
213              rules  are  used.  See  also  the  Kernel  application parameter
214              source_search_rules.
215
216       find_source(FilePath :: filename()) ->
217                      {ok, filename()} | {error, not_found}
218
219              Equivalent  to  find_source(Base,  Dir),  where  Dir  is   file‐
220              name:dirname(FilePath) and Base is filename:basename(FilePath).
221
222       find_source(Filename :: filename(), Dir :: filename()) ->
223                      {ok, filename()} | {error, not_found}
224
225       find_source(Filename :: filename(),
226                   Dir :: filename(),
227                   Rules :: [find_source_rule()]) ->
228                      {ok, filename()} | {error, not_found}
229
230              Applies  file  extension  specific rules to find the source file
231              for a given object file relative to the  object  directory.  For
232              example,  for  a file with the extension .beam, the default rule
233              is to look for a file with a  corresponding  extension  .erl  by
234              replacing  the  suffix  "ebin" of the object directory path with
235              "src" or "src/*". The file search is done  through  find_file/3.
236              The  directory  of  the  object  file is always tried before any
237              other directory specified by the rules.
238
239              If Rules is left out or is an empty  list,  the  default  system
240              rules  are  used.  See  also  the  Kernel  application parameter
241              source_search_rules.
242
243
244
245Ericsson AB                     stdlib 3.4.5.1                      filelib(3)