File: filename.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (554 lines) | stat: -rw-r--r-- 15,470 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>filename</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>filename</H1>
</CENTER>

<H3>MODULE</H3>
<DIV CLASS=REFBODY>
filename
</DIV>

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
Filename Manipulation Functions
</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P>The module <CODE>filename</CODE> 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 <CODE>foo.erl</CODE>, very long absolute
name which include a drive designator and directory names like
<CODE>D:\usr/local\bin\erl/lib\tools\foo.erl</CODE>, or any variations
in between.
<P>In Windows, all functions return file names with forward slashes
only, even if the arguments contain back slashes. Use
<CODE>join/1</CODE> to normalize a file name by removing redundant
directory separators.
</DIV>

<H3>DATA TYPES</H3>
<DIV CLASS=REFBODY>

<PRE>
name() = string() | atom() | DeepList
  DeepList = [char() | atom() | DeepList]
    
</PRE>

</DIV>

<H3>EXPORTS</H3>

<P><A NAME="absname/1"><STRONG><CODE>absname(Filename) -&#62; string()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Filename = name()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Converts a relative <CODE>Filename</CODE> 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.
<P>Unix examples:
<PRE>
1&#62; <STRONG>pwd().</STRONG>
&#34;/usr/local&#34;
2&#62; <STRONG>filename:absname(&#34;foo&#34;).</STRONG>
&#34;/usr/local/foo&#34;
3&#62; <STRONG>filename:absname(&#34;../x&#34;).</STRONG>
&#34;/usr/local/../x&#34;
4&#62; <STRONG>filename:absname(&#34;/&#34;).</STRONG>
&#34;/&#34;
        
</PRE>

<P>Windows examples:
<PRE>
1&#62; <STRONG>pwd().</STRONG>
&#34;D:/usr/local&#34;
2&#62; <STRONG>filename:absname(&#34;foo&#34;).</STRONG>
&#34;D:/usr/local/foo&#34;
3&#62; <STRONG>filename:absname(&#34;../x&#34;).</STRONG>
&#34;D:/usr/local/../x&#34;
4&#62; <STRONG>filename:absname(&#34;/&#34;).</STRONG>
&#34;D:/&#34;
        
</PRE>

</DIV>

<P><A NAME="absname/2"><STRONG><CODE>absname(Filename, Dir) -&#62; string()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Filename = name()</CODE></STRONG><BR>
<STRONG><CODE>Dir = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

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

<P><A NAME="absname_join/2"><STRONG><CODE>absname_join(Dir, Filename) -&#62; string()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Dir = string()</CODE></STRONG><BR>
<STRONG><CODE>Filename = name()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

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

<P><A NAME="basename/1"><STRONG><CODE>basename(Filename) -&#62; string()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Filename = name()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns the last component of <CODE>Filename</CODE>, or
         <CODE>Filename</CODE> itself if it does not contain any directory
         separators.
<PRE>
5&#62; <STRONG>filename:basename(&#34;foo&#34;).</STRONG>
&#34;foo&#34;
6&#62; <STRONG>filename:basename(&#34;/usr/foo&#34;).</STRONG>
&#34;foo&#34;
7&#62; <STRONG>filename:basename(&#34;/&#34;).</STRONG>
[]
        
</PRE>

</DIV>

<P><A NAME="basename/2"><STRONG><CODE>basename(Filename, Ext) -&#62; string()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Filename = Ext = name()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns the last component of <CODE>Filename</CODE> with the
         extension <CODE>Ext</CODE> stripped. This function should be used
         to remove a specific extension which might, or might not, be
         there. Use <CODE>rootname(basename(Filename))</CODE> to remove an
         extension that exists, but you are not sure which one it is.
        
<PRE>
8&#62; <STRONG>filename:basename(&#34;~/src/kalle.erl&#34;, &#34;.erl&#34;).</STRONG>
&#34;kalle&#34;
9&#62; <STRONG>filename:basename(&#34;~/src/kalle.beam&#34;, &#34;.erl&#34;).</STRONG>
&#34;kalle.beam&#34;
10&#62; <STRONG>filename:basename(&#34;~/src/kalle.old.erl&#34;, &#34;.erl&#34;).</STRONG>
&#34;kalle.old&#34;
11&#62; <STRONG>filename:rootname(filename:basename(&#34;~/src/kalle.erl&#34;)).</STRONG>
&#34;kalle&#34;
12&#62; <STRONG>filename:rootname(filename:basename(&#34;~/src/kalle.beam&#34;)).</STRONG>
&#34;kalle&#34;
        
</PRE>

</DIV>

<P><A NAME="dirname/1"><STRONG><CODE>dirname(Filename) -&#62; string()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Filename = name()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns the directory part of <CODE>Filename</CODE>.
<PRE>
13&#62; <STRONG>filename:dirname(&#34;/usr/src/kalle.erl&#34;).</STRONG>
&#34;/usr/src&#34;
14&#62; <STRONG>filename:dirname(&#34;kalle.erl&#34;).</STRONG>
&#34;.&#34;

5&#62; <STRONG>filename:dirname(&#34;\\usr\\src/kalle.erl&#34;).</STRONG> % Windows
&#34;/usr/src&#34;
        
</PRE>

</DIV>

<P><A NAME="extension/1"><STRONG><CODE>extension(Filename) -&#62; string()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Filename = name()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns the file extension of <CODE>Filename</CODE>, including
         the period. Returns an empty string if there is no extension.
        
<PRE>
15&#62; <STRONG>filename:extension(&#34;foo.erl&#34;).</STRONG>
&#34;.erl&#34;
16&#62; <STRONG>filename:extension(&#34;beam.src/kalle&#34;).</STRONG>
[]
        
</PRE>

</DIV>

<P><A NAME="flatten/1"><STRONG><CODE>flatten(Filename) -&#62; string()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Filename = name()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Converts a possibly deep list filename consisting of
         characters and atoms into the corresponding flat string
         filename.
</DIV>

<P><A NAME="join/1"><STRONG><CODE>join(Components) -&#62; string()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Components = [string()]</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Joins a list of file name <CODE>Components</CODE> with directory
         separators. If one of the elements of <CODE>Components</CODE>
         includes an absolute path, for example <CODE>&#34;/xxx&#34;</CODE>,
         the preceding elements, if any, are removed from the result.
        
<P>The result is &#34;normalized&#34;:
<P>
<UL>

<LI>
Redundant directory separators are removed.
</LI>


<LI>
In Windows, all directory separators are forward
         slashes and the drive letter is in lower case.
</LI>


</UL>

<PRE>
17&#62; <STRONG>filename:join([&#34;/usr&#34;, &#34;local&#34;, &#34;bin&#34;]).</STRONG>
&#34;/usr/local/bin&#34;
18&#62; <STRONG>filename:join([&#34;a/b///c/&#34;]).</STRONG>
&#34;a/b/c&#34;

6&#62; <STRONG>filename:join([&#34;B:a\\b///c/&#34;]).</STRONG> % Windows
&#34;b:a/b/c&#34;
        
</PRE>

</DIV>

<P><A NAME="join/2"><STRONG><CODE>join(Name1, Name2) -&#62; string()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Name1 = Name2 = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Joins two file name components with directory separators. 
         Equivalent to <CODE>join([Name1, Name2])</CODE>.
</DIV>

<P><A NAME="nativename/1"><STRONG><CODE>nativename(Path) -&#62; string()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Path = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Converts <CODE>Path</CODE> 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 <CODE>join/1</CODE>.
        
<PRE>
19&#62; <STRONG>filename:nativename(&#34;/usr/local/bin/&#34;).</STRONG> % Unix
&#34;/usr/local/bin&#34;

7&#62; <STRONG>filename:nativename(&#34;/usr/local/bin/&#34;).</STRONG> % Windows
&#34;\\usr\\local\\bin&#34;
        
</PRE>

</DIV>

<P><A NAME="pathtype/1"><STRONG><CODE>pathtype(Path) -&#62; absolute | relative | volumerelative
</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Returns the type of path, one of <CODE>absolute</CODE>,
         <CODE>relative</CODE>, or <CODE>volumerelative</CODE>.
<P>
<DL>

<DT>
<CODE>absolute</CODE>
</DT>

<DD>
         The path name refers to a specific file on a specific
         volume.<BR>


         Unix example: <CODE>/usr/local/bin</CODE><BR>


         Windows example: <CODE>D:/usr/local/bin</CODE><BR>

         
</DD>

<DT>
<CODE>relative</CODE>
</DT>

<DD>
         The path name is relative to the current working
         directory on the current volume.<BR>


         Example: <CODE>foo/bar, ../src</CODE><BR>

         
</DD>

<DT>
<CODE>volumerelative</CODE>
</DT>

<DD>
         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.<BR>


         Windows example: <CODE>D:bar.erl, /bar/foo.erl</CODE><BR>

         
</DD>

</DL>

</DIV>

<P><A NAME="rootname/1"><STRONG><CODE>rootname(Filename) -&#62; string()</CODE></STRONG></A><BR>
<A NAME="rootname/2"><STRONG><CODE>rootname(Filename, Ext) -&#62; string()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Filename = Ext = name()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Remove a filename extension. <CODE>rootname/2</CODE> works as
         <CODE>rootname/1</CODE>, except that the extension is removed only
         if it is <CODE>Ext</CODE>.
<PRE>
20&#62; <STRONG>filename:rootname(&#34;/beam.src/kalle&#34;).</STRONG>
/beam.src/kalle&#34;
21&#62; <STRONG>filename:rootname(&#34;/beam.src/foo.erl&#34;).</STRONG>
&#34;/beam.src/foo&#34;
22&#62; <STRONG>filename:rootname(&#34;/beam.src/foo.erl&#34;, &#34;.erl&#34;).</STRONG>
&#34;/beam.src/foo&#34;
23&#62; <STRONG>filename:rootname(&#34;/beam.src/foo.beam&#34;, &#34;.erl&#34;).</STRONG>
&#34;/beam.src/foo.beam&#34;
        
</PRE>

</DIV>

<P><A NAME="split/1"><STRONG><CODE>split(Filename) -&#62; Components</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Filename = name()</CODE></STRONG><BR>
<STRONG><CODE>Components = [string()]</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns a list whose elements are the path components of
         <CODE>Filename</CODE>.
<PRE>
24&#62; <STRONG>filename:split(&#34;/usr/local/bin&#34;).</STRONG>
[&#34;/&#34;,&#34;usr&#34;,&#34;local&#34;,&#34;bin&#34;]
25&#62; <STRONG>filename:split(&#34;foo/bar&#34;).</STRONG>
[&#34;foo&#34;,&#34;bar&#34;]
26&#62; <STRONG>filename:split(&#34;a:\\msdev\\include&#34;).</STRONG>
[&#34;a:/&#34;,&#34;msdev&#34;,&#34;include&#34;]
        
</PRE>

</DIV>

<P><A NAME="find_src/1"><STRONG><CODE>find_src(Beam) -&#62; {SourceFile, Options}</CODE></STRONG></A><BR>
<A NAME="find_src/2"><STRONG><CODE>find_src(Beam, Rules) -&#62; {SourceFile, Options}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Beam = Module | Filename</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Filename = string() | atom()</CODE></STRONG><BR>
<STRONG><CODE>SourceFile = string()</CODE></STRONG><BR>
<STRONG><CODE>Options = [Opt]</CODE></STRONG><BR>
<STRONG><CODE>Opt = {i, string()} | {outdir, string()} | {d, atom()}
        </CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Finds the source filename and compiler options for a module.
         The result can be fed to <CODE>compile:file/2</CODE> in order to
         compile the file again.
<P>The <CODE>Beam</CODE> 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 <CODE>&#34;.erl&#34;</CODE> extension. In either
         case, the module must be known by the code server, i.e.
         <CODE>code:which(Module)</CODE> must succeed.
<P><CODE>Rules</CODE> describes how the source directory can be found,
         when the object code directory is known. It is a list of
         tuples <CODE>{BinSuffix, SourceSuffix}</CODE> and is interpreted
         as follows: If the end of the directory name where the object
         is located matches <CODE>BinSuffix</CODE>, then the source code
         directory has the same name, but with <CODE>BinSuffix</CODE>
         replaced by <CODE>SourceSuffix</CODE>. <CODE>Rules</CODE> defaults to:
<PRE>
[{&#34;&#34;, &#34;&#34;}, {&#34;ebin&#34;, &#34;src&#34;}, {&#34;ebin&#34;, &#34;esrc&#34;}]
        
</PRE>

<P>If the source file is found in the resulting directory, then
         the function returns that location together with
         <CODE>Options</CODE>. Otherwise, the next rule is tried, and so on.
        
<P>The function returns <CODE>{SourceFile, Options}</CODE>.
         <CODE>SourceFile</CODE> is the absolute path to the source file 
         without the <CODE>&#34;.erl&#34;</CODE> extension. <CODE>Options</CODE>
         include the options which are necessary to recompile the file
         with <CODE>compile:file/2</CODE>, but excludes options
         such as <CODE>report</CODE> or <CODE>verbose</CODE> which do not change
         the way code is generated. The paths in the <CODE>{outdir,
         Path}</CODE> and <CODE>{i, Path}</CODE> options are guaranteed to be
         absolute.
</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Bjrn Gustavsson - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>stdlib 1.14.2<BR>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>