ref: 5622b0bbd878dbc34045cc6fd37cffa64461eabe
dir: /sys/man/1/tar/
.TH TAR 1
.SH NAME
tar, dircp \- archiver
.SH SYNOPSIS
.B tar
.I key
[
.I file ...
]
.PP
.B dircp
.I fromdir
.I todir
.SH DESCRIPTION
.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 r
The named files
are appended to the archive.
.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 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.
.PP
The modifiers are:
.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 g
Use the next (numeric) argument as the group id for files in
the output archive.
.TP
.B i
Ignore errors encountered when reading.
Errors writing either produce a corrupt archive
or indicate deeper file system problems.
.TP
.B k
(keep)
Modifies the behavior of
.B x
not to extract files which already exist.
.TP
.B m
Do not set the modification time on extracted files.
This is the default behavior; the flag exists only for compatibility with other tars.
.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.
This is the default behavior; the flag exists only for backwards compatibility
with older versions of tar.
.TP
.B P
Do not generate the POSIX ustar format.
.TP
.B R
When extracting, respect leading slash on file names.
By default, files are always extracted relative to the current directory.
.TP
.B s
When extracting, attempt to resynchronise after not finding a tape header
block where expected.
.TP
.B T
Modifies the behavior of
.B x
to set the modified time,
mode and, for POSIX archives and filesystem permitting,
the user and group
of each file to that specified in the archive.
.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 v
(verbose)
Print the name of each file as it is processed.
With
.BR t ,
give more details about the
archive entries.
.TP
.B z
Operate on compressed
.I tar
archives.
The type of compression is inferred from the file name extension:
.IR gzip (1)
for
.B .tar.gz
and
.BR .tgz ;
.I bzip2
(see
.IR gzip (1))
for
.BR .tar.bz ,
.BR .tbz ,
.BR .tar.bz2 ,
and
.BR .tbz2 ;
.I compress
for
.B .tar.Z
and
.BR .tz .
If no extension matches,
.I gzip
is used.
The
.B z
flag is unnecessary (but allowed) when using the
.B t
and
.B x
verbs on archives with recognized extensions.
.br
.ne 6
.SH EXAMPLES
.I Tar
can be used to copy hierarchies thus:
.IP
.EX
@{cd fromdir && tar c .} | @{cd todir && tar xT}
.EE
.PP
.I Dircp
does this.
.SH SOURCE
.B /sys/src/cmd/tar.c
.br
.B /rc/bin/dircp
.SH SEE ALSO
.IR ar (1),
.IR bundle (1),
.IR tapefs (4),
.IR mkfs (8)
.SH BUGS
There is no way to ask for any but the last
occurrence of a file.
.PP
File path names are limited to
100 characters
(256 when using ustar format).
.PP
The
.I tar
format allows specification of links and symbolic links,
concepts foreign to Plan 9: they are ignored.
.PP
The
.B r
key (append)
cannot be used on compressed archives.
.PP
The
.B T
key (write metadata) won't work for non-empty directories.
.PP
.IR Tar ,
thus
.IR dircp ,
doesn't record Plan-9-specific metadata
such as append-only and exclusive-open permission bits, so they aren't copied.