Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

NAME

       filename - Filename Manipulation Functions

DESCRIPTION

       The  module  filename provides a number of useful functions for analyzing and manipulating
       file names. These functions are designed  so  that  the  Erlang  code  can  work  on  many
       different  platforms  with  different  formats for file names. With file name is meant all
       strings that can be used to denote a file. They can be short relative names like  foo.erl,
       very  long  absolute  name  which  include  a  drive  designator  and directory names like
       D:\usr/local\bin\erl/lib\tools\foo.erl, or any variations in between.

       In Windows, all functions return file  names  with  forward  slashes  only,  even  if  the
       arguments  contain back slashes. Use join/1 to normalize a file name by removing redundant
       directory separators.

       The module supports raw file names in the way that if a binary is  present,  or  the  file
       name cannot be interpreted according to the return value of file:native_name_encoding/0, a
       raw file name will also be returned. For example  filename:join/1  provided  with  a  path
       component  being  a  binary  (and  also  not being possible to interpret under the current
       native file name encoding) will result in  a  raw  file  name  being  returned  (the  join
       operation  will have been performed of course). For more information about raw file names,
       see the file module.

EXPORTS

       absname(Filename) -> file:filename_all()

              Types:

                 Filename = file:name_all()

              Converts a relative Filename and returns an absolute name. No attempt  is  made  to
              create  the shortest absolute name, because this can give incorrect results on file
              systems which allow links.

              Unix examples:

              1> pwd().
              "/usr/local"
              2> filename:absname("foo").
              "/usr/local/foo"
              3> filename:absname("../x").
              "/usr/local/../x"
              4> filename:absname("/").
              "/"

              Windows examples:

              1> pwd().
              "D:/usr/local"
              2> filename:absname("foo").
              "D:/usr/local/foo"
              3> filename:absname("../x").
              "D:/usr/local/../x"
              4> filename:absname("/").
              "D:/"

       absname(Filename, Dir) -> file:filename_all()

              Types:

                 Filename = Dir = file:name_all()

              This function works like absname/1, except that the directory  to  which  the  file
              name should be made relative is given explicitly in the Dir argument.

       absname_join(Dir, Filename) -> file:filename_all()

              Types:

                 Dir = Filename = file:name_all()

              Joins  an  absolute  directory  with a relative filename. Similar to join/2, but on
              platforms with tight restrictions  on  raw  filename  length  and  no  support  for
              symbolic links (read: VxWorks), leading parent directory components in Filename are
              matched against trailing directory components in Dir so they can  be  removed  from
              the result - minimizing its length.

       basename(Filename) -> file:filename_all()

              Types:

                 Filename = file:name_all()

              Returns  the  last component of Filename, or Filename itself if it does not contain
              any directory separators.

              5> filename:basename("foo").
              "foo"
              6> filename:basename("/usr/foo").
              "foo"
              7> filename:basename("/").
              []

       basename(Filename, Ext) -> file:filename_all()

              Types:

                 Filename = Ext = file:name_all()

              Returns the last component of  Filename  with  the  extension  Ext  stripped.  This
              function  should  be used to remove a specific extension which might, or might not,
              be there. Use rootname(basename(Filename)) to remove an extension that exists,  but
              you are not sure which one it is.

              8> filename:basename("~/src/kalle.erl", ".erl").
              "kalle"
              9> filename:basename("~/src/kalle.beam", ".erl").
              "kalle.beam"
              10> filename:basename("~/src/kalle.old.erl", ".erl").
              "kalle.old"
              11> filename:rootname(filename:basename("~/src/kalle.erl")).
              "kalle"
              12> filename:rootname(filename:basename("~/src/kalle.beam")).
              "kalle"

       dirname(Filename) -> file:filename_all()

              Types:

                 Filename = file:name_all()

              Returns the directory part of Filename.

              13> filename:dirname("/usr/src/kalle.erl").
              "/usr/src"
              14> filename:dirname("kalle.erl").
              "."

              5> filename:dirname("\\usr\\src/kalle.erl"). % Windows
              "/usr/src"

       extension(Filename) -> file:filename_all()

              Types:

                 Filename = file:name_all()

              Returns  the  file  extension  of  Filename, including the period. Returns an empty
              string if there is no extension.

              15> filename:extension("foo.erl").
              ".erl"
              16> filename:extension("beam.src/kalle").
              []

       flatten(Filename) -> file:filename_all()

              Types:

                 Filename = file:name_all()

              Converts a possibly deep list filename consisting of characters and atoms into  the
              corresponding flat string filename.

       join(Components) -> file:filename_all()

              Types:

                 Components = [file:name_all()]

              Joins  a  list  of  file  name  Components with directory separators. If one of the
              elements of Components includes an absolute path, for example "/xxx", the preceding
              elements, if any, are removed from the result.

              The result is "normalized":

                * Redundant directory separators are removed.

                * In  Windows,  all directory separators are forward slashes and the drive letter
                  is in lower case.

              17> filename:join(["/usr", "local", "bin"]).
              "/usr/local/bin"
              18> filename:join(["a/b///c/"]).
              "a/b/c"

              6> filename:join(["B:a\\b///c/"]). % Windows
              "b:a/b/c"

       join(Name1, Name2) -> file:filename_all()

              Types:

                 Name1 = Name2 = file:name_all()

              Joins  two  file  name  components  with  directory   separators.   Equivalent   to
              join([Name1, Name2]).

       nativename(Path) -> file:filename_all()

              Types:

                 Path = file:name_all()

              Converts  Path  to  a form accepted by the command shell and native applications on
              the current platform. On Windows, forward slashes is converted to backward slashes.
              On all platforms, the name is normalized as done by join/1.

              19> filename:nativename("/usr/local/bin/"). % Unix
              "/usr/local/bin"

              7> filename:nativename("/usr/local/bin/"). % Windows
              "\\usr\\local\\bin"

       pathtype(Path) -> absolute | relative | volumerelative

              Types:

                 Path = file:name_all()

              Returns the type of path, one of absolute, relative, or volumerelative.

                absolute:
                  The path name refers to a specific file on a specific volume.

                  Unix example: /usr/local/bin

                  Windows example: D:/usr/local/bin

                relative:
                  The  path  name  is  relative  to  the current working directory on the current
                  volume.

                  Example: foo/bar, ../src

                volumerelative:
                  The path name is relative to the  current  working  directory  on  a  specified
                  volume, or it is a specific file on the current working volume.

                  Windows example: D:bar.erl, /bar/foo.erl

       rootname(Filename) -> file:filename_all()

       rootname(Filename, Ext) -> file:filename_all()

              Types:

                 Filename = Ext = file:name_all()

              Remove  a  filename  extension.  rootname/2  works  as  rootname/1, except that the
              extension is removed only if it is Ext.

              20> filename:rootname("/beam.src/kalle").
              /beam.src/kalle"
              21> filename:rootname("/beam.src/foo.erl").
              "/beam.src/foo"
              22> filename:rootname("/beam.src/foo.erl", ".erl").
              "/beam.src/foo"
              23> filename:rootname("/beam.src/foo.beam", ".erl").
              "/beam.src/foo.beam"

       split(Filename) -> Components

              Types:

                 Filename = file:name_all()
                 Components = [file:name_all()]

              Returns a list whose elements are the path components of Filename.

              24> filename:split("/usr/local/bin").
              ["/","usr","local","bin"]
              25> filename:split("foo/bar").
              ["foo","bar"]
              26> filename:split("a:\\msdev\\include").
              ["a:/","msdev","include"]

       find_src(Beam) ->
                   {SourceFile, Options} | {error, {ErrorReason, Module}}

       find_src(Beam, Rules) ->
                   {SourceFile, Options} | {error, {ErrorReason, Module}}

              Types:

                 Beam = Module | Filename
                 Filename = atom() | string()
                 Rules = [{BinSuffix :: string(), SourceSuffix :: string()}]
                 Module = module()
                 SourceFile = string()
                 Options = [Option]
                 Option = {i, Path :: string()}
                        | {outdir, Path :: string()}
                        | {d, atom()}
                 ErrorReason = non_existing | preloaded | interpreted

              Finds the source filename and compiler options for a module. The result can be  fed
              to compile:file/2 in order to compile the file again.

          Warning:
              We  don't recommend using this function. If possible, use beam_lib(3erl) to extract
              the abstract code format from the BEAM file and compile that instead.

              The Beam argument, which can be a string or an atom, specifies  either  the  module
              name  or  the  path  to  the  source code, with or without the ".erl" extension. In
              either case, the module must be known by the code server,  i.e.  code:which(Module)
              must succeed.

              Rules  describes  how  the  source  directory  can  be  found, when the object code
              directory is known. It is  a  list  of  tuples  {BinSuffix,  SourceSuffix}  and  is
              interpreted  as  follows:  If  the  end  of  the directory name where the object is
              located matches BinSuffix, then the source code directory has the  same  name,  but
              with BinSuffix replaced by SourceSuffix. Rules defaults to:

              [{"", ""}, {"ebin", "src"}, {"ebin", "esrc"}]

              If  the  source file is found in the resulting directory, then the function returns
              that location together with Options. Otherwise, the next rule is tried, and so on.

              The function returns {SourceFile,  Options}  if  it  succeeds.  SourceFile  is  the
              absolute  path to the source file without the ".erl" extension. Options include the
              options which are necessary to recompile the file with compile:file/2, but excludes
              options  such  as  report or verbose which do not change the way code is generated.
              The paths in the {outdir,  Path}  and  {i,  Path}  options  are  guaranteed  to  be
              absolute.