File: erl_tar.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 (607 lines) | stat: -rw-r--r-- 17,112 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>erl_tar</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>erl_tar</H1>
</CENTER>

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

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
Unix 'tar' utility for reading and writing tar archives
</DIV>

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

<P>The <CODE>erl_tar</CODE> module archives and extract files to and from
a tar file. The tar file format is the POSIX extended tar file format
specified in IEEE Std 1003.1 and ISO/IEC9945-1. That is the same
format as used by <CODE>tar</CODE> program on Solaris, but is not the same
as used by the GNU tar program.
<P>By convention, the name of a tar file should end in &#34;<CODE>.tar</CODE>&#34;.
To abide to the convention, you'll need to add &#34;<CODE>.tar</CODE>&#34; yourself
to the name.
<P>Tar files can be created in one operation using the
<A HREF="#create_2">create/2</A> or
<A HREF="#create_3">create/3</A> function.
<P>Alternatively, for more control, the
<A HREF="#open">open</A>,
<A HREF="#add">add/3,4</A>, and 
<A HREF="#close">close/1</A> functions can be used.
<P>To extract all files from a tar file, use the 
<A HREF="#extract_1">extract/1</A> function.
To extract only some files or to be able to specify some more options,
use the <A HREF="#extract_2">extract/2</A> function.
<P>To return a list of the files in a tar file,
use either the <A HREF="#table_1">table/1</A> or
<A HREF="#table_2">table/2</A> function.
To print a list of files to the Erlang shell,
use either the <A HREF="#t_1">t/1</A> or
<A HREF="#tt_1">tt/1</A> function.
<P>To convert an error term returned from one of the functions
above to a readable message, use the
<A HREF="#format_error_1">format_error/1</A> function.

</DIV>

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

<P>For maximum compatibility, it is safe to archive files with names
up to 100 characters in length. Such tar files can generally be
extracted by any <CODE>tar</CODE> program.
<P>If filenames exceed 100 characters in length, the resulting tar
file can only be correctly extracted by a POSIX-compatible <CODE>tar</CODE>
program (such as Solaris <CODE>tar</CODE>), not by GNU tar.
<P>File have longer names than 256 bytes cannot be stored at all.
<P>The filename of the file a symbolic link points is always limited
to 100 characters.
</DIV>

<H3>EXPORTS</H3>

<P><A NAME="add/3"><STRONG><CODE>add(TarDescriptor, Filename, Options) -&#62; RetValue</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>TarDescriptor = term()</CODE></STRONG><BR>
<STRONG><CODE>Filename = filename()</CODE></STRONG><BR>
<STRONG><CODE>Options = [Option]</CODE></STRONG><BR>
<STRONG><CODE>Option = dereference|verbose</CODE></STRONG><BR>
<STRONG><CODE>RetValue = ok|{error,{Filename,Reason}}</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="add"><!-- Empty --></A><CODE>add/3</CODE> function adds a file to a tar file
        that has been opened for writing by
<A HREF="#open">open/1</A>.
<P>
<DL>

<DT>
<CODE>dereference</CODE>
</DT>

<DD>
By default, symbolic links will be stored as symbolic links
        in the tar file. Use the <CODE>dereference</CODE> option to override the
        default and store the file that the symbolic link points to into
        the tar file.<BR>


</DD>

<DT>
<CODE>verbose</CODE>
</DT>

<DD>
Print an informational message about the file being added.<BR>


</DD>

</DL>

</DIV>

<P><A NAME="add/4"><STRONG><CODE>add(TarDescriptor, Filename, NameInArchive, Options) -&#62; RetValue </CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>TarDescriptor = term()</CODE></STRONG><BR>
<STRONG><CODE>Filename = filename()</CODE></STRONG><BR>
<STRONG><CODE>NameInArchive = filename()</CODE></STRONG><BR>
<STRONG><CODE>Options = [Option]</CODE></STRONG><BR>
<STRONG><CODE>Option = dereference|verbose</CODE></STRONG><BR>
<STRONG><CODE>RetValue = ok|{error,{Filename,Reason}}</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <CODE>add/4</CODE> function adds a file to a tar file
        that has been opened for writing by
<A HREF="#open">open/1</A>. It accepts the same
        options as <A HREF="#add">add/3</A>.
<P><CODE>NameInArchive</CODE> is the name under which the file will
        be stored in the tar file. That is the name that the file will
        get when it will be extracted from the tar file.
</DIV>

<P><A NAME="close/1"><STRONG><CODE>close(TarDescriptor)</CODE></STRONG></A><BR>

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

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="close"><!-- Empty --></A><CODE>close/1</CODE> function closes a tar file
        opened by <A HREF="#open">open/1</A>.

</DIV>

<P><A NAME="create/2"><STRONG><CODE>create(Name, FileList) -&#62;RetValue </CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Name = filename()</CODE></STRONG><BR>
<STRONG><CODE>FileList = [filename()]</CODE></STRONG><BR>
<STRONG><CODE>RetValue = ok|{error,{Name,Reason}}
&#60;V&#62;Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="create_2"><!-- Empty --></A><CODE>create/2</CODE> function 
        creates a tar file and archives the files whose names are given
        in <CODE>FileList</CODE> into it.
</DIV>

<P><A NAME="create/3"><STRONG><CODE>create(Name, FileList, OptionList)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Name = filename()</CODE></STRONG><BR>
<STRONG><CODE>FileList = [filename()]</CODE></STRONG><BR>
<STRONG><CODE>OptionList = [Option]</CODE></STRONG><BR>
<STRONG><CODE>Option = compressed|cooked|dereference|verbose</CODE></STRONG><BR>
<STRONG><CODE>RetValue = ok|{error,{Name,Reason}}
&#60;V&#62;Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="create_3"><!-- Empty --></A><CODE>create/3</CODE> function 
        creates a tar file and archives the files whose names are given
        in <CODE>FileList</CODE> into it.
<P>The options in <CODE>OptionList</CODE> modify the defaults   as follows.


<P>
<DL>

<DT>
<CODE>compressed</CODE>
</DT>

<DD>
The entire tar file will be compressed, as if it has
        been run through the <CODE>gzip</CODE> program. To abide to the
        convention that a compressed tar file should end in &#34;<CODE>.tar.gz</CODE>&#34; or
        &#34;<CODE>.tgz</CODE>&#34;, you'll need to add the appropriate extension yourself.<BR>


</DD>

<DT>
<CODE>cooked</CODE>
</DT>

<DD>
By default, the <CODE>open/2</CODE> function will open the tar file
        in <CODE>raw</CODE> mode, which is faster but does not allow a remote (erlang)
        file server to be used. Adding <CODE>cooked</CODE> to the mode list will 
        override the default and open the tar file without the <CODE>raw</CODE>
        option.<BR>


</DD>

<DT>
<CODE>dereference</CODE>
</DT>

<DD>
By default, symbolic links will be stored as symbolic links
        in the tar file. Use the <CODE>dereference</CODE> option to override the
        default and store the file that the symbolic link points to into
        the tar file.<BR>


</DD>

<DT>
<CODE>verbose</CODE>
</DT>

<DD>
Print an informational message about each file being added.<BR>


</DD>

</DL>

</DIV>

<P><A NAME="extract/1"><STRONG><CODE>extract(Name) -&#62; RetValue</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Name = filename()</CODE></STRONG><BR>
<STRONG><CODE>RetValue = ok|{error,{Name,Reason}}</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="extract_1"><!-- Empty --></A><CODE>extract/1</CODE> function extracts
        all files from a tar archive.
<P>If the <CODE>Name</CODE> argument is given as &#34;<CODE>{binary,Binary}</CODE>&#34;,
        the contents of the binary is assumed to be a tar archive.
        
        
<P>If the <CODE>Name</CODE> argument is given as &#34;<CODE>{file,Fd}</CODE>&#34;,
        <CODE>Fd</CODE> is assumed to be a file descriptor returned from
        the <CODE>file:open/2</CODE> function.

        
<P>Otherwise, <CODE>Name</CODE> should be a filename.

</DIV>

<P><A NAME="extract/2"><STRONG><CODE>extract(Name, OptionList)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Name = filename() | {binary,Binary} | {file,Fd} </CODE></STRONG><BR>
<STRONG><CODE>Binary = binary()</CODE></STRONG><BR>
<STRONG><CODE>Fd = file_descriptor()</CODE></STRONG><BR>
<STRONG><CODE>OptionList = [Option]</CODE></STRONG><BR>
<STRONG><CODE>Option = {cwd,Cwd}|{files,FileList}|keep_old_files|verbose</CODE></STRONG><BR>
<STRONG><CODE>Cwd = [dirname()]</CODE></STRONG><BR>
<STRONG><CODE>FileList = [filename()]</CODE></STRONG><BR>
<STRONG><CODE>RetValue = ok|{error,{Name,Reason}}</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="extract_2"><!-- Empty --></A><CODE>extract/2</CODE> function extracts
        files from a tar archive.
<P>If the <CODE>Name</CODE> argument is given as &#34;<CODE>{binary,Binary}</CODE>&#34;,
        the contents of the binary is assumed to be a tar archive.
        
        
<P>If the <CODE>Name</CODE> argument is given as &#34;<CODE>{file,Fd}</CODE>&#34;,
        <CODE>Fd</CODE> is assumed to be a file descriptor returned from
        the <CODE>file:open/2</CODE> function.

        
<P>Otherwise, <CODE>Name</CODE> should be a filename.

        
<P>The following options modify the defaults for the extraction as
        follows.
<P>
<DL>

<DT>
<CODE>{cwd,Cwd}</CODE>
</DT>

<DD>
Files with relative filenames will by default be extracted
        to the current working directory.
        Given the <CODE>{cwd,Cwd}</CODE> option, the <CODE>extract/2</CODE> function
        will extract into the directory <CODE>Cwd</CODE> instead of to the current
        working directory.<BR>


</DD>

<DT>
<CODE>{files,FileList}</CODE>
</DT>

<DD>
By default, all files will be extracted from the tar file.
        Given the <CODE>{files,Files}</CODE> option, the <CODE>extract/2</CODE> function
        will only extract the files whose names are included in <CODE>FileList</CODE>.<BR>


</DD>

<DT>
<CODE>compressed</CODE>
</DT>

<DD>
Given the <CODE>compressed</CODE> option, the <CODE>extract/2</CODE>
        function will uncompress the file while extracting
        If the tar file is not actually compressed, the <CODE>compressed</CODE>
        will effectively be ignored.<BR>


</DD>

<DT>
<CODE>cooked</CODE>
</DT>

<DD>
By default, the <CODE>open/2</CODE> function will open the tar file
        in <CODE>raw</CODE> mode, which is faster but does not allow a remote (erlang)
        file server to be used. Adding <CODE>cooked</CODE> to the mode list will 
        override the default and open the tar file without the <CODE>raw</CODE>
        option.<BR>


</DD>

<DT>
<CODE>keep_old_files</CODE>
</DT>

<DD>
By default, all existing files with the same name as file in
        the tar file will be overwritten
        Given the <CODE>keep_old_files</CODE> option, the <CODE>extract/2</CODE> function
        will not overwrite any existing files.<BR>


</DD>

<DT>
<CODE>verbose</CODE>
</DT>

<DD>
Print an informational message as each file is being extracted.<BR>


</DD>

</DL>

</DIV>

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

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

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="format_error_1"><!-- Empty --></A><CODE>format_error/1</CODE> converts
        an error reason term to a human-readable error message string.

</DIV>

<P><A NAME="open/2"><STRONG><CODE>open(Name, OpenModeList) -&#62; RetValue</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Name = filename()</CODE></STRONG><BR>
<STRONG><CODE>OpenModeList = [OpenMode]</CODE></STRONG><BR>
<STRONG><CODE>Mode = read|write|compressed|cooked</CODE></STRONG><BR>
<STRONG><CODE>RetValue = {ok,TarDescriptor}|{error,{Name,Reason}}
&#60;V&#62;TarDescriptor = term()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="open"><!-- Empty --></A><CODE>open/2</CODE> function opens a tar file.
<P>By convention, the name of a tar file should end in &#34;<CODE>.tar</CODE>&#34;.
        To abide to the convention, you'll need to add &#34;<CODE>.tar</CODE>&#34; yourself
        to the name.
<P>Note that there is currently no function for reading
        from an opened tar file, meaning that opening a tar file for reading is
        not very useful.
<P>Except for <CODE>read</CODE> and <CODE>write</CODE> (which are mutually
        exclusive), the following atoms may be added to <CODE>OpenModeList</CODE>:


<P>
<DL>

<DT>
<CODE>compressed</CODE>
</DT>

<DD>
The entire tar file will be compressed, as if it has
        been run through the <CODE>gzip</CODE> program. To abide to the
        convention that a compressed tar file should end in &#34;<CODE>.tar.gz</CODE>&#34; or
        &#34;<CODE>.tgz</CODE>&#34;, you'll need to add the appropriate extension yourself.<BR>


</DD>

<DT>
<CODE>cooked</CODE>
</DT>

<DD>
By default, the <CODE>open/2</CODE> function will open the tar file
        in <CODE>raw</CODE> mode, which is faster but does not allow a remote (erlang)
        file server to be used. Adding <CODE>cooked</CODE> to the mode list will 
        override the default and open the tar file without the <CODE>raw</CODE>
        option.<BR>


</DD>

</DL>

<P>Use the <A HREF="#add">add/3,4</A> functions
        to add one file at the time into an opened tar file. When you are
        finished adding files, use the <A HREF="#close">close</A>
        function to close the tar file.
<P>
<TABLE CELLPADDING=4>
  <TR>
    <TD VALIGN=TOP><IMG ALT="Warning!" SRC="warning.gif"></TD>
    <TD>

<P>The <CODE>TarDescriptor</CODE> term is not a file descriptor.
        You should not rely on the specific contents of the <CODE>TarDescriptor</CODE>
        term, as it may change in future versions as more features are added
        to the <CODE>erl_tar</CODE> module.
<P>    </TD>
  </TR>
</TABLE>

</DIV>

<P><A NAME="table/1"><STRONG><CODE>table(Name) -&#62; RetValue</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Name = filename()</CODE></STRONG><BR>
<STRONG><CODE>RetValue = {ok,[string()]}|{error,{Name,Reason}}</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="table_1"><!-- Empty --></A><CODE>table/1</CODE> function retrieves
        the names of all files in the tar file <CODE>Name</CODE>.

</DIV>

<P><A NAME="table/2"><STRONG><CODE>table(Name, Options)</CODE></STRONG></A><BR>

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

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="table_2"><!-- Empty --></A><CODE>table/2</CODE> function retrieves
        the names of all files in the tar file <CODE>Name</CODE>.

</DIV>

<P><A NAME="t/1"><STRONG><CODE>t(Name)</CODE></STRONG></A><BR>

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

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="t_1"><!-- Empty --></A><CODE>t/1</CODE> function prints the names
        of all files in the tar file <CODE>Name</CODE> to the Erlang shell.
        (Similar to &#34;<CODE>tart</CODE>&#34;.)
</DIV>

<P><A NAME="tt/1"><STRONG><CODE>tt(Name)</CODE></STRONG></A><BR>

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

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="tt_1"><!-- Empty --></A><CODE>tt/1</CODE> function prints names and
        information about all files in the tar file <CODE>Name</CODE> to
        the Erlang shell. (Similar to &#34;<CODE>tartv</CODE>&#34;.)
</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Bjorn 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>