tar.texinfo

speech signal process tools

@item -k (+keep-old-files)
The @samp{-k} option prevents @code{tar} from over-writing existing
files with files with the same name from the archive.

The @samp{-k} option is meaningless with @samp{-t}.

@item -K (+starting-file) @var{filename}
The @samp{-K} option causes @code{tar} to begin extracting or listing
the archive with the file @var{filename}, and to consider only the
files starting at that point in the archive.  This is useful if a
previous attempt to extract files failed when it reached
@var{filename} due to lack of free space.  (This assumes, of course,
that there is now free space, or that you are now extracting into a
different file system.)

@item -m
@item +modification-time
When this option is used, @code{tar} leaves the modification times of
the files it extracts as the time when the files were extracted,
instead of setting it to the time recorded in the archive.

This option is meaningless with @samp{-t}.

@item -O
@itemx +to-stdout
When this option is used, instead of creating the files specified,
@code{tar} writes the contents of the files extracted to its standard
output.  This may be useful if you are only extracting the files in
order to send them through a pipe.

This option is meaningless with @samp{-t}.

@item -p
@itemx +same-permissions
@itemx +preserve-permissions
This option causes @code{tar} to set the modes (access permissions) of
extracted files exactly as recorded in the archive.  If this option is
not used, the current @code{umask} setting limits the permissions on
extracted files.

This option is meaningless with @samp{-t}.

@item -P
@itemx +absolute-paths
This option should be used when the absolute pathname of a file should
be preserved in the archive.  @code{tar} normally strips the leading `/'
from the name of the file, thus making /usr/foo/bar/baz into
usr/foo/bar/baz.  Using the @samp{-P} option keeps the pathname intact,
and is useful in that it is not necessary to change to the root
directory when extracting files.

@item -s
@itemx +same-order
@itemx +preserve-order
This option tells @code{tar} that the list of filenames to be listed or
extracted is sorted in the same order as the files in the archive.  This
allows a large list of names to be used, even on a small machine that
would not otherwise be able to hold all the names in memory at the same
time.  Such a sorted list can easily be created by running @samp{tar -t}
on the archive and editing its output.

This option is probably never needed on modern computer systems.

@item +preserve
The @samp{+preserve} option has no equivalent short option name.
It is equivalent to @samp{-p} plus @samp{-s}.
@end table

@node Option Syntax, , Extraction Options, Options
@section Old Syntax for Options

For compatibility with Unix @code{tar}, the first argument can contain
option letters in addition to the command letter; for example, @samp{tar
cv} specifies the option @samp{-v} in addition to the command @samp{-c}.
The first argument to GNU @code{tar} is always treated as command and
option letters even if it doesn't start with @samp{-}.

Some options need their own arguments; for example, @samp{-f} is followed
by the name of the archive file.  When the option is given separately, its
argument follows it, as is usual for Unix programs.  For example:

@example
tar -c -v -b 20 -f /dev/rmt0
@end example

When options that need arguments are given together with the command, all
the associated arguments follow, in the same order as the options.  Thus,
the example above could also be written in the old style as follows:

@example
tar cvbf 20 /dev/rmt0
@end example

@noindent
Here @samp{20} is the argument of @samp{-b} and @file{/dev/rmt0} is the
argument of @samp{-f}.

The long-named options can be used instead of the single-letter flags.
They are meant to be obvious and easy to remember, possibly more so than
their corresponding single-letter options.  The above example using
long-named options would look like this:

@example
tar +create +verbose +block-size +file 20 /dev/rmt0
@end example

@node FullDumps, IncDumps, Options, Top
@chapter Using @code{tar} to Perform Full Dumps
Full dumps should only be made when no other people or programs are
modifying files in the filesystem.  If files are modified while
@code{tar} is making the backup, they may not be stored properly in
the archive, in which case you won't be able to restore them if you
have to.

You will want to use the @samp{-V} option to give the archive a
volume label, so you can tell what this archive is even if the label
falls off the tape, or anything like that.

Unless the filesystem you are dumping is guaranteed to fit on one
volume, you will need to use the @samp{-M} option.  Make sure you
have enough tapes on hand to complete the backup.

If you want to dump each filesystem separately you will need to use
the @samp{-l} option to prevent @code{tar} from crossing filesystem
boundaries when storing (sub)directories.

The @samp{-G} option is not needed, since this is a complete copy of
everything in the filesystem, and a full restore from this backup
would only be done onto a completely empty disk.

Unless you are in a hurry, and trust the @code{tar} program (and
your tapes), it is a good idea to use the @code{-W} (verify) option,
to make sure your files really made it onto the dump properly.  This
will also detect cases where the file was modified while (or just
after) it was being archived.

@node IncDumps, Problems, FullDumps, Top
@chapter Using @code{tar} to Perform Incremental Dumps
Performing incremental dumps is similar to performing full dumps,
although a few more options will usually be needed.

You will need to use the @samp{-N @var{date}} option to tell @code{tar} to
only store files that have been modified since @var{date}.
@var{date} should be the date and time of the last full/incremental
dump.

A standard scheme is to do a @samp{monthly} (full) dump once a month,
a @samp{weekly} dump once a week of everything since the last monthly and
a @samp{daily} every day of everything since the last (weekly or monthly)
dump.

Here is a copy of the script used to dump the filesystems of the
machines here at the Free Software Foundation.  This script is run
(semi-)automatically late at night when people are least likely to
be using the machines.  This script dumps several filesystems from
several machines at once (by using a network-filesystem).  The
operator is responsible for ensuring that all the machines will be
up at the time the dump happens.  If a machine is not running, its
files will not be dumped, and the next day's incremental dump will
@emph{not} store files that would have gone onto that dump.

@example
#!/bin/csh
# Dump thingie
set now = `date`
set then = `cat date.nfs.dump`
/u/hack/bin/tar -c -G -v\
 -f /dev/rtu20\
 -b 126\
 -N "$then"\
 -V "Dump from $then to $now"\
 /alpha-bits/gp\
 /gnu/hack\
 /hobbes/u\
 /spiff/u\
 /sugar-bombs/u
echo $now > date.nfs.dump
mt -f /dev/rtu20 rew
@end example

Output from this script is stored in a file, for the operator to
read later.

This script uses the file @file{date.nfs.dump} to store the date/time of
the last dump.

Since this is a streaming tape drive, no attempt to verify the
archive is done.  This is also why the high blocking factor (126) is
used.  The tape drive must also be rewound by the @code{mt} command
after the dump is made.

@node Problems, Rem Tape, IncDumps, Top
@chapter Common Problems Using @code{tar}

Unless you use the @code{-P} option, GNU @code{tar} will not allow
you to create an archive that contains absolute pathnames.  (An
absolute pathname is one that begins with a @samp{/}.) If you try,
@code{tar} will automatically remove the leading @samp{/} from the
file names it stores in the archive.  It will also type a warning
message telling you what it is doing.

When reading an archive that was created with a different @code{tar}
program, GNU @code{tar} automatically extracts entries in the
archive which have absolute pathnames as if the pathnames were not
absolute.  If the archive contained a file @samp{/usr/bin/computoy},
GNU @code{tar} would extract the file to @samp{usr/bin/computoy} in
the current directory.  If you want to extract the files in an
archive to the same absolute names that they had when the archive
was created, you should do a @samp{cd /} before extracting the files
from the archive, or you should either use the @samp{-P} option, or
use the command @samp{tar -C / @dots{}}.

Some versions of UNIX, (Ultrix 3.1 is know to have this problem) can
claim that a short write near the end of a tape succeeded, when it
actually failed.  This will result in the -M option not working
correctly.  The best workaround at the moment is to use a
significantly larger blocksize than the default 20.

In order to update an archive, @code{tar} must be able to backspace
the archive in order to re-read or re-write a block that was just read
(or written).  This is currently possible only on two kinds of
files:  normal disk files (or any other file that can be
backspaced with @code{lseek()}), and industry-standard 9-track magnetic
tape (or any other kind of tape that can be backspaced with
@code{ioctl(@dots{},MTIOCTOP,@dots{})}).

This means that the @samp{-r}, @samp{-u}, @samp{-A}, and @samp{-D}
commands will not work on any other kind of file.  Some media simply
cannot be backspaced, which means these commands and options will
never be able to work on them.  These non-backspacing media include
pipes and cartridge tape drives.

Some other media can be backspaced, and @code{tar} will work on them
once @code{tar} is modified to do so.

Archives created with the @samp{-M}, @samp{-V}, and @samp{-G}
options may not be readable by other version of @code{tar}.  In particular,
restoring a file that was split over a volume boundary will require
some careful work with @code{dd}, if it can be done at all.  Other versions
of @code{tar} may also create an empty file whose name is that of
the volume header.  Some versions of @code{tar} may create normal
files instead of directories archived with the @samp{-G} option.

@node Rem Tape, Format, Problems, Top
@chapter The Remote Tape Server
In order to access the tape drive on a remote machine, @code{tar}
uses the remote tape server written at the University of California
at Berkeley.  The remote tape server must be installed as
@file{/etc/rmt} on any machine whose tape drive you want to use.
@code{tar} calls @file{/etc/rmt} by running an @code{rsh} or
@code{remsh} to the remote machine, optionally using a different
login name if one is supplied.

A copy of the source for the remote tape server is provided.  It is
Copyright @copyright{} 1983 by the Regents of the University of California, but
can be freely distributed.  Instructions for compiling and
installing it are included in the @file{Makefile}.

The remote tape server may need to be modified in order to run on a
non-4.3BSD system.

@node Format, , Rem Tape, Top
@chapter The Format of a @code{tar} Archive
This chapter is based heavily on John Gilmore's @i{tar}(5) manual page
for the public domain @code{tar} that GNU @code{tar} is based on.

@section The Standard Format
A @dfn{tar tape} or file contains a series of records.  Each record
contains @code{RECORDSIZE} bytes.  Although this format may be
thought of as being on magnetic tape, other media are often used.

Each file archived is represented by a header record which describes
the file, followed by zero or more records which give the contents
of the file.  At the end of the archive file there may be a record
filled with binary zeros as an end-of-file marker.  A reasonable
system should write a record of zeros at the end, but must not
assume that such a record exists when reading an archive.

The records may be @dfn{blocked} for physical I/O operations.  Each
block of @var{N} records (where @var{N} is set by the @samp{-b}
option to @code{tar}) is written with a single @code{write()}
operation.  On magnetic tapes, the result of such a write is a
single tape record.  When writing an archive, the last block of
records should be written at the full size, with records after the
zero record containing all zeroes.  When reading an archive, a
reasonable system should properly handle an archive whose last block
is shorter than the rest, or which contains garbage records after a
zero record.

The header record is defined in C as follows:

@example
/*
 * Standard Archive Format - Standard TAR - USTAR
 */
#define RECORDSIZE  	512
#define NAMSIZ      	100
#define TUNMLEN      	32
#define TGNMLEN      	32
#define SPARSE_EXT_HDR	21
#define	SPARSE_IN_HDR	4

struct sparse @{
	char offset[12];
	char numbytes[12];
@};

union record @{
    char        charptr[RECORDSIZE];
    struct header @{
        char    name[NAMSIZ];
        char    mode[8];
        char    uid[8];
        char    gid[8];
        char    size[12];
        char    mtime[12];
        char    chksum[8];
        char    linkflag;
        char    linkname[NAMSIZ];