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

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.

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

### EXPORTS

`add(TarDescriptor, Filename, Options) -> RetValue`

Types:

`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, Filename, NameInArchive, Options) -> RetValue`

Types:

`TarDescriptor = term()`
`Filename = filename()`
`NameInArchive = filename()`
`Options = [Option]`
`Option = dereference|verbose`
`RetValue = ok|{error,{Filename,Reason}}`
`Reason = term()`

The `add/4` function adds a file to a tar file that has been opened for writing by open/1. It accepts the same options as add/3.

`NameInArchive` is the name under which the file will be stored in the tar file. That is the name that the file will get when it will be extracted from the tar file.

`close(TarDescriptor)`

Types:

`TarDescriptor = term()`

The `close/1` function closes a tar file opened by open/1.

`create(Name, FileList) ->RetValue`

Types:

`Name = filename()`
`FileList = [filename()]`
`RetValue = ok|{error,{Name,Reason}} <V>Reason = term()`

The `create/2` function creates a tar file and archives the files whose names are given in `FileList` into it.

`create(Name, FileList, OptionList)`

Types:

`Name = filename()`
`FileList = [filename()]`
`OptionList = [Option]`
`Option = compressed|cooked|dereference|verbose`
`RetValue = ok|{error,{Name,Reason}} <V>Reason = term()`

The `create/3` function creates a tar file and archives the files whose names are given in `FileList` into it.

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`

Types:

`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)`

Types:

`Name = filename() | {binary,Binary} | {file,Fd}`
`Binary = binary()`
`Fd = file_descriptor()`
`OptionList = [Option]`
`Option = {cwd,Cwd}|{files,FileList}|keep_old_files|verbose`
`Cwd = [dirname()]`
`FileList = [filename()]`
`RetValue = ok|{error,{Name,Reason}}`
`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.
`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()`

Types:

`Reason = term()`

The `format_error/1` converts an error reason term to a human-readable error message string.

`open(Name, OpenModeList) -> RetValue`

Types:

`Name = filename()`
`OpenModeList = [OpenMode]`
`Mode = read|write|compressed|cooked`
`RetValue = {ok,TarDescriptor}|{error,{Name,Reason}} <V>TarDescriptor = term()`
`Reason = term()`

The `open/2` function opens a tar file.

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.

Note that there is currently no function for reading from an opened tar file, meaning that opening a tar file for reading is not very useful.

Except for `read` and `write` (which are mutually exclusive), 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.

| 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`

Types:

`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)`

Types:

`Name = filename()`

The `table/2` function retrieves the names of all files in the tar file `Name`.

`t(Name)`

Types:

`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)`

Types:

`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`".)

### AUTHORS

Bjorn Gustavsson - support@erlang.ericsson.se

stdlib 1.12
Copyright © 1991-2003 Ericsson Utvecklings AB