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   D:\usr/lo‐
15       cal\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       flatten(Filename) -> file:filename_all()
348
349              Types:
350
351                 Filename = file:name_all()
352
353              Converts  a possibly deep list filename consisting of characters
354              and atoms into the corresponding flat string filename.
355
356       join(Components) -> file:filename_all()
357
358              Types:
359
360                 Components = [file:name_all()]
361
362              Joins a list of filename Components with  directory  separators.
363              If  one of the elements of Components includes an absolute path,
364              such as "/xxx", the preceding elements, if any, are removed from
365              the result.
366
367              The result is "normalized":
368
369                * Redundant directory separators are removed.
370
371                * In Windows, all directory separators are forward slashes and
372                  the drive letter is in lower case.
373
374              Examples:
375
376              17> filename:join(["/usr", "local", "bin"]).
377              "/usr/local/bin"
378              18> filename:join(["a/b///c/"]).
379              "a/b/c"
380
381              6> filename:join(["B:a\\b///c/"]). % Windows
382              "b:a/b/c"
383
384       join(Name1, Name2) -> file:filename_all()
385
386              Types:
387
388                 Name1 = Name2 = file:name_all()
389
390              Joins two filename components with directory separators. Equiva‐
391              lent to join([Name1, Name2]).
392
393       nativename(Path) -> file:filename_all()
394
395              Types:
396
397                 Path = file:name_all()
398
399              Converts Path to a form accepted by the command shell and native
400              applications  on  the  current  platform.  On  Windows,  forward
401              slashes are converted to backward slashes. On all platforms, the
402              name is normalized as done by join/1.
403
404              Examples:
405
406              19> filename:nativename("/usr/local/bin/"). % Unix
407              "/usr/local/bin"
408
409              7> filename:nativename("/usr/local/bin/"). % Windows
410              "\\usr\\local\\bin"
411
412       pathtype(Path) -> absolute | relative | volumerelative
413
414              Types:
415
416                 Path = file:name_all()
417
418              Returns the path type, which is one of the following:
419
420                absolute:
421                  The path name refers to a specific file on a  specific  vol‐
422                  ume.
423
424                  Unix example: /usr/local/bin
425
426                  Windows example: D:/usr/local/bin
427
428                relative:
429                  The  path  name is relative to the current working directory
430                  on the current volume.
431
432                  Example: foo/bar, ../src
433
434                volumerelative:
435                  The path name is relative to the current  working  directory
436                  on  a specified volume, or it is a specific file on the cur‐
437                  rent working volume.
438
439                  Windows example: D:bar.erl, /bar/foo.erl
440
441       rootname(Filename) -> file:filename_all()
442
443       rootname(Filename, Ext) -> file:filename_all()
444
445              Types:
446
447                 Filename = Ext = file:name_all()
448
449              Removes a filename extension. rootname/2  works  as  rootname/1,
450              except that the extension is removed only if it is Ext.
451
452              Examples:
453
454              20> filename:rootname("/beam.src/kalle").
455              "/beam.src/kalle"
456              21> filename:rootname("/beam.src/foo.erl").
457              "/beam.src/foo"
458              22> filename:rootname("/beam.src/foo.erl", ".erl").
459              "/beam.src/foo"
460              23> filename:rootname("/beam.src/foo.beam", ".erl").
461              "/beam.src/foo.beam"
462
463       safe_relative_path(Filename) -> unsafe | SafeFilename
464
465              Types:
466
467                 Filename = SafeFilename = file:name_all()
468
469              Sanitizes  the  relative path by eliminating ".." and "." compo‐
470              nents to protect against directory traversal attacks. Either re‐
471              turns the sanitized path name, or the atom unsafe if the path is
472              unsafe. The path is considered unsafe in the  following  circum‐
473              stances:
474
475                * The path is not relative.
476
477                * A  ".." component would climb up above the root of the rela‐
478                  tive path.
479
480          Warning:
481              This function is  deprecated.  Use  filelib:safe_relative_path/2
482              instead for sanitizing paths.
483
484
485              Examples:
486
487              1> filename:safe_relative_path("dir/sub_dir/..").
488              "dir"
489              2> filename:safe_relative_path("dir/..").
490              []
491              3> filename:safe_relative_path("dir/../..").
492              unsafe
493              4> filename:safe_relative_path("/abs/path").
494              unsafe
495
496       split(Filename) -> Components
497
498              Types:
499
500                 Filename = file:name_all()
501                 Components = [file:name_all()]
502
503              Returns  a  list whose elements are the path components of File‐
504              name.
505
506              Examples:
507
508              24> filename:split("/usr/local/bin").
509              ["/","usr","local","bin"]
510              25> filename:split("foo/bar").
511              ["foo","bar"]
512              26> filename:split("a:\\msdev\\include").
513              ["a:/","msdev","include"]
514
515
516
517Ericsson AB                      stdlib 3.16.1                     filename(3)