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

NAME

6       filename - Filename manipulation functions.
7

DESCRIPTION

9       This  module  provides  functions  for analyzing and manipulating file‐
10       names. These functions are designed so that the Erlang code can work on
11       many different platforms with different filename formats. With filename
12       is meant all strings that can be used to denote a  file.  The  filename
13       can be a short relative name like foo.erl, a long absolute name includ‐
14       ing    a    drive     designator,     a     directory     name     like
15       D:\usr/local\bin\erl/lib\tools\foo.erl, or any variations in between.
16
17       In  Windows,  all functions return filenames with forward slashes only,
18       even if the arguments contain backslashes. To normalize a  filename  by
19       removing redundant directory separators, use join/1.
20
21       The  module  supports  raw  filenames  in  the  way that if a binary is
22       present, or the filename cannot be interpreted according to the  return
23       value  of file:native_name_encoding/0, a raw filename is also returned.
24       For example, join/1 provided with a path component  that  is  a  binary
25       (and  cannot be interpreted under the current native filename encoding)
26       results in a raw filename that is returned (the join operation is  per‐
27       formed  of  course).  For more information about raw filenames, see the
28       file module.
29
30   Note:
31       Functionality in this module generally assumes valid input and does not
32       necessarily  fail  on input that does not use a valid encoding, but may
33       instead very likely produce invalid output.
34
35       File operations used to accept  filenames  containing  null  characters
36       (integer  value zero). This caused the name to be truncated and in some
37       cases arguments to primitive operations to be mixed up. Filenames  con‐
38       taining  null  characters inside the filename are now rejected and will
39       cause primitive file operations to fail.
40
41
42   Warning:
43       Currently null characters at the end of the filename will  be  accepted
44       by  primitive  file  operations. Such filenames are however still docu‐
45       mented as invalid. The implementation will also change  in  the  future
46       and reject such filenames.
47
48

EXPORTS

50       absname(Filename) -> file:filename_all()
51
52              Types:
53
54                 Filename = file:name_all()
55
56              Converts  a  relative  Filename and returns an absolute name. No
57              attempt is made to create the shortest absolute  name,  as  this
58              can give incorrect results on file systems that allow links.
59
60              Unix examples:
61
62              1> pwd().
63              "/usr/local"
64              2> filename:absname("foo").
65              "/usr/local/foo"
66              3> filename:absname("../x").
67              "/usr/local/../x"
68              4> filename:absname("/").
69              "/"
70
71              Windows examples:
72
73              1> pwd().
74              "D:/usr/local"
75              2> filename:absname("foo").
76              "D:/usr/local/foo"
77              3> filename:absname("../x").
78              "D:/usr/local/../x"
79              4> filename:absname("/").
80              "D:/"
81
82       absname(Filename, Dir) -> file:filename_all()
83
84              Types:
85
86                 Filename = Dir = file:name_all()
87
88              Same  as absname/1, except that the directory to which the file‐
89              name is to be made relative is specified in argument Dir.
90
91       absname_join(Dir, Filename) -> file:filename_all()
92
93              Types:
94
95                 Dir = Filename = file:name_all()
96
97              Joins an absolute directory with a relative filename. Similar to
98              join/2, but on platforms with tight restrictions on raw filename
99              length and no support for symbolic links (read: VxWorks),  lead‐
100              ing  parent directory components in Filename are matched against
101              trailing directory components in Dir so they can be removed from
102              the result - minimizing its length.
103
104       basedir(PathType, Application) -> file:filename_all()
105
106       basedir(PathsType, Application) -> [file:filename_all()]
107
108              Types:
109
110                 PathType = basedir_path_type()
111                 PathsType = basedir_paths_type()
112                 Application = string() | binary()
113                 basedir_path_type() =
114                     user_cache | user_config | user_data | user_log
115                 basedir_paths_type() = site_config | site_data
116
117              Equivalent    to    basedir(PathType,   Application,   #{})   or
118              basedir(PathsType, Application, #{}).
119
120       basedir(PathType, Application, Opts) -> file:filename_all()
121
122       basedir(PathsType, Application, Opts) -> [file:filename_all()]
123
124              Types:
125
126                 PathType = basedir_path_type()
127                 PathsType = basedir_paths_type()
128                 Application = string() | binary()
129                 Opts = basedir_opts()
130                 basedir_path_type() =
131                     user_cache | user_config | user_data | user_log
132                 basedir_paths_type() = site_config | site_data
133                 basedir_opts() =
134                     #{author => string() | binary(),
135                       os => windows | darwin | linux,
136                       version => string() | binary()}
137
138              Returns a suitable path, or paths, for a given type.  If  os  is
139              not  set in Opts the function will default to the native option,
140              that  is  'linux',  'darwin'  or  'windows',  as  understood  by
141              os:type/0.  Anything  not recognized as 'darwin' or 'windows' is
142              interpreted as 'linux'.
143
144              The options 'author' and 'version' are only used with  'windows'
145              option mode.
146
147                * user_cache
148
149                  The  path location is intended for transient data files on a
150                  local machine.
151
152                  On   Linux:   Respects   the   os    environment    variable
153                  XDG_CACHE_HOME.
154
155                1> filename:basedir(user_cache, "my_application", #{os=>linux}).
156                "/home/otptest/.cache/my_application"
157
158                1> filename:basedir(user_cache, "my_application", #{os=>darwin}).
159                "/home/otptest/Library/Caches/my_application"
160
161                1> filename:basedir(user_cache, "My App").
162                "c:/Users/otptest/AppData/Local/My App/Cache"
163                2> filename:basedir(user_cache, "My App").
164                "c:/Users/otptest/AppData/Local/My App/Cache"
165                3> filename:basedir(user_cache, "My App", #{author=>"Erlang"}).
166                "c:/Users/otptest/AppData/Local/Erlang/My App/Cache"
167                4> filename:basedir(user_cache, "My App", #{version=>"1.2"}).
168                "c:/Users/otptest/AppData/Local/My App/1.2/Cache"
169                5> filename:basedir(user_cache, "My App", #{author=>"Erlang",version=>"1.2"}).
170                "c:/Users/otptest/AppData/Local/Erlang/My App/1.2/Cache"
171
172                * user_config
173
174                  The  path  location is intended for persistent configuration
175                  files.
176
177                  On Linux: Respects  the  os  environment  variable  XDG_CON‐
178                  FIG_HOME.
179
180                2> filename:basedir(user_config, "my_application", #{os=>linux}).
181                "/home/otptest/.config/my_application"
182
183                2> filename:basedir(user_config, "my_application", #{os=>darwin}).
184                "/home/otptest/Library/Application Support/my_application"
185
186                1> filename:basedir(user_config, "My App").
187                "c:/Users/otptest/AppData/Roaming/My App"
188                2> filename:basedir(user_config, "My App", #{author=>"Erlang", version=>"1.2"}).
189                "c:/Users/otptest/AppData/Roaming/Erlang/My App/1.2"
190
191                * user_data
192
193                  The path location is intended for persistent data files.
194
195                  On    Linux:    Respects   the   os   environment   variable
196                  XDG_DATA_HOME.
197
198                3> filename:basedir(user_data, "my_application", #{os=>linux}).
199                "/home/otptest/.local/my_application"
200
201                3> filename:basedir(user_data, "my_application", #{os=>darwin}).
202                "/home/otptest/Library/Application Support/my_application"
203
204                8> filename:basedir(user_data, "My App").
205                "c:/Users/otptest/AppData/Local/My App"
206                9> filename:basedir(user_data, "My App",#{author=>"Erlang",version=>"1.2"}).
207                "c:/Users/otptest/AppData/Local/Erlang/My App/1.2"
208
209                * user_log
210
211                  The path location is intended for transient log files  on  a
212                  local machine.
213
214                  On    Linux:    Respects   the   os   environment   variable
215                  XDG_CACHE_HOME.
216
217                4> filename:basedir(user_log, "my_application", #{os=>linux}).
218                "/home/otptest/.cache/my_application/log"
219
220                4> filename:basedir(user_log, "my_application", #{os=>darwin}).
221                "/home/otptest/Library/Caches/my_application"
222
223                12> filename:basedir(user_log, "My App").
224                "c:/Users/otptest/AppData/Local/My App/Logs"
225                13> filename:basedir(user_log, "My App",#{author=>"Erlang",version=>"1.2"}).
226                "c:/Users/otptest/AppData/Local/Erlang/My App/1.2/Logs"
227
228                * site_config
229
230                  On Linux: Respects  the  os  environment  variable  XDG_CON‐
231                  FIG_DIRS.
232
233                5> filename:basedir(site_data, "my_application", #{os=>linux}).
234                ["/usr/local/share/my_application",
235                 "/usr/share/my_application"]
236                6> os:getenv("XDG_CONFIG_DIRS").
237                "/etc/xdg/xdg-ubuntu:/usr/share/upstart/xdg:/etc/xdg"
238                7> filename:basedir(site_config, "my_application", #{os=>linux}).
239                ["/etc/xdg/xdg-ubuntu/my_application",
240                 "/usr/share/upstart/xdg/my_application",
241                 "/etc/xdg/my_application"]
242                8> os:unsetenv("XDG_CONFIG_DIRS").
243                true
244                9> filename:basedir(site_config, "my_application", #{os=>linux}).
245                ["/etc/xdg/my_application"]
246
247                5> filename:basedir(site_config, "my_application", #{os=>darwin}).
248                ["/Library/Application Support/my_application"]
249
250                * site_data
251
252                  On    Linux:    Respects   the   os   environment   variable
253                  XDG_DATA_DIRS.
254
255                10> os:getenv("XDG_DATA_DIRS").
256                "/usr/share/ubuntu:/usr/share/gnome:/usr/local/share/:/usr/share/"
257                11> filename:basedir(site_data, "my_application", #{os=>linux}).
258                ["/usr/share/ubuntu/my_application",
259                 "/usr/share/gnome/my_application",
260                 "/usr/local/share/my_application",
261                 "/usr/share/my_application"]
262                12> os:unsetenv("XDG_DATA_DIRS").
263                true
264                13> filename:basedir(site_data, "my_application", #{os=>linux}).
265                ["/usr/local/share/my_application",
266                 "/usr/share/my_application"]
267
268                5> filename:basedir(site_data, "my_application", #{os=>darwin}).
269                ["/Library/Application Support/my_application"]
270
271       basename(Filename) -> file:filename_all()
272
273              Types:
274
275                 Filename = file:name_all()
276
277              Returns the last component of Filename, or Filename itself if it
278              does not contain any directory separators.
279
280              Examples:
281
282              5> filename:basename("foo").
283              "foo"
284              6> filename:basename("/usr/foo").
285              "foo"
286              7> filename:basename("/").
287              []
288
289       basename(Filename, Ext) -> file:filename_all()
290
291              Types:
292
293                 Filename = Ext = file:name_all()
294
295              Returns  the  last  component  of  Filename  with  extension Ext
296              stripped. This function is to be used  to  remove  a  (possible)
297              specific extension. To remove an existing extension when you are
298              unsure which one it is, use rootname(basename(Filename)).
299
300              Examples:
301
302              8> filename:basename("~/src/kalle.erl", ".erl").
303              "kalle"
304              9> filename:basename("~/src/kalle.beam", ".erl").
305              "kalle.beam"
306              10> filename:basename("~/src/kalle.old.erl", ".erl").
307              "kalle.old"
308              11> filename:rootname(filename:basename("~/src/kalle.erl")).
309              "kalle"
310              12> filename:rootname(filename:basename("~/src/kalle.beam")).
311              "kalle"
312
313       dirname(Filename) -> file:filename_all()
314
315              Types:
316
317                 Filename = file:name_all()
318
319              Returns the directory part of Filename.
320
321              Examples:
322
323              13> filename:dirname("/usr/src/kalle.erl").
324              "/usr/src"
325              14> filename:dirname("kalle.erl").
326              "."
327
328              5> filename:dirname("\\usr\\src/kalle.erl"). % Windows
329              "/usr/src"
330
331       extension(Filename) -> file:filename_all()
332
333              Types:
334
335                 Filename = file:name_all()
336
337              Returns the file extension of Filename,  including  the  period.
338              Returns an empty string if no extension exists.
339
340              Examples:
341
342              15> filename:extension("foo.erl").
343              ".erl"
344              16> filename:extension("beam.src/kalle").
345              []
346
347       find_src(Beam) ->
348                   {SourceFile, Options} | {error, {ErrorReason, Module}}
349
350       find_src(Beam, Rules) ->
351                   {SourceFile, Options} | {error, {ErrorReason, Module}}
352
353              Types:
354
355                 Beam = Module | Filename
356                 Filename = atom() | string()
357                 Rules = [{BinSuffix :: string(), SourceSuffix :: string()}]
358                 Module = module()
359                 SourceFile = string()
360                 Options = [Option]
361                 Option =
362                     {i, Path :: string()} |
363                     {outdir, Path :: string()} |
364                     {d, atom()}
365                 ErrorReason = non_existing | preloaded | interpreted
366
367              Finds the source filename and compiler options for a module. The
368              result can be fed to compile:file/2 to compile the file again.
369
370          Warning:
371              This function is deprecated. Use  filelib:find_source/1  instead
372              for finding source files.
373
374              If  possible, use the beam_lib(3) module to extract the compiler
375              options and the abstract code format from the Beam file and com‐
376              pile that instead.
377
378
379              Argument  Beam,  which  can  be  a  string or an atom, specifies
380              either the module name or the path to the source code,  with  or
381              without  extension  ".erl".  In  either case, the module must be
382              known by the code server, that is, code:which(Module) must  suc‐
383              ceed.
384
385              Rules  describes  how the source directory can be found when the
386              object code directory is known. It is a list of tuples  {BinSuf‐
387              fix,  SourceSuffix} and is interpreted as follows: if the end of
388              the directory name where the object is located  matches  BinSuf‐
389              fix,  then  the name created by replacing BinSuffix with Source‐
390              Suffix is expanded by calling filelib:wildcard/1. If  a  regular
391              file is found among the matches, the function returns that loca‐
392              tion together with Options. Otherwise the next  rule  is  tried,
393              and so on.
394
395              Rules defaults to:
396
397              [{"", ""}, {"ebin", "src"}, {"ebin", "esrc"},
398               {"ebin", "src/*"}, {"ebin", "esrc/*"}]
399
400              The  function  returns  {SourceFile,  Options}  if  it succeeds.
401              SourceFile is the absolute  path  to  the  source  file  without
402              extension  ".erl".  Options includes the options that are neces‐
403              sary to recompile the file  with  compile:file/2,  but  excludes
404              options  such as report and verbose, which do not change the way
405              code is generated. The paths in options {outdir, Path}  and  {i,
406              Path} are guaranteed to be absolute.
407
408       flatten(Filename) -> file:filename_all()
409
410              Types:
411
412                 Filename = file:name_all()
413
414              Converts  a possibly deep list filename consisting of characters
415              and atoms into the corresponding flat string filename.
416
417       join(Components) -> file:filename_all()
418
419              Types:
420
421                 Components = [file:name_all()]
422
423              Joins a list of filename Components with  directory  separators.
424              If  one of the elements of Components includes an absolute path,
425              such as "/xxx", the preceding elements, if any, are removed from
426              the result.
427
428              The result is "normalized":
429
430                * Redundant directory separators are removed.
431
432                * In Windows, all directory separators are forward slashes and
433                  the drive letter is in lower case.
434
435              Examples:
436
437              17> filename:join(["/usr", "local", "bin"]).
438              "/usr/local/bin"
439              18> filename:join(["a/b///c/"]).
440              "a/b/c"
441
442              6> filename:join(["B:a\\b///c/"]). % Windows
443              "b:a/b/c"
444
445       join(Name1, Name2) -> file:filename_all()
446
447              Types:
448
449                 Name1 = Name2 = file:name_all()
450
451              Joins two filename components with directory separators. Equiva‐
452              lent to join([Name1, Name2]).
453
454       nativename(Path) -> file:filename_all()
455
456              Types:
457
458                 Path = file:name_all()
459
460              Converts Path to a form accepted by the command shell and native
461              applications  on  the  current  platform.  On  Windows,  forward
462              slashes are converted to backward slashes. On all platforms, the
463              name is normalized as done by join/1.
464
465              Examples:
466
467              19> filename:nativename("/usr/local/bin/"). % Unix
468              "/usr/local/bin"
469
470              7> filename:nativename("/usr/local/bin/"). % Windows
471              "\\usr\\local\\bin"
472
473       pathtype(Path) -> absolute | relative | volumerelative
474
475              Types:
476
477                 Path = file:name_all()
478
479              Returns the path type, which is one of the following:
480
481                absolute:
482                  The path name refers to a specific file on a  specific  vol‐
483                  ume.
484
485                  Unix example: /usr/local/bin
486
487                  Windows example: D:/usr/local/bin
488
489                relative:
490                  The  path  name is relative to the current working directory
491                  on the current volume.
492
493                  Example: foo/bar, ../src
494
495                volumerelative:
496                  The path name is relative to the current  working  directory
497                  on  a specified volume, or it is a specific file on the cur‐
498                  rent working volume.
499
500                  Windows example: D:bar.erl, /bar/foo.erl
501
502       rootname(Filename) -> file:filename_all()
503
504       rootname(Filename, Ext) -> file:filename_all()
505
506              Types:
507
508                 Filename = Ext = file:name_all()
509
510              Removes a filename extension. rootname/2  works  as  rootname/1,
511              except that the extension is removed only if it is Ext.
512
513              Examples:
514
515              20> filename:rootname("/beam.src/kalle").
516              /beam.src/kalle"
517              21> filename:rootname("/beam.src/foo.erl").
518              "/beam.src/foo"
519              22> filename:rootname("/beam.src/foo.erl", ".erl").
520              "/beam.src/foo"
521              23> filename:rootname("/beam.src/foo.beam", ".erl").
522              "/beam.src/foo.beam"
523
524       safe_relative_path(Filename) -> unsafe | SafeFilename
525
526              Types:
527
528                 Filename = SafeFilename = file:name_all()
529
530              Sanitizes  the  relative path by eliminating ".." and "." compo‐
531              nents to protect against  directory  traversal  attacks.  Either
532              returns  the sanitized path name, or the atom unsafe if the path
533              is unsafe. The path is considered unsafe in the  following  cir‐
534              cumstances:
535
536                * The path is not relative.
537
538                * A  ".." component would climb up above the root of the rela‐
539                  tive path.
540
541              Examples:
542
543              1> filename:safe_relative_path("dir/sub_dir/..").
544              "dir"
545              2> filename:safe_relative_path("dir/..").
546              []
547              3> filename:safe_relative_path("dir/../..").
548              unsafe
549              4> filename:safe_relative_path("/abs/path").
550              unsafe
551
552       split(Filename) -> Components
553
554              Types:
555
556                 Filename = file:name_all()
557                 Components = [file:name_all()]
558
559              Returns a list whose elements are the path components  of  File‐
560              name.
561
562              Examples:
563
564              24> filename:split("/usr/local/bin").
565              ["/","usr","local","bin"]
566              25> filename:split("foo/bar").
567              ["foo","bar"]
568              26> filename:split("a:\\msdev\\include").
569              ["a:/","msdev","include"]
570
571
572
573Ericsson AB                     stdlib 3.8.2.1                     filename(3)