tar.texinfo

speech signal process tools

set up to be the ``first'' tape drive or other transportable I/O medium
on the system.

If the filename is @samp{-}, @code{tar} reads the archive from
standard input (when listing or extracting), or writes it to standard
output (when creating).  If the @samp{-} filename is given when
updating an archive, @code{tar} will read the original archive from
its standard input, and will write the entire new archive to its
standard output.

If the filename contains @samp{:/dev/}, it is interpreted as
@samp{hostname:filename}.  If the @var{hostname} contains an ``at'' sign
(@samp{@@}), it is treated as @samp{user@@hostname:filename}.
In either case, @code{tar} will invoke the command @code{rsh}
(or @code{remsh}) to start
up an @code{/etc/rmt} on the remote machine.  If you give an alternate login
name, it will be given to the @code{rsh}.  Naturally, the remote machine must
have a copy of @file{/etc/rmt}.  @code{/etc/rmt} is free software
from the University of California, and a copy of the source code can be found
with the sources for @code{tar}.  @code{/etc/rmt} will have to be modified to
run on non-BSD4.3 systems.@refill

@item -C @var{dir}
@itemx +directory @var{dir}
This option causes @code{tar} to change into the directory @var{dir}
before continuing.  This option is usually interspersed with the files
@code{tar} is to work on.  For example,

@example 
tar -c iggy ziggy -C baz melvin
@end example

@noindent
will place the files @file{iggy} and @file{ziggy} from the current
directory on the tape, followed by the file @file{melvin} from the
directory @file{baz}.  This option is especially useful when you have
several widely separated files that you want to store in the same
directory in the archive.

Note that the file @file{melvin} is recorded in the archive under the
precise name @file{melvin}, @emph{not} @file{baz/melvin}.  Thus, the
archive will contain three files that all appear to have come from the
same directory; if the archive is extracted with plain @samp{tar -x},
all three files will be created in the current directory.

Contrast this with the command

@example
tar -c iggy ziggy bar/melvin
@end example

@noindent
which records the third file in the archive under the name @file{bar/melvin}
so that, if plain @samp{tar -x} is used, the third file will be created
in a subdirectory named @file{bar}.

@item -M
@itemx +multi-volume
This option causes @code{tar} to write a @dfn{multi-volume} archive--one
that may be larger than will fit on the medium used to hold it.

When this option is used, @code{tar} will not abort when it cannot
read or write any more data.  Instead, it will ask you to prepare a
new volume.  If the archive is on a magnetic tape, you should change
tapes now; if the archive is on a floppy disk, you should change
disks, etc.

Each volume of a multi-volume archive is an independent tar archive,
complete in itself.  For example, you can list or extract any volume
alone (just don't specify @samp{-M}).  However, if one file in the
archive is split across volumes, the only way to extract it
successfully is with a multi-volume extract command (@samp{-xM})
starting on or before the volume where the file begins.

@item -N (+after-date) @var{date}
This option causes @code{tar} to only work on files whose modification
or inode-changed times are newer than the @var{date} given.  The main
use is for creating an archive; then only new files are written.  If
extracting, only newer files are extracted.

Remember that the entire date argument should be quoted if it contains
any spaces.

The date is parsed using @code{getdate}.

@item -R (+record-number)
If @samp{-R} is used, @code{tar} prints, along with every message it
would normally produce, the record number within the archive where
the message occurred.  This option is especially useful when reading
damaged archives, since it helps pinpoint the damaged sections.

This can also be useful when making a log of a file-system backup tape,
since the results allow you to find the file you want to retrieve
on several backup tapes and choose the tape where the file appears
earliest (closest to the front of the tape).

@item -T (+files-from) @var{filename}
Instead of taking the list of files to work on from the command
line, the list of files to work on is read from the file
@var{filename}.  If @var{filename} is given as @samp{-}, the list is
read from standard input.  Note that using both @samp{-T -} and
@samp{-f -} will not work unless you are using the @samp{-c} command.

@item -v (+verbose)
This option causes @code{tar} to be verbose about the actions it is
taking.

Normally, the @samp{-t} command to list an archive prints
just the file names (one per line) and the other commands are silent.

@samp{-tv} prints a full line of information about each file, like the
output of @samp{ls -l}.  @samp{-v} with any other command (aside from
@samp{-t}) prints just the name of each file operated on.

The output from @samp{-v} appears on the standard output except when
creating or updating an archive to the standard output, 
in which case the output from @samp{-v} is sent to the standard
error.

@item +version

This option causes @code{tar} to print out its version number to the
standard error.  It has no equivalent short option name.

@item -w (+interactive)
This option causes @code{tar} to print a message for each action it
intends to take, and ask for confirmation on the terminal.  To
confirm, you must type a line of input.  If your input line begins
with @samp{y}, the action is performed, otherwise it is skipped.

The actions which require confirmation include adding a file to the
archive, extracting a file from the archive, deleting a file from the
archive, and deleting a file from disk.

If @code{tar} is reading the archive from the standard input,
@code{tar} will open the file @file{/dev/tty} to ask for
confirmation on.

@item -X (+exclude) @var{file} This option causes @code{tar} to
read a list of filename regular expressions, one per line, from
the file @var{file}; @code{tar} will ignore files with those
names.  Thus if @code{tar} is called as @samp{tar -c -X foo .}
and the file @file{foo} contains @samp{*.o} none of the files
whose names end in @file{.o} in the current directory (or any
subdirectory of the current directory) will be added to the
archive.  Multiple @code{-X} options may be given.

@item -z
@itemx -Z (+compress or +uncompress)
The archive should be compressed as it is written, or decompressed
as it is read, using the @code{compress} program.  This option works
on physical devices (tape drives, etc.) and remote files as well as
on normal files; data to or from such devices or remote files is
reblocked by another copy of the @code{tar} program to enforce the
specified (or default) block size.  The default compression
parameters are used; if you need to override them, avoid the
@samp{-z} option and run @code{compress} explicitly.

If the @samp{-z} option is given twice, or the @samp{+compress-block} option
is used, @code{tar} will pad the archive out to the next block boundry
(@pxref{General Options}).  This may be useful with some devices that
require that all write operations be a multiple of a certain size.

Note that the @samp{-z} option will not work with the @samp{-M} option,
or with the @samp{-u}, @samp{-r}, @samp{-A}, or @samp{-D} commands.
@end table

@node Creation Options, Extraction Options, General Options, Options
@section Options for Creating Or Updating an Archive

These options are used to control which files @code{tar} puts in an
archive, or to control the format the archive is written in (@pxref{Format}).

Except as noted below, these options are useful with the @samp{-c},
@samp{-r}, @samp{-u}, @samp{-A}, and @samp{-D} commands.
Also note that the @samp{-B} option, (@pxref{Extraction Options}),
is also useful with the @samp{-r}, @samp{-u}, @samp{-A}, and @samp{-D} commands.

@table @code
@c this command no longer exists  -D is now the old -J command
@c @item -D
@c The @samp{-D} option tells @code{tar} to only store entries for the
@c directories it encounters, and to not to store the files inside the
@c directories.  In conjunction with @code{find} this is useful for
@c creating incremental dumps for archival backups, similar to those
@c produced by @code{dump}.
 
@item -G (+incremental)
This option should only be used when creating an incremental backup of
a filesystem.  When the @samp{-G} option is used, @code{tar} writes, at
the beginning of the archive, an entry for each of the directories that
will be operated on.  The entry for a directory includes a list of all
the files in the directory at the time the dump was done, and a flag
for each file indicating whether the file is going to be put in the
archive.  This information is used when doing a complete incremental
restore.

Note that this option causes @code{tar} to create a non-standard
archive that may not be readable by non-GNU versions of the @code{tar}
program.

@item -h (+dereference)
If @samp{-h} is used, when @code{tar} encounters a symbolic link, it
will archive the linked-to file, instead of simply recording the
presence of a symbolic link.  If the linked-to file is archived
again, an entire second copy of it will be archived, instead of a
link.  This could be considered a bug.

@item -l (+one-file-system)
This option causes @code{tar} to not cross filesystem boundaries
when archiving parts of a directory tree.  This option only
affects files that are archived because they are in a directory that
is archived; files named on the command line are archived
regardless, and they can be from various file systems.

This option is useful for making full or incremental archival backups of
a file system, as with the Unix @code{dump} command.

Files which are skipped due to this option are mentioned on the
standard error.

@item -o (+old-archive or +old or +portability)
This option causes @code{tar} to write an old format archive, which
does not include information about directories, pipes, fifos,
contiguous files, or device files, and specifies file ownership by
numeric user- and group-ids rather than by user and group names.  In
most cases, a @emph{new} format archive can be read by an @emph{old}
@code{tar} program without serious trouble, so this option should
seldom be needed.  When updating an archive, do not use @samp{-o}
unless the archive was created with the @samp{-o} option.

@item -S (+sparse)
This option causes all files to be put in the archive to be tested for
sparseness, and handled specially if they are.  The @samp{-S} option
is useful when many dbm files, for example, are being backed up, and
running out of space on the tape is an issue.  Using this option
dramatically decreases the amount of space needed to store such a file.

In later versions, this option may be removed, and the testing and
treatment of sparse files may be done automatically with any special
GNU options.  For now, it is an option needing to be specified on the
command line with the creation or updating of an archive.

@item -V (+volume) @var{name}
This option causes @code{tar} to write out a @dfn{volume header} at
the beginning of the archive.  If @samp{-M} is used, each volume of
the archive will have a volume header of @samp{@var{name} Volume @var{N}},
where @var{N} is 1 for the first volume, 2 for the next, and so on.

@item -W (+verify)
This option causes @code{tar} to verify the archive after writing it.
Each volume is checked after it is written, and any discrepancies are
recorded on the standard error output.

Verification requires that the archive be on a back-space-able medium.
This means pipes, some cartridge tape drives, and some other devices
cannot be verified.
@end table

@node Extraction Options, Option Syntax, Creation Options, Options
@section Options for Listing Or Extracting Files

The options in this section are meaningful with the @samp{-x} command.
Unless otherwise stated, they are also meaningful with the @samp{-t}
command.

@table @code
@item -B (+read-full-blocks)
If @samp{-B} is used, @code{tar} will not panic if an attempt to
read a block from the archive does not return a full block.  Instead,
@code{tar} will keep reading until it has obtained a full block.

This option is turned on by default when @code{tar} is reading an
archive from standard input, or from a remote machine.  This is
because on BSD Unix systems, a read of a pipe will return however much
happens to be in the pipe, even if it is less than @code{tar}
requested.  If this option was not used, @code{tar} would fail
as soon as it read an incomplete block from the pipe.

This option is also useful with the commands for updating an archive.

@item -G (+incremental)
The @samp{-G} option means the archive is an incremental backup.
Its meaning depends on the command that it modifies.

If the @samp{-G} option is used with @samp{-t}, @code{tar} will
list, for each directory in the archive, the list of files in that
directory at the time the archive was created.  This information is
put out in a format that is not easy for humans to read, but which
is unambiguous for a program: each filename is preceded by either a
@samp{Y} if the file is present in the archive, an @samp{N} if the
file is not included in the archive, or a @samp{D} if the file is a
directory (and is included in the archive).  Each filename is
terminated by a null character.  The last file is followed by an
additional null and a newline to indicate the end of the data.

If the @samp{-G} option is used with @samp{-x}, then when the entry
for a directory is found, all files that currently exist in that directory
but are not listed in the archive @emph{are deleted from the directory}.

This behavior is convenient when you are restoring a damaged file system
from a succession of incremental backups: it restores the entire state
of the file system to that which obtained when the backup was made.
If you don't use @samp{-G}, the file system will probably fill up
with files that shouldn't exist any more.

@item -i (+ignore-zeros)
The @samp{-i} option causes @code{tar} to ignore blocks of zeros in the
archive.  Normally a block of zeros indicates the end of the
archive, but when reading a damaged archive, or one which was created by
@code{cat}-ing several archives together, this option allows
@code{tar} to read the entire archive.  This option is not on by
default because many versions of @code{tar} write garbage after the
zeroed blocks.

Note that this option causes @code{tar} to read to the end of the
archive file, which may sometimes avoid problems when multiple files
are stored on a single physical tape.