aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/erl_tar.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/stdlib/doc/src/erl_tar.xml')
-rw-r--r--lib/stdlib/doc/src/erl_tar.xml434
1 files changed, 434 insertions, 0 deletions
diff --git a/lib/stdlib/doc/src/erl_tar.xml b/lib/stdlib/doc/src/erl_tar.xml
new file mode 100644
index 0000000000..929620bb88
--- /dev/null
+++ b/lib/stdlib/doc/src/erl_tar.xml
@@ -0,0 +1,434 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2003</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>erl_tar</title>
+ <prepared>Bjorn Gustavsson</prepared>
+ <responsible>Bjorn Gustavsson</responsible>
+ <docno>1</docno>
+ <approved>Kenneth Lundin</approved>
+ <checked></checked>
+ <date>03-01-21</date>
+ <rev>A</rev>
+ <file>erl_tar.sgml</file>
+ </header>
+ <module>erl_tar</module>
+ <modulesummary>Unix 'tar' utility for reading and writing tar archives</modulesummary>
+ <description>
+ <p>The <c>erl_tar</c> 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/IEC&nbsp;9945-1. That is the same
+ format as used by <c>tar</c> program on Solaris, but is not the same
+ as used by the GNU tar program.</p>
+ <p>By convention, the name of a tar file should end in "<c>.tar</c>".
+ To abide to the convention, you'll need to add "<c>.tar</c>" yourself
+ to the name.</p>
+ <p>Tar files can be created in one operation using the
+ <seealso marker="#create_2">create/2</seealso> or
+ <seealso marker="#create_3">create/3</seealso> function.</p>
+ <p>Alternatively, for more control, the
+ <seealso marker="#open">open</seealso>,
+ <seealso marker="#add">add/3,4</seealso>, and
+ <seealso marker="#close">close/1</seealso> functions can be used.</p>
+ <p>To extract all files from a tar file, use the
+ <seealso marker="#extract_1">extract/1</seealso> function.
+ To extract only some files or to be able to specify some more options,
+ use the <seealso marker="#extract_2">extract/2</seealso> function.</p>
+ <p>To return a list of the files in a tar file,
+ use either the <seealso marker="#table_1">table/1</seealso> or
+ <seealso marker="#table_2">table/2</seealso> function.
+ To print a list of files to the Erlang shell,
+ use either the <seealso marker="#t_1">t/1</seealso> or
+ <seealso marker="#tt_1">tt/1</seealso> function.</p>
+ <p>To convert an error term returned from one of the functions
+ above to a readable message, use the
+ <seealso marker="#format_error_1">format_error/1</seealso> function.</p>
+ </description>
+
+ <section>
+ <title>LIMITATIONS</title>
+ <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 <c>tar</c> program.</p>
+ <p>If filenames exceed 100 characters in length, the resulting tar
+ file can only be correctly extracted by a POSIX-compatible <c>tar</c>
+ program (such as Solaris <c>tar</c>), not by GNU tar.</p>
+ <p>File have longer names than 256 bytes cannot be stored at all.</p>
+ <p>The filename of the file a symbolic link points is always limited
+ to 100 characters.</p>
+ </section>
+ <funcs>
+ <func>
+ <name>add(TarDescriptor, Filename, Options) -> RetValue</name>
+ <fsummary>Add a file to an open tar file</fsummary>
+ <type>
+ <v>TarDescriptor = term()</v>
+ <v>Filename = filename()</v>
+ <v>Options = [Option]</v>
+ <v>Option = dereference|verbose</v>
+ <v>RetValue = ok|{error,{Filename,Reason}}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>The <marker id="add"></marker>
+<c>add/3</c> function adds a file to a tar file
+ that has been opened for writing by
+ <seealso marker="#open">open/1</seealso>.</p>
+ <taglist>
+ <tag><c>dereference</c></tag>
+ <item>
+ <p>By default, symbolic links will be stored as symbolic links
+ in the tar file. Use the <c>dereference</c> option to override the
+ default and store the file that the symbolic link points to into
+ the tar file.</p>
+ </item>
+ <tag><c>verbose</c></tag>
+ <item>
+ <p>Print an informational message about the file being added.</p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>add(TarDescriptor, FilenameOrBin, NameInArchive, Options) -> RetValue </name>
+ <fsummary>Add a file to an open tar file</fsummary>
+ <type>
+ <v>TarDescriptor = term()</v>
+ <v>FilenameOrBin = Filename()|binary()</v>
+ <v>Filename = filename()()</v>
+ <v>NameInArchive = filename()</v>
+ <v>Options = [Option]</v>
+ <v>Option = dereference|verbose</v>
+ <v>RetValue = ok|{error,{Filename,Reason}}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>The <c>add/4</c> function adds a file to a tar file
+ that has been opened for writing by
+ <seealso marker="#open">open/1</seealso>. It accepts the same
+ options as <seealso marker="#add">add/3</seealso>.</p>
+ <p><c>NameInArchive</c> 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.</p>
+ </desc>
+ </func>
+ <func>
+ <name>close(TarDescriptor)</name>
+ <fsummary>Close an open tar file</fsummary>
+ <type>
+ <v>TarDescriptor = term()</v>
+ </type>
+ <desc>
+ <p>The <marker id="close"></marker>
+<c>close/1</c> function closes a tar file
+ opened by <seealso marker="#open">open/1</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>create(Name, FileList) ->RetValue </name>
+ <fsummary>Create a tar archive</fsummary>
+ <type>
+ <v>Name = filename()</v>
+ <v>FileList = [Filename|{NameInArchive, binary()},{NameInArchive, Filename}]</v>
+ <v>Filename = filename()</v>
+ <v>NameInArchive = filename()</v>
+ <v>RetValue = ok|{error,{Name,Reason}} &lt;V>Reason = term()</v>
+ </type>
+ <desc>
+ <p>The <marker id="create_2"></marker>
+<c>create/2</c> function creates a tar file and
+ archives the files whose names are given in <c>FileList</c> into it.
+ The files may either be read from disk or given as
+ binaries.</p>
+ </desc>
+ </func>
+ <func>
+ <name>create(Name, FileList, OptionList)</name>
+ <fsummary>Create a tar archive with options</fsummary>
+ <type>
+ <v>Name = filename()</v>
+ <v>FileList = [Filename|{NameInArchive, binary()},{NameInArchive, Filename}]</v>
+ <v>Filename = filename()</v>
+ <v>NameInArchive = filename()</v>
+ <v>OptionList = [Option]</v>
+ <v>Option = compressed|cooked|dereference|verbose</v>
+ <v>RetValue = ok|{error,{Name,Reason}} &lt;V>Reason = term()</v>
+ </type>
+ <desc>
+ <p>The <marker id="create_3"></marker>
+<c>create/3</c> function
+ creates a tar file and archives the files whose names are given
+ in <c>FileList</c> into it. The files may either be read from
+ disk or given as binaries.</p>
+ <p>The options in <c>OptionList</c> modify the defaults as follows.
+ </p>
+ <taglist>
+ <tag><c>compressed</c></tag>
+ <item>
+ <p>The entire tar file will be compressed, as if it has
+ been run through the <c>gzip</c> program. To abide to the
+ convention that a compressed tar file should end in "<c>.tar.gz</c>" or
+ "<c>.tgz</c>", you'll need to add the appropriate extension yourself.</p>
+ </item>
+ <tag><c>cooked</c></tag>
+ <item>
+ <p>By default, the <c>open/2</c> function will open the tar file
+ in <c>raw</c> mode, which is faster but does not allow a remote (erlang)
+ file server to be used. Adding <c>cooked</c> to the mode list will
+ override the default and open the tar file without the <c>raw</c>
+ option.</p>
+ </item>
+ <tag><c>dereference</c></tag>
+ <item>
+ <p>By default, symbolic links will be stored as symbolic links
+ in the tar file. Use the <c>dereference</c> option to override the
+ default and store the file that the symbolic link points to into
+ the tar file.</p>
+ </item>
+ <tag><c>verbose</c></tag>
+ <item>
+ <p>Print an informational message about each file being added.</p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>extract(Name) -> RetValue</name>
+ <fsummary>Extract all files from a tar file</fsummary>
+ <type>
+ <v>Name = filename()</v>
+ <v>RetValue = ok|{error,{Name,Reason}}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>The <marker id="extract_1"></marker>
+<c>extract/1</c> function extracts
+ all files from a tar archive.</p>
+ <p>If the <c>Name</c> argument is given as "<c>{binary,Binary}</c>",
+ the contents of the binary is assumed to be a tar archive.
+ </p>
+ <p>If the <c>Name</c> argument is given as "<c>{file,Fd}</c>",
+ <c>Fd</c> is assumed to be a file descriptor returned from
+ the <c>file:open/2</c> function.
+ </p>
+ <p>Otherwise, <c>Name</c> should be a filename.</p>
+ </desc>
+ </func>
+ <func>
+ <name>extract(Name, OptionList)</name>
+ <fsummary>Extract files from a tar file</fsummary>
+ <type>
+ <v>Name = filename() | {binary,Binary} | {file,Fd} </v>
+ <v>Binary = binary()</v>
+ <v>Fd = file_descriptor()</v>
+ <v>OptionList = [Option]</v>
+ <v>Option = {cwd,Cwd}|{files,FileList}|keep_old_files|verbose|memory</v>
+ <v>Cwd = [dirname()]</v>
+ <v>FileList = [filename()]</v>
+ <v>RetValue = ok|MemoryRetValue|{error,{Name,Reason}}</v>
+ <v>MemoryRetValue = {ok, [{NameInArchive,binary()}]}</v>
+ <v>NameInArchive = filename()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>The <marker id="extract_2"></marker>
+<c>extract/2</c> function extracts
+ files from a tar archive.</p>
+ <p>If the <c>Name</c> argument is given as "<c>{binary,Binary}</c>",
+ the contents of the binary is assumed to be a tar archive.
+ </p>
+ <p>If the <c>Name</c> argument is given as "<c>{file,Fd}</c>",
+ <c>Fd</c> is assumed to be a file descriptor returned from
+ the <c>file:open/2</c> function.
+ </p>
+ <p>Otherwise, <c>Name</c> should be a filename.
+ </p>
+ <p>The following options modify the defaults for the extraction as
+ follows.</p>
+ <taglist>
+ <tag><c>{cwd,Cwd}</c></tag>
+ <item>
+ <p>Files with relative filenames will by default be extracted
+ to the current working directory.
+ Given the <c>{cwd,Cwd}</c> option, the <c>extract/2</c> function
+ will extract into the directory <c>Cwd</c> instead of to the current
+ working directory.</p>
+ </item>
+ <tag><c>{files,FileList}</c></tag>
+ <item>
+ <p>By default, all files will be extracted from the tar file.
+ Given the <c>{files,Files}</c> option, the <c>extract/2</c> function
+ will only extract the files whose names are included in <c>FileList</c>.</p>
+ </item>
+ <tag><c>compressed</c></tag>
+ <item>
+ <p>Given the <c>compressed</c> option, the <c>extract/2</c>
+ function will uncompress the file while extracting
+ If the tar file is not actually compressed, the <c>compressed</c>
+ will effectively be ignored.</p>
+ </item>
+ <tag><c>cooked</c></tag>
+ <item>
+ <p>By default, the <c>open/2</c> function will open the tar file
+ in <c>raw</c> mode, which is faster but does not allow a remote (erlang)
+ file server to be used. Adding <c>cooked</c> to the mode list will
+ override the default and open the tar file without the <c>raw</c>
+ option.</p>
+ </item>
+ <tag><c>memory</c></tag>
+ <item>
+ <p>Instead of extracting to a directory, the memory option will
+ give the result as a list of tuples {Filename, Binary}, where
+ Binary is a binary containing the extracted data of the file named
+ Filename in the tar file.</p>
+ </item>
+ <tag><c>keep_old_files</c></tag>
+ <item>
+ <p>By default, all existing files with the same name as file in
+ the tar file will be overwritten
+ Given the <c>keep_old_files</c> option, the <c>extract/2</c> function
+ will not overwrite any existing files.</p>
+ </item>
+ <tag><c>verbose</c></tag>
+ <item>
+ <p>Print an informational message as each file is being extracted.</p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>format_error(Reason) -> string()</name>
+ <fsummary>Convert error term to a readable string</fsummary>
+ <type>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>The <marker id="format_error_1"></marker>
+<c>format_error/1</c> converts
+ an error reason term to a human-readable error message string.</p>
+ </desc>
+ </func>
+ <func>
+ <name>open(Name, OpenModeList) -> RetValue</name>
+ <fsummary>Open a tar file for writing.</fsummary>
+ <type>
+ <v>Name = filename()</v>
+ <v>OpenModeList = [OpenMode]</v>
+ <v>Mode = write|compressed|cooked</v>
+ <v>RetValue = {ok,TarDescriptor}|{error,{Name,Reason}}</v>
+ <v>TarDescriptor = term()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>The <marker id="open"></marker>
+<c>open/2</c> function creates a tar file for writing.
+ (Any existing file with the same name will be truncated.)</p>
+ <p>By convention, the name of a tar file should end in "<c>.tar</c>".
+ To abide to the convention, you'll need to add "<c>.tar</c>" yourself
+ to the name.</p>
+ <p>Except for the <c>write</c> atom the following atoms
+ may be added to <c>OpenModeList</c>:</p>
+ <taglist>
+ <tag><c>compressed</c></tag>
+ <item>
+ <p>The entire tar file will be compressed, as if it has
+ been run through the <c>gzip</c> program. To abide to the
+ convention that a compressed tar file should end in "<c>.tar.gz</c>" or
+ "<c>.tgz</c>", you'll need to add the appropriate extension yourself.</p>
+ </item>
+ <tag><c>cooked</c></tag>
+ <item>
+ <p>By default, the <c>open/2</c> function will open the tar file
+ in <c>raw</c> mode, which is faster but does not allow a remote (erlang)
+ file server to be used. Adding <c>cooked</c> to the mode list will
+ override the default and open the tar file without the <c>raw</c>
+ option.</p>
+ </item>
+ </taglist>
+ <p>Use the <seealso marker="#add">add/3,4</seealso> functions
+ to add one file at the time into an opened tar file. When you are
+ finished adding files, use the <seealso marker="#close">close</seealso>
+ function to close the tar file.</p>
+ <warning>
+ <p>The <c>TarDescriptor</c> term is not a file descriptor.
+ You should not rely on the specific contents of the <c>TarDescriptor</c>
+ term, as it may change in future versions as more features are added
+ to the <c>erl_tar</c> module.</p>
+ <p></p>
+ </warning>
+ </desc>
+ </func>
+ <func>
+ <name>table(Name) -> RetValue</name>
+ <fsummary>Retrieve the name of all files in a tar file</fsummary>
+ <type>
+ <v>Name = filename()</v>
+ <v>RetValue = {ok,[string()]}|{error,{Name,Reason}}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>The <marker id="table_1"></marker>
+<c>table/1</c> function retrieves
+ the names of all files in the tar file <c>Name</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>table(Name, Options)</name>
+ <fsummary>Retrieve name and information of all files in a tar file</fsummary>
+ <type>
+ <v>Name = filename()</v>
+ </type>
+ <desc>
+ <p>The <marker id="table_2"></marker>
+<c>table/2</c> function retrieves
+ the names of all files in the tar file <c>Name</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>t(Name)</name>
+ <fsummary>Print the name of each file in a tar file</fsummary>
+ <type>
+ <v>Name = filename()</v>
+ </type>
+ <desc>
+ <p>The <marker id="t_1"></marker>
+<c>t/1</c> function prints the names
+ of all files in the tar file <c>Name</c> to the Erlang shell.
+ (Similar to "<c>tar&nbsp;t</c>".)</p>
+ </desc>
+ </func>
+ <func>
+ <name>tt(Name)</name>
+ <fsummary>Print name and information for each file in a tar file</fsummary>
+ <type>
+ <v>Name = filename()</v>
+ </type>
+ <desc>
+ <p>The <marker id="tt_1"></marker>
+<c>tt/1</c> function prints names and
+ information about all files in the tar file <c>Name</c> to
+ the Erlang shell. (Similar to "<c>tar&nbsp;tv</c>".)</p>
+ </desc>
+ </func>
+ </funcs>
+</erlref>
+