erl_tar

MODULE

erl_tar

MODULE SUMMARY

Unix 'tar' utility for reading and writing tar archives

DESCRIPTION

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.

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.

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.

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.

Warning

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.