Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
filename(3)		   Erlang Module Definition		   filename(3)

       filename	- Filename Manipulation	Functions

       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 re-
       turned. For example filename:join/1 provided with a path	component  be-
       ing  a  binary (and also	not being possible to interpret	under the cur-
       rent 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.

       absname(Filename) -> file:filename_all()


		 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

	      Unix examples:

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

	      Windows examples:

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

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


		 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()


		 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), lead-
	      ing 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()


		 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").
	      6> filename:basename("/usr/foo").
	      7> filename:basename("/").

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


		 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  ex-
	      tension  which might, or might not, be there. Use	rootname(base-
	      name(Filename)) to remove	an extension that exists, but you  are
	      not sure which one it is.

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

       dirname(Filename) -> file:filename_all()


		 Filename = file:name_all()

	      Returns the directory part of Filename.

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

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

       extension(Filename) -> file:filename_all()


		 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").
	      16> filename:extension("beam.src/kalle").

       flatten(Filename) -> file:filename_all()


		 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()


		 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"]).
	      18> filename:join(["a/b///c/"]).

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

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


		 Name1 = Name2 = file:name_all()

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

       nativename(Path)	-> file:filename_all()


		 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

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

       pathtype(Path) -> absolute | relative | volumerelative


		 Path =	file:name_all()

	      Returns  the  type  of  path, one	of absolute, relative, or vol-

		  The path name	refers to a specific file on a	specific  vol-

		  Unix example:	/usr/local/bin

		  Windows example: D:/usr/local/bin

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

		  Example: foo/bar, ../src

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

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

       rootname(Filename) -> file:filename_all()

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


		 Filename = Ext	= file:name_all()

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

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

       split(Filename) -> Components


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

	      Returns  a  list whose elements are the path components of File-

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

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

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


		 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

	      We  don't	 recommend  using  this	 function.  If	possible,  use
	      beam_lib(3)  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  {BinSuf-
	      fix,  SourceSuffix} and is interpreted as	follows: If the	end of
	      the directory name where the object is located  matches  BinSuf-
	      fix,  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	neces-
	      sary to recompile	the file with compile:file/2, but excludes op-
	      tions such as report or verbose which do not change the way code
	      is  generated. The paths in the {outdir, Path} and {i, Path} op-
	      tions are	guaranteed to be absolute.

Ericsson AB			  stdlib 2.4			   filename(3)


Want to link to this manual page? Use this URL:

home | help