-spec add(TarDescriptor, Name, Options) -> ok | {error, term()}
             when
                 TarDescriptor :: tar_descriptor(),
                 Name :: name_in_archive() | {name_in_archive(), file:filename_all()},
                 Options :: [add_opt()].

Equivalent to add/4.

If Name is name_in_archive/0, then add(TarDescriptor, Name, Name, Options) is called.

If Name is a two tuple then add(TarDescriptor, NameInArchive, Name, Options) is called.

-spec add(TarDescriptor, Filename, NameInArchive, Options) -> ok | {error, term()}
             when
                 TarDescriptor :: tar_descriptor(),
                 Filename :: file:filename_all(),
                 NameInArchive :: name_in_archive(),
                 Options :: [add_opt()].

Adds a file to a tar file that has been opened for writing by open/1.

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

Options:

• dereference - 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 dereference.

• verbose - Prints an informational message about the added file.

• {chunks,ChunkSize} - 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 ssh_sftp:open_tar/3.

• {atime,non_neg_integer()} - Sets the last time, as POSIX time, when the file was read. See also file:read_file_info/1.

• {mtime,non_neg_integer()} - Sets the last time, as POSIX time, when the file was written. See also file:read_file_info/1.

• {ctime,non_neg_integer()} - Sets the time, as POSIX time, when the file was created. See also file:read_file_info/1.

• {uid,non_neg_integer()} - Sets the file owner. file:read_file_info/1.

• {gid,non_neg_integer()} - Sets the group that the file owner belongs to. file:read_file_info/1.

-spec close(TarDescriptor :: tar_descriptor()) -> ok | {error, term()}.

Closes a tar file opened by open/2.

-spec create(file:filename_all(), filelist()) -> ok | {error, {string(), term()}}.

Creates a tar file and archives the files whose names are specified in FileList into it. The files can either be read from disk or be specified as binaries.

-spec create(file:filename_all(), filelist(), [create_opt()]) ->
                ok | {error, term()} | {error, {string(), term()}}.

Creates a tar file and archives the files whose names are specified in FileList into it. The files can either be read from disk or be specified as binaries.

The options in OptionList modify the defaults as follows:

• compressed - The entire tar file is compressed, as if it has been run through the gzip program. To abide to the convention that a compressed tar file is to end in ".tar.gz" or ".tgz", add the appropriate extension.

• cooked - By default, function open/2 opens 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 overrides the default and opens the tar file without option raw.

• dereference - 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 dereference.

• verbose - Prints an informational message about each added file.

-spec extract(Open :: open_type()) -> ok | {error, term()}.

Extracts all files from a tar archive.

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

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

Otherwise, Name is to be a filename.

Note

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.

Warning

The compressed and cooked flags are invalid when passing a file descriptor with {file,Fd}. The file is assumed to have been opened with the appropriate flags.

-spec extract(Open :: open_type(), [extract_opt()]) ->
                 {ok, [{string(), binary()}]} | {error, term()} | ok.

Extracts files from a tar archive.

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

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

Otherwise, Name is to be a filename.

The following options modify the defaults for the extraction as follows:

• {cwd,Cwd} - Files with relative filenames are by default extracted to the current working directory. With this option, files are instead extracted into directory Cwd.

• {files,FileList} - By default, all files are extracted from the tar file. With this option, only those files are extracted whose names are included in FileList.

• compressed - With this option, the file is uncompressed while extracting. If the tar file is not compressed, this option is ignored.

• cooked - By default, function open/2 function opens 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 overrides the default and opens the tar file without option raw.

• memory - Instead of extracting to a directory, this option gives 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 files in the tar file are overwritten. With this option, existing files are not overwriten.

• verbose - Prints an informational message for each extracted file.

Warning

The compressed and cooked flags are invalid when passing a file descriptor with {file,Fd}. The file is assumed to have been opened with the appropriate flags.

-spec format_error(term()) -> string().

Converts an error reason term to a human-readable error message string.

-spec init(UserData :: user_data(), write | read, file_op()) -> {ok, tar_descriptor()} | {error, badarg}.

The Fun 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 add/3, add/4, and close/1).

The Fun is called when the tar function wants to do a low-level operation, like writing a block to a file. The Fun is called as Fun(Op, {UserData,Parameters...}), where Op is the operation name, UserData is the term passed as the first argument to init/1 and Parameters... are the data added by the tar function to be passed down to the storage handling function.

Parameter UserData is typically the result of opening a low-level structure like a file descriptor or an SFTP channel id. The different Fun clauses operate on that very term.

The following are the fun clauses parameter lists:

• (write, {UserData,DataToWrite}) - Writes term DataToWrite using UserData.

• (close, UserData) - Closes the access.

• (read2, {UserData,Size}) - Reads using UserData but only Size bytes. Notice that there is only an arity-2 read function, not an arity-1 function.

• (position,{UserData,Position}) - Sets the position of UserData as defined for files in file:position/2

Example:

The following is a complete Fun parameter for reading and writing on files using the file module:

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

Here Fd was specified to function init/3 as:

{ok,Fd} = file:open(Name, ...).
{ok,TarDesc} = erl_tar:init(Fd, [write], ExampleFun),

TarDesc is then used:

erl_tar:add(TarDesc, SomeValueIwantToAdd, FileNameInTarFile),
...,
erl_tar:close(TarDesc)

When the erl_tar core wants to, for example, write a piece of Data, it would call ExampleFun(write, {UserData,Data}).

Note

This example with the file module operations is not necessary to use directly, as that is what function open/2 in principle does.

Warning

The TarDescriptor 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.

-spec open(Open :: open_type(), [write | compressed | cooked]) ->
              {ok, tar_descriptor()} | {error, term()}.

Creates a tar file for writing (any existing file with the same name is truncated).

By convention, the name of a tar file is to end in ".tar". To abide to the convention, add ".tar" to the name.

Except for the write atom, the following atoms can be added to OpenModeList:

• compressed - The entire tar file is compressed, as if it has been run through the gzip program. To abide to the convention that a compressed tar file is to end in ".tar.gz" or ".tgz", add the appropriate extension.

• cooked - By default, the tar file is opened in raw mode, which is faster but does not allow a remote (Erlang) file server to be used. Adding cooked to the mode list overrides the default and opens the tar file without option raw.

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

Warning

The compressed and cooked flags are invalid when passing a file descriptor with {file,Fd}. The file must already be opened with the appropriate flags.

Warning

The TarDescriptor 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.

-spec t(file:filename()) -> ok | {error, term()}.

Prints the names of all files in the tar file Name to the Erlang shell (similar to "tar t").

-spec table(Open :: open_type()) -> {ok, [name_in_archive()]} | {error, term()}.

Equivalent to table(Open, []).

-spec table(Open :: open_type(), [compressed | verbose | cooked]) ->
               {ok, [name_in_archive() | tar_entry()]} | {error, term()}.

Retrieves the names of all files in the tar file Name.

-spec tt(open_type()) -> ok | {error, term()}.

Prints names and information about all files in the tar file Name to the Erlang shell (similar to "tar tv").