.TH TAR 1
.SH NAME
tar \- archiver
.SH SYNOPSIS
.B tar
.I key
[
.I file ...
]
.SH DESCRIPTION
.PP
.I Tar
saves and restores file trees.
It is most often used to transport a tree of files from one
system to another.
The
.I key
is a string that contains
at most one function letter plus optional modifiers.
Other arguments to the command are names of
files or directories to be dumped or restored.
A directory name implies all the contained
files and subdirectories (recursively).
.PP
The function is one of the following letters:
.TP
.B  c
Create a new archive with the given files as contents.
.TP
.B  x
Extract the named files from the archive.
If a file is a directory, the directory is extracted recursively.
Modes are restored if possible.
If no file argument is given, extract the entire archive.
If the archive contains multiple entries for a file,
the latest one wins.
.TP
.B  t
List all occurrences of each 
.I file
in the archive, or of all files if there are no
.I file
arguments.
.TP
.B  r
The named files
are appended to the archive.
.PP
The modifiers are:
.TP
.B  v
(verbose)
Print the name of each file treated
preceded by the function letter.
With 
.BR t ,
give more details about the
archive entries.
.TP
.B f
Use the next argument as the name of the archive instead of
the default standard input (for keys
.B x
and
.BR t )
or standard output (for keys
.B c
and
.BR r ).
.TP
.B u
Use the next (numeric) argument as the user id for files in
the output archive.  This is only useful when moving files to
a non-Plan 9 system.
.TP
.B g
Use the next (numeric) argument as the group id for files in
the output archive.
.TP
.B p
Create archive in POSIX ustar format,
which raises the maximum pathname length from 100 to 256 bytes.
Ustar archives are recognised automatically by
.I tar
when reading archives.
.TP
.B R
When extracting, ignore leading slash on file names,
i.e., extract all files relative to the current directory.
.TP
.B T
Modifies the behavior of
.B x
to set the mode and modified time
of each file to that specified in the archive.
.SH EXAMPLES
.I Tar
can be used to copy hierarchies thus:
.IP
.EX
@{cd fromdir && tar cp .} | @{cd todir && tar xT}
.EE
.SH SOURCE
.B /usr/local/plan9/src/cmd/tar.c
.SH SEE ALSO
.IR ar (1),
.IR bundle (1),
.IR tapefs (1)
.SH BUGS
There is no way to ask for any but the last
occurrence of a file.
.br
File path names are limited to
100 characters
(256 when using ustar format).
.br
The tar format allows specification of links and symbolic links,
concepts foreign to Plan 9: they are ignored.