.TH TAR 1 "5 November 1987"
.\" @(#)tar.1 1.12 11/6/87 Public Domain - gnu
.SH NAME
tar \- tape (or other media) file archiver
.SH SYNOPSIS
\fBtar\fP \-[\fBBcdDhiklmopRstvxXzZ\fP]
[\fB\-b\fP \fIN\fP]
[\fB\-f\fP \fIF\fP]
[\fB\-T\fP \fIF\fP]
[\fIfilename\fP|\fIregexp\fP\| .\|.\|.]
.SH DESCRIPTION
\fBtar\fP provides a way to store many files into a single archive,
which can be kept in another Unix file, stored on an I/O device
such as tape, floppy, cartridge, or disk, sent over a network, or piped to
another program.
It is useful for making backup copies, or for packaging up a set of
files to move them to another system.
.LP
\fBtar\fP has existed since Version 7 Unix with very little change.
It has been proposed as the standard format for interchange of files
among systems that conform to the IEEE P1003 ``Portable Operating System''
standard.
.LP
This version of \fBtar\fP supports some of the extensions which
were proposed in the P1003 draft standards, including owner and group
names, and support for named pipes, fifos, contiguous files,
and block and character devices.
.LP
When reading an archive, this version of \fBtar\fP continues after
finding an error.  Previous versions required the `i' option to ignore
checksum errors.
.SH OPTIONS
\fBtar\fP options can be specified in either of two ways.  The usual
Unix conventions can be used: each option is preceded by `\-'; arguments
directly follow each option; multiple options can be combined behind one `\-'
as long as they take no arguments.  For compatability with the Unix
\fBtar\fP program, the options may also be specified as ``keyletters,''
wherein all the option letters occur in the first argument to \fBtar\fP,
with no `\-', and their arguments, if any, occur in the second, third, ...
arguments.  Examples:
.LP
Normal:  tar -f arcname -cv file1 file2
.LP
Old:  tar fcv arcname file1 file2
.LP
At least one of the \fB\-c\fP, \fB\-t\fP, \fB-d\fP, or \fB\-x\fP options
must be included.  The rest are optional.
.LP
Files to be operated upon are specified by a list of file names, which
follows the option specifications (or can be read from a file by the
\fB\-T\fP option).  Specifying a directory name causes that directory
and all the files it contains to be (recursively) processed.
.ig \" If I use a full path, then I want a full path! (kjb)
If a
full path name is specified when creating an archive, it will be written
to the archive without the initial "/", to allow the files to be later
read into a different place than where they were
dumped from, and a warning will be printed.  If
files are extracted from an archive which contains 
full path names, they will be extracted relative to the current directory
and a warning message printed.
..
.LP
When extracting or listing files, the ``file names'' are treated as
regular expressions, using mostly the same syntax as the shell.  The
shell actually matches each substring between ``/''s separately, while
\fBtar\fP matches the entire string at once, so some anomalies will
occur; e.g. ``*'' or ``?'' can match a ``/''.  To specify a regular
expression as an argument to \fBtar\fP, quote it so the shell will not
expand it.
.IP "\fB\-b\fP \fIN\fP"
Specify a blocking factor for the archive.  The block size will be
\fIN\fP x 512 bytes.  Larger blocks typically run faster and let you
fit more data on a tape.  The default blocking factor is set when
\fBtar\fP is compiled, and is typically 20.  There is no limit to the
maximum block size, as long as enough memory can be allocated for it,
and as long as the device containing the archive can read or write
that block size.
.IP \fB\-B\fP
When reading an archive, reblock it as we read it.
Normally, \fBtar\fP reads each
block with a single \fBread\fP(2) system call.  This does not work
when reading from a pipe or network socket under Berkeley Unix;
\fBread\fP(2) only gives as much data as has arrived at the moment.
With this option, it
will do multiple \fBread\fP(2)s to fill out to a record boundary,
rather than reporting an error.
This option is default when reading an archive from standard input,
or over a network.
.IP \fB\-c\fP
Create an archive from a list of files.
.IP \fB\-d\fP
Diff an archive against the files in the file system.  Reports
differences in file size, mode, uid, gid, and contents.  If a file
exists on the tape, but not in the file system, that is reported.
This option needs further work to be really useful.
.IP \fB\-D\fP
When creating an archive, only dump each directory itself; don't dump
all the files inside the directory.  In conjunction with \fBfind\fP(1),
this is useful in creating incremental dumps for archival backups,
similar to those produced by \fBdump\fP(8).
.IP "\fB\-f\fP \fIF\fP"
Specify the filename of the archive.  If the specified filename is ``\-'',
the archive is read from the standard input or written to the standard output.
If the \fB-f\fP option is not used, and the environment variable \fBTAPE\fP
exists, its value will be used; otherwise,
a default archive name (which was picked when tar was compiled) is used.
The default is normally set to the ``first'' tape drive or other transportable
I/O medium on the system.
.IP
If the filename contains a colon before a slash, it is interpreted
as a ``hostname:/file/name'' pair.  \fBtar\fP will invoke the commands
\fBrsh\fP and \fBdd\fP to access the specified file or device on the
system \fIhostname\fP.  If you need to do something unusual like rsh with
a different user name, use ``\fB\-f \-\fP'' and pipe it to rsh manually.
.IP \fB\-h\fP
When creating an archive, if a symbolic link is encountered, dump
the file or directory to which it points, rather than
dumping it as a symbolic link.
.IP \fB\-i\fP
When reading an archive, ignore blocks of zeros in the archive.  Normally
a block of zeros indicates the end of the archive,
but in a damaged archive, or one which was
created by appending several archives, this option allows \fBtar\fP to 
continue.  It is not on by default because there is garbage written after the
zeroed blocks by the Unix \fBtar\fP program.  Note that with this option
set, \fBtar\fP will read all the way to the end of the file, eliminating
problems with multi-file tapes.
.IP \fB\-k\fP
When extracting files from an archive, keep existing files, rather than
overwriting them with the version from the archive.
.IP \fB\-l\fP
When dumping the contents of a directory to an archive, stay within the
local file system of that directory.  This option
only affects the files dumped because
they are in a dumped directory; files named on the command line are
always dumped, and they can be from various file systems.
This is useful for making ``full dump'' archival backups of a file system,
as with the \fBdump\fP(8) command.  Files which are skipped due to this
option are mentioned on the standard error.
.IP \fB\-m\fP
When extracting files from an archive, set each file's modified timestamp
to the current time, rather than extracting each file's modified
timestamp from the archive.
.IP \fB\-n\fP
Use the numeric user and group id instead of the user and group names when
extracting or listing.
.IP \fB\-o\fP
When creating an archive, write an old format archive, which does not
include information about directories, pipes, fifos, 
contiguous files, or device files, and 
specifies file ownership by uid's and gid's rather than by
user names and group names.  In most cases, a ``new'' format archive
can be read by an ``old'' tar program without serious trouble, so this
option should seldom be needed.
.IP \fB\-p\fP
When extracting files from an archive, restore them to the same permissions
that they had in the archive.  If \fB\-p\fP is not specified, the current
umask limits the permissions of the extracted files.  See \fBumask\fP(2).
.IP \fB\-R\fP
With each message that \fBtar\fP produces, print the record number
within the archive where the message occurred.  This option is especially
useful when reading damaged archives, since it helps to pinpoint the damaged
section.
.IP \fB\-s\fP
When specifying a list of filenames to be listed
or extracted from an archive,
the \fB\-s\fP flag specifies that the list
is sorted into the same order as the tape.  This allows a large list
to be used, even on small machines, because
the entire list need not be read into memory at once.  Such a sorted
list can easily be created by running ``tar \-t'' on the archive and
editing its output.
.IP \fB\-t\fP
List a table of contents of an existing archive.  If file names are
specified, just list files matching the specified names.  The listing
appears on the standard output.
.IP "\fB\-T\fP \fIF\fP"
Rather than specifying file names or regular expressions as arguments to
the \fBtar\fP command, this option specifies that they should
be read from the file \fIF\fP, one per line.
If the file name specified is ``\-'',
the list is read from the standard input.
This option, in conjunction with the \fB\-s\fP option,
allows an arbitrarily large list of files to be processed, 
and allows the list to be piped to \fBtar\fP.
.IP \fB\-v\fP
Be verbose about the files that are being processed or listed.  Normally,
archive creation, file extraction, and differencing are silent,
and archive listing just
gives file names.  The \fB\-v\fP option causes an ``ls \-l''\-like listing
to be produced.  The output from -v appears on the standard output except
when creating an archive (since the new archive might be on standard output),
where it goes to the standard error output.
.IP \fB\-x\fP
Extract files from an existing archive.  If file names are
specified, just extract files matching the specified names, otherwise extract
all the files in the archive.
.IP \fB\-X\fP
Strip leading slashes from an absolute path, allowing these paths to be
extracted in a different place.
.IP "\fB\-z\fP or \fB\-Z\fP"
The archive should be compressed as it is written, or decompressed as it
is read, using the \fBcompress\fP(1) program.  This option works on I/O
devices and over the network, as well as on disk files; data to or from
such devices is reblocked using a ``dd'' command
to enforce the specified (or default) block size.  The default compression
parameters are used; if you need to override them, avoid the ``z'' option
and compress it yourself.
.SH "SEE ALSO"
\fBshar\fP(1), \fBtar\fP(5), \fBar\fP(1), \fBcpio\fP(1), \fBdump\fP(8),
\fBrestore\fP(8), \fBrsh\fP(1), \fBdd\fP(1), \fBfind\fP(1).
.SH BUGS
The \fBr, u, w, l, F, C\fP, and \fIdigit\fP options of Unix \fBtar\fP
are not supported.
.LP
Multiple-tape (or floppy) archives should be supported, but so far no
clean way has been implemented.
.LP
A bug in the Bourne Shell usually causes an extra newline to be written
to the standard error when using compressed or remote archives.
.LP
A bug in ``dd'' prevents turning off the ``x+y records in/out'' messages
on the standard error when ``dd'' is used to reblock or transport an archive.