   This file documents GNU `tar', a utility used to store, backup, and
transport files.

   Copyright (C) 1992, 1994, 1995 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.

   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, except that this permission notice may be stated in a
translation approved by the Foundation.

Options to Help Read Archives
-----------------------------

     *(This message will disappear, once this node revised.)*

FIXME: each option wants its own node.  summary after menu

   Normally, `tar' will request data in full block increments from an
archive storage device.  If the device cannot return a full block,
`tar' will report an error.  However, some devices do not always return
full blocks, or do not require the last block of an archive to be
padded out to the next block boundary.  To keep reading until you
obtain a full block, or to accept an incomplete block if it contains an
end-of-archive marker, specify the `--read-full-blocks' (`-B') option
in conjunction with the `--extract' (`-x') or `--list' (`-t')
operations.

FIXME: xref Listing Contents
   .

   The `--read-full-blocks' (`-B') option is turned on by default when
`tar' reads an archive from standard input, or from a remote machine.
This is because on BSD Unix systems, attempting to read a pipe returns
however much happens to be in the pipe, even if it is less than was
requested.  If this option were not enabled, `tar' would fail as soon
as it read an incomplete block from the pipe.

   If you're not sure of the blocking factor of an archive, you can
read the archive by specifying `--read-full-blocks' (`-B') and
`--block-size=512-SIZE' (`-b 512-SIZE'), using a blocking factor larger
than what the archive uses.  This lets you avoid having to determine
the blocking factor of an archive.
FIXME: xref Blocking Factor
   .

`--read-full-blocks'
`-B'
     Use in conjunction with `--extract' (`-x') to read an archive which
     contains incomplete blocks, or one which has a blocking factor less
     than the one specified.

   Normally `tar' stops reading when it encounters a block of zeros
between file entries (which usually indicates the end of the archive).
`--ignore-zeros' (`-i') allows `tar' to completely read an archive
which contains a block of zeros before the end (i.e. a damaged archive,
or one which was created by `cat'-ing several archives together).

   The `--ignore-zeros' (`-i') option is turned off by default because
many versions of `tar' write garbage after the end-of-archive entry,
since that part of the media is never supposed to be read.  GNU `tar'
does not write after the end of an archive, but seeks to maintain
compatablity among archiving utilities.

`--ignore-zeros'
`-i'
     To ignore blocks of zeros (ie. end-of-archive entries) which may be
     encountered while reading an archive.  Use in conjunction with
     `--extract' (`-x') or `--list' (`-t').

   If you are using a machine with a small amount of memory, and you
need to process large list of file names, you can reduce the amount of
space `tar' needs to process the list.  To do so, specify the
`--same-order' (`-s') option and provide an ordered list of file names.
This option tells `tar' that the NAME arguments provided on the command
line, or read from a file using the `--files-from=FILE-OF-NAMES' (`-T
FILE-OF-NAMES') option, are listed in the same order as the files in
the archive.

   You can create a file containing an ordered list of files in the
archive by storing the output produced by `tar --list
--file=ARCHIVE-NAME'.
FIXME: xref Listing Contents
   , for information on the `--list' (`-t') operation.

   This option is probably never needed on modern computer systems.

`--same-order'
`--preserve-order'
`-s'
     To process large lists of file names on machines with small
     amounts of memory.  Use in conjunction with `--compare' (`-d'),
     `--list' (`-t') or `--extract' (`-x').

FIXME: we don't need/want --preserve to exist any more

Changing How `tar' Writes Files
-------------------------------

FIXME: find a better title

     *(This message will disappear, once this node revised.)*

   Normally, `tar' writes extracted files into the file system without
regard to the files already on the system--files with the same name as
archive members are overwritten.  To prevent `tar' from extracting an
archive member from an archive, if doing so will overwrite a file in
the file system, use `--keep-old-files' (`-k') in conjunction with the
`--extract' (`-x') operation.  When this option is specified, `tar'
reports an error stating the name of the files in conflict, instead of
writing the file from the archive.

`--keep-old files'
`-k'
     Prevents `tar' from overwriting files in the file system during
     extraction.

   Normally, `tar' sets the modification times of extracted files to
the modification times recorded for the files in the archive, but
limits the permissions of extracted files by the current `umask'
setting.

   To set the modification times of extracted files to the time when
the files were extracted, use the `--modification-time' (`-m') option in
conjunction with `--extract' (`-x').

`--modification-time'
`-m'
     Sets the modification time of extracted archive members to the time
     they were extracted, not the time recorded for them in the archive.
     Use in conjunction with `--extract' (`-x').

   To set the modes (access permissions) of extracted files to those
recorded for those files in the archive, use the {No Value For
"same-persmissions"} option in conjunction with the `--extract' (`-x')
operation.
FIXME: mib --- should be aliased to ignore-umask.

`--preserve-permission'
`--same-permission'
`--ignore-umask'
`-p'
     Set modes of extracted archive members to those recorded in the
     archive, instead of current umask settings.  Use in conjunction
     with `--extract' (`-x').

FIXME: following paragraph needs to be rewritten: why doesnt' this cat
FIXME: files together, why is this useful.  is it really useful with
FIXME: more than one file?
   To write the files extracted to the standard output, instead of
creating the files on the file system, use `--to-stdout' (`-O') in
conjunction with `--extract' (`-x').  This option is useful if you are
extracting files to send them through a pipe, and do not need to
preserve them in the file system.

`--to-stdout'
`-O'
     Writes files to the standard output.  Used in conjunction with
     `--extract' (`-x').

FIXME: why would you want to do such a thing, how are files separated on
FIXME: the standard output? is this useful with more that one file?  are
FIXME: pipes the real reason?

Recovering From Scarce Disk Space
---------------------------------

     *(This message will disappear, once this node revised.)*

   If a previous attempt to extract files failed due to lack of disk
space, you can use `--starting-file=NAME' (`-K NAME') to start
extracting only after file NAME when extracting files from the archive.
This assumes, of course, that there is now free space, or that you are
now extracting into a different file system.

`--starting-file=FILE NAME'
`-K FILE NAME'
     Starts an operation in the middle of an archive.  Use in
     conjunction with `--extract' (`-x') or `--list' (`-t').

   If you notice you are running out of disk space during an extraction
operation, you can also suspend `tar', remove unnecessary files from
the file system, and then restart the same `tar' operation.  In this
case, `--starting-file=NAME' (`-K NAME') is not necessary.

FIXME: xref --incremental,  xref --interactive,  xref --exclude

Comparing Archives Members with Files
=====================================

     *(This message will disappear, once this node revised.)*

   The `--compare' (`-d') or `--diff' option compares the contents of
the specified archive members against the files with the same names,
and reports its findings.  If no members are named on the command line,
or through `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES'), then the
entire archive is so compared.

Matching the Format Parameters
==============================

     *(This message will disappear, once this node revised.)*

   Some format parameters must be taken into consideration when
modifying an archive:

   Compressed archives cannot be modified.

   You have to specify the block size of the archive when modifying an
archive with a non-default block size.

   Multi-volume archives can be modified like any other archive.  To add
files to a multi-volume archive, you need to only mount the last volume
of the archive media (and new volumes, if needed).  For all other
operations, you need to use the entire archive.

   If a multi-volume archive was labeled using `--label=ARCHIVE-LABEL'
(`-V ARCHIVE-LABEL') (
FIXME: pxref Archive Label
   ) when it was created, `tar' will not automatically label volumes
which are added later.  To label subsequent volumes, specify
`--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') again in conjunction with
the `--append' (`-r'), `--update' (`-u') or `--concatenate' (`-A')
operation.
FIXME: example

FIXME: xref somewhere, for more information about format parameters.

Specifying Names to `tar'
*************************

     *(This message will disappear, once this node revised.)*

Changing the Archive Name
=========================

     *(This message will disappear, once this node revised.)*

   By default, `tar' uses an archive file name compiled in when `tar'
was built.  Usually this refers to some physical tape drive on the
machine.  Often, the installer of `tar' didn't set the default to
anything meaningful at all.

   As a result, most uses of `tar' need to tell `tar' where to find (or
create) the archive.  The `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME')
option selects another file to use as the archive.

   If the archive file name includes a colon (`:'), then it is assumed
to be a file on another machine.  If the archive file is
`USER@HOST:FILE', then FILE is used on the host HOST.  The remote host
is accessed using the `rsh' program, with a username of USER.  If the
username is omitted (along with the `@' sign), then your user name will
be used.  (This is the normal `rsh' behavior.)  It is necessary for the
remote machine, in addition to permitting your `rsh' access, to have
the `/usr/ucb/rmt' program installed.  If you need to use a file whose
name includes a colon, then the remote tape drive behavior can be
inhibited by using the `--force-local' option.

   If the file name you give to `--file=ARCHIVE-NAME' (`-f
ARCHIVE-NAME') is a single dash (`-'), then `tar' will read the archive
from (or write it to) standard input (or standard output).

   The Name of an Archive

   An archive can be saved as a file in the file system, sent through a
pipe or over a network, or written to an I/O device such as a tape or
disk drive.  To specify the name of the archive, use the
`--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option.

   An archive name can be the name of an ordinary file or the name of an
I/O device.  `tar' always needs an archive name--if you do not specify
an archive name, the archive name comes from the environment variable
`TAPE' or, if that variable is not specified, a default archive name,
which is usually the name of tape unit zero (ie.  /dev/tu00).

   If you use `-' as an ARCHIVE-NAME, `tar' reads the archive from
standard input (when listing or extracting files), or writes it to
standard output (when creating an archive).  If you use `-' as an
ARCHIVE-NAME when modifying an archive, `tar' reads the original
archive from its standard input and writes the entire new archive to
its standard output.

FIXME: does standard input and output redirection work with all
FIXME: operations?
FIXME: need example for standard input and output (screen and keyboard?)

   To specify an archive file on a device attached to a remote machine,
use the following:

     --file=HOSTNAME:/DEV/FILE NAME

`tar' will complete the remote connection, if possible, and prompt you
for a username and password.  If you use `--file=@HOSTNAME:/DEV/FILE
NAME', `tar' will complete the remote connection, if possible, using
your username as the username on the remote machine.

FIXME: is this clear?

`--file=ARCHIVE-NAME'
`-f ARCHIVE-NAME'
     Names the archive to create or operate on.  Use in conjunction with
     any operation.

   Selecting Archive Members

   "File Name arguments" specify which files in the file system `tar'
operates on, when creating or adding to an archive, or which archive
members `tar' operates on, when reading or deleting from an archive.  (
FIXME: pxref Reading and Writing
   .)

   To specify file names, you can include them as the last arguments on
the command line, as follows:
     tar OPERATION [OPTION1 OPTION2 ..] [FILE NAME-1 FILE NAME-2 ...]

   If you specify a directory name as a file name argument, all the
files in that directory are operated on by `tar'.

   If you do not specify files when `tar' is invoked, `tar' operates on
all the non-directory files in the working directory (if the operation
is `--create' (`-c')), all the archive members in the archive (if a
read operation is specified), or does nothing (if any other operation
is specified).

   When specifying the names of files or members to `tar', it by
default takes the names of the files from the command line.  There are
other ways, however, to specify file or member names, or to modify the
manner in which `tar' selects the files or members upon which to
operate.  In general, these methods work both for specifying the names
of files and archive members.

Selecting Files by Characteristic
=================================

   To avoid crossing file system boundaries when archiving parts of a
directory tree, use `--one-file-system' (`-l').  This option only
affects files that are archived because they are in a directory that is
being archived; files explicitly named on the command line are archived
regardless of where they reside.

   This option is useful for making full or incremental archival backups
of a file system.

   If this option is used in conjunction with `--verbose' (`-v'), files
that are excluded are mentioned by name on the standard error.

`--one-file-system'
`-l'
     Prevents `tar' from crossing file system boundaries when
     archiving.  Use in conjunction with any write operation.

   To avoid operating on files whose names match a particular pattern,
use the `--exclude=PATTERN' or `--exclude-from=FILE-OF-PATTERNS' (`-X
FILE-OF-PATTERNS') options.

   When you specify the `--exclude=PATTERN' option, `tar' ignores files
which match the PATTERN, which can be a single file name or a more
complex expression.  Thus, if you invoke `tar' with `tar --create
--exclude=*.o', no files whose names end in `.o' are included in the
archive.
FIXME: what other things can you use besides "*"?

   `--exclude-from=FILE-OF-PATTERNS' (`-X FILE-OF-PATTERNS') acts like
`--exclude=PATTERN', but specifies a file FILE containing a list of
patterns.  `tar' ignores files with names that fit any of these
patterns.

   You can use either option more than once in a single command.

`--exclude=PATTERN'
     Causes `tar' to ignore files that match the PATTERN.

`--exclude-from=FILE'
     Causes `tar' to ignore files that match the patterns listed in
     FILE.
FIXME: --exclude-from used to be "--exclude", --exclude didn't used to
FIXME: exist.

   To operate only on files with modification or status-change times
after a particular date, use `--after-date=DATE' (`-N DATE').  You can
use this option with `--create' (`-c') or `--append' (`-r') to insure
only new files are archived, or with `--extract' (`-x') to insure only
recent files are resurrected.
FIXME: or --newer DATE

   `--newer-mtime=DATE' acts like `--after-date=DATE' (`-N DATE') but
tests just the modification times of the files, ignoring status-change
times.

FIXME: need example of --newer-mtime with quoted argument
   Remember that the entire date argument should be quoted if it
contains any spaces.

   *Please Note:* `--after-date=DATE' (`-N DATE') and
`--newer-mtime=DATE' should not be used for incremental backups.  Some
files (such as those in renamed directories) are not selected up
properly by these options.
FIXME: xref to incremental backup chapter when node name is decided.

`--after-date=DATE'
`--newer=DATE'
`-N DATE'
     Acts on files only if their modification or inode-changed times are
     later than DATE.  Use in conjunction with any operation.

`--newer-mtime=DATE'
     Acts like `--after-date=DATE' (`-N DATE'), but only looks at
     modification times.

FIXME: following is the getdate date format --- needs to be re-written,
FIXME: made a sub-node:

   Time/Date Formats Accepted by getdate (omitting obscure
constructions)

   The input consists of one or more of: time zone day date year in any
order.

   Those in turn consist of (`|' and `/' mean `or', `[]' means
`optional'):

   time: H am/pm | H:M [am/pm] | H:M:S [am/pm] zone: timezone-name |
timezone-name dst day: day-name | day-name, | N day-name date: M/D |
M/D/Y | month-name D | month-name D, Y | D month-name | D month-name Y
year: Y

   am can also be a.m., pm can also be p.m.  case and spaces around
punctuation are not significant.
FIXME: month and day names can be abbreviated.

Reading Names from a File
-------------------------

     *(This message will disappear, once this node revised.)*

   Instead of giving the names of files or archive members on the
command line, you can put the names into a file, and then use the
`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option to `tar'.
Give the name of the file which contains the list as the argument to
`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES').  The file names
should be separated by newlines in the list.  If you give a single dash
as a file name for `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES'),
that is, you specify `--files-from=-' (`-T -'), then the file names are
read from standard input.

   If you want to specify names that might contain newlines, use the
`--null' option.  Then, the file names should be separated by NUL
characters (ASCII 000) instead of newlines.  In addition, the `--null'
option turns off the `--directory=DIRECTORY' (`-C DIRECTORY') option (
FIXME: pxref Changing Directory
   ).

   Reading a List of File Names from a File

     *(This message will disappear, once this node revised.)*

   To read file names from a file on the file system, instead of from
the command line, use the `--files-from=FILE-OF-NAMES' (`-T
FILE-OF-NAMES') option.  If you specify `-' as FILE, the file names are
read from standard input.  Note that using both `--files-from=-' (`-T
-') and `--file=-' (`-f -') in the same command will not work unless
the operation is `--create' (`-c').
FIXME: xref Archive Name
   , for an explanation of the `--file=ARCHIVE-NAME' (`-f
ARCHIVE-NAME') option.

`--files-from=FILE'
`-T FILE'
     Reads file name arguments from a file on the file system, instead
     of from the command line.  Use in conjunction with any operation.

Excluding Some Files
--------------------

     *(This message will disappear, once this node revised.)*

   The `--exclude=PATTERN' option will prevent any file or member which
matches the regular expression PATTERN from being operated on.  For
example, if you want to create an archive with all the contents of
`/tmp' except the file `/tmp/foo', you can use the command `tar
--create --file=arch.tar --exclude=foo'.

   If there are many files you want to exclude, you can use the
`--exclude-from=FILE-OF-PATTERNS' (`-X FILE-OF-PATTERNS') option.  This
works just like the `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES')
option: specify the name of a file as EXCLUDE-LIST which contains the
list of patterns you want to exclude.

FIXME: xref Regular Expressions
   for more information on the syntax and meaning of regular
expressions.

Operating Only on New Files
---------------------------

     *(This message will disappear, once this node revised.)*

   The `--after-date=DATE' (`-N DATE') or `--newer=DATE' limits `tar'
to only operating on files which have been modified after the date
specified.  (For more information on how to specify a date,

FIXME: xref Date Formats
   .)  A file is considered to have changed if the contents have been
modified, or if the owner, permissions, and so forth, have been changed.

   If you only want `tar' make the date comparison on the basis of the
actual contents of the file's modification, then use the
`--newer-mtime=DATE' option.

   You should never use this option for making incremental dumps.  To
learn how to use `tar' to make backups,
FIXME: ref Making Backups
   .

Crossing Filesystem Boundaries
------------------------------

     *(This message will disappear, once this node revised.)*

   The `--one-file-system' (`-l') option causes `tar' to modify its
normal behavior in archiving the contents of directories.  If a file in
a directory is not on the same filesystem as the directory itself
(because it is a mounted filesystem in its own right), then `tar' will
not archive that file, or (if it is a directory itself) anything
beneath it.

   This does not necessarily limit `tar' to only archiving the contents
of a single filesystem, because all files named on the command line, or
through the `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option,
will always be archived.

Local file selection
====================

     *(This message will disappear, once this node revised.)*

   Local file selection

`-C DIR'
`--directory DIR'
     Change to directory DIR.

     This option causes `tar' to change into the directory DIR before
     continuing.  This option can be interspersed with the files `tar'
     is to work on.  For example,

          tar -c iggy ziggy -C baz melvin

     will place the files `iggy' and `ziggy' from the current directory
     on the tape, followed by the file `melvin' from the directory
     `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.

     Here, the file `melvin' is recorded in the archive under the
     precise name `melvin', *not* `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 `tar -x', all
     three files will be created in the current directory.

     Contrast this with the command:

          tar -c iggy ziggy bar/melvin

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

     Suppose that, without changing your current directory, you want to
     call `tar' to dump files from `/users/ctd/dipp' say.  Then
     `--directory=DIRECTORY' (`-C DIRECTORY') is for you.  You could do
     things like:

          tar cfC archive.tar /users/ctd/dipp .

     (the `.' means the current directory, once the
     `--directory=DIRECTORY' (`-C DIRECTORY') obeyed).

     Some people might want some option to extract everything from an
     archive in the current directory, ignore directory structure in
     the archive.  This is so rarely proper that I doubt such an option
     would be really useful.  It would only help getting around improper
     `tar' usage, it might even encourage improper usage.  In general,
     `--directory=DIRECTORY' (`-C DIRECTORY') might be used to produce
     archives with a cleaner structure in the first place.

`-T FILENAME'
`--files-from=FILENAME'
     Get names to extract or create from file 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 FILENAME.
     If FILENAME is given as `-', the list is read from standard input.
     Note that using both `-T -' and `-f -' will not work unless you
     are using the `--create' (`-c') command.

     This is typically useful when you have generated the list of files
     to archive with `find'.

`--null'
     This option causes `--files-from=FILE-OF-NAMES' (`-T
     FILE-OF-NAMES') to read file names terminated by a NUL instead of
     a newline, so files whose names contain newlines can be archived
     using `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES').  The
     `--null' option is just like the one in GNU `xargs' and `cpio',
     and is useful with the `-print0' predicate of GNU `find'.  In
     `tar', `--null' also causes `--directory=DIRECTORY' (`-C
     DIRECTORY') options to be treated as file names to archive, in
     case there are any files out there called `-C'.

`--exclude=FILE'
     Exclude file FILE.

`-X FILE'
`--exclude-from=FILE'
     Exclude files listed in FILE.

     This option causes `tar' to read a list of regular expressions (in
     shell wildcard syntax), one per line, from FILE; `tar' will ignore
     files matching those regular expressions.  Thus if `tar' is called
     as `tar -c -X foo .' and the file `foo' contains a single line
     `*.o', no files whose names end in `.o' will be added to the
     archive.  Multiple `--exclude=PATTERN' options may be given.

`-P'
`--absolute-names'
     Do not strip leading `/'s from file names.

     By default, GNU `tar' drops a leading `/' on input or output.
     This option turns off this behavior; it's equivalent to changing
     to the root directory before running `tar' (except it also turns
     off the usual warning message).

`-l'
`--one-file-system'
     Stay in local filesystem when creating archive.

     This option causes `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 filesystem, as with the Unix `dump' command.

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

`-K NAME'
`--starting-file=NAME'
     Begin at file NAME in the archive.

     The `--starting-file=NAME' (`-K NAME') option causes `tar' to begin
     extracting or listing the archive with the file 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 FILENAME due to lack of free space.  (Assuming, of
     course, that there is now free space, or that you are now
     extracting into a different file system.)

`-N DATE'
`--newer=DATE'
`--after-date=DATE'
     Only store files newer than DATE.

     This option causes `tar' to only work on files whose modification
     or inode-changed times are newer than the 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 must be quoted if it
     contains any spaces.

     The date is parsed using `getdate'.

   Changing the Names of Members when Archiving

Changing Directory
------------------

     *(This message will disappear, once this node revised.)*

   The `--directory=DIRECTORY' (`-C DIRECTORY') option causes `tar' to
change its current working directory to DIRECTORY.  Unlike most
options, this one is processed at the point it occurs within the list
of files to be processed.  Consider the following command:
     tar --create --file=foo.tar -C /etc passwd hosts -C /lib libc.a

   This command will place the files `/etc/passwd', `/etc/hosts', and
`/lib/libc.a' into the archive.  However, the names of the archive
members will be exactly what they were on the command line: `passwd',
`hosts', and `libc.a'.  The `--directory=DIRECTORY' (`-C DIRECTORY')
option is frequently used to make the archive independent of the
original name of the directory holding the files.

   Note that `--directory=DIRECTORY' (`-C DIRECTORY') options are
interpreted consecutively.  If `--directory=DIRECTORY' (`-C DIRECTORY')
option specifies a relative file name, it is interpreted relative to
the then current directory, which might not be the same as the original
current working directory of `tar', due to a previous
`--directory=DIRECTORY' (`-C DIRECTORY') option.

   When using `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') (
FIXME: pxref Reading Names from a File
   ), you can put `-C' options in the file list.  Unfortunately, you
cannot put `--directory' options in the file list.  (This interpretation
can be disabled by using the `--null' option.)

   Changing the Working Directory Within a List of File Names

     *(This message will disappear, once this node revised.)*

   To change working directory in the middle of a list of file names,
either on the command line or in a file specified using
`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES'), use
`--directory=DIRECTORY' (`-C DIRECTORY').  This will change the working
directory to the directory DIRECTORY after that point in the list.  For
example,

     tar --create iggy ziggy --directory=baz melvin

will place the files `iggy' and `ziggy' from the current directory into
the archive, followed by the file `melvin' from the directory `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 `melvin' is recorded in the archive under the
precise name `melvin', *not* `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 `tar --extract', all
three files will be written in the current directory.

   Contrast this with the command

     tar -c iggy ziggy bar/melvin

which records the third file in the archive under the name `bar/melvin'
so that, if the archive is extracted using `tar --extract', the third
file will be written in a subdirectory named `bar'.

`--directory=`directory''
`-C `directory''
     Changes the working directory.

FIXME: need to test how extract deals with this, and add an example

Absolute File Names
-------------------

     *(This message will disappear, once this node revised.)*

   When `tar' extracts archive members from an archive, it strips any
leading slashes (`/') from the member name.  This causes absolute
member names in the archive to be treated as relative file names.  This
allows you to have such members extracted wherever you want, instead of
being restricted to extracting the member in the exact directory named
in the archive.  For example, if the archive member has the name
`/etc/passwd', `tar' will extract it as if the name were really
`etc/passwd'.

   Other `tar' programs do not do this.  As a result, if you create an
archive whose member names start with a slash, they will be difficult
for other people with an inferior `tar' program to use.  Therefore, GNU
`tar' also strips leading slashes from member names when putting
members into the archive.  For example, if you ask `tar' to add the
file `/bin/ls' to an archive, it will do so, but the member name will
be `bin/ls'.

   If you use the `--absolute-names' (`-P') option, `tar' will do
neither of these transformations.

FIXME: is this what this does, or does it just preserve the slash?

   To archive or extract files relative to the root directory, specify
the `--absolute-names' (`-P') option.

   Normally, `tar' acts on files relative to the working
directory--ignoring superior directory names when archiving, and
ignoring leading slashes when extracting.

   When you specify `--absolute-names' (`-P'), `tar' stores file names
including all superior directory names, and preserves leading slashes.
If you only invoked `tar' from the root directory you would never need
the `--absolute-names' (`-P') option, but using this option may be more
convenient than switching to root.

FIXME: should be an example in the tutorial/wizardry section using this
FIXME: to transfer files between systems.

FIXME: is write access an issue?

`--absolute-names'
     Preserves full file names (inclusing superior dirctory names) when
     archiving files.  Preserves leading slash when extracting files.

Being Even More Careful
***********************

GNU `tar' documentation
=======================

   Being careful, the first thing is really checking that you are using
GNU `tar', indeed.  The `--version' option will generate a message
giving confirmation that you are using GNU `tar', with the precise
version of GNU `tar' you are using.  `tar' identifies itself and prints
the version number to the standard output, then immediately exits
successfully, without doing anything else, ignoring all other options.
For example, `tar --version' might return:

     GNU tar version 1.11.8

   Another thing you might want to do is checking the spelling or
meaning of some particular `tar' option, without resorting to this
manual, for once you have carefully read it.  GNU `tar' has a short help
feature, triggerable through the `--help' option.  By using this
option, `tar' will print a usage message listing all available options
on standard output, then exit successfully, without doing anything else
and ignoring all other options.  Even if this is only a brief summary,
it may be several screens long.  So, if you are not using some kind of
scrollable window, you might prefer to use something like:

     tar --help | less

presuming, here, that you like using `less' for a pager.  Other popular
pagers are `more' and `pg'.

   The perceptive reader would have noticed some contradiction in the
previous paragraphs.  It is written that both `--version' and `--help'
print something, and have all other options ignored.  In fact, they
cannot ignore each other, and one of them has to win.  We do not
specify which is stronger, here; experiment if you really wonder!

   The short help output is quite succint, and you might have to get
back to the full documentation for precise points.  If you are reading
this paragraph, you already have the `tar' manual in some form.  This
manual is available in printed form, as a kind of small book.  It may
printed out of the GNU `tar' distribution, provided you have TeX
already installed somewhere, and a laser printer around.  Just configure
the distribution, execute the command `make dvi', then print
`doc/tar.dvi' the usual way (contact your local guru to know how).  If
GNU `tar' has been conveniently installed at your place, this manual is
also available in interactive, hypertextual form as an Info file.  Just
call `info tar' or, if you do not have the `info' program handy, use
the Info reader provided within GNU Emacs, calling `tar' from the main
Info menu.

Checking `tar' progress
=======================

   Typically, `tar' performs most operations without reporting any
information to the user except error messages.  When using `tar' with
many options, particularly ones with complicated or
difficult-to-predict behavior, it is possible to make serious mistakes.
`tar' provides several options that make observing `tar' easier.  These
options cause `tar' to print information as it progresses in its job,
and you might want to use them just for being more careful about what
is going on, or merely for entertaining yourself.  If you have
encountered a problem when operating on an archive, however, you may
need more information than just an error message in order to solve the
problem.  The following options can be helpful diagnostic tools.

   Normally, the `--list' (`-t') command to list an archive prints just
the file names (one per line) and the other commands are silent.  When
used with most operations, the `--verbose' (`-v') option causes `tar'
to print the name of each file or archive member as it is processed.
This and the other options which make `tar' print status information
can be useful in monitoring `tar'.

   With `--create' (`-c') or `--extract' (`-x'), `--verbose' (`-v')
used once just prints the names of the files or members as they are
processed.  Using it twice causes `tar' to print a longer listing
(reminiscent of `ls -l') for each member.  Since `--list' (`-t')
already prints the names of the members, `--verbose' (`-v') used once
with `--list' (`-t') causes `tar' to print an `ls -l' type listing of
the files in the archive.  The following examples both extract members
with long list output:

     tar --extract --file=archive.tar --verbose --verbose
     tar xvv archive.tar

   Verbose output appears on the standard output except when an archive
is being written to the standard output, as with `tar --create --file=-
--verbose' (`tar cfv -', or even `tar cv'--if the installer let
standard output be the default archive).  In that case `tar' writes
verbose output to the standard error stream.

   The `--totals' option--which is only meaningful when used with
`--create' (`-c')--causes `tar' to print the total amount written to
the archive, after it has been fully created.

   The `--checkpoint' option prints an occasional message as `tar'
reads or writes the archive.  In fact, it print directory names while
reading the archive.  It is designed for those who don't need the more
detailed (and voluminous) output of `--record-number' (`-R'), but do
want visual confirmation that `tar' is actually making forward progress.
FIXME: There is some confusion here.  It seems that -R once wrote a
FIXME: message at `every' block read or written.

   The `--show-omitted-dirs' option, when reading an archive--with
`--list' (`-t') or `--extract' (`-x'), for example--causes a message to
be printed for each directory in the archive which is skipped.  This
happens regardless of the reason for skipping: the directory might not
have been named on the command line (implicitly or explicitly), it
might be excluded by the use of the `--exclude=PATTERN' option, or some
other reason.

   If `--record-number' (`-R') is used, `tar' prints, along with every
message it would normally produce, the record number within the archive
where the message was triggered.  This option is especially useful when
reading damaged archives, since it helps pinpoint the damaged sections.
It can also be used with `--list' (`-t') when listing a file-system
backup tape, allowing you to choose among several backup tapes when
retrieving a file later, in favor of the tape where the file appears
earliest (closest to the front of the tape).
FIXME: xref when the node name is set and the backup section written

Asking for Confirmation During Operations
=========================================

   Typically, `tar' carries out a command without stopping for further
instructions.  In some situations however, you may want to exclude some
files and archive members from the operation (for instance if disk or
storage space is tight).  You can do this by excluding certain files
automatically (
FIXME: pxref File Exclusion
   ), or by performing an operation interactively, using the
`--interactive' (`-w') option.  `tar' also accepts `--confirmation' for
this option.

   When the `--interactive' (`-w') option is specified, before reading,
writing, or deleting files, `tar' first prints a message for each such
file, telling what operation it intends to take, then asks for
confirmation on the terminal.  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.  To confirm the action, you must type a line of input beginning
with `y'.  If your input line begins with anything other than `y',
`tar' skips that file.

   If `tar' is reading the archive from the standard input, `tar' opens
the file `/dev/tty' to support the interactive communications.

Verifying Data as It is Stored
==============================

   You can insure the accuracy of an archive by comparing files in the
system with archive members.  `tar' can compare an archive to the file
system as the archive is being written, to verify a write operation, or
can compare a previously written archive, to insure that it is up to
date.

   To check for discrepancies in an archive immediately after it is
written, use the `--verify' (`-W') option in conjunction with the
`--create' (`-c') operation.  When this option is specified, `tar'
checks archive members against their counterparts in the file system,
and reports discrepancies on the standard error.  In multi-volume
archives, each volume is verified after it is written, before the next
volume is written.

   To verify an archive, you must be able to read it from before the end
of the last written entry.  This option is useful for detecting data
errors on some tapes.  Archives written to pipes, some cartridge tape
drives, and some other devices cannot be verified.

Comparing an Archive with the File System
=========================================

     *(This message will disappear, once this node revised.)*

   `--compare' (`-d') compares archive members in an existing archive
with their counterparts in the file system, and reports differences in
file size, mode, owner, modification date and contents.  If a file is
represented in the archive but does not exist in the file system, `tar'
reports a difference.

   If you use FILE NAME arguments in conjunction with `tar --compare',
`tar' compares the archived versions of the files specified with their
counterparts in the file system.  If you specify a file that is not in
the archive, `tar' will report an error.  If you don't specify any
files, `tar' compares all the files in the archive.

   Because `tar' only checks files in the archive against files in the
file system, and not vice versa, it ignores files in the file system
that do not exist in the archive.

   The following example compares the archive members `larry', `moe'
and `curly' in the archive `stooges' with files of the same name in the
file system.

     tar --compare --file=stooges larry moe curly

If a file, for example `curly', did not exist in the archive, `tar'
would report an error, as follows:

     curly: does not exist

Making `tar' Archives More Portable
===================================

   Creating a `tar' archive on a particular system, meant to be later
useful on many other machines and with other versions of `tar', is more
a challenge than you might think.  `tar' archive formats evolved since
the first versions of Unix, many such formats are flying around, not
always comptabile between them.  This section wants to discuss a few
problems, and give some advice, for making `tar' archives more portable.

   One golden rule is simplicity.  For example, limit your `tar'
archives to contain only regular files and directories, avoiding other
kind of special files.  Do not attempt to save sparse files or
contiguous files as such.  Let's discuss a few more problems, in turn.

Portable Names
--------------

   Use *straight* file and directory names, made up of printable ASCII
characters, avoiding colons, slashes, backslashes, and other
*dangerous* characters.  Avoid deep directory nesting.  Accounting for
oldish System V machines, limit your file and directory names to 14
characters or less.

   If you intend to have your `tar' archives to be read under MSDOS,
you should not rely on case distinction for file names, and you might
use the GNU `doschk' program for helping you further diagnosing illegal
MSDOS names, which are even more limited than System V's.

Symbolic Links
--------------

   Normally, when `tar' archives a symbolic link, it writes a record to
the archive naming the target of the link.  In that way, the `tar'
archive is a faithful record of the filesystem contents.
`--dereference' (`-h') is used with `--create' (`-c'), and causes `tar'
to archive the files symbolic links point to, instead of the links
themselves.  When this option is used, when `tar' encounters a symbolic
link, it will archive the linked-to file, instead of simply recording
the presence of a symbolic link.

   The name under which the file is stored in the file system is not
recorded in the archive.  To record both the symbolic link name and the
file name in the system, archive the file under both names.  If all
links were recorded automatically by `tar', an extracted file might be
linked to a file name that no longer exists in the file system.

   If a linked-to file is encountered again by `tar' while creating the
same archive, an entire second copy of it will be stored.  (This
*might* be considered a bug.)

   So, for portable archives, do not archive symbolic links as such,
and use `--dereference' (`-h'): many systems do not support symbolic
links, and moreover, your distribution might be unusable if it contains
unresolved symbolic links.

Old V7 and POSIX Archives
-------------------------

   GNU `tar' implements an early draft of the POSIX 1003.1 `ustar'
standard which is different from the final standard.  Adding support
for the new changes in a backward-compatible fashion is not trivial.

   Certain old versions of `tar' cannot handle additional information
recorded by newer `tar' programs.  To create an archive in V7 format
(not ANSI), which can be read by these old versions, specify the
`--old-archive' (`-o') option in conjunction with the `--create'
(`-c').  `tar' also accepts `--portability' for this option.  When you
specify it, `tar' leaves out information about directories, pipes,
fifos, contiguous files, and device files, and specifies file ownership
by group and user IDs instead of group and user names.

   When updating an archive, do not use `--old-archive' (`-o') unless
the archive was created with using this option.

   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.  On the other hand, most modern `tar's are able to read old
format archives, so it might be safer for you to always use
`--old-archive' (`-o') for your distributions.