.TH erl_tar 3erl "stdlib 4.3.1.3" "Ericsson AB" "Erlang Module Definition"
.SH NAME
erl_tar \- Unix 'tar' utility for reading and writing tar archives.
  
.SH DESCRIPTION
.LP
This module archives and extract files to and from a tar file\&. This module supports reading most common tar formats, namely v7, STAR, USTAR, and PAX, as well as some of GNU tar\&'s extensions to the USTAR format (sparse files most notably)\&. It produces tar archives in USTAR format, unless the files being archived require PAX format due to restrictions in USTAR (such as unicode metadata, filename length, and more)\&. As such, \fIerl_tar\fR\& supports tar archives produced by most all modern tar utilities, and produces tarballs which should be similarly portable\&.
.LP
By convention, the name of a tar file is to end in "\fI\&.tar\fR\&"\&. To abide to the convention, add "\fI\&.tar\fR\&" to the name\&.
.LP
Tar files can be created in one operation using function \fIcreate/2\fR\& or \fIcreate/3\fR\&\&.
.LP
Alternatively, for more control, use functions \fIopen/2\fR\&, \fIadd/3,4\fR\&, and \fIclose/1\fR\&\&.
.LP
To extract all files from a tar file, use function \fIextract/1\fR\&\&. To extract only some files or to be able to specify some more options, use function \fIextract/2\fR\&\&.
.LP
To return a list of the files in a tar file, use function \fItable/1\fR\& or \fItable/2\fR\&\&. To print a list of files to the Erlang shell, use function \fIt/1\fR\& or \fItt/1\fR\&\&.
.LP
To convert an error term returned from one of the functions above to a readable message, use function \fIformat_error/1\fR\&\&.
.SH "UNICODE SUPPORT"

.LP
If \fIfile:native_name_encoding/0\fR\& returns \fIutf8\fR\&, 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\&.
.LP
If \fIfile:native_name_encoding/0\fR\& returns \fIlatin1\fR\&, no translation of path names is done\&.
.LP
Unicode metadata stored in PAX headers is preserved
.SH "OTHER STORAGE MEDIA"

.LP
The \fIftp\fR\& module normally accesses the tar file on disk using the \fIfile\fR\& 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 \fIinit/3\fR\&\&.
.LP
An example of this is the SFTP support in \fIssh_sftp:open_tar/3\fR\&\&. This function opens a tar file on a remote machine using an SFTP channel\&.
.SH "LIMITATIONS"

.RS 2
.TP 2
*
If you must remain compatible with the USTAR tar format, you must ensure file paths being stored are less than 255 bytes in total, with a maximum filename component length of 100 bytes\&. USTAR uses a header field (prefix) in addition to the name field, and splits file paths longer than 100 bytes into two parts\&. This split is done on a directory boundary, and is done in such a way to make the best use of the space available in those two fields, but in practice this will often mean that you have less than 255 bytes for a path\&. \fIerl_tar\fR\& will automatically upgrade the format to PAX to handle longer filenames, so this is only an issue if you need to extract the archive with an older implementation of \fIerl_tar\fR\& or \fItar\fR\& which does not support PAX\&. In this case, the PAX headers will be extracted as regular files, and you will need to apply them manually\&.
.LP
.TP 2
*
Like the above, if you must remain USTAR compatible, you must also ensure than paths for symbolic/hard links are no more than 100 bytes, otherwise PAX headers will be used\&.
.LP
.RE

.SH DATA TYPES
.nf

\fBname_in_archive()\fR\& = string()
.br
.fi
.nf

\fBopen_type()\fR\& = 
.br
    file:filename_all() |
.br
    {binary, binary()} |
.br
    {file, file:io_device()}
.br
.fi
.nf

\fBtar_descriptor()\fR\&
.br
.fi
.SH EXPORTS
.LP
.nf

.B
add(TarDescriptor, AddType, Options) -> ok | {error, term()}
.br
.fi
.br
.nf

.B
add(TarDescriptor, Filename, NameInArchive, Options) ->
.B
       ok | {error, term()}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
TarDescriptor = tar_descriptor()
.br
Filename = file:filename_all()
.br
NameInArchive = name_in_archive()
.br
Options = [add_opt()]
.br
.nf
\fBadd_type()\fR\& = 
.br
    name_in_archive() | {name_in_archive(), file:filename_all()}
.fi
.br
.nf
\fBadd_opt()\fR\& = 
.br
    dereference | verbose |
.br
    {chunks, integer() >= 1} |
.br
    {atime, integer() >= 0} |
.br
    {mtime, integer() >= 0} |
.br
    {ctime, integer() >= 0} |
.br
    {uid, integer() >= 0} |
.br
    {gid, integer() >= 0}
.fi
.br
.RE
.RE
.RS
.LP
Adds a file to a tar file that has been opened for writing by \fIopen/1\fR\&\&.
.LP
\fINameInArchive\fR\& 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\&.
.LP
Options:
.RS 2
.TP 2
.B
\fIdereference\fR\&:
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 \fIdereference\fR\&\&.
.TP 2
.B
\fIverbose\fR\&:
Prints an informational message about the added file\&.
.TP 2
.B
\fI{chunks,ChunkSize}\fR\&:
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 \fIssh_sftp:open_tar/3\fR\&\&.
.TP 2
.B
\fI{atime,non_neg_integer()}\fR\&:
Sets the last time, as  POSIX time, when the file was read\&. See also \fIfile:read_file_info/1\fR\&\&.
.TP 2
.B
\fI{mtime,non_neg_integer()}\fR\&:
Sets the last time, as  POSIX time, when the file was written\&. See also \fIfile:read_file_info/1\fR\&\&.
.TP 2
.B
\fI{ctime,non_neg_integer()}\fR\&:
Sets the time, as  POSIX time, when the file was created\&. See also \fIfile:read_file_info/1\fR\&\&.
.TP 2
.B
\fI{uid,non_neg_integer()}\fR\&:
Sets the file owner\&. \fIfile:read_file_info/1\fR\&\&.
.TP 2
.B
\fI{gid,non_neg_integer()}\fR\&:
Sets the group that the file owner belongs to\&. \fIfile:read_file_info/1\fR\&\&.
.RE
.RE

.LP
.nf

.B
close(TarDescriptor :: tar_descriptor()) -> ok | {error, term()}
.br
.fi
.br
.RS
.LP
Closes a tar file opened by \fIopen/2\fR\&\&.
.RE

.LP
.nf

.B
create(Name :: file:filename_all(), FileList :: filelist()) ->
.B
          ok | {error, {string(), term()}}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
.nf
\fBfilelist()\fR\& = 
.br
    [file:filename() | {name_in_archive(), file:filename_all()}]
.fi
.br
.RE
.RE
.RS
.LP
Creates a tar file and archives the files whose names are specified in \fIFileList\fR\& into it\&. The files can either be read from disk or be specified as binaries\&.
.RE

.LP
.nf

.B
create(Name :: file:filename_all(),
.B
       FileList :: filelist(),
.B
       Options :: [create_opt()]) ->
.B
          ok | {error, term()} | {error, {string(), term()}}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
.nf
\fBfilelist()\fR\& = 
.br
    [file:filename() | {name_in_archive(), file:filename_all()}]
.fi
.br
.nf
\fBcreate_opt()\fR\& = compressed | cooked | dereference | verbose
.fi
.br
.RE
.RE
.RS
.LP
Creates a tar file and archives the files whose names are specified in \fIFileList\fR\& into it\&. The files can either be read from disk or be specified as binaries\&.
.LP
The options in \fIOptionList\fR\& modify the defaults as follows:
.RS 2
.TP 2
.B
\fIcompressed\fR\&:
The entire tar file is compressed, as if it has been run through the \fIgzip\fR\& program\&. To abide to the convention that a compressed tar file is to end in "\fI\&.tar\&.gz\fR\&" or "\fI\&.tgz\fR\&", add the appropriate extension\&.
.TP 2
.B
\fIcooked\fR\&:
By default, function \fIopen/2\fR\& opens the tar file in \fIraw\fR\& mode, which is faster but does not allow a remote (Erlang) file server to be used\&. Adding \fIcooked\fR\& to the mode list overrides the default and opens the tar file without option \fIraw\fR\&\&.
.TP 2
.B
\fIdereference\fR\&:
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 \fIdereference\fR\&\&.
.TP 2
.B
\fIverbose\fR\&:
Prints an informational message about each added file\&.
.RE
.RE

.LP
.nf

.B
extract(Open :: open_type()) -> ok | {error, term()}
.br
.fi
.br
.RS
.LP
Extracts all files from a tar archive\&.
.LP
If argument \fIName\fR\& is specified as \fI{binary,Binary}\fR\&, the contents of the binary is assumed to be a tar archive\&.
.LP
If argument \fIName\fR\& is specified as \fI{file,Fd}\fR\&, \fIFd\fR\& is assumed to be a file descriptor returned from function \fIfile:open/2\fR\&\&.
.LP
Otherwise, \fIName\fR\& is to be a filename\&.
.LP

.RS -4
.B
Note:
.RE
Leading slashes in tar member names will be removed before writing the file\&. That is, absolute paths will be turned into relative paths\&. There will be an info message written to the error logger when paths are changed in this way\&.

.LP

.RS -4
.B
Warning:
.RE
The \fIcompressed\fR\& and \fIcooked\fR\& flags are invalid when passing a file descriptor with \fI{file,Fd}\fR\&\&. The file is assumed to have been opened with the appropriate flags\&.

.RE

.LP
.nf

.B
extract(Open :: open_type(), Opts :: [extract_opt()]) ->
.B
           {ok, [{string(), binary()}]} | {error, term()} | ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
.nf
\fBextract_opt()\fR\& = 
.br
    {cwd, string()} |
.br
    {files, [name_in_archive()]} |
.br
    compressed | cooked | memory | keep_old_files | verbose
.fi
.br
.RE
.RE
.RS
.LP
Extracts files from a tar archive\&.
.LP
If argument \fIName\fR\& is specified as \fI{binary,Binary}\fR\&, the contents of the binary is assumed to be a tar archive\&.
.LP
If argument \fIName\fR\& is specified as \fI{file,Fd}\fR\&, \fIFd\fR\& is assumed to be a file descriptor returned from function \fIfile:open/2\fR\&\&.
.LP
Otherwise, \fIName\fR\& is to be a filename\&.
.LP
The following options modify the defaults for the extraction as follows:
.RS 2
.TP 2
.B
\fI{cwd,Cwd}\fR\&:
Files with relative filenames are by default extracted to the current working directory\&. With this option, files are instead extracted into directory \fICwd\fR\&\&.
.TP 2
.B
\fI{files,FileList}\fR\&:
By default, all files are extracted from the tar file\&. With this option, only those files are extracted whose names are included in \fIFileList\fR\&\&.
.TP 2
.B
\fIcompressed\fR\&:
With this option, the file is uncompressed while extracting\&. If the tar file is not compressed, this option is ignored\&.
.TP 2
.B
\fIcooked\fR\&:
By default, function \fIopen/2\fR\& function opens the tar file in \fIraw\fR\& mode, which is faster but does not allow a remote (Erlang) file server to be used\&. Adding \fIcooked\fR\& to the mode list overrides the default and opens the tar file without option \fIraw\fR\&\&.
.TP 2
.B
\fImemory\fR\&:
Instead of extracting to a directory, this option gives the result as a list of tuples \fI{Filename, Binary}\fR\&, where \fIBinary\fR\& is a binary containing the extracted data of the file named \fIFilename\fR\& in the tar file\&.
.TP 2
.B
\fIkeep_old_files\fR\&:
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\&.
.TP 2
.B
\fIverbose\fR\&:
Prints an informational message for each extracted file\&.
.RE
.LP

.RS -4
.B
Warning:
.RE
The \fIcompressed\fR\& and \fIcooked\fR\& flags are invalid when passing a file descriptor with \fI{file,Fd}\fR\&\&. The file is assumed to have been opened with the appropriate flags\&.

.RE

.LP
.nf

.B
format_error(Atom :: term()) -> string()
.br
.fi
.br
.RS
.LP
Converts an error reason term to a human-readable error message string\&.
.RE

.LP
.nf

.B
init(UserData :: user_data(),
.B
     AccessMode :: write | read,
.B
     Fun :: file_op()) ->
.B
        {ok, tar_descriptor()} | {error, badarg}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
.nf
\fBuser_data()\fR\& = term()
.fi
.br
.nf
\fBfile_op()\fR\& = 
.br
    fun((write | close | read2 | position,
.br
         {user_data(), iodata()} |
.br
         user_data() |
.br
         {user_data(), integer() >= 0} |
.br
         {user_data(), integer() >= 0}) ->
.br
            ok | eof |
.br
            {ok, string() | binary()} |
.br
            {ok, integer() >= 0} |
.br
            {error, term()})
.fi
.br
.RE
.RE
.RS
.LP
The \fIFun\fR\& 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 \fIadd/3\fR\&, \fIadd/4\fR\&, and \fIclose/1\fR\&)\&.
.LP
The \fIFun\fR\& is called when the tar function wants to do a low-level operation, like writing a block to a file\&. The \fIFun\fR\& is called as \fIFun(Op, {UserData,Parameters\&.\&.\&.})\fR\&, where \fIOp\fR\& is the operation name, \fIUserData\fR\& is the term passed as the first argument to \fIinit/1\fR\& and \fIParameters\&.\&.\&.\fR\& are the data added by the tar function to be passed down to the storage handling function\&.
.LP
Parameter \fIUserData\fR\& is typically the result of opening a low-level structure like a file descriptor or an SFTP channel id\&. The different \fIFun\fR\& clauses operate on that very term\&.
.LP
The following are the fun clauses parameter lists:
.RS 2
.TP 2
.B
\fI(write, {UserData,DataToWrite})\fR\&:
Writes term \fIDataToWrite\fR\& using \fIUserData\fR\&\&.
.TP 2
.B
\fI(close, UserData)\fR\&:
Closes the access\&.
.TP 2
.B
\fI(read2, {UserData,Size})\fR\&:
Reads using \fIUserData\fR\& but only \fISize\fR\& bytes\&. Notice that there is only an arity-2 read function, not an arity-1 function\&.
.TP 2
.B
\fI(position,{UserData,Position})\fR\&:
Sets the position of \fIUserData\fR\& as defined for files in \fIfile:position/2\fR\&
.RE
.LP
\fIExample:\fR\&
.LP
The following is a complete \fIFun\fR\& parameter for reading and writing on files using the \fIfile\fR\& module:
.LP
.nf

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
.fi
.LP
Here \fIFd\fR\& was specified to function \fIinit/3\fR\& as:
.LP
.nf

{ok,Fd} = file:open(Name, ...).
{ok,TarDesc} = erl_tar:init(Fd, [write], ExampleFun),
.fi
.LP
\fITarDesc\fR\& is then used:
.LP
.nf

erl_tar:add(TarDesc, SomeValueIwantToAdd, FileNameInTarFile),
\&...,
erl_tar:close(TarDesc)
.fi
.LP
When the \fIerl_tar\fR\& core wants to, for example, write a piece of \fIData\fR\&, it would call \fIExampleFun(write, {UserData,Data})\fR\&\&.
.LP

.RS -4
.B
Note:
.RE
This example with the \fIfile\fR\& module operations is not necessary to use directly, as that is what function \fIopen/2\fR\& in principle does\&.

.LP

.RS -4
.B
Warning:
.RE
The \fITarDescriptor\fR\& 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\&.

.RE

.LP
.nf

.B
open(Open :: open_type(), Mode :: [write | compressed | cooked]) ->
.B
        {ok, tar_descriptor()} | {error, term()}
.br
.fi
.br
.RS
.LP
Creates a tar file for writing (any existing file with the same name is truncated)\&.
.LP
By convention, the name of a tar file is to end in "\fI\&.tar\fR\&"\&. To abide to the convention, add "\fI\&.tar\fR\&" to the name\&.
.LP
Except for the \fIwrite\fR\& atom, the following atoms can be added to \fIOpenModeList\fR\&:
.RS 2
.TP 2
.B
\fIcompressed\fR\&:
The entire tar file is compressed, as if it has been run through the \fIgzip\fR\& program\&. To abide to the convention that a compressed tar file is to end in "\fI\&.tar\&.gz\fR\&" or "\fI\&.tgz\fR\&", add the appropriate extension\&.
.TP 2
.B
\fIcooked\fR\&:
By default, the tar file is opened in \fIraw\fR\& mode, which is faster but does not allow a remote (Erlang) file server to be used\&. Adding \fIcooked\fR\& to the mode list overrides the default and opens the tar file without option \fIraw\fR\&\&.
.RE
.LP
To add one file at the time into an opened tar file, use function \fIadd/3,4\fR\&\&. When you are finished adding files, use function \fIclose/1\fR\& to close the tar file\&.
.LP

.RS -4
.B
Warning:
.RE
The \fIcompressed\fR\& and \fIcooked\fR\& flags are invalid when passing a file descriptor with \fI{file,Fd}\fR\&\&. The file must already be opened with the appropriate flags\&.

.LP

.RS -4
.B
Warning:
.RE
The \fITarDescriptor\fR\& 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\&.

.RE

.LP
.nf

.B
table(Open :: open_type()) ->
.B
         {ok, [name_in_archive()]} | {error, term()}
.br
.fi
.br
.nf

.B
table(Open :: open_type(),
.B
      Opts :: [compressed | verbose | cooked]) ->
.B
         {ok, [name_in_archive() | tar_entry()]} | {error, term()}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
.nf
\fBtar_entry()\fR\& = 
.br
    {Name :: name_in_archive(),
.br
     Type :: typeflag(),
.br
     Size :: integer() >= 0,
.br
     MTime :: tar_time(),
.br
     Mode :: mode(),
.br
     Uid :: uid(),
.br
     Gid :: gid()}
.fi
.br
.nf
\fBtar_time()\fR\& = integer() >= 0
.fi
.br
.nf
\fBtypeflag()\fR\& = 
.br
    regular | link | symlink | char | block | directory | fifo |
.br
    reserved | unknown
.fi
.br
.nf
\fBmode()\fR\& = integer() >= 0
.fi
.br
.nf
\fBuid()\fR\& = integer() >= 0
.fi
.br
.nf
\fBgid()\fR\& = integer() >= 0
.fi
.br
.RE
.RE
.RS
.LP
Retrieves the names of all files in the tar file \fIName\fR\&\&.
.RE

.LP
.nf

.B
t(Name :: file:filename()) -> ok | {error, term()}
.br
.fi
.br
.RS
.LP
Prints the names of all files in the tar file \fIName\fR\& to the Erlang shell (similar to "\fItar t\fR\&")\&.
.RE

.LP
.nf

.B
tt(Name :: open_type()) -> ok | {error, term()}
.br
.fi
.br
.RS
.LP
Prints names and information about all files in the tar file \fIName\fR\& to the Erlang shell (similar to "\fItar tv\fR\&")\&.
.RE