From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/stdlib/doc/src/erl_tar.xml | 434 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 434 insertions(+) create mode 100644 lib/stdlib/doc/src/erl_tar.xml (limited to 'lib/stdlib/doc/src/erl_tar.xml') 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 @@ + + + + +
+ + 20032009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + erl_tar + Bjorn Gustavsson + Bjorn Gustavsson + 1 + Kenneth Lundin + + 03-01-21 + A + erl_tar.sgml +
+ erl_tar + Unix 'tar' utility for reading and writing tar archives + +

The erl_tar 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 9945-1. That is the same + format as used by tar program on Solaris, but is not the same + as used by the GNU tar program.

+

By convention, the name of a tar file should end in ".tar". + To abide to the convention, you'll need to add ".tar" yourself + to the name.

+

Tar files can be created in one operation using the + create/2 or + create/3 function.

+

Alternatively, for more control, the + open, + add/3,4, and + close/1 functions can be used.

+

To extract all files from a tar file, use the + extract/1 function. + To extract only some files or to be able to specify some more options, + use the extract/2 function.

+

To return a list of the files in a tar file, + use either the table/1 or + table/2 function. + To print a list of files to the Erlang shell, + use either the t/1 or + tt/1 function.

+

To convert an error term returned from one of the functions + above to a readable message, use the + format_error/1 function.

+ + +
+ LIMITATIONS +

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 tar program.

+

If filenames exceed 100 characters in length, the resulting tar + file can only be correctly extracted by a POSIX-compatible tar + program (such as Solaris tar), not by GNU tar.

+

File have longer names than 256 bytes cannot be stored at all.

+

The filename of the file a symbolic link points is always limited + to 100 characters.

+
+ + + add(TarDescriptor, Filename, Options) -> RetValue + Add a file to an open tar file + + TarDescriptor = term() + Filename = filename() + Options = [Option] + Option = dereference|verbose + RetValue = ok|{error,{Filename,Reason}} + Reason = term() + + +

The +add/3 function adds a file to a tar file + that has been opened for writing by + open/1.

+ + dereference + +

By default, symbolic links will be stored as symbolic links + in the tar file. Use the dereference option to override the + default and store the file that the symbolic link points to into + the tar file.

+ + verbose + +

Print an informational message about the file being added.

+ + + + + + add(TarDescriptor, FilenameOrBin, NameInArchive, Options) -> RetValue + Add a file to an open tar file + + TarDescriptor = term() + FilenameOrBin = Filename()|binary() + Filename = filename()() + NameInArchive = filename() + Options = [Option] + Option = dereference|verbose + RetValue = ok|{error,{Filename,Reason}} + Reason = term() + + +

The add/4 function adds a file to a tar file + that has been opened for writing by + open/1. It accepts the same + options as add/3.

+

NameInArchive 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.

+ + + + close(TarDescriptor) + Close an open tar file + + TarDescriptor = term() + + +

The +close/1 function closes a tar file + opened by open/1.

+ + + + create(Name, FileList) ->RetValue + Create a tar archive + + Name = filename() + FileList = [Filename|{NameInArchive, binary()},{NameInArchive, Filename}] + Filename = filename() + NameInArchive = filename() + RetValue = ok|{error,{Name,Reason}} <V>Reason = term() + + +

The +create/2 function creates a tar file and + archives the files whose names are given in FileList into it. + The files may either be read from disk or given as + binaries.

+ + + + create(Name, FileList, OptionList) + Create a tar archive with options + + Name = filename() + FileList = [Filename|{NameInArchive, binary()},{NameInArchive, Filename}] + Filename = filename() + NameInArchive = filename() + OptionList = [Option] + Option = compressed|cooked|dereference|verbose + RetValue = ok|{error,{Name,Reason}} <V>Reason = term() + + +

The +create/3 function + creates a tar file and archives the files whose names are given + in FileList into it. The files may either be read from + disk or given as binaries.

+

The options in OptionList modify the defaults as follows. +

+ + compressed + +

The entire tar file will be compressed, as if it has + been run through the gzip program. To abide to the + convention that a compressed tar file should end in ".tar.gz" or + ".tgz", you'll need to add the appropriate extension yourself.

+ + cooked + +

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

+ + dereference + +

By default, symbolic links will be stored as symbolic links + in the tar file. Use the dereference option to override the + default and store the file that the symbolic link points to into + the tar file.

+ + verbose + +

Print an informational message about each file being added.

+ + + + + + extract(Name) -> RetValue + Extract all files from a tar file + + Name = filename() + RetValue = ok|{error,{Name,Reason}} + Reason = term() + + +

The +extract/1 function extracts + all files from a tar archive.

+

If the Name argument is given as "{binary,Binary}", + the contents of the binary is assumed to be a tar archive. +

+

If the Name argument is given as "{file,Fd}", + Fd is assumed to be a file descriptor returned from + the file:open/2 function. +

+

Otherwise, Name should be a filename.

+ + + + extract(Name, OptionList) + Extract files from a tar file + + Name = filename() | {binary,Binary} | {file,Fd} + Binary = binary() + Fd = file_descriptor() + OptionList = [Option] + Option = {cwd,Cwd}|{files,FileList}|keep_old_files|verbose|memory + Cwd = [dirname()] + FileList = [filename()] + RetValue = ok|MemoryRetValue|{error,{Name,Reason}} + MemoryRetValue = {ok, [{NameInArchive,binary()}]} + NameInArchive = filename() + Reason = term() + + +

The +extract/2 function extracts + files from a tar archive.

+

If the Name argument is given as "{binary,Binary}", + the contents of the binary is assumed to be a tar archive. +

+

If the Name argument is given as "{file,Fd}", + Fd is assumed to be a file descriptor returned from + the file:open/2 function. +

+

Otherwise, Name should be a filename. +

+

The following options modify the defaults for the extraction as + follows.

+ + {cwd,Cwd} + +

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

+ + {files,FileList} + +

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

+ + compressed + +

Given the compressed option, the extract/2 + function will uncompress the file while extracting + If the tar file is not actually compressed, the compressed + will effectively be ignored.

+ + cooked + +

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

+ + memory + +

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.

+ + keep_old_files + +

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

+ + verbose + +

Print an informational message as each file is being extracted.

+ + + + + + format_error(Reason) -> string() + Convert error term to a readable string + + Reason = term() + + +

The +format_error/1 converts + an error reason term to a human-readable error message string.

+ + + + open(Name, OpenModeList) -> RetValue + Open a tar file for writing. + + Name = filename() + OpenModeList = [OpenMode] + Mode = write|compressed|cooked + RetValue = {ok,TarDescriptor}|{error,{Name,Reason}} + TarDescriptor = term() + Reason = term() + + +

The +open/2 function creates a tar file for writing. + (Any existing file with the same name will be truncated.)

+

By convention, the name of a tar file should end in ".tar". + To abide to the convention, you'll need to add ".tar" yourself + to the name.

+

Except for the write atom the following atoms + may be added to OpenModeList:

+ + compressed + +

The entire tar file will be compressed, as if it has + been run through the gzip program. To abide to the + convention that a compressed tar file should end in ".tar.gz" or + ".tgz", you'll need to add the appropriate extension yourself.

+ + cooked + +

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

+ + +

Use the add/3,4 functions + to add one file at the time into an opened tar file. When you are + finished adding files, use the close + function to close the tar file.

+ +

The TarDescriptor term is not a file descriptor. + You should not rely on the specific contents of the TarDescriptor + term, as it may change in future versions as more features are added + to the erl_tar module.

+

+ + + + + table(Name) -> RetValue + Retrieve the name of all files in a tar file + + Name = filename() + RetValue = {ok,[string()]}|{error,{Name,Reason}} + Reason = term() + + +

The +table/1 function retrieves + the names of all files in the tar file Name.

+ + + + table(Name, Options) + Retrieve name and information of all files in a tar file + + Name = filename() + + +

The +table/2 function retrieves + the names of all files in the tar file Name.

+ + + + t(Name) + Print the name of each file in a tar file + + Name = filename() + + +

The +t/1 function prints the names + of all files in the tar file Name to the Erlang shell. + (Similar to "tar t".)

+ + + + tt(Name) + Print name and information for each file in a tar file + + Name = filename() + + +

The +tt/1 function prints names and + information about all files in the tar file Name to + the Erlang shell. (Similar to "tar tv".)

+ + + + + -- cgit v1.2.3