| erl_tar(3erl) | Erlang Module Definition | erl_tar(3erl) |
erl_tar - Unix 'tar' utility for reading and writing tar archives.
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, erl_tar supports tar archives produced by most all modern tar utilities, and produces tarballs which should be similarly portable.
By convention, the name of a tar file is to end in ".tar". To abide to the convention, add ".tar" to the name.
Tar files can be created in one operation using function create/2 or create/3.
Alternatively, for more control, use functions open/2, add/3,4, and close/1.
To extract all files from a tar file, use function extract/1. To extract only some files or to be able to specify some more options, use function extract/2.
To return a list of the files in a tar file, use function table/1 or table/2. To print a list of files to the Erlang shell, use function t/1 or tt/1.
To convert an error term returned from one of the functions above to a readable message, use function format_error/1.
If file:native_name_encoding/0 returns utf8, 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.
If file:native_name_encoding/0 returns latin1, no translation of path names is done.
Unicode metadata stored in PAX headers is preserved
The ftp module normally accesses the tar file on disk using the file 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 init/3.
An example of this is the SFTP support in ssh_sftp:open_tar/3. This function opens a tar file on a remote machine using an SFTP channel.
name_in_archive() = string()
open_type() =
file:filename_all() |
{binary, binary()} |
{file, file:io_device()}
tar_descriptor()
add(TarDescriptor, AddType, Options) -> ok | {error, term()}
add(TarDescriptor, Filename, NameInArchive, Options) ->
ok | {error, term()}
Types:
add_type() =
name_in_archive() | {name_in_archive(), file:filename_all()}
add_opt() =
dereference | verbose |
{chunks, integer() >= 1} |
{atime, integer() >= 0} |
{mtime, integer() >= 0} |
{ctime, integer() >= 0} |
{uid, integer() >= 0} |
{gid, integer() >= 0}
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:
close(TarDescriptor :: tar_descriptor()) -> ok | {error, term()}
Closes a tar file opened by open/2.
create(Name :: file:filename_all(), FileList :: filelist()) ->
ok | {error, {string(), term()}}
Types:
filelist() =
[file:filename() | {name_in_archive(), file:filename_all()}]
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.
create(Name :: file:filename_all(),
FileList :: filelist(),
Options :: [create_opt()]) ->
ok | {error, term()} | {error, {string(), term()}}
Types:
filelist() =
[file:filename() | {name_in_archive(), file:filename_all()}]
create_opt() = compressed | cooked | dereference | verbose
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:
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.
extract(Open :: open_type(), Opts :: [extract_opt()]) ->
{ok, [{string(), binary()}]} | {error, term()} | ok
Types:
extract_opt() =
{cwd, string()} |
{files, [name_in_archive()]} |
compressed | cooked | memory | keep_old_files | verbose
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:
format_error(Atom :: term()) -> string()
Converts an error reason term to a human-readable error message string.
init(UserData :: user_data(),
AccessMode :: write | read,
Fun :: file_op()) ->
{ok, tar_descriptor()} | {error, badarg}
Types:
user_data() = term()
file_op() =
fun((write | close | read2 | position,
{user_data(), iodata()} |
user_data() |
{user_data(), integer() >= 0} |
{user_data(), integer() >= 0}) ->
ok | eof |
{ok, string() | binary()} |
{ok, integer() >= 0} |
{error, term()})
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:
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}).
open(Open :: open_type(), Mode :: [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:
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.
table(Open :: open_type()) ->
{ok, [name_in_archive()]} | {error, term()}
table(Open :: open_type(),
Opts :: [compressed | verbose | cooked]) ->
{ok, [name_in_archive() | tar_entry()]} | {error, term()}
Types:
tar_entry() =
{Name :: name_in_archive(),
Type :: typeflag(),
Size :: integer() >= 0,
MTime :: tar_time(),
Mode :: mode(),
Uid :: uid(),
Gid :: gid()}
tar_time() = integer() >= 0
typeflag() =
regular | link | symlink | char | block | directory | fifo |
reserved | unknown
mode() = integer() >= 0
uid() = integer() >= 0
gid() = integer() >= 0
Retrieves the names of all files in the tar file Name.
t(Name :: file:filename()) -> ok | {error, term()}
Prints the names of all files in the tar file Name to the Erlang shell (similar to "tar t").
tt(Name :: 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").
| stdlib 3.14 | Ericsson AB |