1filename(3) Erlang Module Definition filename(3)
2
6 filename - Filename manipulation functions.
7
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 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 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
31 basedir_type() =
32 user_cache |
33 user_config |
34 user_data |
35 user_log |
36 site_config |
37 site_data
38
40 absname(Filename) -> file:filename_all()
41 Types:
43 Filename = file:name_all()
45 Converts a relative Filename and returns an absolute name. No
47 attempt is made to create the shortest absolute name, as this
48 can give incorrect results on file systems that allow links.
49 Unix examples:
51 1> pwd().
53 "/usr/local"
54 2> filename:absname("foo").
55 "/usr/local/foo"
56 3> filename:absname("../x").
57 "/usr/local/../x"
58 4> filename:absname("/").
59 "/"
60 Windows examples:
62 1> pwd().
64 "D:/usr/local"
65 2> filename:absname("foo").
66 "D:/usr/local/foo"
67 3> filename:absname("../x").
68 "D:/usr/local/../x"
69 4> filename:absname("/").
70 "D:/"
71 absname(Filename, Dir) -> file:filename_all()
73 Types:
75 Filename = Dir = file:name_all()
77 Same as absname/1, except that the directory to which the file‐
79 name is to be made relative is specified in argument Dir.
80 absname_join(Dir, Filename) -> file:filename_all()
82 Types:
84 Dir = Filename = file:name_all()
86 Joins an absolute directory with a relative filename. Similar to
88 join/2, but on platforms with tight restrictions on raw filename
89 length and no support for symbolic links (read: VxWorks), lead‐
90 ing parent directory components in Filename are matched against
91 trailing directory components in Dir so they can be removed from
92 the result - minimizing its length.
93 basedir(Type, Application) -> file:filename_all()
95 Types:
97 Type = basedir_type()
99 Application = string() | binary()
100 Equivalent to basedir(Type, Application, #{}).
102 basedir(Type, Application, Opts) -> file:filename_all()
104 Types:
106 Type = basedir_type()
108 Application = string() | binary()
109 Opts =
110 #{author => string() | binary(),
111 os => windows | darwin | linux,
112 version => string() | binary()}
113 Returns a suitable path, or paths, for a given type. If os is
115 not set in Opts the function will default to the native option,
116 that is 'linux', 'darwin' or 'windows', as understood by
117 os:type/0. Anything not recognized as 'darwin' or 'windows' is
118 interpreted as 'linux'.
119 The options 'author' and 'version' are only used with 'windows'
121 option mode.
122 * user_cache
124 The path location is intended for transient data files on a
126 local machine.
127 On Linux: Respects the os environment variable
129 XDG_CACHE_HOME.
130 1> filename:basedir(user_cache, "my_application", #{os=>linux}).
132 "/home/otptest/.cache/my_application"
133 1> filename:basedir(user_cache, "my_application", #{os=>darwin}).
135 "/home/otptest/Library/Caches/my_application"
136 1> filename:basedir(user_cache, "My App").
138 "c:/Users/otptest/AppData/Local/My App/Cache"
139 2> filename:basedir(user_cache, "My App").
140 "c:/Users/otptest/AppData/Local/My App/Cache"
141 3> filename:basedir(user_cache, "My App", #{author=>"Erlang"}).
142 "c:/Users/otptest/AppData/Local/Erlang/My App/Cache"
143 4> filename:basedir(user_cache, "My App", #{version=>"1.2"}).
144 "c:/Users/otptest/AppData/Local/My App/1.2/Cache"
145 5> filename:basedir(user_cache, "My App", #{author=>"Erlang",version=>"1.2"}).
146 "c:/Users/otptest/AppData/Local/Erlang/My App/1.2/Cache"
147 * user_config
149 The path location is intended for persistent configuration
151 files.
152 On Linux: Respects the os environment variable XDG_CON‐
154 FIG_HOME.
155 2> filename:basedir(user_config, "my_application", #{os=>linux}).
157 "/home/otptest/.config/my_application"
158 2> filename:basedir(user_config, "my_application", #{os=>darwin}).
160 "/home/otptest/Library/Application Support/my_application"
161 1> filename:basedir(user_config, "My App").
163 "c:/Users/otptest/AppData/Roaming/My App"
164 2> filename:basedir(user_config, "My App", #{author=>"Erlang", version=>"1.2"}).
165 "c:/Users/otptest/AppData/Roaming/Erlang/My App/1.2"
166 * user_data
168 The path location is intended for persistent data files.
170 On Linux: Respects the os environment variable
172 XDG_DATA_HOME.
173 3> filename:basedir(user_data, "my_application", #{os=>linux}).
175 "/home/otptest/.local/my_application"
176 3> filename:basedir(user_data, "my_application", #{os=>darwin}).
178 "/home/otptest/Library/Application Support/my_application"
179 8> filename:basedir(user_data, "My App").
181 "c:/Users/otptest/AppData/Local/My App"
182 9> filename:basedir(user_data, "My App",#{author=>"Erlang",version=>"1.2"}).
183 "c:/Users/otptest/AppData/Local/Erlang/My App/1.2"
184 * user_log
186 The path location is intended for transient log files on a
188 local machine.
189 On Linux: Respects the os environment variable
191 XDG_CACHE_HOME.
192 4> filename:basedir(user_log, "my_application", #{os=>linux}).
194 "/home/otptest/.cache/my_application/log"
195 4> filename:basedir(user_log, "my_application", #{os=>darwin}).
197 "/home/otptest/Library/Caches/my_application"
198 12> filename:basedir(user_log, "My App").
200 "c:/Users/otptest/AppData/Local/My App/Logs"
201 13> filename:basedir(user_log, "My App",#{author=>"Erlang",version=>"1.2"}).
202 "c:/Users/otptest/AppData/Local/Erlang/My App/1.2/Logs"
203 * site_config
205 On Linux: Respects the os environment variable XDG_CON‐
207 FIG_DIRS.
208 5> filename:basedir(site_data, "my_application", #{os=>linux}).
210 ["/usr/local/share/my_application",
211 "/usr/share/my_application"]
212 6> os:getenv("XDG_CONFIG_DIRS").
213 "/etc/xdg/xdg-ubuntu:/usr/share/upstart/xdg:/etc/xdg"
214 7> filename:basedir(site_config, "my_application", #{os=>linux}).
215 ["/etc/xdg/xdg-ubuntu/my_application",
216 "/usr/share/upstart/xdg/my_application",
217 "/etc/xdg/my_application"]
218 8> os:unsetenv("XDG_CONFIG_DIRS").
219 true
220 9> filename:basedir(site_config, "my_application", #{os=>linux}).
221 ["/etc/xdg/my_application"]
222 5> filename:basedir(site_config, "my_application", #{os=>darwin}).
224 ["/Library/Application Support/my_application"]
225 * site_data
227 On Linux: Respects the os environment variable
229 XDG_DATA_DIRS.
230 10> os:getenv("XDG_DATA_DIRS").
232 "/usr/share/ubuntu:/usr/share/gnome:/usr/local/share/:/usr/share/"
233 11> filename:basedir(site_data, "my_application", #{os=>linux}).
234 ["/usr/share/ubuntu/my_application",
235 "/usr/share/gnome/my_application",
236 "/usr/local/share/my_application",
237 "/usr/share/my_application"]
238 12> os:unsetenv("XDG_DATA_DIRS").
239 true
240 13> filename:basedir(site_data, "my_application", #{os=>linux}).
241 ["/usr/local/share/my_application",
242 "/usr/share/my_application"]
243 5> filename:basedir(site_data, "my_application", #{os=>darwin}).
245 ["/Library/Application Support/my_application"]
246 basename(Filename) -> file:filename_all()
248 Types:
250 Filename = file:name_all()
252 Returns the last component of Filename, or Filename itself if it
254 does not contain any directory separators.
255 Examples:
257 5> filename:basename("foo").
259 "foo"
260 6> filename:basename("/usr/foo").
261 "foo"
262 7> filename:basename("/").
263 []
264 basename(Filename, Ext) -> file:filename_all()
266 Types:
268 Filename = Ext = file:name_all()
270 Returns the last component of Filename with extension Ext
272 stripped. This function is to be used to remove a (possible)
273 specific extension. To remove an existing extension when you are
274 unsure which one it is, use rootname(basename(Filename)).
275 Examples:
277 8> filename:basename("~/src/kalle.erl", ".erl").
279 "kalle"
280 9> filename:basename("~/src/kalle.beam", ".erl").
281 "kalle.beam"
282 10> filename:basename("~/src/kalle.old.erl", ".erl").
283 "kalle.old"
284 11> filename:rootname(filename:basename("~/src/kalle.erl")).
285 "kalle"
286 12> filename:rootname(filename:basename("~/src/kalle.beam")).
287 "kalle"
288 dirname(Filename) -> file:filename_all()
290 Types:
292 Filename = file:name_all()
294 Returns the directory part of Filename.
296 Examples:
298 13> filename:dirname("/usr/src/kalle.erl").
300 "/usr/src"
301 14> filename:dirname("kalle.erl").
302 "."
303 5> filename:dirname("\\usr\\src/kalle.erl"). % Windows
305 "/usr/src"
306 extension(Filename) -> file:filename_all()
308 Types:
310 Filename = file:name_all()
312 Returns the file extension of Filename, including the period.
314 Returns an empty string if no extension exists.
315 Examples:
317 15> filename:extension("foo.erl").
319 ".erl"
320 16> filename:extension("beam.src/kalle").
321 []
322 find_src(Beam) ->
324 {SourceFile, Options} | {error, {ErrorReason, Module}}
325 find_src(Beam, Rules) ->
327 {SourceFile, Options} | {error, {ErrorReason, Module}}
328 Types:
330 Beam = Module | Filename
332 Filename = atom() | string()
333 Rules = [{BinSuffix :: string(), SourceSuffix :: string()}]
334 Module = module()
335 SourceFile = string()
336 Options = [Option]
337 Option =
338 {i, Path :: string()} |
339 {outdir, Path :: string()} |
340 {d, atom()}
341 ErrorReason = non_existing | preloaded | interpreted
342 Finds the source filename and compiler options for a module. The
344 result can be fed to compile:file/2 to compile the file again.
345 Warning:
347 This function is deprecated. Use filelib:find_source/1 instead
348 for finding source files.
349 If possible, use the beam_lib(3) module to extract the compiler
351 options and the abstract code format from the Beam file and com‐
352 pile that instead.
353 Argument Beam, which can be a string or an atom, specifies
356 either the module name or the path to the source code, with or
357 without extension ".erl". In either case, the module must be
358 known by the code server, that is, code:which(Module) must suc‐
359 ceed.
360 Rules describes how the source directory can be found when the
362 object code directory is known. It is a list of tuples {BinSuf‐
363 fix, SourceSuffix} and is interpreted as follows: if the end of
364 the directory name where the object is located matches BinSuf‐
365 fix, then the name created by replacing BinSuffix with Source‐
366 Suffix is expanded by calling filelib:wildcard/1. If a regular
367 file is found among the matches, the function returns that loca‐
368 tion together with Options. Otherwise the next rule is tried,
369 and so on.
370 Rules defaults to:
372 [{"", ""}, {"ebin", "src"}, {"ebin", "esrc"},
374 {"ebin", "src/*"}, {"ebin", "esrc/*"}]
375 The function returns {SourceFile, Options} if it succeeds.
377 SourceFile is the absolute path to the source file without
378 extension ".erl". Options includes the options that are neces‐
379 sary to recompile the file with compile:file/2, but excludes
380 options such as report and verbose, which do not change the way
381 code is generated. The paths in options {outdir, Path} and {i,
382 Path} are guaranteed to be absolute.
383 flatten(Filename) -> file:filename_all()
385 Types:
387 Filename = file:name_all()
389 Converts a possibly deep list filename consisting of characters
391 and atoms into the corresponding flat string filename.
392 join(Components) -> file:filename_all()
394 Types:
396 Components = [file:name_all()]
398 Joins a list of filename Components with directory separators.
400 If one of the elements of Components includes an absolute path,
401 such as "/xxx", the preceding elements, if any, are removed from
402 the result.
403 The result is "normalized":
405 * Redundant directory separators are removed.
407 * In Windows, all directory separators are forward slashes and
409 the drive letter is in lower case.
410 Examples:
412 17> filename:join(["/usr", "local", "bin"]).
414 "/usr/local/bin"
415 18> filename:join(["a/b///c/"]).
416 "a/b/c"
417 6> filename:join(["B:a\\b///c/"]). % Windows
419 "b:a/b/c"
420 join(Name1, Name2) -> file:filename_all()
422 Types:
424 Name1 = Name2 = file:name_all()
426 Joins two filename components with directory separators. Equiva‐
428 lent to join([Name1, Name2]).
429 nativename(Path) -> file:filename_all()
431 Types:
433 Path = file:name_all()
435 Converts Path to a form accepted by the command shell and native
437 applications on the current platform. On Windows, forward
438 slashes are converted to backward slashes. On all platforms, the
439 name is normalized as done by join/1.
440 Examples:
442 19> filename:nativename("/usr/local/bin/"). % Unix
444 "/usr/local/bin"
445 7> filename:nativename("/usr/local/bin/"). % Windows
447 "\\usr\\local\\bin"
448 pathtype(Path) -> absolute | relative | volumerelative
450 Types:
452 Path = file:name_all()
454 Returns the path type, which is one of the following:
456 absolute:
458 The path name refers to a specific file on a specific vol‐
459 ume.
460 Unix example: /usr/local/bin
462 Windows example: D:/usr/local/bin
464 relative:
466 The path name is relative to the current working directory
467 on the current volume.
468 Example: foo/bar, ../src
470 volumerelative:
472 The path name is relative to the current working directory
473 on a specified volume, or it is a specific file on the cur‐
474 rent working volume.
475 Windows example: D:bar.erl, /bar/foo.erl
477 rootname(Filename) -> file:filename_all()
479 rootname(Filename, Ext) -> file:filename_all()
481 Types:
483 Filename = Ext = file:name_all()
485 Removes a filename extension. rootname/2 works as rootname/1,
487 except that the extension is removed only if it is Ext.
488 Examples:
490 20> filename:rootname("/beam.src/kalle").
492 /beam.src/kalle"
493 21> filename:rootname("/beam.src/foo.erl").
494 "/beam.src/foo"
495 22> filename:rootname("/beam.src/foo.erl", ".erl").
496 "/beam.src/foo"
497 23> filename:rootname("/beam.src/foo.beam", ".erl").
498 "/beam.src/foo.beam"
499 safe_relative_path(Filename) -> unsafe | SafeFilename
501 Types:
503 Filename = SafeFilename = file:name_all()
505 Sanitizes the relative path by eliminating ".." and "." compo‐
507 nents to protect against directory traversal attacks. Either
508 returns the sanitized path name, or the atom unsafe if the path
509 is unsafe. The path is considered unsafe in the following cir‐
510 cumstances:
511 * The path is not relative.
513 * A ".." component would climb up above the root of the rela‐
515 tive path.
516 Examples:
518 1> filename:safe_relative_path("dir/sub_dir/..").
520 "dir"
521 2> filename:safe_relative_path("dir/..").
522 []
523 3> filename:safe_relative_path("dir/../..").
524 unsafe
525 4> filename:safe_relative_path("/abs/path").
526 unsafe
527 split(Filename) -> Components
529 Types:
531 Filename = file:name_all()
533 Components = [file:name_all()]
534 Returns a list whose elements are the path components of File‐
536 name.
537 Examples:
539 24> filename:split("/usr/local/bin").
541 ["/","usr","local","bin"]
542 25> filename:split("foo/bar").
543 ["foo","bar"]
544 26> filename:split("a:\\msdev\\include").
545 ["a:/","msdev","include"]
546Ericsson AB stdlib 3.4.5.1 filename(3)