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. erl_tar
supports the ustar
format
(IEEE Std 1003.1 and ISO/IEC 9945-1). All modern tar
programs (including GNU tar) can read this format. To ensure that
that GNU tar produces a tar file that erl_tar
can read,
give the --format=ustar
option to GNU tar.
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.
UNICODE SUPPORT
If file:native_name_encoding/0
returns utf8
, path names will be encoded in UTF-8 when
creating tar files and path names will be assumed to be encoded in
UTF-8 when extracting tar files.
If file:native_name_encoding/0
returns latin1
, no translation of path names will be
done.
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.
Functions
add(TarDescriptor, Filename, Options) -> RetValue
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
TarDescriptor = term()
FilenameOrBin = filename()|binary()
Filename = filename()
NameInArchive = filename()
Options = [Option]
Option = dereference|verbose
RetValue = ok|{error,{Filename,Reason}}
Reason = term()
close(TarDescriptor)
TarDescriptor = term()
The close/1
function
closes a tar file
opened by open/1.
create(Name, FileList) ->RetValue
Name = filename()
FileList = [Filename|{NameInArchive, binary()},{NameInArchive, Filename}]
Filename = filename()
NameInArchive = filename()
RetValue = ok|{error,{Name,Reason}}
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)
Name = filename()
FileList = [Filename|{NameInArchive, binary()},{NameInArchive, Filename}]
Filename = filename()
NameInArchive = filename()
OptionList = [Option]
Option = compressed|cooked|dereference|verbose
RetValue = ok|{error,{Name,Reason}}
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
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)
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()
Reason = term()
The format_error/1
function converts
an error reason term to a human-readable error message string.
open(Name, OpenModeList) -> RetValue
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.
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.
table(Name) -> RetValue
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)
Name = filename()
The table/2
function
retrieves the names of all files in the tar file Name
.
t(Name)
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)
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
".)