Geek Gadgets 1/ADE-1.bin/ade-bin/info/tar.info-3

GNU Info File | 1996-10-12 | 48.4 KB | 1,521 lines

This is Info file tar.info, produced by Makeinfo-1.64 from the input
file /ade-src/fsf/tar/doc/tar.texinfo.

START-INFO-DIR-ENTRY
* tar: (tar).            Making tape (or disk) archives.
END-INFO-DIR-ENTRY

   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.


File: tar.info,  Node: Old Options,  Next: Mixing Styles,  Prev: Short Options,  Up: Option Styles

Old Option Style
----------------

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

   Old options are single letters not preceeded by any dash at all, and
appearing *only* in the position immediately following the `tar'
keyword in the command, after some white space.  The letter of an old
option is exactly the same letter as the corresponding short option.
For example, the old option `t' is the same as the short option `-t',
and consequently, the same as long option `--list' (`-t').

   As far as we know, all `tar' programs, GNU and non-GNU, support old
options.  GNU `tar' supports them not only for historical reasons, but
also because many people are used to them.

   All old options should be written as a single argument, without
separating spaces, by lumping together all letters specifying these
options.  This set of letters should be the first to appear on the
command line, after the `tar' program name; old options cannot appear
anywhere else.  Then, for any old option required an argument, the
argument should follow on the command line.  Arguments to the options
should appear in the same order as the letters to which they
correspond.  The `tar' command synopsis might be rewritten:

     tar LETTER... [ARGUMENT]... [OPTION]... [NAME]...

when old options are being used.

   This command syntax is useful because it lets you type the single
letter forms of the operation and options as a single argument to `tar',
without writing preceding `-'s or inserting spaces between letters.
`tar cv' or `tar -cv' are equivalent to `tar -c -v'.

   For compatibility with Unix `tar', the first argument can contain an
option letter (or a cluster of option letters) *not* introduced by a
dash; for example, `tar cv' specifies the option `-v' in addition to
the command `-c'.  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:

     tar cvbf 20 /dev/rmt0

Here `20' is the argument of `-b' and `/dev/rmt0' is the argument of
`-f'.

   On the other hand, this old style syntax makes it difficult to match
option letters with their corresponding arguments, and is often
confusing.  In the command `tar cvbf 20 /dev/rmt0', for example, `20'
is the argument for `-b', `/dev/rmt0' is the argument for `-f', and
`-v' does not have a corresponding argument.  Even using short options
like in `tar -c -v -b 20 -f /dev/rmt0' is clearer, putting all
arguments next to the option they pertain to.

   If you want to reorder the letters in the old option argument, be
sure to appropriately reorder any corresponding argument.

   This old way of writing `tar' options can surprise even experienced
users.  For example, the two commands:

     tar cfz archive.tar.gz file
     tar -cfz archive.tar.gz file

are quite different.  The first example uses `archive.tar.gz' as the
value for option `f' and recognizes the option `z'.  The second
example, however, uses `z' as the value for option `f'--probably not
what was intended.  (I find it quite inelegant that `getopt' batches
the remaining `z' as the value for `f'.  I think that clarity dictates
that clustering of option letters, when some require arguments, should
be diagnosed and disallowed.  But compatibility with traditional
systems dictates it.) This second example could be corrected in many
ways, among which:

     tar -czf archive.tar.gz file
     tar -cf archive.tar.gz -z file
     tar cf archive.tar.gz -z file


File: tar.info,  Node: Mixing Styles,  Prev: Old Options,  Up: Option Styles

Mixing Option Styles
--------------------

   All three styles may be intermixed in a single `tar' command, as
long as the rules for each style are fully respected.

   In GNU `tar' up to 1.11.6, using old style options was cutting out
the possibility of using many options not having short forms.  Many
users rightly expressed their frustration at fighting with the current
`tar' option decoder, so I changed it.  However, GNU `tar' needs to be
compatible with other `tar's, in the things that other `tar's can do.
Short options should provide upward compatibility.  So, if the current
option decoding raises incompatibilities, please let me know.

   Old style options and modern options may be mixed on a single call
to the `tar' program.  However, old style options should be introduced
in the first argument only; modern options may be given only after all
arguments to old style options have been collected.  If this rule is
not respected, a modern option might be falsely interpreted as the
value of the argument to one of the old style options.

   For example, currently, all the following commands are wholly
equivalent, and illustrate many combinations and orderings of option
styles.

     tar --create --file=archive.tar
     tar --create -f archive.tar
     tar --create -farchive.tar
     tar --file=archive.tar --create
     tar --file=archive.tar -c
     tar -c --file=archive.tar
     tar -c -f archive.tar
     tar -c -farchive.tar
     tar -cf archive.tar
     tar -cfarchive.tar
     tar -f archive.tar --create
     tar -f archive.tar -c
     tar -farchive.tar --create
     tar -farchive.tar -c
     tar c --file=archive.tar
     tar c -f archive.tar
     tar c -farchive.tar
     tar cf archive.tar
     tar f archive.tar --create
     tar f archive.tar -c
     tar fc archive.tar

   On the other hand, the following commands are *not* equivalent to
the previous set:

     tar -f -c archive.tar
     tar -fc archive.tar
     tar -fcarchive.tar
     tar -farchive.tarc
     tar cfarchive.tar

These last examples mean something completely different of what the user
might have intended.  The first four specify that the `tar' archive
would be a file named `-c', `c', `carchive.tar' or `archive.tarc',
respectively.  The first two examples also specify a single non-option,
NAME argument having value `archive.tar'.  The last example contains
only old style option letters (repeating option `c' twice) and no
argument value.


File: tar.info,  Node: Options,  Prev: Option Styles,  Up: Invoking tar

All Available Options
=====================

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

   Options change the way `tar' performs an operation.

`--absolute-names'
`--after-date=DATE'
     Limit the operation to files changed after the given date.

     FIXME: xref File Exclusion
     .

`--block-size=NUMBER'
     Specify the blocking factor of an archive.
     FIXME: xref Blocking Factor
     .

`--compress'
     Specify a compressed archive.
     FIXME: xref Compressed Archives
     .

`--compress-block.'
     Create a whole block sized compressed archive.
     FIXME: xref Compressed Archives
     .

`--confirmation'
     Solicit confirmation for each file.
     FIXME: xref Interactive Operation

     FIXME: --selective should be a synonym.

`--dereference'
     Treat a symbolic link as an alternate name for the file the link
     points to.
     FIXME: xref Symbolic Links
     .

`--directory=`directory''
     Change the working directory.
     FIXME: xref Changing Working Directory
     .

`--exclude=PATTERN'
     Exclude files which match the regular expression PATTERN.

     FIXME: xref File Exclusion
     .

`--exclude-from=`file''
     Exclude files which match any of the regular expressions listed in
     the file `file'.
     FIXME: xref File Exclusion
     .

`--file=ARCHIVE-NAME'
     Name the archive.
     FIXME: xref Archive Name
     ).

`--files-from=`file''
     Read file name arguments from a file on the file system.

     FIXME: xref File Name Lists
     .

`--ignore-umask'
     Set modes of extracted files to those recorded in the archive.

     FIXME: xref File Writing Options
     .

`--ignore-zeros'
     Ignore end-of-archive entries.
     FIXME: xref Archive Reading Options
     .
     FIXME: this should be changed to --ignore-end

`--tape-length=N  (-L)'
     FIXME: alternate way of doing multi archive, will go to that length and
     FIXME: prompts for new tape, automatically turns on multi-volume.  this
     FIXME: needs to be written into main body as well

`--info-script=PROGRAM-FILE'
     Create a multi-volume archive via a script.
     FIXME: xref Multi-Volume Archives
     .

`--interactive'
     Ask for confirmation before performing any operation on a file or
     archive member.

`--keep-old-files'
     Prevent overwriting during extraction.
     FIXME: xref File Writing Options
     .

`--label=ARCHIVE-LABEL'
     Include an archive-label in the archive being created.
     FIXME: xref Archive
     Label
     .

`--modification-time'
     Set the modification time of extracted files to the time they were
     extracted.
     FIXME: xref File Writing Options
     .

`--multi-volume'
     Specify a multi-volume archive.
     FIXME: xref Multi-Volume Archives
     .

`--newer=DATE'
     Limit the operation to files changed after the given date.

     FIXME: xref File Exclusion
     .

`--newer-mtime=DATE'
     Limit the operation to files modified after the given date.
     FIXME: xref File
     Exclusion
     .

`--old'
     Create an old format archive.
     FIXME: xref Old Style File Information
     .
     FIXME: did we agree this should go away as a synonym?

`--old-archive'
     Create an old format archive.
     FIXME: xref Old Style File Information
     .

`--one-file-system'
     Prevent `tar' from crossing file system boundaries when archiving.
     FIXME: xref File Exclusion
     .

`--portability'
     Create an old format archive.
     FIXME: xref Old Style File Information
     .
     FIXME: was portability, may still need to be changed

`--preserve-order'
     Help process large lists of file names on machines with small
     amounts of memory.
     FIXME: xref Archive Reading Options
     .

`--preserve-permission'
     Set modes of extracted files to those recorded in the archive.

     FIXME: xref File Writing Options
     .

`--read-full-blocks'
     Read an archive with a smaller than specified block size or which
     contains incomplete blocks.
     FIXME: xref Archive Reading Options
     ).
     FIXME: should be --partial-blocks (!)

`--record-number'
     Print the record number where a message is generated.

     FIXME: xref Additional Information
     .

`--same-order'
     Help process large lists of file names on machines with small
     amounts of memory.
     FIXME: xref Archive Reading Options
     .

`--same-permission'
     Set the modes of extracted files to those recorded in the archive.

     FIXME: xref File Writing Options
     .

`--sparse'
     Archive sparse files sparsely.
     FIXME: xref Sparse Files
     .

`--starting-file=FILE NAME'
     Begin reading in the middle of an archive.
     FIXME: xref Scarce Disk Space
     .

`--to-stdout'
     Write files to the standard output.
     FIXME: xref File Writing Options
     .

`--uncompress'
     Specifdo  a compressed archive.
     FIXME: xref Compressed Archives
     .

`-V ARCHIVE-LABEL'
     Include an archive-label in the archive being created.
     FIXME: xref Archive
     Label
     .
     FIXME: was --volume

`--verbose'
     Print the names of files or archive members as they are being
     operated on.
     FIXME: xref Additional Information
     .

`--verify'
     Check for discrepancies in the archive immediately after it is
     written.
     FIXME: xref Write Verification
     .

`-B'
     Read an archive with a smaller than specified block size or which
     contains incomplete blocks.
     FIXME: xref Archive Reading Options
     ).

`-K FILE NAME'
     Begin reading in the middle of an archive.
     FIXME: xref Scarce Disk Space
     .

`-M'
     Specify a multi-volume archive.
     FIXME: xref Multi-Volume Archives
     .

`-N DATE'
     Limit operation to files changed after the given date.
     FIXME: xref File Exclusion
     .

`-O'
     Write files to the standard output.
     FIXME: xref File Writing Options
     .

     FIXME: - P is absolute names, add when resolved.

`-R'
     Print the record number where a message is generated.

     FIXME: xref Additional Information
     .

`-S'
     Archive sparse files sparsely.
     FIXME: xref Sparse Files
     .

`-T FILE'
     Read file name arguments from a file on the file system.

     FIXME: xref File Name Lists
     .

`-W'
     Check for discrepancies in the archive immediately after it is
     written.
     FIXME: xref Write Verification
     .

`-Z'
     Specify a compressed archive.
     FIXME: xref Compressed Archives
     .

`-b NUMBER'
     Specify the blocking factor of an archive.
     FIXME: xref Blocking Factor
     .

`-f ARCHIVE-NAME'
     Name the archive.
     FIXME: xref Archive Name
     ).

`-h'
     Treat a symbolic link as an alternate name for the file the link
     points to.
     FIXME: xref Symbolic Links
     .

`-i'
     Ignore end-of-archive entries.
     FIXME: xref Archive Reading Options
     .

`-k'
     Prevent overwriting during extraction.
     FIXME: xref File Writing Options
     .

`-l'
     Prevent `tar' from crossing file system boundaries when archiving.
     FIXME: xref File Exclusion
     .

`-m'
     Set the modification time of extracted files to the time they were
     extracted.
     FIXME: xref File Writing Options
     .

`-o'
     Create an old format archive.
     FIXME: xref Old Style File Information
     .

`-p'
     Set the modes of extracted files to those recorded in the archive.

     FIXME: xref File Writing Options
     .

`-s'
     Help process large lists of file names on machines with small
     amounts of memory.
     FIXME: xref Archive Reading Options
     .

`-v'
     Print the names of files or archive members they are being operated
     on.
     FIXME: xref Additional Information
     .

`-w'
     FIXME: see --interactive.

`-z'
     Specify a compressed archive.
     FIXME: xref Compressed Archives
     .

`-z -z'
     Create a whole block sized compressed archive.
     FIXME: xref Compressed Archives
     .
     FIXME: I would rather this were -Z.  it is the only double letter short
     FIXME: form.

`-C `directory''
     Change the working directory.
     FIXME: xref Changing Working Directory
     .

`-F PROGRAM-FILE'
     Create a multi-volume archive via a script.
     FIXME: xref Multi-Volume Archives
     .

`-X `file''
     Exclude files which match any of the regular expressions listed in
     the file `file'.
     FIXME: xref File Exclusion
     .

* Menu:

* Device Options::
* Blocking Options::
* Classification Options::


File: tar.info,  Node: Device Options,  Next: Blocking Options,  Prev: Options,  Up: Options

Device selection and switching
------------------------------

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

`-f [HOSTNAME:]FILE'
`--file=[HOSTNAME:]FILE'
     Use archive file or device FILE on HOSTNAME.
     FIXME: xref Device
     .

`--force-local'
     Archive file is local even if it contains a colon.
     FIXME: xref Device
     .

`--rsh-command=COMMAND'
     Use remote COMMAND instead of `rsh'.
     FIXME: xref Device
     .

`-[0-7][lmh]'
     Specify drive and density.
     FIXME: xref Device
     .

`-M'
`--multi-volume'
     Create/list/extract multi-volume archive.
     FIXME: xref Multi
     .

`-L NUM'
`--tape-length=NUM'
     Change tape after writing NUM x 1024 bytes.
     FIXME: xref Multi
     .

`-F FILE'
`--info-script=FILE'
`--new-volume-script=FILE'
     Execute `file' at end of each tape.  This implies `--multi-volume'
     (`-M')).
     FIXME: xref Multi
     .


File: tar.info,  Node: Blocking Options,  Next: Classification Options,  Prev: Device Options,  Up: Options

Device blocking
---------------

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

`-b BLOCKS'
`--block-size=BLOCKS'
     Set block size to BLOCKS * 512 bytes.
     FIXME: xref Blocking
     .

`--block-compress'
     Block the output of compression for tapes.
     FIXME: xref Blocking
     .

`-i'
`--ignore-zeros'
     Ignore blocks of zeros in archive (means EOF).
     FIXME: xref Blocking
     .

`-B'
`--read-full-blocks'
     Reblock as we read (for reading 4.2BSD pipes).
     FIXME: xref Blocking
     .


File: tar.info,  Node: Classification Options,  Prev: Blocking Options,  Up: Options

Old classification of options
-----------------------------

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

   The information here is to be revised and merged into the remainder
of this document, possibly altering its structure.

   Options could be regrouped in three categories:

General Options
     Options that are always meaningful.

Creation Options
     Options for creating or updating an archive.

Extraction Options
     Options for listing or extracting files.

   Here are the options that are always meaningful.

`-B NUMBER', `--block-size NUMBER'
`-f FILENAME', `--file FILENAME'
`-C DIR', `--directory DIR'
`-M', `--multi-volume'
`-N DATE', `--after-date DATE'
`-R', `--record-number' (`-R')
`-T FILENAME', `--files-from FILENAME'
`-v', `--verbose' (`-v')
`-w', `--interactive'
`-X FILE', `--exclude FILE'
`-z', `-Z', `--compress', `--uncompress'
   Here are the options for creating or updating an archive.  These
options are used to control which files `tar' puts in an archive, or to
control the format the archive is written in
FIXME: ref Format
   .  Except as noted elsewhere, these options are useful with the
`--create' (`-c'), `--append' (`-r'), `--update' (`-u'),
`--concatenate' (`-A'), and `--delete' commands.  Also note that the
{No Value For "read-full-block"} option
FIXME: (pxref Extraction Options),
   is also useful with the `--append' (`-r'), `--update' (`-u'),
`--concatenate' (`-A'), and `--delete' commands.

`-G', `--incremental'
`-h', `--dereference' (`-h')
`-l', `--one-file-system'
`-o', `--old-archive' (`-o')
`--old', `--portability'
`-S', `--sparse'
`-V NAME', `--volume NAME'
`-W', `--verify'
   Here are the options for listing or extracting files.  The options
in this section are meaningful with the `--extract' (`-x') command.
Unless otherwise stated, they are also meaningful with the `--list'
(`-t') command.

`-B', `--read-full-blocks'
`-G', `--incremental'
`-i', `--ignore-zeros'
`-k', `--keep-old-files'
`-K FILENAME', `--starting-file FILENAME'
`-m', `--modification-time'
`-O', `--to-stdout'
`-p', `--same-permissions', `--preserve-permissions'
`-P', `--absolute-names' (`-P')
`-s', `--same-order', `--preserve-order'
`--preserve'

File: tar.info,  Node: Basic tar Operations,  Next: Specifying Names to tar,  Prev: Invoking tar,  Up: Top

Basic `tar' Operations
**********************

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

   This chapter describes the basic operations supported by the `tar'
program.  A given invocation of `tar' will do exactly one of these
operations.

   An archive member in normally extracted into a file with the same
name as the archive member.  However, you can use the `--to-stdout'
(`-O') to cause `tar' to write extracted archive members to standard
output.  If you extract multiple members, they appear on standard output
concatenated, in the order they are found in the archive.

   The `--create' (`-c') operation writes a new archive, and the
`--extract' (`-x') operation reads files from an archive and writes them
into the file system.  You can use other `tar' operations to write new
information into an existing archive (adding files to it, adding
another archive to it, or deleting files from it), and you can read a
list of the files in an archive without extracting it using the
`--list' (`-t') operation.

   The primary argument to `tar' is the "operation", which specifies
what `tar' does.  `tar' can be used to:

   * Add files to an existing archive--`--append' (`-r').

   * Compare files in an archive with files in the file
     system--`--compare' (`-d') or `--diff'.

   * Add archives to another archive--`--concatenate' (`-A').

   * Create an archive--`--create' (`-c').

   * Delete files from an archive--`--delete'.

   * Extract files from an archive--`--extract' (`-x') or `--get'.

   * List the files in an archive--`--list' (`-t').

   * Update an archive by appending newer versions of already stored
     files--`--update' (`-u').

FIXME: xref Reading and Writing
   , for more information about these operations.

   "Option" arguments to `tar' change details of the operation, such as
archive format, archive name, or level of user interaction. You can
specify more than one option.  All options are optional.

   "File Name" arguments specify which files (including directory
files) to archive, extract, delete or otherwise operate on.

   If you don't use any file name arguments, `--append' (`-r'),
`--update' (`-u') and `--delete' will do nothing.  The other operations
of `tar' will act on defaults.

   When you use a file name argument to specify a directory file, `tar'
acts on all the files in that directory, including sub-directories.

   You must give exactly one option from the following list to `tar'.
This option specifies the basic operation for `tar' to perform.

`--create'
`-c'
     Create a new archive

`--catenate'
`--concatenate'
`-A'
     Add the contents of one or more archives to another archive

`--append'
`-a'
     Add files to an existing archive

`--list'
`-t'
     List the members in an archive

`--delete'
     Delete members from an archive

`--extract'
`--get'
`-x'
     Extract members from an archive

`--compare'
`--diff'
`-d'
     Compare members in an archive with files in the file system

`--update'
`-u'
     Update an archive by appending newer versions of already stored
     files

   The remaining options to `tar' change details of the operation, such
as archive format, archive name, or level of user interaction.  You can
specify more than one option.

   The remaining arguments are interpreted either as file names or as
member names, depending on the basic operation `tar' is performing.
For `--append' (`-r') and `--create' (`-c') these arguments specify the
names of files (which must already exist) to place in the archive.  For
the remaining operation types, the additional arguments specify archive
members to compare, delete, extract, list, or update.  When naming
archive members, you must give the exact name of the member in the
archive, as it is printed by `--list' (`-t').  When naming files, the
normal file name rules apply.

   If you don't use any additional arguments, `--append' (`-r'),
`--concatenate' (`-A'), and `--delete' will do nothing.  Naturally,
`--create' (`-c') will make an empty archive if given no files to add.
The other operations of `tar' (`--list' (`-t'), `--extract' (`-x'),
`--compare' (`-d'), and `--update' (`-u')) will act on the entire
contents of the archive.

   If you give the name of a directory as either a file name or a member
name, then `tar' acts recursively on all the files and directories
beneath that directory.  For example, the name `/' identifies all the
files in the filesystem to `tar'.

   The operation argument to `tar' specifies which action you want to
take.

`-A'
     Adds copies of an archive or archives to the end of another
     archive.

`-c'
     Creates a new archive.

`-d'
     Compares files in the archive with their counterparts in the file
     system, and reports differences in file size, mode, owner,
     modification date and contents.

`-r'
     Adds files to the end of the archive.

`-t'
     Prints a list of the contents of the archive.

`-x'
     Reads files from the archive and writes them into the active file
     system.

`-u'
     Adds files to the end of the archive, but only if they are newer
     than their counterparts already in the archive, or if they do not
     already exist in the archive.

`--catenate'
     Adds copies of an archive or archives to the end of another
     archive.

`--append'
     Adds files to the end of the archive.

`--append'
     Adds files to the end of the archive.

`--catenate'
     Adds copies of an archive or archives to the end of another
     archive.

`--compare'
     Compares files in the archive with their counterparts in the file
     system, and reports differences in file size, mode, owner,
     modification date and contents.

`--concatenate'
     Adds copies of an archive or archives to the end of another
     archive.

`--create'
     Creates a new archive.

`--delete'
     Deletes files from the archive.  All versions of the files are
     deleted.

`--diff'
     Compares files in the archive with their counterparts in the file
     system, and reports differences in file size, mode, owner,
     modification date and contents.

`--extract'
     Reads files from the archive and writes them into the active file
     system.

`--get'
     Reads files from the archive and writes them into the active file
     system.

`--list'
     Prints a list of the contents of the archive.

`--update'
     Adds files to the end of the archive, but only if they are newer
     than their counterparts already in the archive, or if they do not
     already exist in the archive.

`--version'
     Prints the version number of the `tar' program to the standard
     error.

   The program `tar' can create an archive, extract files from an
archive, modify an archive, or list an archive's contents.  Each time
you run `tar', you must give a "command" to specify which one of these
things you want to do.

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

   In addition, a set of long-named options are provided which can be
used instead of or intermixed 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 begin
with `--'.

   Arguments after the first are either options, if they start with `-'
or `--', or files to operate on.

   The file names that you give as arguments are the files that `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 (recursively) in it are used.

   Here is a list of the `tar' commands:

`-c'
`--create'
     Create a new archive.

     This command tells `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.

`-x'
`--extract'
`--get'
     Extract files from an archive.

     This command causes `tar' to extract the specified files from the
     archive.  If no file names are given, all the files in the archive
     will be extracted.

`-t'
`--list'
     List the contents of an archive.

     This command causes `tar' to display a list of the files in the
     archive.  If you specify file names, only the files that you
     specify will be mentioned (but each of them is mentioned only if it
     appears in the archive).

`-d'
`--diff'
`--compare'
     Find differences between an archive and the corresponding online
     files.

     This command causes `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, `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.

`-r'
`--append'
     Append files to the end of an archive.

     This command causes `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 `tar' program).  If the archive is not in a
     format that `tar' understands, the results will be unpredictable.

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

`-u'
`--update'
     Only append files newer than the version in an archive.

     This command causes `tar' to add the specified files to the end of
     the archive, like `--append' (`-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.

`-A'
`--catenate'
`--concatenate'
     Append existing archives to another archive.

     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 the archive
     file which `tar' works on.  (The other files are not changed).

     You might be tempted to use `cat' for this, but it won't ordinarily
     work.  A `tar' archive contains data which indicates the end of the
     archive, so appended material is ignored.  This command works
     because it removes the end-of-archive markers from the middle of
     the result.

`--delete'
     Delete from the archive (not on tapes!).

     This command causes `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.

   The program `tar' can create an archive, extract files from an
archive, modify an archive, or list an archive's contents.  Each time
you run `tar', you must give a "command" to specify which one of these
things you want to do.

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

   In addition, a set of long-named options are provided which can be
used instead of or intermixed 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 begin
with `--'.

   Arguments after the first are either options, if they start with `-'
or `--', or files to operate on.

   The file names that you give as arguments are the files that `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 (recursively) in it are used.

   Modifying Archives

   Once an archive is created, you can add new archive members to it,
add the contents of another archive, add newer versions of members
already stored, or delete archive members already stored.

   To find out what files are already stored in an archive, use `tar
--list --file=ARCHIVE-NAME'.
FIXME: xref Listing Contents
   .

* Menu:

* Creating a New Archive::
* Adding to an Existing Archive::
* Updating an Archive::
* Combining Archives::
* Removing Archive Members::
* Listing Archive Members::
* Extracting Archive Members::
* Comparing Archives Members with Files::
* Matching Format Parameters::


File: tar.info,  Node: Creating a New Archive,  Next: Adding to an Existing Archive,  Prev: Basic tar Operations,  Up: Basic tar Operations

Creating a New Archive
======================

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

   The `--create' (`-c') option causes `tar' to create a new archive.
The files to be archived are then named on the command line.  Each file
will be added to the archive with a member name exactly the same as the
name given on the command line.  (When you give an absolute file name
`tar' actually modifies it slightly,
FIXME: ref Absolute
Names
   .)  If you list no files to be archived, then an empty archive is
created.

   If there are two many files to conveniently list on the command line,
you can list the names in a file, and `tar' will read that file.

FIXME: xref Reading Names from a File
   .

   If you name a directory, then `tar' will archive not only the
directory, but all its contents, recursively.  For example, if you name
`/', then `tar' will archive the entire filesystem.

   Do not use the option to add files to an existing archive; it will
delete the archive and write a new one.  Use `--append' (`-r') instead.
(
FIXME: xref Adding to an Existing Archive
   .)

   There are various ways of causing `tar' to skip over some files, and
not archive them.
FIXME: xref Specifying Names to tar
   .

FIXME: operations should probably have examples, not tables.

   To create an archive, use `--create' (`-c').  To name the archive,
use `--file=ARCHIVE-NAME' in conjunction with the `--create' (`-c')
operation (
FIXME: pxref Archive Name
   ).  If you do not name the archive, `tar' uses the value of the
environment variable `TAPE' as the file name for the archive, or, if
that is not available, `tar' uses a default archive name, usually that
for tape unit zero.
FIXME: xref Archive Name
   , for more information about specifying an archive name.

   The following example creates an archive named `stooges', containing
the files `larry', `moe' and `curley':

     tar --create --file=stooges larry moe curley

   If you specify a directory name as a file name argument, `tar' will
archive all the files in that directory.  The following example creates
an archive named `hail/hail/fredonia', containing the contents of the
directory `marx':

     tar --create --file=hail/hail/fredonia marx

   If you don't specify files to put in the archive, `tar' archives all
the files in the working directory.  The following example creates an
archive named `home' containing all the files in the working directory:

     tar --create --file=home

FIXME: xref File Name Lists
   , for other ways to specify files to archive.

   Note: In the example above, an archive containing all the files in
the working directory is being written to the working directory.  GNU
`tar' stores files in the working directory in an archive which is
itself in the working directory without falling into an infinite loop.
Other versions of `tar' may fall into this trap.


File: tar.info,  Node: Adding to an Existing Archive,  Next: Updating an Archive,  Prev: Creating a New Archive,  Up: Basic tar Operations

Adding to an Existing Archive
=============================

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

   The `--append' (`-r') option will case `tar' to add new files to an
existing archive.  It interprets file names and member names in exactly
the same manner as `--create' (`-c').  Nothing happens if you don't
list any names.

   This option never deletes members.  If a new member is added under
the same name as an existing member, then both will be in the archive,
with the new member after the old one.  For information on how this
affects reading the archive,
FIXME: ref Multiple Members with the Same Name
   .

   This operation cannot be performed on some tape drives,
unfortunately, due to deficiencies in the formats thoes tape drives use.

   To add files to an archive, use `--append' (`-r').  The archive to
be added to must already exist and be in proper archive format (which
normally means it was created previously using `tar').  If the archive
was created with a different block size than now specified, `tar' will
report an error (
FIXME: pxref Blocking Factor
   ).  If the archive is not a valid `tar' archive, the results will be
unpredictable.  You cannot add files to a compressed archive, however
you can add files to the last volume of a multi-volume archive.

FIXME: xref Matching Format Parameters
   .

   The following example adds the file `shemp' to the archive `stooges'
created above:

     tar --append --file=stooges shemp

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

   `--update' (`-u') acts like `--append' (`-r'), but does not add
files to the archive if there is already a file entry with that name in
the archive that has the same modification time.

   Both `--update' (`-u') and `--append' (`-r') work by adding to the
end of the archive.  When you extract a file from the archive, only the
version stored last will wind up in the file system.  Because
`--extract' (`-x') extracts files from an archive in sequence, and
overwrites files with the same name in the file system, if a file name
appears more than once in an archive the last version of the file will
overwrite the previous versions which have just been extracted.  You
should avoid storing older versions of a file later in the archive.

   Note:  `--update' (`-u') is not suitable for performing backups,
because it doesn't change directory content entries, and because it
lengthens the archive every time it is used.
FIXME: xref to scripted backup, listed incremental, for info on backups.


File: tar.info,  Node: Updating an Archive,  Next: Combining Archives,  Prev: Adding to an Existing Archive,  Up: Basic tar Operations

Updating an Archive
===================

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

   The `--update' (`-u') option updates a `tar' archive by comparing
the date of the specified archive members against the date of the file
with the same name.  If the file has been modified more recently than
the archive member, then the archive member is deleted (as with
`--delete') and then the file is added to the archive (as with
`--append' (`-r')).  On media where the `--delete' option cannot be
performed (such as magnetic tapes), the `--update' (`-u') option
similarly fails.

   If no archive members are named (either on the command line or via
`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES')), then the entire
archive is processed in this manner.


File: tar.info,  Node: Combining Archives,  Next: Removing Archive Members,  Prev: Updating an Archive,  Up: Basic tar Operations

Combining Archives
==================

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

   The `--concatenate' (`-A') or {No Value For "catenate"} option
causes `tar' to add the contents of several archives to an existing
archive.

   Name the archives to be catenated on the command line.  (Nothing
happens if you don't list any.)  The members, and their member names,
will be copied verbatim from those archives.  If this causes multiple
members to have the same name, it does not delete either; all the
members with the same name coexist.  For information on how this
affects reading the archive,
FIXME: ref Multiple Members with the Same Name
   .

   You must use this option to concatenate archives.  If you just
combine them with `cat', the result will not be a valid `tar' format
archive.

   This operation cannot be performed on some tape drives,
unfortunately, due to deficiencies in the formats thoes tape drives use.

   To append copies of an archive or archives to the end of another
archive, use `--concatenate' (`-A').  The source and target archives
must already exist and have been created using compatable format
parameters (
FIXME: pxref Matching Format Parameters
   ).

   `tar' will stop reading an archive if it encounters an
end-of-archive marker.  The `cat' utility does not remove
end-of-archive markers, and is therefore unsuitable for concatenating
archives.  `--concatenate' (`-A') removes the end-of-archive marker
from the target archive before each new archive is appended.
FIXME: xref ignore-zeros

   You must specify the source archives using `--file=ARCHIVE-NAME'
(`-f ARCHIVE-NAME') (
FIXME: pxref Archive
Name
   ).  If you do not specify the target archive , `tar' uses the value
of the environment variable `TAPE', or, if this has not been set, the
default archive name.

   The following example adds the contents of the archive
`hail/hail/fredonia' to the archive `stooges' (both archives were
created in examples above):

     tar --catenate --file=stooges hail/hail/fredonia

   If you need to retrieve files from an archive that was added to using
the `cat' utility, use the `--ignore-zeros' (`-i') option (
FIXME: pxref Archive Reading Options
   ).


File: tar.info,  Node: Removing Archive Members,  Next: Listing Archive Members,  Prev: Combining Archives,  Up: Basic tar Operations

Removing Archive Members
========================

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

   You can use the `--delete' option to remove members from an archive.
Name the members on the command line to be deleted.  This option will
rewrite the archive; because of this, it does not work on tape drives.
If you list no members to be deleted, nothing happens.

   To delete archive members from an archive, use `--delete'.  You must
specify the file names of the members to be deleted.  All archive
members with the specified file names will be removed from the archive.

   The following example removes the file `curley' from the archive
`stooges':

     tar --delete --file=stooges curley

   You can only use `--delete' on an archive if the archive device
allows you to write to any point on the media.

     *Warning:* Don't try to delete an archive member from a magnetic
     tape, lest you scramble the archive.  There is no safe way (except
     by completely re-writing the archive) to delete files from most
     kinds of magnetic tape.

FIXME: how about automatic detection of archive media?  give error
FIXME: unless the archive device is either an ordinary file or different
FIXME: input and output (--file=-).


File: tar.info,  Node: Listing Archive Members,  Next: Extracting Archive Members,  Prev: Removing Archive Members,  Up: Basic tar Operations

Listing Archive Members
=======================

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

   The `--list' (`-t') option will list the names of members of the
archive.  Name the members to be listed on the command line (to modify
the way these names are interpreted,
FIXME: pxref Specifying Names to
tar
   ).  If you name no members, then `--list' (`-t') will list the names
of all the members of the archive.

   To see more than just the names of the members, use the `--verbose'
(`-v') option to cause `tar' to print out a listing similar to that of
`ls -l'.

   Listing the Contents of an Archive

   `--list' (`-t') prints a list of the file names of the archive
members on the standard output.  If you specify FILE NAME arguments on
the command line (or using the `--files-from=FILE-OF-NAMES' (`-T
FILE-OF-NAMES') option,

FIXME: pxref File Name Lists
   ), only the files you specify will be listed, and only if they exist
in the archive.  Files not specified will be ignored, unless they are
under a specific directory.

   If you include the `--verbose' (`-v') option, `tar' prints an `ls
-l' type listing for the archive.
FIXME: pxref Additional
Information
   , for a description of the `--verbose' (`-v') option.

   If the blocking factor of the archive differs from the default,
`tar' reports this.
FIXME: xref Blocking Factor
   .

FIXME: xref Archive Reading Options
   for a list of options which can be used to modify `--list' (`-t')'s
operation.

   This example prints a list of the archive members of the archive
`stooges':

     tar --list --file=stooges

`tar' responds:

     larry
     moe
     shemp
     marx/julius
     marx/alexander
     marx/karl

   This example generates a verbose list of the archive members of the
archive file `dwarves', which has a blocking factor of two:

     tar --list -v --file=blocks

`tar' responds:

     tar: Blocksize = 2 records
     -rw------- ringo/user 42 May   1 13:29 1990 .bashful
     -rw-rw-rw- ringo/user 42 Oct   4 13:29 1990 doc
     -rw-rw-rw- ringo/user 42 Jul  20 18:01 1969 dopey
     -rw-rw---- ringo/user 42 Nov  26 13:42 1963 grumpy
     -rw-rw-rw- ringo/user 42 May   5 13:29 1990 happy
     -rw-rw-rw- ringo/user 42 May   1 12:00 1868 sleepy
     -rw-rw-rw- ringo/user 42 Jul   4 17:29 1776 sneezy


File: tar.info,  Node: Extracting Archive Members,  Next: Comparing Archives Members with Files,  Prev: Listing Archive Members,  Up: Basic tar Operations

Extracting Archive Members
==========================

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

   Use `--extract' (`-x') or `--get' to extract members from an
archive.  For each member named (or for the entire archive if no
members are named) on the command line--or with
`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES')--the a file is
created with the contents of the archive member.  The name of the file
is the same as the member name.

   Various options cause `tar' to extract more than just file contents,
such as the owner, the permissions, the modification date, and so forth.

FIXME: begin
   The `--same-permissions' (`-p') or `--preserve-permissions' options
cause `tar' to cause the new file to have the same permissions as the
original file did when it was placed in the archive.  Without this
option, the current `umask' is used to affect the permissions.

   When extrating, `tar' normally sets the modification time of the
file to the value recorded in the archive.  The `--modification-time'
(`-m') option causes `tar' to omit doing this.
FIXME: end

   To read archive members from the archive and write them into the file
system, use `--extract' (`-x').  The archive itself is left unchanged.

   If you do not specify the files to extract, `tar' extracts all the
files in the archive.  If you specify the name of a directory as a file
name argument, `tar' will extract all files which have been stored as
part of that directory.  If a file was stored with a directory name as
part of its file name, and that directory does not exist under the
working directory when the file is extracted, `tar' will create the
directory.
FIXME: xref Selecting Archive
Members
   , for information on specifying files to extract.

   The following example shows the extraction of the archive `stooges'
into an empty directory:

     tar --extract --file=stooges

Generating a listing of the directory (`ls') produces:

     larry
     moe
     shemp
     marx

The subdirectory `marx' contains the files `julius', `alexander' and
`karl'.

   If you wanted to just extract the files in the subdirectory `marx',
you could specify that directory as a file name argument in conjunction
with the `--extract' (`-x') operation:

     tar --extract --file=stooges marx

     *Warning:* Extraction can overwrite files in the file system.  To
     avoid losing files in the file system when extracting files from
     the archive with the same name, use the `--keep-old-files' (`-k')
     option (
     FIXME: pxref File Writing Options
     ).

   If the archive was created using `--block-size=512-SIZE' (`-b
512-SIZE'), `--compress' (`-Z') or `--multi-volume' (`-M'), you must
specify those format options again when extracting files from the
archive (
FIXME: pxref Format Variations
   ).

* Menu:

* Archive Reading Options::
* File Writing Options::
* Scarce Disk Space::