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

Copyright (C) 1992 Free Software Foundation, Inc.  DRAFT!

tar
***

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

This is DRAFT Edition 0.01 of the tar documentation, , for tar version 1.12.

Tutorial Introduction to tar
****************************

This chapter guides you through some basic examples of tar operations.  If you already know how to use some other version of tar, then you probably don't need to read this chapter.  This chapter omits complicated details about many of the ways tar works.  See later chapters for full information.

What tar Does
=============

The tar program is used to create and manipulate tar archives.  An archive is a single file which contains within it the contents of many files.  In addition, the archive identifies the names of the files, their owner, and so forth.

You can use tar archives in many ways.  Initially, tar archives were used to store files conveniently on magnetic tape.  The name tar comes from this use; it stands for Tape ARchiver. Often, tar archives are used to store related files for convenient file transfer over a network.  For example, the GNU Project distributes its software bundled into tar archives, so that all the files relating to a particular program (or set of related programs) can be transferred as a single unit.

The files inside an archive are called members.  Within this manual, we use the term file to refer only to files accessible in the normal ways (by ls, cat, and so forth), and the term members to refer only to the members of an archive.  Similarly, a file name is the name of a file, as it resides in the filesystem, and a member name is the name of an archive member within the archive.

The tar program provides the ability to create tar archives, as well as for various other kinds of manipulation.  The term extraction is used to refer to the process of copying an archive member into a file in the filesystem.  One might speak of extracting a single member.  Extracting all the members of an archive is often called extracting the archive.  Often the term unpack is used to refer to the extraction of many or all the members of an archive.

Conventionally, tar archives are given names ending with .tar.  This is not necessary for tar to operate properly, but this manual follows the convention in order to get the reader used to seeing it.

Occasionally archive members are referred to as files.  For people familiar with the operation of tar, this causes no difficulty. However, this manual consistently uses the terminology above in referring to files and archive members, to make it easier to learn how to use tar.

How to Create Archives
======================

To create a new archive, use tar --create.  You should generally use the --file option to specify the name the tar archive will have.  Then specify the names of the files you wish to place in the new archive.  For example, to place the files apple, angst, and asparagus into an archive named afiles.tar, use the following command:

     tar --create --file=afiles.tar apple angst asparagus

The order of the arguments is not important.  You could also say:

     tar apple --create angst --file=afiles.tar asparagus

This order is harder to understand however.  In this manual, we will list the arguments in a reasonable order to make the commands easier to understand, but you can type them in any order you wish.

If you don't specify the names of any files to put in the archive, then tar will create an empty archive.  So, the following command will create an archive with nothing in it:

     tar --create --file=empty-archive.tar

Whenever you use tar --create, tar will erase the current contents of the file named by --file if it exists.  To add files to an existing archive, you need to use a different option. See Adding to Archives for information on how to do this.

When tar --create creates an archive, the member names of the members of the archive are exactly the same as the file names as you typed them in the tar command.  So, the member names of afiles (as created by the first example above) are apple, angst, and asparagus.  However, suppose an archive were created with this command:

     tar --create --file=bfiles.tar ./balloons baboon ./bodacious

Then, the three files balloons, baboon, and bodacious would get placed in the archive (because ./ is a synonym for the current directory), but their member names would be ./balloons, baboon, and ./bodacious.

If you want to see the progress of tar as it writes files into the archive, you can use the --verbose option.

If one of the files named to tar --create is a directory, then the operation of tar is more complicated.  See Tar and Directories, the last section of this tutorial, for more information.

If you don't specify the --file option, then tar will use a default.  Usually this default is some physical tape drive attached to your machine.  If there is no tape drive attached, or the default is not meaningful, then tar will print an error message.  This error message might look roughly like one of the following:

     tar: can't open /dev/rmt8 : No such device or address
     tar: can't open /dev/rsmt0 : I/O error

If you get an error like this, mentioning a file you didn't specify (/dev/rmt8 or /dev/rsmt0 in the examples above), then tar is using a default value for --file.  You should generally specify a --file argument whenever you use tar, rather than relying on a default.

How to List Archives
====================

Use tar --list to print the names of members stored in an archive.  Use a --file option just as with tar --create to specify the name of the archive.  For example, the archive afiles.tar created in the last section could be examined with the command tar --list --file=afiles.tar.  The output of tar would then be:

     apple
     angst
     asparagus

The archive bfiles.tar would list as follows:

     ./baloons
     baboon
     ./bodacious

(Of course, tar --list --file=empty-archive.tar would produce no output.)

If you use the --verbose option with tar --list, then tar will print out a listing reminiscent of ls -l, showing owner, file size, and so forth.

You can also specify member names when using tar --list.  In this case, tar will only list the names of members you identify.  For example, tar --list --file=afiles.tar apple would only print apple.  It is essential when specifying member names to tar that you give the exact member names.  For example, tar --list --file=bfiles baloons would produce no output, because there is no member named baloons, only one named ./baloons.  While the file names baloons and ./baloons name the same file, member names are compared using a simplistic name comparison, in which an exact match is necessary.

How to Extract Members from an Archive
======================================

In order to extract members from an archive, use tar --extract. Specify the name of the archive with --file.  To extract specific archive members, give their member names as arguments.  It essential to give their exact member name, as printed by tar --list.  This will create a copy of the archive member, with a file name the same as its name in the archive.

Keeping the example of the two archives created at the beginning of this tutorial, tar --extract --file=afiles.tar apple would create a file apple in the current directory with the contents of the archive member apple.  It would remove any file named apple already present in the directory, but it would not change the archive in any way.

Remember that specifying the exact member name is important.  tar --extract --file=bfiles.tar baloons will fail, because there is no member named baloons.  To extract the member named ./baloons you would need to specify tar --extract --file=bfiles.tar ./baloons.  To find the exact member names of the members of an archive, use tar --list (see Listing Archives).

If you do not list any archive member names, then tar --extract will extract all the members of the archive.

If you give the --verbose option, then tar --extract will print the names of the archive members as it extracts them.

How to Add Files to Existing Archives
=====================================

If you want to add files to an existing archive, then don't use tar --create.  That will erase the archive and create a new one in its place.  Instead, use tar --append.  The command tar --append --file=afiles.tar arbalest would add the file arbalest to the existing archive afiles.tar.  The archive must already exist in order to use tar --append.

As with tar --create, the member names of the newly added files will be the exact same as their names given on the command line.  The --verbose option will print out the names of the files as they are written into the archive.

If you add a file to an archive using tar --append with the same name as an archive member already present in the archive, then the old member is not deleted.  What does happen, however, is somewhat complex.  See Multiple Members with the Same Name.  If you want to replace an archive member, use tar --delete first, and then use tar --append.

How to Delete Members from Archives
===================================

You can delete members from an archive using tar --delete. Specify the name of the archive with --file.  List the member names of the members to be deleted.  (If you list no member names, then nothing will be deleted.)  The --verbose option will cause tar to print the names of the members as they are deleted.  As with tar --extract, it is important that you give the exact member names when using tar --delete.  Use tar --list to find out the exact member names in an archive (see Listing Archives).

The tar --delete command only works with archives stored on disk. You cannot delete members from an archive stored on a tape.

How to Archive Directories
==========================

When the names of files or members specify directories, the operation of tar is more complex.  Generally, when a directory is named, tar also operates on all the contents of the directory, recursively.  Thus, to tar, the file name / names the entire file system.

To archive the entire contents of a directory, use tar --create (or tar --append) as usual, and specify the name of the directory.  For example, to archive all the contents of the current directory, use tar --create --file=ARCHIVE-NAME ..  Doing this will give the archive members names starting with ./.  To archive the contents of a directory named foodir, use tar --create --file=ARCHIVE-NAME foodir.  In this case, the member names will all start with foodir/.

If you give tar a command such as tar --create --file=foo.tar ., it will report tar: foo.tar is the archive; not dumped.  This happens because the archive foo.tar is created before putting any files into it.  Then, when tar attempts to add all the files in the directory . to the archive, it notices that the file foo.tar is the same as the archive, and skips it.  (It makes no sense to put an archive into itself.)  GNU tar will continue in this case, and create the archive as normal, except for the exclusion of that one file.  Other versions of tar, however, are not so clever, and will enter an infinite loop when this happens, so you should not depend on this behavior.  In general, make sure that the archive is not inside a directory being dumped.

When extracting files, you can also name directory archive members on the command line.  In this case, tar extracts all the archive members whose names begin with the name of the directory.  As usual, tar is not particularly clever about interpreting member names. The command tar --extract --file=ARCHIVE-NAME . will not extract all the contents of the archive, but only those members whose member names begin with ./.

Shorthand Names
===============

Most of the options to tar come in both long forms and short forms.  The options described in this tutorial have the following abbreviations (except --delete, which has no shorthand form):

--create
     -c

--list
     -t

--extract
     -x

--append
     -r

--verbose
     -v

--file=ARCHIVE-NAME
     -f ARCHIVE-NAME

These options make typing long tar commands easier.  For example, instead of typing

     tar --create --file=/tmp/afiles.tar --verbose apple angst asparagus

you can type

     tar -c -f /tmp/afiles.tar -v apple angst asparagus

For more information on option syntax, Invoking tar.  In the remainder of this manual, short forms and long forms are given together when an option is discussed.

Invoking tar
************

The usual way to invoke tar is

     tar OPTIONS... [FILE-OR-MEMBER-NAMES...]

All the options start with -.  You can actually type in arguments in any order, but in this manual the options always precede the other arguments, to make examples easier to understand.

The Forms of Arguments
======================

Most options of tar have a single letter form (a single letter preceded by -), and at least one mnemonic form (a word or abbreviation preceded by --).  The forms are absolutely identical in function.  For example, you can use either tar -t or tar --list to list the contents of an archive.  In addition, mnemonic names can be given unique abbreviations.  For example, --cre can be used in place of --create because there is no other option which begins with cre.

Some options require an additional argument.  Single letter options which require arguments use the immediately following argument. Mnemonic options are separated from their arguments by an = sign.  For example, to create an an archive file named george.tar, use either tar --create --file=george.tar or tar --create -f george.tar.  Both --file=ARCHIVE-NAME and -f ARCHIVE-NAME denote the option to give the archive a non-default name, which in the example is george.tar.

You can mix single letter and mnemonic forms in the same command.  You could type the above example as tar -c --file=george or tar --create -f george.  However, tar operations and options are case sensitive.  You would not type the above example as tar -C --file=george, because -C is an option that causes tar to change directories, not an operation that creates an archive.  In fact, -C requires a further argument (the name of the directory which to change to).  In this case, tar would think it needs to change to a directory named --file=george, and wouldn't interpret --file-george as an option at all!

The Functions of Arguments
==========================

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

--help
     Print a summary of the options to tar and do nothing else

--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 and --create 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 tar --list.  When naming files, the normal file name rules apply.

     If you don't use any additional arguments, --append, --catenate, and --delete will do nothing.  Naturally, --create will make an empty archive if given no files to add. The other operations of tar (--list, --extract, --compare, and --update) 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.

An Old, but Still Supported, Syntax for tar Commands
====================================================

For historical reasons, GNU tar also accepts a syntax for commands which splits options that require additional arguments into two parts.  That syntax is of the form:

     tar OPTION-LETTERS... [OPTION-ARGUMENTS...] [FILE-NAMES...]

where arguments to the options appear in the same order as the letters to which they correspond, and the operation and all the option letters appear as a single argument, without separating spaces.

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.

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.  The modern syntax---tar -c -v -b 20 -f /dev/rmt0---is clearer.

Basic tar Operations
********************

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

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

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, Absolute Paths.)  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. See 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 instead. (see Adding to an Existing Archive.)

There are various ways of causing tar to skip over some files, and not archive them.  See Specifying Names to tar.

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

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.  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, 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.

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

The --catenate (or --concatenate, or -A) 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, 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.

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

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.

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

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, see Specifying Names to tar).  If you name no members, then --list will list the names of all the members of the archive.

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

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

Use --extract (or --get, or -x) 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) 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.

XXX The --same-permissions (or --preserve-permissions, or -p) 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 option causes tar to omit doing this. XXX

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

The --update (or -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).  On media where the --delete option cannot be performed (such as magnetic tapes), the --update option similarly fails.

If no archive members are named (either on the command line or via --files-from), then the entire archive is processed in this manner.

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

The --compare (or --diff, or -d) 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), then the entire archive is so compared.

Specifying Names to tar
***********************

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.

Reading Names from a File
=========================

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-NAME-LIST (-T FILE-NAME-LIST) option to tar.  Give the name of the file which contains the list as the argument to --files-from.  The file names should be separated by newlines in the list.  If you give a single dash as a filename for --files-from (that is, you specify --files-from=- or -T -), then the filenames are read from standard input.

If you want to specify names that might contain newlines, use the --null option.  Then, the filenames should be separated by NUL characters (ASCII 000) instead of newlines.  In addition, the --null option turns off the -C option (see Changing Directory).

Excluding Some Files
====================

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=EXCLUDE-LIST (-X EXCLUDE-LIST) option.  This works just like the --files-from=FILE-NAME-LIST option: specify the name of a file as EXCLUDE-LIST which contains the list of patterns you want to exclude.

See Regular Expressions for more information on the syntax and meaning of regular expressions.

Operating Only on New Files
===========================

The --newer=DATE (--after-date=DATE or -N 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, see 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, Making Backups.

Crossing Filesystem Boundaries
==============================

The --one-file-system 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 option) will always be archived.

Changing the Names of Members when Archiving
********************************************

Changing Directory
==================

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 option is frequently used to make the archive independent of the original name of the directory holding the files.

Note that --directory options are interpreted consecutively.  If --directory option specifies a relative pathname, 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 option.

When using --files-from (see 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.)

Absolute Path Names
===================

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-paths option, tar will do neither of these transformations.

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. However, if you want tar to actually dump the contents of the target of the symbolic link, then use the --dereference option.

Making tar More Verbose
***********************

Various options cause tar to print information as it progresses in its job.

The --verbose (or -v) option causes tar to print the name of each archive member or file as it is processed.  Since --list already prints the names of the members, --verbose used with --list causes tar to print a longer listing (reminiscent of ls -l) for each member.

To see the progress of tar through the archive, the --record-number option prints a message for each record read or writted.  (see Archive Structure.)  This option can be very helpful when trying to figure out where in the archive an error occurs.

The --totals option (which is only meaningful when used with --create) 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.  It is designed for those who don't need the more detailed (and voluminous) output of --record-number, but do want visual confirmation that tar is actually making forward progress.

The --version option will generate a message with the version of GNU tar you are using.

Input and Output
****************

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

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 (or -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 filename you give to --file is a single dash (-), then tar will read the archive from (or write it to) standard input (or standard output).

Extracting Members to Standard Output
=====================================

An archive member in normally extracted into a file with the same name as the archive member.  However, you can use the --to-stdout 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.

Dealing with Compressed Archives
================================

You can have archives be compressed by using the --gzip (or -z) option.  This will arrange for tar to use the gzip program to be used to compress or uncompress the archive wren writing or reading it.

To use the older, obsolete, compress program, use the --compress (or -Z) option.  The GNU Project recommends you not use compress, because there is a patent covering the algorithm it uses.  Merely by running compress you could be sued for patent infringment.

When using either --gzip or --compress, tar does not do blocking (see Blocking) correctly.  Use --gzip-block or --compress-block instead when using real tape drives.

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

When using tar with many options, particularly ones with complicated or difficult-to-predict behavior, it is possible to make serious mistakes.  As a result, tar provides several options that make observing tar easier.

The --verbose 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.  See Making tar More Verbose.

If you use --interactive (or --confirm), then tar will ask you for confirmation before each operation.  For example, when extracting, it will prompt you before each archive member is extracted, and you can select that member for extraction or pass over to the next.

The --verify option, when using --create, causes tar, after having finished creating the archive, to go back over it and compare its contents against the files that were placed in the archive.

The --show-omitted-dirs option, when reading an archive (with --list or --extract, 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 option, or some other reason.

Using Real Tape Drives
**********************

Many complexities surround the use of tar on tape drives.  Since the creation and manipulation of archives located on magnetic tape was the original purpose of tar, it contains many features making such manipulation easier.

Blocking
========

When writing to tapes, tar writes the contents of the archive in chunks known as blocks.  To change the default blocksize, use the
--block-size=BLOCKING-FACTOR (-b
BLOCKING-FACTOR) option.  Each block will then be composed of
BLOCKING-FACTOR records.  (Each tar record is 512 bytes.
See Archive Format.)  Each file written to the archive uses at least
one full block.  As a result, using a larger block size can result in
more wasted space for small files.  On the other hand, a larger block
size can ofter be read and written much more efficiently.

Further complicating the problem is that some tape drives ignore the
blocking entirely.  For these, a larger block size can still improve
performance (because the software layers above the tape drive still
honor the blocking), but not as dramatically as on tape drives that
honor blocking.

Wher reading an archive, tar can usually figure out the block
size on itself.  When this is the case, and a non-standard block size
was used when the archive was created, tar will print a message
about a non-standard blocking factor, and then operate normally.  On
some tape devices, however, tar cannot figure out the block size
itself.  On most of those, you can specify a blocking factor (with
--block-size) larger than the actual blocking factor, and then use
the --read-full-blocks option.  (If you specify a blocking factor
with --block-size and don't use the --read-full-blocks
option, then tar will not attempt to figure out the blocking size
itself.)  On some devices, you must always specify the block size
exactly with --block-size when reading, because tar cannot
figure it out.  In any case, use --list before doing any
extractions to see whether tar is reading the archive correctly.

If you use a blocking factor larger than 20, older tar programs
might not be able to read the archive, so we recommend this as a limit
to use in practice.  GNU tar, however, will support arbitrarily
large block sizes, limited only by the amount of virtual memory or the
physical characteristics of the tape device.

If you are writing a compressed archive to tape with --compress
or --gzip (see Input and Output), tar will not block
the archive correctly.  This doesn't matter if you are writing the
archive to a normal file or through a pipe, but if you are writing it to
a tape drive, then this causes problems.  Use --compress-block or
--gzip-block instead, to cause tar to arrange to have
blocking work correctly.

Using Multiple Tapes
====================

Often you might want to write a large archive, one larger than will fit on the actual tape you are using.  In such a case, you can run multiple tar commands, but this can be inconvenient, particularly if you are using options like --exclude or dumping entire filesystems. Therefore, tar supports multiple tapes automatically.

Use --multi-volume on the command line, and then tar will, when it reaches the end of the tape, prompt for another tape, and continue the archive.  Each tape will have an independent archive, and can be read without needing the other.  (As an exception to this, the file that tar was archiving when it ran out of tape will usually be split between the two archives; in this case you need to extract from the first archive, using --multi-volume, and then put in the second tape when prompted, so tar can restore both halves of the file.)

When prompting for a new tape, tar accepts any of the following responses:

?
     Request tar to explain possible responses

q
     Request tar to exit immediately.

n FILE-NAME
     Request tar to write the next volume on the file FILE-NAME.

!
     Request tar to run a subshell.

y
     Request tar to begin writing the next volume.

(You should only type y after you have changed the tape; otherwise tar will write over the volume it just finished.)

If you want more elaborate behavior than this, give tar the --info-script=SCRIPT-NAME option.  The file SCRIPT-NAME is expected to be a program (or shell script) to be run instead of the normal prompting procedure.  When the program finishes, tar will immediately begin writing the next volume. (The behavior of the n response to the normal tape-change prompt is not available if you use --info-script.)

The method tar uses to detect end of tape is not perfect, and fails on some operating systems or on some devices.  You can use the --tape-length=SIZE (or -L SIZE) option if tar can't detect the end of the tape itself.  The SIZE argument should be the size of the tape.

The volume number used by tar in its tape-change prompt can be changed; if you give the --volno-file=FILE-NAME option, then FILE-NAME should contain a decimal number.  That number will be used as the volume number of the first volume written.  When tar is finished, it will rewrite the file with the now--current volume number.  (This does not change the volume number written on a tape label (see Special Options for Archiving; it only affects the number used in the prompt.)

If you want tar to cycle through a series of tape drives, then you can use the n response to the tape-change prompt.  This is error prone, however, and doesn't work at all with --info-script. Therefore, if you give tar multiple --file options, then the specified files will be used, in sequence, as the successive volumes of the archive.  Only when the first one in the sequence needs to be used again will tar prompt for a tape change (or run the info script).

Tape Files
==========

When tar writes an archive to tape, it creates a single tape file.  If multiple archives are written to the same tape, one after the other, they each get written as separate tape files.  When extracting, it is necessary to position the tape at the right place before running tar.  To do this, use the mt command.  For more information on the mt command and on the organization of tapes into a sequence of tape files, see XXX.

Special Options for Archiving
*****************************

To give the archive a name which will be recorded in it, use the --label=VOLUME-LABEL (or -V) option.  This will write a special record identifying VOLUME-LABEL as the name of the archive to the front of the archive which will be displayed when the archive is listed with --list.  If you are creating a multi-volume archive with --multi-volume (see Using Multiple Tapes), then the volume label will have  Volume NNN appended to the name you give, where NNN is the number of the volume of the archive.  (If you use the --label option when reading an archive, it checks to make sure the label on the tape matches the one you give.  See Special Options for Archiving.)

Files in the filesystem occasionally have ``holes.''  A hole in a file is a section of the file's contents which was never written.  The contents of a hole read as all zeros.  On many operating systems, actual disk storage is not allocated for holes, but they are counted in the length of the file.  If you archive such a file, tar could create an archive longer than the original.  To have tar attempt to recognize the holes in a file, use --sparse.  When you use the --sparse option, then, for any file using less disk space than would be expected from its length, tar searches the file for consecutive stretches of zeros.  It then records in the archive for the file where the consecutive stretches of zeros are, and only archives the ``real contents'' of the file.  On extraction (using --sparse is not needed on extraction) any such files have hols created wherever the continuous stretches of zeros were found.  Thus, if you use --sparse, tar archives won't take more space than the original.

When tar reads files, this causes them to have the access times updated.  To have tar attempt to set the access times back to what they were before they were read, use the --atime-preserve option.  This doesn't work for files that you don't own, unless you're root, and it doesn't interact with incremental dumps nicely (see Making Backups), but it is good enough for some purposes.

Special Options for Reading Archives
************************************

XXXX MIB XXXX

Wizardry
********

<<<This section needs to be written  -ringo

To come: using Unix file linking capability to recreate directory structures---linking files into one subdirectory and then tarring that directory.

to come: nice hairy example using absolute-paths, newer, etc.

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

     cd sourcedirectory; tar cf - . | (cd targetdir; tar xf -)

or

<<<  the following using standard input/output correct??

     cd sourcedirectory; tar --create --file=- . | (cd targetdir; tar --extract --file=-)

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

<<<<<end construction>>>>>

The Structure of an Archive
***************************

While an archive may contain many files, the archive itself is a single ordinary file.  Like any other file, an archive file can be written to a storage device such as a tape or disk, sent through a pipe or over a network, saved on the active file system, or even stored in another archive.  An archive file is not easy to read or manipulate without using the tar utility or Tar mode in Emacs.

Physically, an archive consists of a series of file entries terminated by an end-of-archive entry, which consists of 512 zero bytes.  A file entry usually describes one of the files in the archive (an archive member), and consists of a file header and the contents of the file.  File headers contain file names and statistics, checksum information which tar uses to detect file corruption, and information about file types.

More than archive member can have the same file name.  One way this situation can occur is if more than one version of a file has been stored in the archive.  For information about adding new versions of a file to an archive, see Modifying.

In addition to entries describing archive members, an archive may contain entries which tar itself uses to store information. See Archive Label, for an example of such an archive entry.

Old Style File Information
==========================

Archives record not only an archive member's contents, but also its file name or names, its access permissions, user and group, size in bytes, and last modification time.  Some archives also record the file names in each archived directory, as well as other file and directory information.

Certain old versions of tar cannot handle additional information recorded by newer tar programs.  To create an archive which can be read by these old versions, specify the --old-archive option in conjunction with the tar --create operation.  When you specify this option, tar leaves out information about directories, pipes, fifos, contiguous files, and device files, and specifies file ownership by group and user ids instead of names.

The --old-archive option is needed only if the archive must be readable by an older tape archive program which cannot handle the new format. Most tar programs do not have this limitation, so this option is seldom needed.

--old-archive
-o
--old
--portable
     Creates an archive that can be read by an old tar program. Used in conjunction with the tar --create operation.

Including a Label in the Archive
================================

To avoid problems caused by misplaced paper labels on the archive media, you can include a label entry---an archive member which contains the name of the archive---in the archive itself.  Use the --label=ARCHIVE-LABEL option in conjunction with the --create operation to include a label entry in the archive as it is being created.

If you create an archive using both --label=ARCHIVE-LABEL and --multi-volume, each volume of the archive will have an archive label of the form ARCHIVE-LABEL Volume N, where N is 1 for the first volume, 2 for the next, and so on. See Multi-Volume Archives, for information on creating multiple volume archives.

If you extract an archive using --label=ARCHIVE-LABEL, tar will print an error if the archive label doesn't match the ARCHIVE-LABEL specified, and will then not extract the archive. You can include a regular expression in ARCHIVE-LABEL, in this case only.

To find out an archive's label entry (or to find out if an archive has a label at all), use tar --list --verbose.  tar will print the label first, and then print archive member information, as in the example below:

     % tar --verbose --list --file=iamanarchive
     V--------- 0/0        0 Mar  7 12:01 1992 iamalabel--Volume Header--
     -rw-rw-rw- ringo/user 40 May 21 13:30 1990 iamafilename

--label=ARCHIVE-LABEL
-V ARCHIVE-LABEL
     Includes an archive-label at the beginning of the archive when the archive is being created (when used in conjunction with the tar --create operation).  Checks to make sure the archive label matches the one specified (when used in conjunction with the tar --extract operation.

Format Variations
=================

Format parameters specify how an archive is written on the archive media.  The best choice of format parameters will vary depending on the type and number of files being archived, and on the media used to store the archive.

To specify format parameters when accessing or creating an archive, you can use the options described in the following sections.  If you do not specify any format parameters, tar uses default parameters.  You cannot modify a compressed archive.  If you create an archive with the --block-size option specified (see Blocking Factor), you must specify that block-size when operating on the archive.  See Matching Format Parameters, for other examples of format parameter considerations.

Archives Longer than One Tape or Disk
-------------------------------------

To create an archive that is larger than will fit on a single unit of the media, use the --multi-volume option in conjunction with the tar --create operation (see Creating Archives).  A multi-volume archive can be manipulated like any other archive (provided the --multi-volume option is specified), but is stored on more than one tape or disk.

When you specify --multi-volume, tar does not report an error when it comes to the end of an archive volume (when reading), or the end of the media (when writing).  Instead, it prompts you to load a new storage volume.  If the archive is on a magnetic tape, you should change tapes when you see the prompt; if the archive is on a floppy disk, you should change disks; etc.

You can read each individual volume of a multi-volume archive as if it were an archive by itself.  For example, to list the contents of one volume, use tar --list, without --multi-volume specified. To extract an archive member from one volume (assuming it is described that volume), use tar --extract, again without --multi-volume.

If an archive member is split across volumes (ie. its entry begins on one volume of the media and ends on another), you need to specify --multi-volume to extract it successfully.  In this case, you should load the volume where the archive member starts, and use tar --extract --multi-volume---tar will prompt for later volumes as it needs them.  See Extracting From Archives for more information about extracting archives.

--info-script=PROGRAM-FILE is like --multi-volume, except that tar does not prompt you directly to change media volumes when a volume is full---instead, tar runs commands you have stored in PROGRAM-FILE.  This option can be used to broadcast messages such as someone please come change my tape when performing unattended backups.  When PROGRAM-FILE is done, tar will assume that the media has been changed.

<<< There should be a sample program here, including an exit before <<< end.

--multi-volume
-M
     Creates a multi-volume archive, when used in conjunction with tar --create.  To perform any other operation on a multi-volume archive, specify --multi-volume in conjunction with that operation.

--info-script=PROGRAM-FILE
-F PROGRAM-FILE
     Creates a multi-volume archive via a script. Used in conjunction with tar --create.

Archiving Sparse Files
----------------------

A file is sparse if it contains blocks of zeros whose existance is recorded, but that have no space allocated on disk.  When you specify the --sparse option in conjunction with the --create operation, tar tests all files for sparseness while archiving. If tar finds a file to be sparse, it uses a sparse representation of the file in the archive.  See Creating Archives, for more information about creating archives.

--sparse is useful when archiving files, such as dbm files, likely to contain many nulls.  This option dramatically decreases the amount of space needed to store such an archive.

     Please Note: Always use --sparse when performing file system backups, to avoid archiving the expanded forms of files stored sparsely in the system.

     Even if your system has no no sparse files currently, some may be created in the future.  If you use --sparse while making file system backups as a matter of course, you can be assured the archive will always take no more space on the media than the files take on disk (otherwise, archiving a disk filled with sparse files might take hundreds of tapes). <<< xref incremental when node name is set.

tar ignores the --sparse option when reading an archive.

--sparse
-S
     Files stored sparsely in the file system are represented sparsely in the archive.  Use in conjunction with write operations.

The Blocking Factor of an Archive
---------------------------------

The data in an archive is grouped into records, which are 512 bytes. Records are read and written in whole number multiples called blocks.  The number of records in a block (ie. the size of a block in units of 512 bytes) is called the blocking factor.  The --block-size=NUMBER option specifies the blocking factor of an archive.  The default blocking factor is typically 20 (ie. 10240 bytes), but can be specified at installation.  To find out the blocking factor of an existing archive, use tar --list --file=ARCHIVE-NAME.  This may not work on some devices.

Blocks are seperated by gaps, which waste space on the archive media. If you are archiving on magnetic tape, using a larger blocking factor (and therefore larger blocks) provides faster throughput and allows you to fit more data on a tape (because there are fewer gaps). If you are archiving on cartridge, a very large blocking factor (say 126 or more) greatly increases performance. A smaller blocking factor, on the other hand, may be usefull when archiving small files, to avoid archiving lots of nulls as tar fills out the archive to the end of the block. In general, the ideal block size depends on the size of the inter-block gaps on the tape you are using, and the average size of the files you are archiving.  See Creating Archives, for information on writing archives.

Archives with blocking factors larger than 20 cannot be read by very old versions of tar, or by some newer versions of tar running on old machines with small address spaces.  With GNU tar, the blocking factor of an archive is limited only by the maximum block size of the device containing the archive, or by the amount of available virtual memory.

If you use a non-default blocking factor when you create an archive, you must specify the same blocking factor when you modify that archive.  Some archive devices will also require you to specify the blocking factor when reading that archive, however this is not typically the case.  Usually, you can use tar --list without specifying a blocking factor---tar reports a non-default block size and then lists the archive members as it would normally.  To extract files from an archive with a non-standard blocking factor (particularly if you're not sure what the blocking factor is), you can usually use the --read-full-blocks option while specifying a blocking factor larger then the blocking factor of the archive (ie. tar --extract --read-full-blocks --block-size=300.  See Listing Contents for more information on the --list operation. See read-full-blocks for a more detailed explanation of that option.

--block-size=NUMBER
-b NUMBER
     Specifies the blocking factor of an archive.  Can be used with any operation, but is usually not necessary with tar --list.

Creating and Reading Compressed Archives
----------------------------------------

--compress indicates an archive stored in compressed format. The --compress option is useful in saving time over networks and space in pipes, and when storage space is at a premium. --compress causes tar to compress when writing the archive, or to uncompress when reading the archive.

To perform compression and uncompression on the archive, tar runs the compress utility.  tar uses the default compression parameters; if you need to override them, avoid the --compress option and run the compress utility explicitly.  It is useful to be able to call the compress utility from within tar because the compress utility by itself cannot access remote tape drives.

The --compress option will not work in conjunction with the --multi-volume option or the --add-file, --update, --add-file and --delete operations.  See Modifying, for more information on these operations.

If there is no compress utility available, tar will report an error.

--compress-block is like --compress, but when used in conjunction with --create also causes tar to pad the last block of the archive out to the next block boundary as it is written. This is useful with certain devices which require all write operations be a multiple of a specific size.

     Please Note: The compress program may be covered by a patent, and therefore we recommend you stop using it.  We hope to have a different compress program in the future.  We may change the name of this option at that time.

--compress
--uncompress
-z
-Z
     When this option is specified, tar will compress (when writing an archive), or uncompress (when reading an archive).  Used in conjunction with the --create, --extract, --list and --compare operations.

--compress-block
-z -z
     Acts like --compress, but pads the archive out to the next block boundary as it is written when used in conjunction with the --create operation.

Reading and Writing Archives
****************************

The --create operation writes a new archive, and the --extract 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 operation.

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 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.

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.

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

Creating in Detail
==================

To create an archive, use tar --create.  To name the archive, use --file=ARCHIVE-NAME in conjunction with the --create operation (see 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.  See 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

See 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.

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.  See Listing Contents.

Adding Files to an Archive
--------------------------

To add files to an archive, use tar --add-file.  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 (see 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. See Matching Format Parameters.

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

     tar --add-file --file=stooges shemp

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

tar --update acts like tar --add-file, 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 and --add-file 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 tar --extract 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 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.

Appending One Archive's Contents to Another Archive
---------------------------------------------------

To append copies of an archive or archives to the end of another archive, use tar --add-archive.  The source and target archives must already exist and have been created using compatable format parameters (see 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.  tar --add-archive removes the end-of-archive marker from the target archive before each new archive is appended.

You must specify the source archives using --file=ARCHIVE-NAME (see 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 --add-archive --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 option (see Archive Reading Options).

Deleting Files From an Archive
------------------------------

To delete archive members from an archive, use tar --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 tar --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.

Matching the Format Parameters
------------------------------

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 (see Archive Label) when it was created, tar will not automatically label volumes which are added later.  To label subsequent volumes, specify --label=ARCHIVE-LABEL again in conjunction with the --add-file, --update or --add-archive operation.

Listing the Contents of an Archive
==================================

tar --list 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 option, see 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 option, tar prints an ls -l type listing for the archive.  see Additional Information, for a description of the --verbose option.

If the blocking factor of the archive differs from the default, tar reports this.  See Blocking Factor.

See Archive Reading Options for a list of options which can be used to modify --list'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

Extracting Files from an Archive
================================

To read archive members from the archive and write them into the file system, use tar --extract.  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.  See 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 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 option (see File Writing Options).

If the archive was created using --block-size, --compress or --multi-volume, you must specify those format options again when extracting files from the archive (see Format Variations).

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

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 option in conjunction with the --extract or --list operations. See Listing Contents.

The --read-full-blocks 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 and --block-size=N, where N is a blocking factor larger than the blocking factor of the archive.  This lets you avoid having to determine the blocking factor of an archive.  See Blocking Factor.

--read-full-blocks

-B
     Use in conjunction with tar --extract 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 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 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 tar --extract or tar --list.

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 option and provide an ordered list of file names. This option tells tar that the file-name arguments (provided on the command line, or read from a file using the --files-from 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.  See Listing Contents, for information on the --list 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 tar --compare, tar --list or tar --extract.

Changing How tar Writes Files
-----------------------------

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 in conjunction with the --extract 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 option in conjunction with tar --extract.

--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.

To set the modes (access permissions) of extracted files to those recorded for those files in the archive, use the --preserve-permissions option in conjunction with the --extract operation.

--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.

To write the files extracted to the standard output, instead of creating the files on the file system, use --to-stdout in conjunction with tar --extract.  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.

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

If a previous attempt to extract files failed due to lack of disk space, you can use --starting-file=FILE-NAME to start extracting only after file 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 or --list.

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 is not necessary.

Insuring the Accuracy of an Archive
***********************************

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.

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

To check for discrepancies in an archive immediately after it is written, use the --verify option in conjunction with the tar --create 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.

--verify
-W
     Checks for discrepancies in the archive immediately after it is written.  Use in conjunction with tar --create.

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

tar --compare 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

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.  (see 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), all the archive members in the archive (if a read operation is specified), or does nothing (if any other operation is specified).

Reading a List of File Names from a File
========================================

To read file names from a file on the file system, instead of from the command line, use the --files-from=FILE option.  If you specify - as FILE, the file names are read from standard input.  Note that using both --files-from=- and --file=- in the same command will not work unless the operation is --create.  See Archive Name, for an explanation of the --file 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.

File Name Interpretation
========================

Storing and Extracting Files Relative to Root
---------------------------------------------

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

Changing the Working Directory Within a List of File-names
----------------------------------------------------------

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), use --directory=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.

Archiving Using Symbolic Links
------------------------------

--dereference is used with tar --create, and causes tar to archive files which are referenced by a symbolic link, using the name of the link as the file name.

<<<this needs to be checked by MIB and then re-written, with an example 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 could be considered a bug.

--dereference
-h
     Stores files referenced by a symbolic link, using the name of the link as the file name.  Use in conjunction with any write operation.

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

To avoid crossing file system boundaries when archiving parts of a directory tree, use --one-file-system.  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, 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 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.

--exclude-from=FILE acts like --exclude, 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.

To operate only on files with modification or status-change times after a particular date, use --after-date=DATE.  You can use this option with tar --create or tar --add-file to insure only new files are archived, or with tar --extract to insure only recent files are resurrected.

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

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

Please Note: --after-date and --newer-mtime should not be used for incremental backups.  Some files (such as those in renamed directories) are not selected up properly by these options.

--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, but only looks at modification times.

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. month and day names can be abbreviated.  >>>

User Interaction
****************

Once you have typed a tarcommand, it is usually performed without any further information required of the user, or provided by tar.  The following options allow you to generate progress and status information during an operation, or to confirm operations on files as they are performed.

Progress and Status Information
===============================

Typically, tar performs most operations without reporting any information to the user except error messages.  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.

When used with most operations, --verbose causes tar to print the file names of the files or archive members it is operating on.  When used with tar --list, the verbose option causes tar to print out an ls -l type listing of the files in the archive.

Verbose output appears on the standard output except when an archive is being written to the standard output (as with tar --create --file=- --verbose).  In that case tar writes verbose output to the standard error stream.

--verbose
-v
     Prints the names of files or archive members as they are being operated on.  Can be used in conjunction with any operation.   When used with --list, generates an ls -l type listing.

To find out where in an archive a message was triggered, use --record-number.  --record-number causes tar to print, along with every message it produces, 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 tar --list 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).

--record-number
-R
     Prints the record number whenever a message is generated by tar.  Use in conjunction with any operation.

To print the version number of the tar program, use tar --version.  tar prints the version number to the standard error.  For example:

     tar --version

might return:

     GNU tar version 1.09

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 (see File Exclusion), or by performing an operation interactively, using the --interactive operation.

When the --interactive option is specified, tar asks for confirmation before reading, writing, or deleting each file it encounters while carrying out an operation.  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.

Commands which might be useful to perform interactively include appending files to an archive, extracting files from an archive, deleting a file from an archive, and deleting a file from disk during an incremental restore.

If tar is reading the archive from the standard input, tar opens the file /dev/tty to support the interactive communications. <<< this aborts if you won't OK the working directory.  this is a bug. -ringo

--interactive
--confirmation
-w
     Asks for confirmation before reading, writing or deleting an archive member (when listing, comparing or writing an archive or deleting archive members), or before writing or deleting a file (when extracting an archive).

Performing Backups and Restoring Files
**************************************

To back up a file system means to create archives that contain all the files in that file system.  Those archives can then be used to restore any or all of those files (for instance if a disk crashes or a file is accidently deleted).  File system backups are also called dumps.

Levels of Backups
=================

An archive containing all the files in the file system is called a full backup or full dump.  You could insure your data by creating a full dump every day.  This strategy, however, would waste a substantial amount of archive media and user time, as unchanged files are daily re-archived.

It is more efficient to do a full dump only occasionally.  To back up files between full dumps, you can a incremental dump.  A level one dump archives all the files that have changed since the last full dump.

A typical dump strategy would be to perform a full dump once a week, and a level one dump once a day.  This means some versions of files will in fact be archived more than once, but this dump strategy makes it possible to restore a file system to within one day of accuracy by only extracting two archives---the last weekly (full) dump and the last daily (level one) dump.  The only information lost would be in files changed or created since the last daily backup.  (Doing dumps more than once a day is usually not worth the trouble).

Using Scripts to Perform Backups and Restoration
================================================

GNU tar comes with scripts you can use to do full and level-one dumps.  Using scripts (shell programs) to perform backups and restoration is a convenient and reliable alternative to typing out file name lists and tar commands by hand.

Before you use these scripts, you need to edit the file backup-specs, which specifies parameters used by the backup scripts and by the restore script.  See Script Syntax. Once the backup parameters are set, you can perform backups or restoration by running the appropriate script.

The name of the restore script is restore. The names of the level one and full backup scripts are, respectively, level-1 and level-0.  The level-0 script also exists under the name weekly, and the level-1 under the name daily---these additional names can be changed according to your backup schedule.  See Scripted Restoration, for more information on running the restoration script.  See Scripted Backups, for more information on running the backup scripts.

Please Note: The backup scripts and the restoration scripts are designed to be used together.  While it is possible to restore files by hand from an archive which was created using a backup script, and to create an archive by hand which could then be extracted using the restore script, it is easier to use the scripts.  See incremental and listed-incremental, before making such an attempt.

Setting Parameters for Backups and Restoration
----------------------------------------------

The file backup-specs specifies backup parameters for the backup and restoration scripts provided with tar.  You must edit backup-specs to fit your system configuration and schedule before using these scripts.

ADMINISTRATOR
     The user name of the backup administrator.

BACKUP_HOUR
     The hour at which the backups are done.  This can be a number from 0 to 23, or the string now.

TAPE_FILE
     The device tar writes the archive to.  This device should be attached to the host on which the dump scripts are run.

TAPE_STATUS
     The command to use to obtain the status of the archive device, including error count.  On some tape drives there may not be such a command; in that case, simply use `TAPE_STATUS=false'.

BLOCKING
     The blocking factor tar will use when writing the dump archive. See Blocking Factor.

BACKUP_DIRS
     A list of file systems to be dumped.  You can include any directory name in the list---subdirectories on that file system will be included, regardless of how they may look to other networked machines. Subdirectories on other file systems will be ignored.

     The host name specifies which host to run tar on, and should normally be the host that actually contains the file system.  However, the host machine must have GNU tar installed, and must be able to access the directory containing the backup scripts and their support files using the same file name that is used on the machine where the scripts are run (ie. what pwd will print when in that directory on that machine).  If the host that contains the file system does not have this capability, you can specify another host as long as it can access the file system through NFS.

BACKUP_FILES
     A list of individual files to be dumped.  These should be accessible from the machine on which the backup script is run.

An Example Text of Backup-specs
...............................

The following is the text of backup-specs as it appears at FSF:

     # site-specific parameters for file system backup.

     ADMINISTRATOR=friedman
     BACKUP_HOUR=1
     TAPE_FILE=/dev/nrsmt0
     TAPE_STATUS="mts -t $TAPE_FILE"
     BLOCKING=124
     BACKUP_DIRS="
     	albert:/fs/fsf
     	apple-gunkies:/gd
     	albert:/fs/gd2
     	albert:/fs/gp
     	geech:/usr/jla
     	churchy:/usr/roland
     	albert:/
     	albert:/usr
     	apple-gunkies:/
     	apple-gunkies:/usr
     	gnu:/hack
     	gnu:/u
     	apple-gunkies:/com/mailer/gnu
     	apple-gunkies:/com/archive/gnu"

     BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"

Syntax for Backup-specs
.......................

backup-specs is in shell script syntax.  The following conventions should be considered when editing the script:

A quoted string is considered to be contiguous, even if it is on more than one line.  Therefore, you cannot include commented-out lines within a multi-line quoted string.  BACKUP_FILES and BACKUP_DIRS are the two most likely parameters to be multi-line.

A quoted string typically cannot contain wildcards.  In backup-specs, however, the parameters BACKUP_DIRS and BACKUP_FILES can contain wildcards.

Using the Backup Scripts
------------------------

The syntax for running a backup script is:

     script-name [TIME-TO-BE-RUN]

where TIME-TO-BE-RUN can be a specific system time, or can be now.  If you do not specify a time, the script runs at the time specified in backup-specs (see Script Syntax).

You should start a script with a tape or disk mounted.  Once you start a script, it prompts you for new tapes or disks as it needs them. Media volumes don't have to correspond to archive files---a multi-volume archive can be started in the middle of a tape that already contains the end of another multi-volume archive.  The restore script prompts for media by its archive volume, so to avoid an error message you should keep track of which tape (or disk) contains which volume of the archive.  See Scripted Restoration.

The backup scripts write two files on the file system.  The first is a record file in /etc/tar-backup/, which is used by the scripts to store and retrieve information about which files were dumped.  This file is not meant to be read by humans, and should not be deleted by them.  See incremental and listed-incremental, for a more detailed explanation of this file.

The second file is a log file containing the names of the file systems and files dumped, what time the backup was made, and any error messages that were generated, as well as how much space was left in the media volume after the last volume of the archive was written. You should check this log file after every backup.  The file name is log-MMM-DDD-YYYY-level-1 or log-MMM-DDD-YYYY-full.

The script also prints the name of each system being dumped to the standard output.

The --incremental and --listed-incremental Options
==================================================

--incremental is used in conjunction with --create, --extract or --list when backing up and restoring file systems.  An archive cannot be extracted or listed with the --incremental option specified unless it was created with the option specified.  This option should only be used by a script, not by the user, and is usually disregarded in favor of --listed-incremental, which is described below.

--incremental in conjunction with --create causes tar to write, at the beginning of the archive, an entry for each of the directories that will be archived.  The entry for a directory includes a list of all the files in the directory at the time the archive was created and a flag for each file indicating whether or not the file is going to be put in the archive.

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

--incremental in conjunction with --extract causes tar to read the lists of directory contents previously stored in the archive, delete files in the file system that did not exist in their directories when the archive was created, and then extract the files in the archive.

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

--incremental in conjunction with --list, causes tar to print, for each directory in the archive, the list of files in that directory at the time the archive was created.  This information is put out in a format that is not easy for humans to read, but which is unambiguous for a program: each file name is preceded by either a Y if the file is present in the archive, an N if the file is not included in the archive, or a D if the file is a directory (and is included in the archive).  Each file name is terminated by a null character.  The last file is followed by an additional null and a newline to indicate the end of the data.

--listed-incremental=FILE acts like --incremental, but when used in conjunction with --create will also cause tar to use the file FILE, which contains information about the state of the file system at the time of the last backup, to decide which files to include in the archive being created.  That file will then be updated by tar.  If the file FILE does not exist when this option is specified, tar will create it, and include all appropriate files in the archive.

The file FILE, which is archive independent, contains the date it was last modified and a list of devices, inode numbers and directory names.  tar will archive files with newer mod dates or inode change times, and directories with an unchanged inode number and device but a changed directory name.  The file is updated after the files to be archived are determined, but before the new archive is actually created.

Some Common Problems and their Solutions
========================================

errors from system: permission denied no such file or directory not owner

errors from tar: directory checksum error header format error

errors from media/system: i/o error device busy

Tapes and Other Archive Media
*****************************

Archives are usually written on dismountable media---tape cartridges, mag tapes, or floppy disks.

The amount of data a tape or disk holds depends not only on its size, but also on how it is formatted.  A 2400 foot long reel of mag tape holds 40 megabytes of data when formated at 1600 bits per inch.  The physically smaller EXABYTE tape cartridge holds 2.3 gigabytes.

Magnetic media are re-usable---once the archive on a tape is no longer needed, the archive can be erased and the tape or disk used over. Media quality does deteriorate with use, however.  Most tapes or disks should be disgarded when they begin to produce data errors.  EXABYTE tape cartridges should be disgarded when they generate an error count (number of non-usable bits) of more than 10k.

Magnetic media are written and erased using magnetic fields, and should be protected from such fields to avoid damage to stored data. Sticking a floppy disk to a filing cabinet using a magnet is probably not a good idea.

Write Protection
================

All tapes and disks can be write protected, to protect data on them from being changed.  Once an archive is written, you should write protect the media to prevent the archive from being accidently overwritten or deleted.  (This will protect the archive from being changed with a tape or floppy drive---it will not protect it from magnet fields or other physical hazards).

The write protection device itself is usually an integral part of the physical media, and can be a two position (write enabled/write disabled) switch, a notch which can be popped out or covered, a ring which can be removed from the center of a tape reel, or some other changeable feature.

Tape Positions and Tape Marks
=============================

Just as archives can store more than one file from the file system, tapes can store more than one archive file.  To keep track of where archive files (or any other type of file stored on tape) begin and end, tape archive devices write magnetic tape marks on the archive media.  Tape drives write one tape mark between files, two at the end of all the file entries.

If you think of data as a series of "0000"'s, and tape marks as "x"'s, a tape might look like the following:

     0000x000000x00000x00x00000xx-------------------------

Tape devices read and write tapes using a read/write tape head---a physical part of the device which can only access one point on the tape at a time.  When you use tar to read or write archive data from a tape device, the device will begin reading or writing from wherever on the tape the tape head happens to be, regardless of which archive or what part of the archive the tape head is on.  Before writing an archive, you should make sure that no data on the tape will be overwritten (unless it is no longer needed). Before reading an archive, you should make sure the tape head is at the beginning of the archive you want to read.  (The restore script will find the archive automatically.  See Scripted Restoration).  See mt, for an explanation of the tape moving utility.

If you want to add new archive file entries to a tape, you should advance the tape to the end of the existing file entries, backspace over the last tape mark, and write the new archive file.  If you were to add two archives to the example above, the tape might look like the following:

     0000x000000x00000x00x00000x000x0000xx----------------

The mt Utility
--------------

<<< is it true that this only works on non-block devices?  should <<< explain the difference, xref to block-size (fixed or variable).

You can use the mt utility to advance or rewind a tape past a specified number of archive files on the tape.  This will allow you to move to the beginning of an archive before extracting or reading it, or to the end of all the archives before writing a new one.

The syntax of the mt command is:

     mt [-f TAPENAME] OPERATION [NUMBER]

where TAPENAME is the name of the tape device, NUMBER is the number of times an operation is performed (with a default of one), and OPERATION is one of the following:

eof
weof
     Writes NUMBER tape marks at the current position on the tape.

fsf
     Moves tape position forward NUMBER files.

bsf
     Moves tape position back NUMBER files.

rewind
     Rewinds the tape. (Ignores NUMBER).

offline
rewoff1
     Rewinds the tape and takes the tape device off-line. (Ignores NUMBER).

status
     Prints status information about the tape unit.

<<< is there a better way to frob the spacing on the list?  -ringo

If you don't specify a TAPENAME, mt uses the environment variable TAPE; if TAPE does not exist, mt uses the device /dev/rmt12.

mt returns a 0 exit status when the operation(s) were successful, 1 if the command was unrecognized, and 2 if an operation failed.

If you use tar --extract with the --label=ARCHIVE-NAME option specified, tar will read an archive label (the tape head has to be positioned on it) and print an error if the archive label doesn't match the ARCHIVE-NAME specified.  ARCHIVE-NAME can be any regular expression.  If the labels match, tar extracts the archive. See Archive Label.  See Matching Format Parameters. <<< fix cross references

tar --list --label will cause tar to print the label.

A Quick Reference Guide to tar Operations and Options
*****************************************************

A Table of Operations
=====================

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.

--add-archive
     Adds copies of an archive or archives to the end of another archive.

--add-file
     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.

--help
     Prints a list of tar operations and options.

--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.

Table of Options
================

Options change the way tar performs an operation.

--absolute-paths
     WILL BE INPUT WHEN QUESTION IS RESOLVED

--after-date=DATE
     Limit the operation to files changed after the given date. See File Exclusion.

--block-size=NUMBER
     Specify the blocking factor of an archive.  See Blocking Factor.

--compress
     Specify a compressed archive.  See Compressed Archives.

--compress-block.
     Create a whole block sized compressed archive.  See Compressed Archives.

--confirmation
     Solicit confirmation for each file.  See Interactive Operation <<< --selective should be a synonym.

--dereference
     Treat a symbolic link as an alternate name for the file the link points to.  See Symbolic Links.

--directory=directory
     Change the working directory.  See Changing Working Directory.

--exclude=PATTERN
     Exclude files which match the regular expression PATTERN. See File Exclusion.

--exclude-from=file
     Exclude files which match any of the regular expressions listed in the file file.  See File Exclusion.

--file=ARCHIVE-NAME
     Name the archive.  See Archive Name).

--files-from=file
     Read file-name arguments from a file on the file system. See File Name Lists.

--ignore-umask
     Set modes of extracted files to those recorded in the archive. See File Writing Options.

--ignore-zeros
     Ignore end-of-archive entries.  See Archive Reading Options. <<< this should be changed to --ignore-end

--listed-incremental=FILE-NAME   (-g)
     Take a file name argument always.  If the file doesn't exist, run a level zero dump, creating the file.  If the file exists, uses that file to see what has changed.

--incremental (-G)

--tape-length=N  (-L)

--info-script=PROGRAM-FILE
     Create a multi-volume archive via a script.  See Multi-Volume Archives.

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

--keep-old-files
     Prevent overwriting during extraction.  See File Writing Options.

--label=ARCHIVE-LABEL
     Include an archive-label in the archive being created.  See Archive Label.

--modification-time
     Set the modification time of extracted files to the time they were extracted.  See File Writing Options.

--multi-volume
     Specify a multi-volume archive.  See Multi-Volume Archives.

--newer=DATE
     Limit the operation to files changed after the given date. See File Exclusion.

--newer-mtime=DATE
     Limit the operation to files modified after the given date.  See File Exclusion.

--old
     Create an old format archive.  See Old Style File Information.

--old-archive
     Create an old format archive.  See Old Style File Information.

--one-file-system
     Prevent tar from crossing file system boundaries when archiving.  See File Exclusion.

--portable
     Create an old format archive.  See Old Style File Information.

--preserve-order
     Help process large lists of file-names on machines with small amounts of memory.  See Archive Reading Options.

--preserve-permission
     Set modes of extracted files to those recorded in the archive. See File Writing Options.

--read-full-blocks
     Read an archive with a smaller than specified block size or which contains incomplete blocks.  See Archive Reading Options).

--record-number
     Print the record number where a message is generated. See Additional Information.

--same-order
     Help process large lists of file-names on machines with small amounts of memory.  See Archive Reading Options.

--same-permission
     Set the modes of extracted files to those recorded in the archive. See File Writing Options.

--sparse
     Archive sparse files sparsely.  See Sparse Files.

--starting-file=FILE-NAME
     Begin reading in the middle of an archive.  See Scarce Disk Space.

--to-stdout
     Write files to the standard output.  See File Writing Options.

--uncompress
     Specifdo  a compressed archive.  See Compressed Archives.

-V ARCHIVE-LABEL
     Include an archive-label in the archive being created.  See Archive Label.

--verbose
     Print the names of files or archive members as they are being operated on.  See Additional Information.

--verify
     Check for discrepancies in the archive immediately after it is written.  See Write Verification.

-B
     Read an archive with a smaller than specified block size or which contains incomplete blocks.  See Archive Reading Options).

-K FILE-NAME
     Begin reading in the middle of an archive.  See Scarce Disk Space.

-M
     Specify a multi-volume archive.  See Multi-Volume Archives.

-N DATE
     Limit operation to files changed after the given date.  See File Exclusion.

-O
     Write files to the standard output.  See File Writing Options.

-R
     Print the record number where a message is generated. See Additional Information.

-S
     Archive sparse files sparsely.  See Sparse Files.

-T FILE
     Read file-name arguments from a file on the file system. See File Name Lists.

-W
     Check for discrepancies in the archive immediately after it is written.  See Write Verification.

-Z
     Specify a compressed archive.  See Compressed Archives.

-b NUMBER
     Specify the blocking factor of an archive.  See Blocking Factor.

-f ARCHIVE-NAME
     Name the archive.  See Archive Name).

-h
     Treat a symbolic link as an alternate name for the file the link points to.  See Symbolic Links.

-i
     Ignore end-of-archive entries.  See Archive Reading Options.

-k
     Prevent overwriting during extraction.  See File Writing Options.

-l
     Prevent tar from crossing file system boundaries when archiving.  See File Exclusion.

-m
     Set the modification time of extracted files to the time they were extracted.  See File Writing Options.

-o
     Create an old format archive.  See Old Style File Information.

-p
     Set the modes of extracted files to those recorded in the archive. See File Writing Options.

-s
     Help process large lists of file-names on machines with small amounts of memory.  See Archive Reading Options.

-v
     Print the names of files or archive members they are being operated on.  See Additional Information.

-w

-z
     Specify a compressed archive.  See Compressed Archives.

-z -z
     Create a whole block sized compressed archive.  See Compressed Archives.

-C directory
     Change the working directory.  See Changing Working Directory.

-F PROGRAM-FILE
     Create a multi-volume archive via a script.  See Multi-Volume Archives.

-X file
     Exclude files which match any of the regular expressions listed in the file file.  See File Exclusion.

Details of the Archive Data Format
**********************************

This chapter is based heavily on John Gilmore's tar(5) manual page for the public domain tar that GNU tar is based on.

The archive media contains a series of records, each of which contains 512 bytes.  Each archive member is represented by a header record, which describes the file, followed by zero or more records which represent the contents of the file.  At the end of the archive file there may be a record consisting of a series of binary zeros, as an end-of-archive marker.  GNU tar writes a record of zeros at the end of an archive, but does not assume that such a record exists when reading an archive.

Records may be grouped into blocks for I/O operations.  A block of records is written with a single write() operation.  The number of records in a block is specified using the --block-size option.  See Blocking Factor, for more information about specifying block size.

The Distribution of Data in the Header
======================================

The header record is defined in C as follows:

     Standard Archive Format - Standard TAR - USTAR

     #define RECORDSIZE  	512
     #define NAMSIZ      	100
     #define TUNMLEN      	32
     #define TGNMLEN      	32
     #define SPARSE_EXT_HDR	21
     #define	SPARSE_IN_HDR	4

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

     union record {
         char        charptr[RECORDSIZE];
         struct header {
             char    name[NAMSIZ];
             char    mode[8];
             char    uid[8];
             char    gid[8];
             char    size[12];
             char    mtime[12];
             char    chksum[8];
             char    linkflag;
             char    linkname[NAMSIZ];
             char    magic[8];
             char    uname[TUNMLEN];
             char    gname[TGNMLEN];
             char    devmajor[8];
             char    devminor[8];

     The following fields were added by gnu and are not used by other
     versions of tar.
             char	atime[12];
             char	ctime[12];
             char	offset[12];
             char	longnames[4];
     The next three fields were added by gnu to deal with shrinking down
     sparse files.
             struct	sparse sp[SPARSE_IN_HDR];
             char	isextended;
     This is the number of nulls at the end of the file, if any.
             char	ending_blanks[12];

         } header;

         struct extended_header {
             struct sparse sp[21];
             char isextended;
         } ext_hdr;

     };

     The checksum field is filled with this while the checksum is computed.
     #define    CHKBLANKS    "        "        8 blanks, no null

     Inclusion of this field marks an archive as being in standard
     Posix format (though GNU tar itself is not Posix conforming).  GNU
     tar puts "ustar" in this field if uname and gname are valid.
     #define    TMAGIC    "ustar  "        7 chars and a null

     The magic field is filled with this if this is a GNU format dump entry.
     #define    GNUMAGIC  "GNUtar "        7 chars and a null

     The linkflag defines the type of file.
     #define  LF_OLDNORMAL '\0'       Normal disk file, Unix compatible
     #define  LF_NORMAL    '0'        Normal disk file
     #define  LF_LINK      '1'        Link to previously dumped file
     #define  LF_SYMLINK   '2'        Symbolic link
     #define  LF_CHR       '3'        Character special file
     #define  LF_BLK       '4'        Block special file
     #define  LF_DIR       '5'        Directory
     #define  LF_FIFO      '6'        FIFO special file
     #define  LF_CONTIG    '7'        Contiguous file

     hhe following are further link types which were defined later.

     This is a dir entry that contains the names of files that were in
     the dir at the time the dump was made.
     #define LF_DUMPDIR	'D'

     This is the continuation of a file that began on another volume
     #define LF_MULTIVOL	'M'

     This is for sparse files
     #define LF_SPARSE	'S'

     This file is a tape/volume header. Ignore it on extraction.
     #define LF_VOLHDR	'V'

     These are bits used in the mode field - the values are in octal
     #define  TSUID    04000        Set UID on execution
     #define  TSGID    02000        Set GID on execution
     #define  TSVTX    01000        Save text (sticky bit)

     These are file permissions
     #define  TUREAD   00400        read by owner
     #define  TUWRITE  00200        write by owner
     #define  TUEXEC   00100        execute/search by owner
     #define  TGREAD   00040        read by group
     #define  TGWRITE  00020        write by group
     #define  TGEXEC   00010        execute/search by group
     #define  TOREAD   00004        read by other
     #define  TOWRITE  00002        write by other
     #define  TOEXEC   00001        execute/search by other

All characters in headers are 8-bit characters in the local variant of ASCII.  Each field in the header is contiguous; that is, there is no padding in the header format.

Data representing the contents of files is not translated in any way and is not constrained to represent characters in any character set. tar does not distinguish between text files and binary files.

The name, linkname, magic, uname, and gname fields contain null-terminated character strings.  All other fields contain zero-filled octal numbers in ASCII.  Each numeric field of width W contains W - 2 digits, a space, and a null, except size and mtime, which do not contain the trailing null.

The Meaning of Header Fields
============================

The name field contains the name of the file. <<< how big a name before field overflows?

The mode field contains nine bits which specify file permissions, and three bits which specify the Set UID, Set GID, and Save Text (``stick'') modes.  Values for these bits are defined above. See File Writing Options, for information on how file permissions and modes are used by tar.

The uid and gid fields contain the numeric user and group IDs of the file owners.  If the operating system does not support numeric user or group IDs, these fields should be ignored.

The size field contains the size of the file in bytes; this field contains a zero if the header describes a link to a file.

The mtime field contains the modification time of the file. This is the ASCII representation of the octal value of the last time the file was modified, represented as an integer number of seconds since January 1, 1970, 00:00 Coordinated Universal Time. See File Writing Options, for a description of how tar uses this information.

The chksum field contains the ASCII representation of the octal value of the simple sum of all bytes in the header record.  To generate this sum, each 8-bit byte in the header is added to an unsigned integer, which has been initialized to zero.  The precision of the integer is seventeen bits.  When calculating the checksum, the chksum field itself is treated as blank.

The atime and ctime fields are used when making incremental backups; they store, respectively, the file's access time and last inode-change time.

The value in the offset field is used when making a multi-volume archive.  The offset is number of bytes into the file that we need to go to pick up where we left off in the previous volume, i.e the location that a continued file is continued from.

The longnames field supports a feature that is not yet implemented.  This field should be empty.

The magic field indicates that this archive was output in the P1003 archive format.  If this field contains TMAGIC, the uname and gname fields will contain the ASCII representation of the owner and group of the file respectively.  If found, the user and group IDs are used rather than the values in the uid and gid fields.

The sp field is used to archive sparse files efficiently. See Sparse File Handling, for a description of this field, and other fields it may imply.

The typeflag field specifies the file's type.  If a particular implementation does not recognize or permit the specified type, tar extracts the file as if it were a regular file, and reports the discrepancy on the standard error.  See File Types.  See GNU File Types.

File Types
----------

The following flags are used to describe file types:

LF_NORMAL
LF_OLDNORMAL
     Indicates a regular file.  In order to be compatible with older versions of tar, a typeflag value of LF_OLDNORMAL should be silently recognized as a regular file.  New archives should be created using LF_NORMAL for regular files.  For backward compatibility, tar treats a regular file whose name ends with a slash as a directory.

LF_LINK
     Indicates a link to another file, of any type, which has been previously archived.  tar identifies linked files in Unix by matching device and inode numbers.  The linked-to name is specified in the linkname field with a trailing null.

LF_SYMLINK
     Indicates a symbolic link to another file.  The linked-to name is specified in the linkname field with a trailing null. See File Writing Options, for information on archiving files referenced by a symbolic link.

LF_CHR
LF_BLK
     Indicate character special files and block special files, respectively.  In this case the devmajor and devminor fields will contain the major and minor device numbers.  Operating systems may map the device specifications to their own local specification, or may ignore the entry.

LF_DIR
     Indicates a directory or sub-directory.  The directory name in the name field should end with a slash.  On systems where disk allocation is performed on a directory basis, the size field will contain the maximum number of bytes (which may be rounded to the nearest disk block allocation unit) that the directory can hold.  A size field of zero indicates no size limitations.  Systems that do not support size limiting in this manner should ignore the size field.

LF_FIFO
     Indicates a FIFO special file.  Note that archiving a FIFO file archives the existence of the file and not its contents.

LF_CONTIG
     Indicates a contiguous file.  Contiguous files are the same as normal files except that, in operating systems that support it, all the files' disk space is allocated contiguously.  Operating systems which do not allow contiguous allocation should silently treat this type as a normal file.

'A' ...
'Z'
     These are reserved for custom implementations.  Some of these are used in the GNU modified format, which is described below.  See GNU File Types.

Certain other flag values are reserved for specification in future revisions of the P1003 standard, and should not be used by any tar program.

Additional File Types Supported by GNU
--------------------------------------

GNU tar uses additional file types to describe new types of files in an archive.  These are listed below.

LF_DUMPDIR
'D'
     Indicates a directory and a list of files created by the --incremental option.  The size field gives the total size of the associated list of files.  Each file name is preceded by either a 'Y' (the file should be in this archive) or an 'N' (the file is a directory, or is not stored in the archive). Each file name is terminated by a null.  There is an additional null after the last file name.

LF_MULTIVOL
'M'
     Indicates a file continued from another volume of a multi-volume archive (see Multi-Volume Archives).  The original type of the file is not given here.  The size field gives the maximum size of this piece of the file (assuming the volume does not end before the file is written out).  The offset field gives the offset from the beginning of the file where this part of the file begins.  Thus size plus offset should equal the original size of the file.

LF_SPARSE
'S'
     Indicates a sparse file.  See Sparse Files.  See Sparse File Handling.

LF_VOLHDR
'V'
     Marks an archive label that was created using the --label option when the archive was created (see Archive Label.  The name field contains the argument to the option.  The size field is zero.  Only the first file in each volume of an archive should have this type.

Fields to Handle Sparse Files
=============================

The following header information was added to deal with sparse files (see Sparse Files):

The sp field (fields? something else?) is an array of struct sparse.  Each struct sparse contains two 12-character strings, which represent the offset into the file and the number of bytes to be written at that offset.  The offset is absolute, and not relative to the offset in preceding array elements.

The header can contain four of these struct sparse; if more are needed, they are not stored in the header, instead, the flag isextended is set and the next record is an extended_header.

The isextended flag is only set for sparse files, and then only if extended header records are needed when archiving the file.

Each extended header record can contain an array of 21 sparse structures, as well as another isextended flag.  There is no limit (except that implied by the archive media) on the number of extended header records that can be used to describe a sparse file.