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.xml608
1 files changed, 314 insertions, 294 deletions
diff --git a/lib/stdlib/doc/src/erl_tar.xml b/lib/stdlib/doc/src/erl_tar.xml
index 1f4a43f622..24e7b64b9e 100644
--- a/lib/stdlib/doc/src/erl_tar.xml
+++ b/lib/stdlib/doc/src/erl_tar.xml
@@ -28,117 +28,146 @@
<docno>1</docno>
<approved>Kenneth Lundin</approved>
<checked></checked>
- <date>03-01-21</date>
+ <date>2003-01-21</date>
<rev>A</rev>
- <file>erl_tar.sgml</file>
+ <file>erl_tar.xml</file>
</header>
<module>erl_tar</module>
- <modulesummary>Unix 'tar' utility for reading and writing tar archives</modulesummary>
+ <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. <c>erl_tar</c> supports the <c>ustar</c> format
+ <p>This module archives and extract files to and from
+ a tar file. This module supports the <c>ustar</c> format
(IEEE Std 1003.1 and ISO/IEC&nbsp;9945-1). All modern <c>tar</c>
programs (including GNU tar) can read this format. To ensure that
that GNU tar produces a tar file that <c>erl_tar</c> can read,
- give the <c>--format=ustar</c> option to GNU tar.</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.
+ specify option <c>--format=ustar</c> to GNU tar.</p>
+
+ <p>By convention, the name of a tar file is to end in "<c>.tar</c>".
+ To abide to the convention, add "<c>.tar</c>" to the name.</p>
+
+ <p>Tar files can be created in one operation using function
+ <seealso marker="#create/2"><c>create/2</c></seealso> or
+ <seealso marker="#create/3"><c>create/3</c></seealso>.</p>
+
+ <p>Alternatively, for more control, use functions
+ <seealso marker="#open/2"><c>open/2</c></seealso>,
+ <seealso marker="#add/3"><c>add/3,4</c></seealso>, and
+ <seealso marker="#close/1"><c>close/1</c></seealso>.</p>
+
+ <p>To extract all files from a tar file, use function
+ <seealso marker="#extract/1"><c>extract/1</c></seealso>.
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>
+ use function <seealso marker="#extract/2"><c>extract/2</c></seealso>.</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.
+ use function <seealso marker="#table/1"><c>table/1</c></seealso> or
+ <seealso marker="#table/2"><c>table/2</c></seealso>.
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>
+ use function <seealso marker="#t/1"><c>t/1</c></seealso> or
+ <seealso marker="#tt/1"><c>tt/1</c></seealso>.</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>
+ above to a readable message, use function
+ <seealso marker="#format_error/1"><c>format_error/1</c></seealso>.</p>
</description>
<section>
- <title>UNICODE SUPPORT</title>
- <p>If <seealso
- marker="kernel:file#native_name_encoding/0">file:native_name_encoding/0</seealso>
- returns <c>utf8</c>, path names will be encoded in UTF-8 when
- creating tar files and path names will be assumed to be encoded in
- UTF-8 when extracting tar files.</p>
+ <title>Unicode Support</title>
+ <p>If <seealso marker="kernel:file#native_name_encoding/0">
+ <c>file:native_name_encoding/0</c></seealso>
+ returns <c>utf8</c>, path names are encoded in UTF-8 when
+ creating tar files, and path names are assumed to be encoded in
+ UTF-8 when extracting tar files.</p>
- <p>If <seealso
- marker="kernel:file#native_name_encoding/0">file:native_name_encoding/0</seealso>
- returns <c>latin1</c>, no translation of path names will be
- done.</p>
+ <p>If <seealso marker="kernel:file#native_name_encoding/0">
+ <c>file:native_name_encoding/0</c></seealso>
+ returns <c>latin1</c>, no translation of path names is done.</p>
</section>
<section>
- <title>OTHER STORAGE MEDIA</title>
- <p>The <c>erl_ftp</c> module normally accesses the tar-file on disk using the <seealso marker="kernel:file">file module</seealso>. When other needs arise, there is a way to define your own low-level Erlang functions to perform the writing and reading on the storage media. See <seealso marker="#init/3">init/3</seealso> for usage.</p>
- <p>An example of this is the sftp support in <seealso marker="ssh:ssh_sftp#open_tar/3">ssh_sftp:open_tar/3</seealso>. That function opens a tar file on a remote machine using an sftp channel.</p>
+ <title>Other Storage Media</title>
+ <p>The <seealso marker="inets:ftp"><c>ftp</c></seealso>
+ module (Inets) normally accesses the tar file on disk using
+ the <seealso marker="kernel:file"><c>file</c></seealso> module.
+ When other needs arise, you can define your own low-level Erlang
+ functions to perform the writing and reading on the storage media;
+ use function <seealso marker="#init/3"><c>init/3</c></seealso>.</p>
+
+ <p>An example of this is the SFTP support in
+ <seealso marker="ssh:ssh_sftp#open_tar/3">
+ <c>ssh_sftp:open_tar/3</c></seealso>. This function opens a tar file
+ on a remote machine using an SFTP channel.</p>
</section>
<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>
+ <title>Limitations</title>
+ <list type="bulleted">
+ <item>
+ <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>
+ </item>
+ <item>
+ <p>For filenames exceeding 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> or a modern GNU <c>tar</c>).</p>
+ </item>
+ <item>
+ <p>Files with longer names than 256 bytes cannot be stored.</p>
+ </item>
+ <item>
+ <p>The file name a symbolic link points is always limited
+ to 100 characters.</p>
+ </item>
+ </list>
</section>
+
<funcs>
<func>
<name>add(TarDescriptor, Filename, Options) -> RetValue</name>
- <fsummary>Add a file to an open tar file</fsummary>
+ <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|{chunks,ChunkSize}</v>
- <v>ChunkSize = positive_integer()</v>
+ <v>ChunkSize = positive_integer()</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>
+ <p>Adds a file to a tar file that has been opened for writing by
+ <seealso marker="#open/2"><c>open/1</c></seealso>.</p>
+ <p>Options:</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>
+ <p>By default, symbolic links are stored as symbolic links
+ in the tar file. To override the default and store the file
+ that the symbolic link points to into the tar file, use
+ option <c>dereference</c>.</p>
</item>
<tag><c>verbose</c></tag>
<item>
- <p>Print an informational message about the file being added.</p>
+ <p>Prints an informational message about the added file.</p>
+ </item>
+ <tag><c>{chunks,ChunkSize}</c></tag>
+ <item>
+ <p>Reads data in parts from the file. This is intended for
+ memory-limited machines that, for example, builds a tar file
+ on a remote machine over SFTP, see
+ <seealso marker="ssh:ssh_sftp#open_tar/3">
+ <c>ssh_sftp:open_tar/3</c></seealso>.</p>
</item>
- <tag><c>{chunks,ChunkSize}</c></tag>
- <item>
- <p>Read data in parts from the file. This is intended for memory-limited
- machines that for example builds a tar file on a remote machine over
- <seealso marker="ssh:ssh_sftp#open_tar/3">sftp</seealso>.</p>
- </item>
</taglist>
</desc>
</func>
+
<func>
- <name>add(TarDescriptor, FilenameOrBin, NameInArchive, Options) -> RetValue </name>
- <fsummary>Add a file to an open tar file</fsummary>
+ <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>
@@ -150,53 +179,55 @@
<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>
+ <p>Adds a file to a tar file that has been opened for writing by
+ <seealso marker="#open/2"><c>open/2</c></seealso>. This function
+ accepts the same options as
+ <seealso marker="#add/3"><c>add/3</c></seealso>.</p>
+ <p><c>NameInArchive</c> is the name under which the file becomes
+ stored in the tar file. The file gets this name when it is
+ extracted from the tar file.</p>
</desc>
</func>
+
<func>
<name>close(TarDescriptor)</name>
- <fsummary>Close an open tar file</fsummary>
+ <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>
+ <p>Closes a tar file
+ opened by <seealso marker="#open/2"><c>open/2</c></seealso>.</p>
</desc>
</func>
+
<func>
<name>create(Name, FileList) ->RetValue </name>
- <fsummary>Create a tar archive</fsummary>
+ <fsummary>Create a tar archive.</fsummary>
<type>
<v>Name = filename()</v>
- <v>FileList = [Filename|{NameInArchive, binary()},{NameInArchive, Filename}]</v>
+ <v>FileList = [Filename|{NameInArchive, binary()},{NameInArchive,
+ Filename}]</v>
<v>Filename = filename()</v>
<v>NameInArchive = filename()</v>
<v>RetValue = ok|{error,{Name,Reason}}</v>
<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>
+ <p>Creates a tar file and archives the files whose names are specified
+ in <c>FileList</c> into it. The files can either be read from disk
+ or be specified as binaries.</p>
</desc>
</func>
+
<func>
<name>create(Name, FileList, OptionList)</name>
- <fsummary>Create a tar archive with options</fsummary>
+ <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>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>
@@ -204,68 +235,66 @@
<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>
+ <p>Creates a tar file and archives the files whose names are specified
+ in <c>FileList</c> into it. The files can either be read from disk
+ or be specified 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
+ <p>The entire tar file is 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>
+ convention that a compressed tar file is to end in
+ "<c>.tar.gz</c>" or "<c>.tgz</c>", add the appropriate
+ extension.</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>
+ <p>By default, function <c>open/2</c> opens 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 overrides the default and opens the tar file without
+ option <c>raw</c>.</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>
+ <p>By default, symbolic links are stored as symbolic links in
+ the tar file. To override the default and store the file that
+ the symbolic link points to into the tar file, use
+ option <c>dereference</c>.</p>
</item>
<tag><c>verbose</c></tag>
<item>
- <p>Print an informational message about each file being added.</p>
+ <p>Prints an informational message about each added file.</p>
</item>
</taglist>
</desc>
</func>
+
<func>
<name>extract(Name) -> RetValue</name>
- <fsummary>Extract all files from a tar file</fsummary>
+ <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>
+ <p>Extracts all files from a tar archive.</p>
+ <p>If argument <c>Name</c> is specified as <c>{binary,Binary}</c>,
+ the contents of the binary is assumed to be a tar archive.</p>
+ <p>If argument <c>Name</c> is specified as <c>{file,Fd}</c>,
+ <c>Fd</c> is assumed to be a file descriptor returned from function
+ <c>file:open/2</c>.</p>
+ <p>Otherwise, <c>Name</c> is to be a filename.</p>
</desc>
</func>
+
<func>
<name>extract(Name, OptionList)</name>
- <fsummary>Extract files from a tar file</fsummary>
+ <fsummary>Extract files from a tar file.</fsummary>
<type>
- <v>Name = filename() | {binary,Binary} | {file,Fd} </v>
+ <v>Name = filename() | {binary,Binary} | {file,Fd}</v>
<v>Binary = binary()</v>
<v>Fd = file_descriptor()</v>
<v>OptionList = [Option]</v>
@@ -278,272 +307,263 @@
<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>Extracts files from a tar archive.</p>
+ <p>If argument <c>Name</c> is specified as <c>{binary,Binary}</c>,
+ the contents of the binary is assumed to be a tar archive.</p>
+ <p>If argument <c>Name</c> is specified as <c>{file,Fd}</c>,
+ <c>Fd</c> is assumed to be a file descriptor returned from function
+ <c>file:open/2</c>.</p>
+ <p>Otherwise, <c>Name</c> is to be a filename.</p>
<p>The following options modify the defaults for the extraction as
- follows.</p>
+ 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>
+ <p>Files with relative filenames are by default extracted
+ to the current working directory. With this option, files are
+ instead extracted into directory <c>Cwd</c>.</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>
+ <p>By default, all files are extracted from the tar file. With
+ this option, only those files are extracted 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>
+ <p>With this option, the file is uncompressed while extracting.
+ If the tar file is not compressed, this option is 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>
+ <p>By default, function <c>open/2</c> function opens 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 overrides the default and opens the tar file without option
+ <c>raw</c>.</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>
+ <p>Instead of extracting to a directory, this option gives the
+ result as a list of tuples <c>{Filename, Binary}</c>, where
+ <c>Binary</c> is a binary containing the extracted data of the
+ file named <c>Filename</c> 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>
+ <p>By default, all existing files with the same name as files in
+ the tar file are overwritten. With this option, existing
+ files are not overwriten.</p>
</item>
<tag><c>verbose</c></tag>
<item>
- <p>Print an informational message as each file is being extracted.</p>
+ <p>Prints an informational message for each extracted file.</p>
</item>
</taglist>
</desc>
</func>
+
<func>
<name>format_error(Reason) -> string()</name>
- <fsummary>Convert error term to a readable string</fsummary>
+ <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>
- function converts
- an error reason term to a human-readable error message string.</p>
+ <p>Cconverts 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>
+ <name>init(UserPrivate, AccessMode, Fun) ->
+ {ok,TarDescriptor} | {error,Reason}</name>
+ <fsummary>Create a <c>TarDescriptor</c> used in subsequent tar operations
+ when defining own low-level storage access functions.</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>UserPrivate = term()</v>
+ <v>AccessMode = [write] | [read]</v>
+ <v>Fun when AccessMode is [write] =
+ fun(write, {UserPrivate,DataToWrite})->...;
+ (position,{UserPrivate,Position})->...;
+ (close, UserPrivate)->... end</v>
+ <v>Fun when AccessMode is [read] =
+ fun(read2, {UserPrivate,Size})->...;
+ (position,{UserPrivate,Position})->...;
+ (close, UserPrivate)->... end</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>
+ <p>The <c>Fun</c> is the definition of what to do when the different
+ storage operations functions are to be called from the higher tar
+ handling functions (such as <c>add/3</c>, <c>add/4</c>, and
+ <c>close/1</c>).</p>
+ <p>The <c>Fun</c> is called when the tar function wants to do a
+ low-level operation, like writing a block to a file. The <c>Fun</c>
+ is called as <c>Fun(Op, {UserPrivate,Parameters...})</c>, where
+ <c>Op</c> is the operation name, <c>UserPrivate</c> is the term
+ passed as the first argument to <c>init/1</c> and
+ <c>Parameters...</c> are the data added by the tar function to be
+ passed down to the storage handling function.</p>
+ <p>Parameter <c>UserPrivate</c> is typically the result of opening a
+ low-level structure like a file descriptor or an SFTP channel id.
+ The different <c>Fun</c> clauses operate on that very term.</p>
+ <p>The following are the fun clauses parameter lists:</p>
<taglist>
- <tag><c>compressed</c></tag>
+ <tag><c>(write, {UserPrivate,DataToWrite})</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>
+ <p>Writes term <c>DataToWrite</c> using <c>UserPrivate</c>.</p>
</item>
- <tag><c>cooked</c></tag>
+ <tag><c>(close, UserPrivate)</c></tag>
+ <item>
+ <p>Closes the access.</p>
+ </item>
+ <tag><c>(read2, {UserPrivate,Size})</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>
+ <p>Reads using <c>UserPrivate</c> but only <c>Size</c> bytes.
+ Notice that there is only an arity-2 read function, not an arity-1
+ function.</p>
+ </item>
+ <tag><c>(position,{UserPrivate,Position})</c></tag>
+ <item>
+ <p>Sets the position of <c>UserPrivate</c> as defined for files in
+ <seealso marker="kernel:file#position-2">
+ <c>file:position/2</c></seealso></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>
+ <p><em>Example:</em></p>
+ <p>The following is a complete <c>Fun</c> parameter for reading and
+ writing on files using the
+ <seealso marker="kernel:file"><c>file</c></seealso> module:</p>
+ <code type="none">
+ExampleFun =
+ fun(write, {Fd,Data}) -> file:write(Fd, Data);
+ (position, {Fd,Pos}) -> file:position(Fd, Pos);
+ (read2, {Fd,Size}) -> file:read(Fd, Size);
+ (close, Fd) -> file:close(Fd)
+ end</code>
+ <p>Here <c>Fd</c> was specified to function <c>init/3</c> as:</p>
+ <code>
+{ok,Fd} = file:open(Name, ...).
+{ok,TarDesc} = erl_tar:init(Fd, [write], ExampleFun),</code>
+ <p><c>TarDesc</c> is then used:</p>
+ <code>
+erl_tar:add(TarDesc, SomeValueIwantToAdd, FileNameInTarFile),
+...,
+erl_tar:close(TarDesc)</code>
+ <p>When the <c>erl_tar</c> core wants to, for example, write a piece
+ of <c>Data</c>, it would call
+ <c>ExampleFun(write, {UserPrivate,Data})</c>.</p>
+ <note>
+ <p>This example with the <c>file</c> module operations is
+ not necessary to use directly, as that is what function
+ <seealso marker="#open/2"><c>open/2</c></seealso> in principle
+ does.</p>
+ </note>
<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>The <c>TarDescriptor</c> term is not a file descriptor. You are
+ advised not to rely on the specific contents of this term, as it
+ can change in future Erlang/OTP releases when more features are
+ added to this module.</p>
</warning>
</desc>
</func>
<func>
- <name>init(UserPrivate, AccessMode, Fun) -> {ok,TarDescriptor} | {error,Reason}
-</name>
- <fsummary>Creates a TarDescriptor used in subsequent tar operations when
- defining own low-level storage access functions
- </fsummary>
+ <name>open(Name, OpenModeList) -> RetValue</name>
+ <fsummary>Open a tar file for writing.</fsummary>
<type>
- <v>UserPrivate = term()</v>
- <v>AccessMode = [write] | [read]</v>
- <v>Fun when AccessMode is [write] = fun(write, {UserPrivate,DataToWrite})->...;
- (position,{UserPrivate,Position})->...;
- (close, UserPrivate)->...
- end
- </v>
- <v>Fun when AccessMode is [read] = fun(read2, {UserPrivate,Size})->...;
- (position,{UserPrivate,Position})->...;
- (close, UserPrivate)->...
- end
- </v>
- <v>TarDescriptor = term()</v>
- <v>Reason = term()</v>
+ <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 <c>Fun</c> is the definition of what to do when the different
- storage operations functions are to be called from the higher tar
- handling functions (<c>add/3</c>, <c>add/4</c>, <c>close/1</c>...).
- </p>
- <p>The <c>Fun</c> will be called when the tar function wants to do
- a low-level operation, like writing a block to a file. The Fun is called
- as <c>Fun(Op,{UserPrivate,Parameters...})</c> where <c>Op</c> is the operation name,
- <c>UserPrivate</c> is the term passed as the first argument to <c>init/1</c> and
- <c>Parameters...</c> are the data added by the tar function to be passed down to
- the storage handling function.
- </p>
- <p>The parameter <c>UserPrivate</c> is typically the result of opening a low level
- structure like a file descriptor, a sftp channel id or such. The different <c>Fun</c>
- clauses operates on that very term.
- </p>
- <p>The fun clauses parameter lists are:</p>
- <taglist>
- <tag><c>(write, {UserPrivate,DataToWrite})</c></tag>
- <item>Write the term <c>DataToWrite</c> using <c>UserPrivate</c></item>
- <tag><c>(close, UserPrivate)</c></tag>
- <item>Close the access.</item>
- <tag><c>(read2, {UserPrivate,Size})</c></tag>
- <item>Read using <c>UserPrivate</c> but only <c>Size</c> bytes. Note that there is
- only an arity-2 read function, not an arity-1
- </item>
- <tag><c> (position,{UserPrivate,Position})</c></tag>
- <item>Sets the position of <c>UserPrivate</c> as defined for files in <seealso marker="kernel:file#position-2">file:position/2</seealso></item>
- <tag><c></c></tag>
- <item></item>
- </taglist>
- <p>A complete <c>Fun</c> parameter for reading and writing on files using the
- <seealso marker="kernel:file">file module</seealso> could be:
- </p>
- <code type="none">
- ExampleFun =
- fun(write, {Fd,Data}) -> file:write(Fd, Data);
- (position, {Fd,Pos}) -> file:position(Fd, Pos);
- (read2, {Fd,Size}) -> file:read(Fd,Size);
- (close, Fd) -> file:close(Fd)
- end
- </code>
- <p>where <c>Fd</c> was given to the <c>init/3</c> function as:</p>
- <code>
- {ok,Fd} = file:open(Name,...).
- {ok,TarDesc} = erl_tar:init(Fd, [write], ExampleFun),
- </code>
- <p>The <c>TarDesc</c> is then used:</p>
- <code>
- erl_tar:add(TarDesc, SomeValueIwantToAdd, FileNameInTarFile),
- ....,
- erl_tar:close(TarDesc)
- </code>
- <p>When the erl_tar core wants to e.g. write a piece of Data, it would call
- <c>ExampleFun(write,{UserPrivate,Data})</c>.
- </p>
- <note>
- <p>The example above with <c>file</c> module operations is not necessary to
- use directly since that is what the <seealso marker="#open">open</seealso> function
- in principle does.
- </p>
- </note>
+ <p>Creates a tar file for writing (any existing file with the same
+ name is truncated).</p>
+ <p>By convention, the name of a tar file is to end in "<c>.tar</c>".
+ To abide to the convention, add "<c>.tar</c>" to the name.</p>
+ <p>Except for the <c>write</c> atom, the following atoms
+ can be added to <c>OpenModeList</c>:</p>
+ <taglist>
+ <tag><c>compressed</c></tag>
+ <item>
+ <p>The entire tar file is compressed, as if it has been run
+ through the <c>gzip</c> program. To abide to the convention
+ that a compressed tar file is to end in "<c>.tar.gz</c>" or
+ "<c>.tgz</c>", add the appropriate extension.</p>
+ </item>
+ <tag><c>cooked</c></tag>
+ <item>
+ <p>By default, the tar file is opened 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 overrides the
+ default and opens the tar file without option <c>raw</c>.</p>
+ </item>
+ </taglist>
+ <p>To add one file at the time into an opened tar file, use function
+ <seealso marker="#add/3"><c>add/3,4</c></seealso>. When you are
+ finished adding files, use function <seealso marker="#close/1">
+ <c>close/1</c></seealso> 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>The <c>TarDescriptor</c> term is not a file descriptor. You are
+ advised not to rely on the specific contents of this term, as it
+ can change in future Erlang/OTP releases when more features are
+ added to this module..</p>
</warning>
</desc>
</func>
<func>
<name>table(Name) -> RetValue</name>
- <fsummary>Retrieve the name of all files in a tar file</fsummary>
+ <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>
+ <p>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>
+ <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>
+ <p>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>
+ <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>
+ <p>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>
+ <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>
+ <p>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>