tar.texinfo

speech signal process tools

\input texinfo @c -*-texinfo-*-

@setfilename tar-info
@settitle The @code{tar} Manual: DRAFT
@ifinfo
This file documents the tape archive of the GNU system.

Copyright (C) 1988 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of
a permission notice identical to this one.

Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for
modified versions.
@end ifinfo

@iftex
@finalout
@end iftex

@titlepage
@sp 11
@center @titlefont{tar}
@sp 1
@center The GNU tape archive
@sp 2
@center by Jay Fenlason
@sp 2
@center DRAFT!
@sp 1
@center @today
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1988 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the same conditions as for modified versions.

@end titlepage
@node Top, Preface, (dir), (dir)

@node Preface, Why, Top, Top
@unnumbered Preface

This manual describes the GNU tape archiver, @code{tar}, and how you
can use it to store copies of a file or a group of files in an
@dfn{archive}.  This archive may be written directly to a magnetic
tape or other storage medium, stored as a file, or sent through a
pipe to another program.  @code{tar} can also be used to add files
to an already existing archive, list the files in an archive, or
extract the files in the archive.
@sp 2
GNU @code{tar} was written by John Gilmore, and modified by many
people.  The GNU enhancements were written by Jay Fenlason.

@ifinfo
@ichapter Using the Tape Archiver

You can use the GNU tape archiver, @code{tar}, to store copies of a file
or a group of files in an @dfn{archive}.  This archive may be written
directly to a magnetic tape or other storage medium, stored as a file,
or sent through a pipe to another program.  @code{tar} can also be used
to add files to an already existing archive, list the files in an
archive, or extract the files in the archive.

@menu
* Why::			What @code{tar} archives are good for.
* Commands::		How to tell @code{tar} what to do.
* Options::		Options that change the way @code{tar} behaves.
* FullDumps::		Using @code{tar} to perform full dumps.
* IncDumps::		Using @code{tar} to perform incremental dumps.
* Problems::		Common problems using @code{tar}.
* Rem Tape::		The remote tape server.
* Format::		The format of a @code{tar} archive.
@end menu
@end ifinfo

@node Why, Commands, Preface, Top
@chapter The Uses of Tape Archives

The tape archiver @code{tar} allows you to store many files in an
@dfn{archive file} or @dfn{tar file} which describes the names and contents
of the constituent files.  Later you can extract some or all of these files
from the archive.

Tar files are not restricted to magnetic tapes.  The @code{tar} program
can equally well use an ordinary file, or a pipe, or any device, as the
archive.  But they were originally designed for use with magnetic tapes,
and that is how the name ``tar'' came about.

Archive files can be used for transporting a group of files from one system
to another:  put all relevant files into an archive on one computer system,
transfer the archive to another, and extract the contents there.  The basic
transfer medium might be magnetic tape, Internet FTP, or even electronic
mail (though you must encode the archive with @code{uuencode} in order to
transport it properly by mail).  Both machines do not have to use the same
operating system, as long as they both support the @code{tar} program.

A magnetic tape can store several files in sequence, but has no names for
them, just relative position on the tape.  A tar file or something like it
is the only way to store several files on one tape and retain their names.
Even when the basic transfer mechanism can keep track of names, as FTP can,
the nuisance of handling multiple files, directories, and multiple links,
may make a tar file a much easier method.

Archive files are also used for long-term storage, which you can think
of as transportation from one time to another.

Piping one @code{tar} to another is an easy way to copy a directory's
contents from one disk to another, while preserving the dates, modes, owners
and link-structure of all the files therein.

The GNU version of @code{tar} has special features that allow it to be
used to make incremental and full dumps of all the files in a
filesystem.

@node Commands, Options, Why, Top
@chapter The Different Operations @code{tar} Can Perform

One program, @code{tar}, is used to create an archive, to extract files
from an archive, to modify an archive, or to list the contents.  Each
time you run @code{tar}, you must give a @dfn{command} to specify which
one of these things you want to do.

The command must always be in the first argument to @code{tar}.  This
argument can also contain options (@pxref{Options}).  For compatibility
with Unix @code{tar}, the first argument is always treated as containing
command and option letters even if it doesn't start with @samp{-}.  Thus,
@samp{tar c} is equivalent to @samp{tar -c}: both of them specify the
@samp{-c} command to create an archive.

In addition, a set of long-named options are provided which can be used
instead of or inter-mixed with the single-letter flags.  The long-named
options are meant to be easy to remember and logical, while the single
letter flags may not always be.  Long-named options are preceded by a
@samp{+}.  In the list of single-letter commands below, each
corresponding long-named option is listed next to it, in parentheses.

The remaining arguments to @code{tar} are either options, if they start
with @samp{-} or @samp{+}, or files to operate on.

The file names that you give as arguments are the files that @code{tar} will
act on -- for example, they are the files to put in the archive, or the files
to extract from it.  If you don't give any file name arguments, the default
depends on which command you used.  Some commands use all relevant files;
some commands have no default and will report an error if you don't specify
files.

If a file name argument actually names a directory, then that directory
and all files and subdirectories in it are used.

Here is a list of all the @code{tar} commands:

@table @samp
@item -c
@itemx +create
This command tells @code{tar} to create a new archive that contains the
file(s) specified on the command line.  If you don't specify files, all
the files in the current directory are used.

If the archive file already exists, it is overwritten; the old contents
are lost.

@item -d
@itemx +compare
@itemx +diff
This command causes @code{tar} to compare the archive with the files in
the file system.  It will report differences in file size, mode, owner,
and contents.  If a file exists in the archive, but not in the file
system, @code{tar} will report this.

If you specify file names, those files are compared with the tape and
they must all exist in the archive.  If you don't specify files, all
the files in the archive are compared.

@item -r
@itemx +append
This command causes @code{tar} to add the specified file(s) to the end of
the archive.  This assumes that the archive file already exists and is
in the proper format (which probably means it was created previously
with the @code{tar} program).  If the archive is not in a format that
@code{tar} understands, the results will be unpredictable.

You must specify the files to be used; there is no default.

@item -t
@itemx +list
This command causes @code{tar} to display a list of the files in the
archive.  If you specify file names, only the files hat you specify will
be mentioned (but each of them is mentioned only if it appears in the
archive).

@item -u
@itemx +update
This command causes @code{tar} to add the specified files to the end of
the archive, like @w{@samp{-r}}, but only when a file doesn't already
exist in the archive or is newer than the version in the archive
(the last-modification time is compared).  Adding files to the end of an
archive can be very slow.

You must specify the files to be used; there is no default.

@item -x
@itemx +extract
@itemx +get
This command causes @code{tar} to extract the specified files from the
archive.  If no file names are given, all the files in the archive will
be extracted.

@item -A
@itemx +catenate
@itemx +concatenate
This command is used for concatenating several archive files into one big
archive file.  The files to operate on should all be archive files.
They are all appended to the end of @emph{the} archive file which
@code{tar} works on.  (The other files are not changed).

You might be tempted to use @code{cat} for this, but it won't ordinarily
work.  A @code{tar} archive contains data which indicates the end of the
archive, so more material added to the end with @code{cat} would be
ignored.  This command works because it removes the end-of-archive
markers from the middle of the result.

@item -D
@itemx +delete
This command causes @code{tar} to delete the specified files from the
archive.  This command is extremely slow.  Warning: Use of this command
on archives stored on magnetic tape may result in a scrambled archive.
There is no safe way (except for completely re-writing the archive) to
delete files from a magnetic tape.
@end table

@node Options, FullDumps, Commands, Top
@chapter Options That Change How @code{tar} Works

Options may be specified as individual arguments starting with @samp{-}.
In this case, if the option wants an argument (as does, for example,
@samp{-f}) then the argument should come after the option, separated
from it by a space.
All options are optional.  Some options make sense with any command, while
others are meaningful only with particular commands.@refill

@menu
* General Options::		Options that are always meaningful.
* Creation Options::		Options for creating or updating an archive.
* Extraction Options::		Options for listing or extracting files.
* Option Syntax::		Old syntax for options
@end menu

@node General Options, Creation Options, , Options
@section Options That Are Always Meaningful

@table @samp
@item -b @var{number}
@itemx +block-size @var{number}
This option is used to specify a @dfn{blocking factor} for the
archive.  When reading or writing the archive, @code{tar}, will do
reads and writes of the archive in blocks of @var{number}*512 bytes.

The default blocking factor is set when @code{tar} is compiled, and is
typically 20.

Blocking factors larger than 20 cannot be read by very old versions of
@code{tar}, or by some newer versions of @code{tar} running on old machines
with small address spaces.

With a magnetic tape, larger blocks give faster throughput and fit
more data on a tape (because there are fewer inter-record gaps).  If
the archive is in a disk file or a pipe, you may want to specify a
smaller blocking factor, since a large one will result in a large
number of null bytes at the end of the archive.

When writing cartridge or other streaming tapes, a much larger
blocking factor (say 126 or more) will greatly increase performance.
However, you must specify the same blocking factor when reading or
updating the archive.

With GNU @code{tar} the blocking factor is limited only by the maximum
block size of the device containing the archive, or by the amount of
available virtual memory.

@item -f @var{filename}
@itemx +file @var{filename}
This option is used to specify the file name of the archive @code{tar}
works on.

If this option is not given, but the environment variable @code{TAPE}
is set, its value is used; otherwise, a default archive name (which was
picked when @code{tar} was compiled) is used.  The default is normally