+@option{--info-script}
+
+@item -G
+
+@option{--incremental}
+
+@item -K
+
+@option{--starting-file}
+
+@item -L
+
+@option{--tape-length}
+
+@item -M
+
+@option{--multi-volume}
+
+@item -N
+
+@option{--newer}
+
+@item -O
+
+@option{--to-stdout}
+
+@item -P
+
+@option{--absolute-names}
+
+@item -R
+
+@option{--block-number}
+
+@item -S
+
+@option{--sparse}
+
+@item -T
+
+@option{--files-from}
+
+@item -U
+
+@option{--unlink-first}
+
+@item -V
+
+@option{--label}
+
+@item -W
+
+@option{--verify}
+
+@item -X
+
+@option{--exclude-from}
+
+@item -Z
+
+@option{--compress}
+
+@item -b
+
+@option{--blocking-factor}
+
+@item -c
+
+@option{--create}
+
+@item -d
+
+@option{--compare}
+
+@item -f
+
+@option{--file}
+
+@item -g
+
+@option{--listed-incremental}
+
+@item -h
+
+@option{--dereference}
+
+@item -i
+
+@option{--ignore-zeros}
+
+@item -j
+
+@option{--bzip2}
+
+@item -k
+
+@option{--keep-old-files}
+
+@item -l
+
+@option{--one-file-system}. Use of this short option is deprecated. It
+is retained for compatibility with the earlier versions of GNU
+@command{tar}, and will be changed in future releases.
+
+@xref{Changes}, for more information.
+
+@item -m
+
+@option{--touch}
+
+@item -o
+
+When creating --- @option{--no-same-owner}, when extracting ---
+@option{--portability}.
+
+The later usage is deprecated. It is retained for compatibility with
+the earlier versions of @GNUTAR{}. In the future releases
+@option{-o} will be equivalent to @option{--no-same-owner} only.
+
+@item -p
+
+@option{--preserve-permissions}
+
+@item -r
+
+@option{--append}
+
+@item -s
+
+@option{--same-order}
+
+@item -t
+
+@option{--list}
+
+@item -u
+
+@option{--update}
+
+@item -v
+
+@option{--verbose}
+
+@item -w
+
+@option{--interactive}
+
+@item -x
+
+@option{--extract}
+
+@item -z
+
+@option{--gzip}
+
+@end table
+
+@node help
+@section @GNUTAR{} documentation
+
+@cindex Getting program version number
+@opindex version
+@cindex Version of the @command{tar} program
+Being careful, the first thing is really checking that you are using
+@GNUTAR{}, indeed. The @option{--version} option
+causes @command{tar} to print information about its name, version,
+origin and legal status, all on standard output, and then exit
+successfully. For example, @w{@samp{tar --version}} might print:
+
+@smallexample
+tar (GNU tar) 1.15.2
+Copyright (C) 2006 Free Software Foundation, Inc.
+This is free software. You may redistribute copies of it under the terms of
+the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
+There is NO WARRANTY, to the extent permitted by law.
+
+Written by John Gilmore and Jay Fenlason.
+@end smallexample
+
+@noindent
+The first occurrence of @samp{tar} in the result above is the program
+name in the package (for example, @command{rmt} is another program),
+while the second occurrence of @samp{tar} is the name of the package
+itself, containing possibly many programs. The package is currently
+named @samp{tar}, after the name of the main program it
+contains@footnote{There are plans to merge the @command{cpio} and
+@command{tar} packages into a single one which would be called
+@code{paxutils}. So, who knows if, one of this days, the
+@option{--version} would not output @w{@samp{tar (@acronym{GNU}
+paxutils) 3.2}}}.
+
+@cindex Obtaining help
+@cindex Listing all @command{tar} options
+@opindex help, introduction
+Another thing you might want to do is checking the spelling or meaning
+of some particular @command{tar} option, without resorting to this
+manual, for once you have carefully read it. @GNUTAR{}
+has a short help feature, triggerable through the
+@option{--help} option. By using this option, @command{tar} will
+print a usage message listing all available options on standard
+output, then exit successfully, without doing anything else and
+ignoring all other options. Even if this is only a brief summary, it
+may be several screens long. So, if you are not using some kind of
+scrollable window, you might prefer to use something like:
+
+@smallexample
+$ @kbd{tar --help | less}
+@end smallexample
+
+@noindent
+presuming, here, that you like using @command{less} for a pager. Other
+popular pagers are @command{more} and @command{pg}. If you know about some
+@var{keyword} which interests you and do not want to read all the
+@option{--help} output, another common idiom is doing:
+
+@smallexample
+tar --help | grep @var{keyword}
+@end smallexample
+
+@noindent
+for getting only the pertinent lines. Notice, however, that some
+@command{tar} options have long description lines and the above
+command will list only the first of them.
+
+The exact look of the option summary displayed by @kbd{tar --help} is
+configurable. @xref{Configuring Help Summary}, for a detailed description.
+
+@opindex usage
+If you only wish to check the spelling of an option, running @kbd{tar
+--usage} may be a better choice. This will display a terse list of
+@command{tar} option without accompanying explanations.
+
+The short help output is quite succinct, and you might have to get
+back to the full documentation for precise points. If you are reading
+this paragraph, you already have the @command{tar} manual in some
+form. This manual is available in a variety of forms from
+@url{http://www.gnu.org/software/tar/manual}. It may printed out of the @GNUTAR{}
+distribution, provided you have @TeX{} already installed somewhere,
+and a laser printer around. Just configure the distribution, execute
+the command @w{@samp{make dvi}}, then print @file{doc/tar.dvi} the
+usual way (contact your local guru to know how). If @GNUTAR{}
+has been conveniently installed at your place, this
+manual is also available in interactive, hypertextual form as an Info
+file. Just call @w{@samp{info tar}} or, if you do not have the
+@command{info} program handy, use the Info reader provided within
+@acronym{GNU} Emacs, calling @samp{tar} from the main Info menu.
+
+There is currently no @code{man} page for @GNUTAR{}.
+If you observe such a @code{man} page on the system you are running,
+either it does not belong to @GNUTAR{}, or it has not
+been produced by @acronym{GNU}. Some package maintainers convert
+@kbd{tar --help} output to a man page, using @command{help2man}. In
+any case, please bear in mind that the authoritative source of
+information about @GNUTAR{} is this Texinfo documentation.
+
+@node defaults
+@section Obtaining @GNUTAR{} default values
+
+@opindex show-defaults
+@GNUTAR{} has some predefined defaults that are used when you do not
+explicitely specify another values. To obtain a list of such
+defaults, use @option{--show-defaults} option. This will output the
+values in the form of @command{tar} command line options:
+
+@smallexample
+@group
+@kbd{tar --show-defaults}
+--format=gnu -f- -b20 --rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
+@end group
+@end smallexample
+
+@noindent
+The above output shows that this version of @GNUTAR{} defaults to
+using @samp{gnu} archive format (@pxref{Formats}), it uses standard
+output as the archive, if no @option{--file} option has been given
+(@pxref{file tutorial}), the default blocking factor is 20
+(@pxref{Blocking Factor}). It also shows the default locations where
+@command{tar} will look for @command{rmt} and @command{rsh} binaries.
+
+@node verbose
+@section Checking @command{tar} progress
+
+Typically, @command{tar} performs most operations without reporting any
+information to the user except error messages. When using @command{tar}
+with many options, particularly ones with complicated or
+difficult-to-predict behavior, it is possible to make serious mistakes.
+@command{tar} provides several options that make observing @command{tar}
+easier. These options cause @command{tar} to print information as it
+progresses in its job, and you might want to use them just for being
+more careful about what is going on, or merely for entertaining
+yourself. If you have encountered a problem when operating on an
+archive, however, you may need more information than just an error
+message in order to solve the problem. The following options can be
+helpful diagnostic tools.
+
+@cindex Verbose operation
+@opindex verbose
+Normally, the @option{--list} (@option{-t}) command to list an archive
+prints just the file names (one per line) and the other commands are
+silent. When used with most operations, the @option{--verbose}
+(@option{-v}) option causes @command{tar} to print the name of each
+file or archive member as it is processed. This and the other options
+which make @command{tar} print status information can be useful in
+monitoring @command{tar}.
+
+With @option{--create} or @option{--extract}, @option{--verbose} used
+once just prints the names of the files or members as they are processed.
+Using it twice causes @command{tar} to print a longer listing
+(reminiscent of @samp{ls -l}) for each member. Since @option{--list}
+already prints the names of the members, @option{--verbose} used once
+with @option{--list} causes @command{tar} to print an @samp{ls -l}
+type listing of the files in the archive. The following examples both
+extract members with long list output:
+
+@smallexample
+$ @kbd{tar --extract --file=archive.tar --verbose --verbose}
+$ @kbd{tar xvvf archive.tar}
+@end smallexample
+
+Verbose output appears on the standard output except when an archive is
+being written to the standard output, as with @samp{tar --create
+--file=- --verbose} (@samp{tar cfv -}, or even @samp{tar cv}---if the
+installer let standard output be the default archive). In that case
+@command{tar} writes verbose output to the standard error stream.
+
+If @option{--index-file=@var{file}} is specified, @command{tar} sends
+verbose output to @var{file} rather than to standard output or standard
+error.
+
+@cindex Obtaining total status information
+@opindex totals
+The @option{--totals} option---which is only meaningful when used with
+@option{--create} (@option{-c})---causes @command{tar} to print the total
+amount written to the archive, after it has been fully created.
+
+@cindex Progress information
+@opindex checkpoint
+The @option{--checkpoint} option prints an occasional message
+as @command{tar} reads or writes the archive. In fact, it prints
+a message each 10 records read or written. It is designed for
+those who don't need the more detailed (and voluminous) output of
+@option{--block-number} (@option{-R}), but do want visual confirmation that @command{tar}
+is actually making forward progress.
+
+@FIXME{There is some confusion here. It seems that -R once wrote a
+message at @samp{every} record read or written.}
+
+@opindex show-omitted-dirs
+@anchor{show-omitted-dirs}
+The @option{--show-omitted-dirs} option, when reading an archive---with
+@option{--list} or @option{--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 @option{--exclude=@var{pattern}} option, or
+some other reason.
+
+@opindex block-number
+@cindex Block number where error occurred
+@anchor{block-number}
+If @option{--block-number} (@option{-R}) is used, @command{tar} prints, along with
+every message it would normally produce, the block number within the
+archive where the message was triggered. Also, supplementary messages
+are triggered when reading blocks full of NULs, or when hitting end of
+file on the archive. As of now, if the archive if properly terminated
+with a NUL block, the reading of the file may stop before end of file
+is met, so the position of end of file will not usually show when
+@option{--block-number} (@option{-R}) is used. Note that @GNUTAR{}
+drains the archive before exiting when reading the
+archive from a pipe.
+
+@cindex Error message, block number of
+This option is especially useful when reading damaged archives, since
+it helps pinpoint the damaged sections. It can also be used with
+@option{--list} (@option{-t}) when listing a file-system backup tape, allowing you to
+choose among several backup tapes when retrieving a file later, in
+favor of the tape where the file appears earliest (closest to the
+front of the tape). @xref{backup}.
+
+@node interactive
+@section Asking for Confirmation During Operations
+@cindex Interactive operation
+
+Typically, @command{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 (@pxref{Choosing}), or by performing
+an operation interactively, using the @option{--interactive} (@option{-w}) option.
+@command{tar} also accepts @option{--confirmation} for this option.
+
+@opindex interactive
+When the @option{--interactive} (@option{-w}) option is specified, before
+reading, writing, or deleting files, @command{tar} first prints a message
+for each such file, telling what operation it intends to take, then asks
+for confirmation on the terminal. The actions which require
+confirmation include adding a file to the archive, extracting a file
+from the archive, deleting a file from the archive, and deleting a file
+from disk. To confirm the action, you must type a line of input
+beginning with @samp{y}. If your input line begins with anything other
+than @samp{y}, @command{tar} skips that file.
+
+If @command{tar} is reading the archive from the standard input,
+@command{tar} opens the file @file{/dev/tty} to support the interactive
+communications.
+
+Verbose output is normally sent to standard output, separate from
+other error messages. However, if the archive is produced directly
+on standard output, then verbose output is mixed with errors on
+@code{stderr}. Producing the archive on standard output may be used
+as a way to avoid using disk space, when the archive is soon to be
+consumed by another process reading it, say. Some people felt the need
+of producing an archive on stdout, still willing to segregate between
+verbose output and error output. A possible approach would be using a
+named pipe to receive the archive, and having the consumer process to
+read from that named pipe. This has the advantage of letting standard
+output free to receive verbose output, all separate from errors.
+
+@node operations
+@chapter @GNUTAR{} Operations
+
+@menu
+* Basic tar::
+* Advanced tar::
+* create options::
+* extract options::
+* backup::
+* Applications::
+* looking ahead::
+@end menu
+
+@node Basic tar
+@section Basic @GNUTAR{} Operations
+
+The basic @command{tar} operations, @option{--create} (@option{-c}),
+@option{--list} (@option{-t}) and @option{--extract} (@option{--get},
+@option{-x}), are currently presented and described in the tutorial
+chapter of this manual. This section provides some complementary notes
+for these operations.
+
+@table @option
+@opindex create, complementary notes
+@item --create
+@itemx -c
+
+Creating an empty archive would have some kind of elegance. One can
+initialize an empty archive and later use @option{--append}
+(@option{-r}) for adding all members. Some applications would not
+welcome making an exception in the way of adding the first archive
+member. On the other hand, many people reported that it is
+dangerously too easy for @command{tar} to destroy a magnetic tape with
+an empty archive@footnote{This is well described in @cite{Unix-haters
+Handbook}, by Simson Garfinkel, Daniel Weise & Steven Strassmann, IDG
+Books, ISBN 1-56884-203-1.}. The two most common errors are:
+
+@enumerate
+@item
+Mistakingly using @code{create} instead of @code{extract}, when the
+intent was to extract the full contents of an archive. This error
+is likely: keys @kbd{c} and @kbd{x} are right next to each other on
+the QWERTY keyboard. Instead of being unpacked, the archive then
+gets wholly destroyed. When users speak about @dfn{exploding} an
+archive, they usually mean something else :-).
+
+@item
+Forgetting the argument to @code{file}, when the intent was to create
+an archive with a single file in it. This error is likely because a
+tired user can easily add the @kbd{f} key to the cluster of option
+letters, by the mere force of habit, without realizing the full
+consequence of doing so. The usual consequence is that the single
+file, which was meant to be saved, is rather destroyed.
+@end enumerate
+
+So, recognizing the likelihood and the catastrophical nature of these
+errors, @GNUTAR{} now takes some distance from elegance, and
+cowardly refuses to create an archive when @option{--create} option is
+given, there are no arguments besides options, and
+@option{--files-from} (@option{-T}) option is @emph{not} used. To get
+around the cautiousness of @GNUTAR{} and nevertheless create an
+archive with nothing in it, one may still use, as the value for the
+@option{--files-from} option, a file with no names in it, as shown in
+the following commands:
+
+@smallexample
+@kbd{tar --create --file=empty-archive.tar --files-from=/dev/null}
+@kbd{tar cfT empty-archive.tar /dev/null}
+@end smallexample
+
+@opindex extract, complementary notes
+@item --extract
+@itemx --get
+@itemx -x
+
+A socket is stored, within a @GNUTAR{} archive, as a pipe.
+
+@item @option{--list} (@option{-t})
+
+@GNUTAR{} now shows dates as @samp{1996-08-30},
+while it used to show them as @samp{Aug 30 1996}. Preferably,
+people should get used to ISO 8601 dates. Local American dates should
+be made available again with full date localization support, once
+ready. In the meantime, programs not being localizable for dates
+should prefer international dates, that's really the way to go.
+
+Look up @url{http://www.ft.uni-erlangen.de/~mskuhn/iso-time.html} if you
+are curious, it contains a detailed explanation of the ISO 8601 standard.
+
+@end table
+
+@node Advanced tar
+@section Advanced @GNUTAR{} Operations
+
+Now that you have learned the basics of using @GNUTAR{}, you may want
+to learn about further ways in which @command{tar} can help you.
+
+This chapter presents five, more advanced operations which you probably
+won't use on a daily basis, but which serve more specialized functions.
+We also explain the different styles of options and why you might want
+to use one or another, or a combination of them in your @command{tar}
+commands. Additionally, this chapter includes options which allow you to
+define the output from @command{tar} more carefully, and provide help and
+error correction in special circumstances.
+
+@FIXME{check this after the chapter is actually revised to make sure
+it still introduces the info in the chapter correctly : ).}
+
+@menu
+* Operations::
+* append::
+* update::
+* concatenate::
+* delete::
+* compare::
+@end menu
+
+@node Operations
+@subsection The Five Advanced @command{tar} Operations
+@UNREVISED
+
+In the last chapter, you learned about the first three operations to
+@command{tar}. This chapter presents the remaining five operations to
+@command{tar}: @option{--append}, @option{--update}, @option{--concatenate},
+@option{--delete}, and @option{--compare}.
+
+You are not likely to use these operations as frequently as those
+covered in the last chapter; however, since they perform specialized
+functions, they are quite useful when you do need to use them. We
+will give examples using the same directory and files that you created
+in the last chapter. As you may recall, the directory is called
+@file{practice}, the files are @samp{jazz}, @samp{blues}, @samp{folk},
+@samp{rock}, and the two archive files you created are
+@samp{collection.tar} and @samp{music.tar}.
+
+We will also use the archive files @samp{afiles.tar} and
+@samp{bfiles.tar}. @samp{afiles.tar} contains the members @samp{apple},
+@samp{angst}, and @samp{aspic}. @samp{bfiles.tar} contains the members
+@samp{./birds}, @samp{baboon}, and @samp{./box}.
+
+Unless we state otherwise, all practicing you do and examples you follow
+in this chapter will take place in the @file{practice} directory that
+you created in the previous chapter; see @ref{prepare for examples}.
+(Below in this section, we will remind you of the state of the examples
+where the last chapter left them.)
+
+The five operations that we will cover in this chapter are:
+
+@table @option
+@item --append
+@itemx -r
+Add new entries to an archive that already exists.
+@item --update
+@itemx -r
+Add more recent copies of archive members to the end of an archive, if
+they exist.
+@item --concatenate
+@itemx --catenate
+@itemx -A
+Add one or more pre-existing archives to the end of another archive.
+@item --delete
+Delete items from an archive (does not work on tapes).
+@item --compare
+@itemx --diff
+@itemx -d
+Compare archive members to their counterparts in the file system.
+@end table
+
+@node append
+@subsection How to Add Files to Existing Archives: @option{--append}
+@UNREVISED
+
+@opindex append
+If you want to add files to an existing archive, you don't need to
+create a new archive; you can use @option{--append} (@option{-r}).
+The archive must already exist in order to use @option{--append}. (A
+related operation is the @option{--update} operation; you can use this
+to add newer versions of archive members to an existing archive. To learn how to
+do this with @option{--update}, @pxref{update}.)
+
+If you use @option{--append} to add a file that has the same name as an
+archive member to an archive containing that archive member, then the
+old member is not deleted. What does happen, however, is somewhat
+complex. @command{tar} @emph{allows} you to have infinite number of files
+with the same name. Some operations treat these same-named members no
+differently than any other set of archive members: for example, if you
+view an archive with @option{--list} (@option{-t}), you will see all
+of those members listed, with their data modification times, owners, etc.
+
+Other operations don't deal with these members as perfectly as you might
+prefer; if you were to use @option{--extract} to extract the archive,
+only the most recently added copy of a member with the same name as four
+other members would end up in the working directory. This is because
+@option{--extract} extracts an archive in the order the members appeared
+in the archive; the most recently archived members will be extracted
+last. Additionally, an extracted member will @emph{replace} a file of
+the same name which existed in the directory already, and @command{tar}
+will not prompt you about this@footnote{Unless you give it
+@option{--keep-old-files} option, or the disk copy is newer than the
+the one in the archive and you invoke @command{tar} with
+@option{--keep-newer-files} option}. Thus, only the most recently archived
+member will end up being extracted, as it will replace the one
+extracted before it, and so on.
+
+There exists a special option that allows you to get around this
+behavior and extract (or list) only a particular copy of the file.
+This is @option{--occurrence} option. If you run @command{tar} with
+this option, it will extract only the first copy of the file. You
+may also give this option an argument specifying the number of
+copy to be extracted. Thus, for example if the archive
+@file{archive.tar} contained three copies of file @file{myfile}, then
+the command
+
+@smallexample
+tar --extract --file archive.tar --occurrence=2 myfile
+@end smallexample
+
+@noindent
+would extract only the second copy. @xref{Option
+Summary,---occurrence}, for the description of @option{--occurrence}
+option.
+
+@FIXME{ hag -- you might want to incorporate some of the above into the
+MMwtSN node; not sure. i didn't know how to make it simpler...
+
+There are a few ways to get around this. (maybe xref Multiple Members
+with the Same Name.}
+
+@cindex Members, replacing with other members
+@cindex Replacing members with other members
+If you want to replace an archive member, use @option{--delete} to
+delete the member you want to remove from the archive, , and then use
+@option{--append} to add the member you want to be in the archive. Note
+that you can not change the order of the archive; the most recently
+added member will still appear last. In this sense, you cannot truly
+``replace'' one member with another. (Replacing one member with another
+will not work on certain types of media, such as tapes; see @ref{delete}
+and @ref{Media}, for more information.)
+
+@menu
+* appending files:: Appending Files to an Archive
+* multiple::
+@end menu
+
+@node appending files
+@subsubsection Appending Files to an Archive
+@UNREVISED
+@cindex Adding files to an Archive
+@cindex Appending files to an Archive
+@cindex Archives, Appending files to
+
+The simplest way to add a file to an already existing archive is the
+@option{--append} (@option{-r}) operation, which writes specified files into the
+archive whether or not they are already among the archived files.
+When you use @option{--append}, you @emph{must} specify file name
+arguments, as there is no default. If you specify a file that already
+exists in the archive, another copy of the file will be added to the
+end of the archive. As with other operations, the member names of the
+newly added files will be exactly the same as their names given on the
+command line. The @option{--verbose} (@option{-v}) option will print
+out the names of the files as they are written into the archive.
+
+@option{--append} cannot be performed on some tape drives, unfortunately,
+due to deficiencies in the formats those tape drives use. The archive
+must be a valid @command{tar} archive, or else the results of using this
+operation will be unpredictable. @xref{Media}.
+
+To demonstrate using @option{--append} to add a file to an archive,
+create a file called @file{rock} in the @file{practice} directory.
+Make sure you are in the @file{practice} directory. Then, run the
+following @command{tar} command to add @file{rock} to
+@file{collection.tar}:
+
+@smallexample
+$ @kbd{tar --append --file=collection.tar rock}
+@end smallexample
+
+@noindent
+If you now use the @option{--list} (@option{-t}) operation, you will see that
+@file{rock} has been added to the archive:
+
+@smallexample
+$ @kbd{tar --list --file=collection.tar}
+-rw-r--r-- me user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
+-rw-r--r-- me user 20 1996-09-23 16:44 folk
+-rw-r--r-- me user 20 1996-09-23 16:44 rock
+@end smallexample
+
+@FIXME{in theory, dan will (soon) try to turn this node into what it's
+title claims it will become...}
+
+@node multiple
+@subsubsection Multiple Files with the Same Name
+
+You can use @option{--append} (@option{-r}) to add copies of files which have been
+updated since the archive was created. (However, we do not recommend
+doing this since there is another @command{tar} option called
+@option{--update}; @pxref{update} for more information. We describe this
+use of @option{--append} here for the sake of completeness.) @FIXME{is
+this really a good idea, to give this whole description for something
+which i believe is basically a Stupid way of doing something? certain
+aspects of it show ways in which tar is more broken than i'd personally
+like to admit to, specifically the last sentence. On the other hand, i
+don't think it's a good idea to be saying that we explicitly don't
+recommend using something, but i can't see any better way to deal with
+the situation.}When you extract the archive, the older version will be
+effectively lost. This works because files are extracted from an
+archive in the order in which they were archived. Thus, when the
+archive is extracted, a file archived later in time will replace a
+file of the same name which was archived earlier, even though the older
+version of the file will remain in the archive unless you delete all
+versions of the file.
+
+Supposing you change the file @file{blues} and then append the changed
+version to @file{collection.tar}. As you saw above, the original
+@file{blues} is in the archive @file{collection.tar}. If you change the
+file and append the new version of the file to the archive, there will
+be two copies in the archive. When you extract the archive, the older
+version of the file will be extracted first, and then replaced by the
+newer version when it is extracted.
+
+You can append the new, changed copy of the file @file{blues} to the
+archive in this way:
+
+@smallexample
+$ @kbd{tar --append --verbose --file=collection.tar blues}
+blues
+@end smallexample
+
+@noindent
+Because you specified the @option{--verbose} option, @command{tar} has
+printed the name of the file being appended as it was acted on. Now
+list the contents of the archive:
+
+@smallexample
+$ @kbd{tar --list --verbose --file=collection.tar}
+-rw-r--r-- me user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
+-rw-r--r-- me user 20 1996-09-23 16:44 folk
+-rw-r--r-- me user 20 1996-09-23 16:44 rock
+-rw-r--r-- me user 58 1996-10-24 18:30 blues
+@end smallexample
+
+@noindent
+The newest version of @file{blues} is now at the end of the archive
+(note the different creation dates and file sizes). If you extract
+the archive, the older version of the file @file{blues} will be
+replaced by the newer version. You can confirm this by extracting
+the archive and running @samp{ls} on the directory.
+
+If you wish to extract the first occurrence of the file @file{blues}
+from the archive, use @option{--occurrence} option, as shown in
+the following example:
+
+@smallexample
+$ @kbd{tar --extract -vv --occurrence --file=collection.tar blues}
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
+@end smallexample
+
+@xref{Writing}, for more information on @option{--extract} and
+@xref{Option Summary, --occurrence}, for the description of
+@option{--occurrence} option.
+
+@node update
+@subsection Updating an Archive
+@UNREVISED
+@cindex Updating an archive
+
+@opindex update
+In the previous section, you learned how to use @option{--append} to
+add a file to an existing archive. A related operation is
+@option{--update} (@option{-u}). The @option{--update} operation
+updates a @command{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 newer version of the file is added to the archive (as with
+@option{--append}).
+
+Unfortunately, you cannot use @option{--update} with magnetic tape drives.
+The operation will fail.
+
+@FIXME{other examples of media on which --update will fail? need to ask
+charles and/or mib/thomas/dave shevett..}
+
+Both @option{--update} and @option{--append} 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, unless you use
+the @option{--backup} option. @FIXME-ref{Multiple Members with the
+Same Name}
+
+@menu
+* how to update::
+@end menu
+
+@node how to update
+@subsubsection How to Update an Archive Using @option{--update}
+
+You must use file name arguments with the @option{--update} (@option{-u}) operation.
+If you don't specify any files, @command{tar} won't act on any files and
+won't tell you that it didn't do anything (which may end up confusing
+you).
+
+@FIXME{note: the above parenthetical added because in fact, this
+behavior just confused the author. :-) }
+
+To see the @option{--update} option at work, create a new file,
+@file{classical}, in your practice directory, and some extra text to the
+file @file{blues}, using any text editor. Then invoke @command{tar} with
+the @samp{update} operation and the @option{--verbose} (@option{-v}) option specified,
+using the names of all the files in the practice directory as file name
+arguments:
+
+@smallexample
+$ @kbd{tar --update -v -f collection.tar blues folk rock classical}
+blues
+classical
+$
+@end smallexample
+
+@noindent
+Because we have specified verbose mode, @command{tar} prints out the names
+of the files it is working on, which in this case are the names of the
+files that needed to be updated. If you run @samp{tar --list} and look
+at the archive, you will see @file{blues} and @file{classical} at its
+end. There will be a total of two versions of the member @samp{blues};
+the one at the end will be newer and larger, since you added text before
+updating it.
+
+(The reason @command{tar} does not overwrite the older file when updating
+it is because writing to the middle of a section of tape is a difficult
+process. Tapes are not designed to go backward. @xref{Media}, for more
+information about tapes.
+
+@option{--update} (@option{-u}) is not suitable for performing backups for two
+reasons: it does not change directory content entries, and it
+lengthens the archive every time it is used. The @GNUTAR{}
+options intended specifically for backups are more
+efficient. If you need to run backups, please consult @ref{Backups}.
+
+@node concatenate
+@subsection Combining Archives with @option{--concatenate}
+
+@cindex Adding archives to an archive
+@cindex Concatenating Archives
+@opindex concatenate
+@opindex catenate
+@c @cindex @option{-A} described
+Sometimes it may be convenient to add a second archive onto the end of
+an archive rather than adding individual files to the archive. To add
+one or more archives to the end of another archive, you should use the
+@option{--concatenate} (@option{--catenate}, @option{-A}) operation.
+
+To use @option{--concatenate}, give the first archive with
+@option{--file} option and name the rest of archives to be
+concatenated on the command line. The members, and their member
+names, will be copied verbatim from those archives to the first one.
+@FIXME-ref{This can cause multiple members to have the same name, for
+information on how this affects reading the archive, Multiple
+Members with the Same Name.}
+The new, concatenated archive will be called by the same name as the
+one given with the @option{--file} option. As usual, if you omit
+@option{--file}, @command{tar} will use the value of the environment
+variable @env{TAPE}, or, if this has not been set, the default archive name.
+
+@FIXME{There is no way to specify a new name...}
+
+To demonstrate how @option{--concatenate} works, create two small archives
+called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant
+files from @file{practice}:
+
+@smallexample
+$ @kbd{tar -cvf bluesrock.tar blues rock}
+blues
+classical
+$ @kbd{tar -cvf folkjazz.tar folk jazz}
+folk
+jazz
+@end smallexample
+
+@noindent
+If you like, You can run @samp{tar --list} to make sure the archives
+contain what they are supposed to:
+
+@smallexample
+$ @kbd{tar -tvf bluesrock.tar}
+-rw-r--r-- melissa user 105 1997-01-21 19:42 blues
+-rw-r--r-- melissa user 33 1997-01-20 15:34 rock
+$ @kbd{tar -tvf folkjazz.tar}
+-rw-r--r-- melissa user 20 1996-09-23 16:44 folk
+-rw-r--r-- melissa user 65 1997-01-30 14:15 jazz
+@end smallexample
+
+We can concatenate these two archives with @command{tar}:
+
+@smallexample
+$ @kbd{cd ..}
+$ @kbd{tar --concatenate --file=bluesrock.tar jazzfolk.tar}
+@end smallexample
+
+If you now list the contents of the @file{bluesclass.tar}, you will see
+that now it also contains the archive members of @file{jazzfolk.tar}:
+
+@smallexample
+$ @kbd{tar --list --file=bluesrock.tar}
+blues
+rock
+jazz
+folk
+@end smallexample
+
+When you use @option{--concatenate}, the source and target archives must
+already exist and must have been created using compatible format
+parameters. Notice, that @command{tar} does not check whether the
+archives it concatenates have compatible formats, it does not
+even check if the files are really tar archives.
+
+Like @option{--append} (@option{-r}), this operation cannot be performed on some
+tape drives, due to deficiencies in the formats those tape drives use.
+
+@cindex @code{concatenate} vs @command{cat}
+@cindex @command{cat} vs @code{concatenate}
+It may seem more intuitive to you to want or try to use @command{cat} to
+concatenate two archives instead of using the @option{--concatenate}
+operation; after all, @command{cat} is the utility for combining files.
+
+However, @command{tar} archives incorporate an end-of-file marker which
+must be removed if the concatenated archives are to be read properly as
+one archive. @option{--concatenate} removes the end-of-archive marker
+from the target archive before each new archive is appended. If you use
+@command{cat} to combine the archives, the result will not be a valid
+@command{tar} format archive. If you need to retrieve files from an
+archive that was added to using the @command{cat} utility, use the
+@option{--ignore-zeros} (@option{-i}) option. @xref{Ignore Zeros}, for further
+information on dealing with archives improperly combined using the
+@command{cat} shell utility.
+
+@node delete
+@subsection Removing Archive Members Using @option{--delete}
+@UNREVISED
+@cindex Deleting files from an archive
+@cindex Removing files from an archive
+
+@opindex delete
+You can remove members from an archive by using the @option{--delete}
+option. Specify the name of the archive with @option{--file}
+(@option{-f}) and then specify the names of the members to be deleted;
+if you list no member names, nothing will be deleted. The
+@option{--verbose} option will cause @command{tar} to print the names
+of the members as they are deleted. As with @option{--extract}, you
+must give the exact member names when using @samp{tar --delete}.
+@option{--delete} will remove all versions of the named file from the
+archive. The @option{--delete} operation can run very slowly.
+
+Unlike other operations, @option{--delete} has no short form.
+
+@cindex Tapes, using @option{--delete} and
+@cindex Deleting from tape archives
+This operation will rewrite the archive. You can only use
+@option{--delete} on an archive if the archive device allows you to
+write to any point on the media, such as a disk; because of this, it
+does not work on magnetic tapes. Do not try to delete an archive member
+from a magnetic tape; the action will not succeed, and you will be
+likely to scramble the archive and damage your tape. There is no safe
+way (except by completely re-writing the archive) to delete files from
+most kinds of magnetic tape. @xref{Media}.
+
+To delete all versions of the file @file{blues} from the archive
+@file{collection.tar} in the @file{practice} directory, make sure you
+are in that directory, and then,
+
+@smallexample
+$ @kbd{tar --list --file=collection.tar}
+blues
+folk
+jazz
+rock
+practice/blues
+practice/folk
+practice/jazz
+practice/rock
+practice/blues
+$ @kbd{tar --delete --file=collection.tar blues}
+$ @kbd{tar --list --file=collection.tar}
+folk
+jazz
+rock
+$
+@end smallexample
+
+@FIXME{I changed the order of these nodes around and haven't had a chance
+to fix the above example's results, yet. I have to play with this and
+follow it and see what it actually does!}
+
+The @option{--delete} option has been reported to work properly when
+@command{tar} acts as a filter from @code{stdin} to @code{stdout}.
+
+@node compare
+@subsection Comparing Archive Members with the File System
+@cindex Verifying the currency of an archive
+@UNREVISED
+
+@opindex compare
+The @option{--compare} (@option{-d}), or @option{--diff} operation compares
+specified archive members against files with the same names, and then
+reports differences in file size, mode, owner, modification date and
+contents. You should @emph{only} specify archive member names, not file
+names. If you do not name any members, then @command{tar} will compare the
+entire archive. If a file is represented in the archive but does not
+exist in the file system, @command{tar} reports a difference.
+
+You have to specify the record size of the archive when modifying an
+archive with a non-default record size.
+
+@command{tar} ignores files in the file system that do not have
+corresponding members in the archive.
+
+The following example compares the archive members @file{rock},
+@file{blues} and @file{funk} in the archive @file{bluesrock.tar} with
+files of the same name in the file system. (Note that there is no file,
+@file{funk}; @command{tar} will report an error message.)
+
+@smallexample
+$ @kbd{tar --compare --file=bluesrock.tar rock blues funk}
+rock
+blues
+tar: funk not found in archive
+@end smallexample
+
+The spirit behind the @option{--compare} (@option{--diff}, @option{-d}) option is to check whether the
+archive represents the current state of files on disk, more than validating
+the integrity of the archive media. For this later goal, @xref{verify}.
+
+@node create options
+@section Options Used by @option{--create}
+
+@opindex create, additional options
+The previous chapter described the basics of how to use
+@option{--create} (@option{-c}) to create an archive from a set of files.
+@xref{create}. This section described advanced options to be used with
+@option{--create}.
+
+@menu
+* Ignore Failed Read::
+@end menu
+
+@node Ignore Failed Read
+@subsection Ignore Fail Read
+
+@table @option
+@item --ignore-failed-read
+Do not exit with nonzero on unreadable files or directories.
+@end table
+
+@node extract options
+@section Options Used by @option{--extract}
+@UNREVISED
+
+@FIXME{i need to get dan to go over these options with me and see if
+there's a better way of organizing them.}
+
+@opindex extract, additional options
+The previous chapter showed how to use @option{--extract} to extract
+an archive into the file system. Various options cause @command{tar} to
+extract more information than just file contents, such as the owner,
+the permissions, the modification date, and so forth. This section
+presents options to be used with @option{--extract} when certain special
+considerations arise. You may review the information presented in
+@ref{extract} for more basic information about the
+@option{--extract} operation.
+
+@menu
+* Reading:: Options to Help Read Archives
+* Writing:: Changing How @command{tar} Writes Files
+* Scarce:: Coping with Scarce Resources
+@end menu
+
+@node Reading
+@subsection Options to Help Read Archives
+@cindex Options when reading archives
+@UNREVISED
+
+@cindex Reading incomplete records
+@cindex Records, incomplete
+@opindex read-full-records
+Normally, @command{tar} will request data in full record increments from
+an archive storage device. If the device cannot return a full record,
+@command{tar} will report an error. However, some devices do not always
+return full records, or do not require the last record of an archive to
+be padded out to the next record boundary. To keep reading until you
+obtain a full record, or to accept an incomplete record if it contains
+an end-of-archive marker, specify the @option{--read-full-records} (@option{-B}) option
+in conjunction with the @option{--extract} or @option{--list} operations.
+@xref{Blocking}.
+
+The @option{--read-full-records} (@option{-B}) option is turned on by default when
+@command{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, @command{tar}
+would fail as soon as it read an incomplete record from the pipe.
+
+If you're not sure of the blocking factor of an archive, you can
+read the archive by specifying @option{--read-full-records} (@option{-B}) and
+@option{--blocking-factor=@var{512-size}} (@option{-b
+@var{512-size}}), using a blocking factor larger than what the archive
+uses. This lets you avoid having to determine the blocking factor
+of an archive. @xref{Blocking Factor}.
+
+@menu
+* read full records::
+* Ignore Zeros::
+@end menu
+
+@node read full records
+@unnumberedsubsubsec Reading Full Records
+
+@FIXME{need sentence or so of intro here}
+
+@table @option
+@opindex read-full-records
+@item --read-full-records
+@item -B
+Use in conjunction with @option{--extract} (@option{--get},
+@option{-x}) to read an archive which contains incomplete records, or
+one which has a blocking factor less than the one specified.
+@end table
+
+@node Ignore Zeros
+@unnumberedsubsubsec Ignoring Blocks of Zeros
+
+@cindex End-of-archive blocks, ignoring
+@cindex Ignoring end-of-archive blocks
+@opindex ignore-zeros
+Normally, @command{tar} stops reading when it encounters a block of zeros
+between file entries (which usually indicates the end of the archive).
+@option{--ignore-zeros} (@option{-i}) allows @command{tar} to
+completely read an archive which contains a block of zeros before the
+end (i.e., a damaged archive, or one that was created by concatenating
+several archives together).
+
+The @option{--ignore-zeros} (@option{-i}) option is turned off by default because many
+versions of @command{tar} write garbage after the end-of-archive entry,
+since that part of the media is never supposed to be read. @GNUTAR{}
+does not write after the end of an archive, but seeks to
+maintain compatiblity among archiving utilities.
+
+@table @option
+@item --ignore-zeros
+@itemx -i
+To ignore blocks of zeros (i.e., end-of-archive entries) which may be
+encountered while reading an archive. Use in conjunction with
+@option{--extract} or @option{--list}.
+@end table
+
+@node Writing
+@subsection Changing How @command{tar} Writes Files
+@UNREVISED
+
+@FIXME{Introductory paragraph}
+
+@menu
+* Dealing with Old Files::
+* Overwrite Old Files::
+* Keep Old Files::
+* Keep Newer Files::
+* Unlink First::
+* Recursive Unlink::
+* Data Modification Times::
+* Setting Access Permissions::
+* Directory Modification Times and Permissions::
+* Writing to Standard Output::
+* Writing to an External Program::
+* remove files::
+@end menu
+
+@node Dealing with Old Files
+@unnumberedsubsubsec Options Controlling the Overwriting of Existing Files
+
+@opindex overwrite-dir, introduced
+When extracting files, if @command{tar} discovers that the extracted
+file already exists, it normally replaces the file by removing it before
+extracting it, to prevent confusion in the presence of hard or symbolic
+links. (If the existing file is a symbolic link, it is removed, not
+followed.) However, if a directory cannot be removed because it is
+nonempty, @command{tar} normally overwrites its metadata (ownership,
+permission, etc.). The @option{--overwrite-dir} option enables this
+default behavior. To be more cautious and preserve the metadata of
+such a directory, use the @option{--no-overwrite-dir} option.
+
+@cindex Overwriting old files, prevention
+@opindex keep-old-files, introduced
+To be even more cautious and prevent existing files from being replaced, use
+the @option{--keep-old-files} (@option{-k}) option. It causes @command{tar} to refuse
+to replace or update a file that already exists, i.e., a file with the
+same name as an archive member prevents extraction of that archive
+member. Instead, it reports an error.
+
+@opindex overwrite, introduced
+To be more aggressive about altering existing files, use the
+@option{--overwrite} option. It causes @command{tar} to overwrite
+existing files and to follow existing symbolic links when extracting.
+
+@cindex Protecting old files
+Some people argue that @GNUTAR{} should not hesitate
+to overwrite files with other files when extracting. When extracting
+a @command{tar} archive, they expect to see a faithful copy of the
+state of the file system when the archive was created. It is debatable
+that this would always be a proper behavior. For example, suppose one
+has an archive in which @file{usr/local} is a link to
+@file{usr/local2}. Since then, maybe the site removed the link and
+renamed the whole hierarchy from @file{/usr/local2} to
+@file{/usr/local}. Such things happen all the time. I guess it would
+not be welcome at all that @GNUTAR{} removes the
+whole hierarchy just to make room for the link to be reinstated
+(unless it @emph{also} simultaneously restores the full
+@file{/usr/local2}, of course!) @GNUTAR{} is indeed
+able to remove a whole hierarchy to reestablish a symbolic link, for
+example, but @emph{only if} @option{--recursive-unlink} is specified
+to allow this behavior. In any case, single files are silently
+removed.
+
+@opindex unlink-first, introduced
+Finally, the @option{--unlink-first} (@option{-U}) option can improve performance in
+some cases by causing @command{tar} to remove files unconditionally
+before extracting them.
+
+@node Overwrite Old Files
+@unnumberedsubsubsec Overwrite Old Files
+
+@table @option
+@opindex overwrite
+@item --overwrite
+Overwrite existing files and directory metadata when extracting files
+from an archive.
+
+This causes @command{tar} to write extracted files into the file system without
+regard to the files already on the system; i.e., files with the same
+names as archive members are overwritten when the archive is extracted.
+It also causes @command{tar} to extract the ownership, permissions,
+and time stamps onto any preexisting files or directories.
+If the name of a corresponding file name is a symbolic link, the file
+pointed to by the symbolic link will be overwritten instead of the
+symbolic link itself (if this is possible). Moreover, special devices,
+empty directories and even symbolic links are automatically removed if
+they are in the way of extraction.
+
+Be careful when using the @option{--overwrite} option, particularly when
+combined with the @option{--absolute-names} (@option{-P}) option, as this combination
+can change the contents, ownership or permissions of any file on your
+system. Also, many systems do not take kindly to overwriting files that
+are currently being executed.
+
+@opindex overwrite-dir
+@item --overwrite-dir
+Overwrite the metadata of directories when extracting files from an
+archive, but remove other files before extracting.
+@end table
+
+@node Keep Old Files
+@unnumberedsubsubsec Keep Old Files
+
+@table @option
+@opindex keep-old-files
+@item --keep-old-files
+@itemx -k
+Do not replace existing files from archive. The
+@option{--keep-old-files} (@option{-k}) option prevents @command{tar}
+from replacing existing files with files with the same name from the
+archive. The @option{--keep-old-files} option is meaningless with
+@option{--list} (@option{-t}). Prevents @command{tar} from replacing
+files in the file system during extraction.
+@end table
+
+@node Keep Newer Files
+@unnumberedsubsubsec Keep Newer Files
+
+@table @option
+@opindex keep-newer-files
+@item --keep-newer-files
+Do not replace existing files that are newer than their archive
+copies. This option is meaningless with @option{--list} (@option{-t}).
+@end table
+
+@node Unlink First
+@unnumberedsubsubsec Unlink First
+
+@table @option
+@opindex unlink-first
+@item --unlink-first
+@itemx -U
+Remove files before extracting over them.
+This can make @command{tar} run a bit faster if you know in advance
+that the extracted files all need to be removed. Normally this option
+slows @command{tar} down slightly, so it is disabled by default.
+@end table
+
+@node Recursive Unlink
+@unnumberedsubsubsec Recursive Unlink
+
+@table @option
+@opindex recursive-unlink
+@item --recursive-unlink
+When this option is specified, try removing files and directory hierarchies
+before extracting over them. @emph{This is a dangerous option!}
+@end table
+
+If you specify the @option{--recursive-unlink} option,
+@command{tar} removes @emph{anything} that keeps you from extracting a file
+as far as current permissions will allow it. This could include removal
+of the contents of a full directory hierarchy.
+
+@node Data Modification Times
+@unnumberedsubsubsec Setting Data Modification Times
+
+@cindex Data modification times of extracted files
+@cindex Modification times of extracted files
+Normally, @command{tar} sets the data modification times of extracted
+files to the corresponding times recorded for the files in the archive, but
+limits the permissions of extracted files by the current @code{umask}
+setting.
+
+To set the data modification times of extracted files to the time when
+the files were extracted, use the @option{--touch} (@option{-m}) option in
+conjunction with @option{--extract} (@option{--get}, @option{-x}).
+
+@table @option
+@opindex touch
+@item --touch
+@itemx -m
+Sets the data 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 @option{--extract} (@option{--get}, @option{-x}).
+@end table
+
+@node Setting Access Permissions
+@unnumberedsubsubsec Setting Access Permissions
+
+@cindex Permissions of extracted files
+@cindex Modes of extracted files
+To set the modes (access permissions) of extracted files to those
+recorded for those files in the archive, use @option{--same-permissions}
+in conjunction with the @option{--extract} (@option{--get},
+@option{-x}) operation. @FIXME{Should be aliased to ignore-umask.}
+
+@table @option
+@opindex preserve-permission
+@opindex same-permission
+@item --preserve-permission
+@itemx --same-permission
+@c @itemx --ignore-umask
+@itemx -p
+Set modes of extracted archive members to those recorded in the
+archive, instead of current umask settings. Use in conjunction with
+@option{--extract} (@option{--get}, @option{-x}).
+@end table
+
+@node Directory Modification Times and Permissions
+@unnumberedsubsubsec Directory Modification Times and Permissions
+
+After sucessfully extracting a file member, @GNUTAR{} normally
+restores its permissions and modification times, as described in the
+previous sections. This cannot be done for directories, because
+after extracting a directory @command{tar} will almost certainly
+extract files into that directory and this will cause the directory
+modification time to be updated. Moreover, restoring that directory
+permissions may not permit file creation within it. Thus, restoring
+directory permissions and modification times must be delayed at least
+until all files have been extracted into that directory. @GNUTAR{}
+restores directories using the following approach.
+
+The extracted directories are created with the mode specified in the
+archive, as modified by the umask of the user, which gives sufficient
+permissions to allow file creation. The meta-information about the
+directory is recorded in the temporary list of directories. When
+preparing to extract next archive member, @GNUTAR{} checks if the
+directory prefix of this file contains the remembered directory. If
+it does not, the program assumes that all files have been extracted
+into that directory, restores its modification time and permissions
+and removes its entry from the internal list. This approach allows
+to correctly restore directory meta-information in the majority of
+cases, while keeping memory requirements sufficiently small. It is
+based on the fact, that most @command{tar} archives use the predefined
+order of members: first the directory, then all the files and
+subdirectories in that directory.
+
+However, this is not always true. The most important exception are
+incremental archives (@pxref{Incremental Dumps}). The member order in
+an incremental archive is reversed: first all directory members are
+stored, followed by other (non-directory) members. So, when extracting
+from incremental archives, @GNUTAR{} alters the above procedure. It
+remebers all restored directories, and restores their meta-data
+only after the entire archive has been processed. Notice, that you do
+not need to specity any special options for that, as @GNUTAR{}
+automatically detects archives in incremental format.
+
+There may be cases, when such processing is required for normal archives
+too. Consider the following example:
+
+@smallexample
+@group
+$ @kbd{tar --no-recursion -cvf archive \
+ foo foo/file1 bar bar/file foo/file2}
+foo/
+foo/file1
+bar/
+bar/file
+foo/file2
+@end group
+@end smallexample
+
+During the normal operation, after encountering @file{bar}
+@GNUTAR{} will assume that all files from the directory @file{foo}
+were already extracted and will therefore restore its timestamp and
+permission bits. However, after extracting @file{foo/file2} the
+directory timestamp will be offset again.
+
+To correctly restore directory meta-information in such cases, use
+@option{delay-directory-restore} command line option:
+
+@table @option
+@opindex delay-directory-restore
+@item --delay-directory-restore
+Delays restoring of the modification times and permissions of extracted
+directories until the end of extraction. This way, correct
+meta-information is restored even if the archive has unusual member
+ordering.
+
+@opindex no-delay-directory-restore
+@item --no-delay-directory-restore
+Cancel the effect of the previous @option{--delay-directory-restore}.
+Use this option if you have used @option{--delay-directory-restore} in
+@env{TAR_OPTIONS} variable (@pxref{TAR_OPTIONS}) and wish to
+temporarily disable it.
+@end table
+
+@node Writing to Standard Output
+@unnumberedsubsubsec Writing to Standard Output
+
+@cindex Writing extracted files to standard output
+@cindex Standard output, writing extracted files to
+To write the extracted files to the standard output, instead of
+creating the files on the file system, use @option{--to-stdout} (@option{-O}) in
+conjunction with @option{--extract} (@option{--get}, @option{-x}). This option is useful if you are
+extracting files to send them through a pipe, and do not need to
+preserve them in the file system. If you extract multiple members,
+they appear on standard output concatenated, in the order they are
+found in the archive.
+
+@table @option
+@opindex to-stdout
+@item --to-stdout
+@itemx -O
+Writes files to the standard output. Use only in conjunction with
+@option{--extract} (@option{--get}, @option{-x}). When this option is
+used, instead of creating the files specified, @command{tar} writes
+the contents of the files extracted to its standard output. This may
+be useful if you are only extracting the files in order to send them
+through a pipe. This option is meaningless with @option{--list}
+(@option{-t}).
+@end table
+
+This can be useful, for example, if you have a tar archive containing
+a big file and don't want to store the file on disk before processing
+it. You can use a command like this:
+
+@smallexample
+tar -xOzf foo.tgz bigfile | process
+@end smallexample
+
+or even like this if you want to process the concatenation of the files:
+
+@smallexample
+tar -xOzf foo.tgz bigfile1 bigfile2 | process
+@end smallexample
+
+Hovewer, @option{--to-command} may be more convenient for use with
+multiple files. See the next section.
+
+@node Writing to an External Program
+@unnumberedsubsubsec Writing to an External Program
+
+You can instruct @command{tar} to send the contents of each extracted
+file to the standard input of an external program:
+
+@table @option
+@opindex to-program
+@item --to-program=@var{command}
+Extract files and pipe their contents to the standard input of
+@var{command}. When this option is used, instead of creating the
+files specified, @command{tar} invokes @var{command} and pipes the
+contents of the files to its standard output. @var{Command} may
+contain command line arguments. The program is executed via
+@code{sh -c}. Notice, that @var{command} is executed once for each regular file
+extracted. Non-regular files (directories, etc.) are ignored when this
+option is used.
+@end table
+
+The command can obtain the information about the file it processes
+from the following environment variables:
+
+@table @var
+@vrindex TAR_FILETYPE, to-command environment
+@item TAR_FILETYPE
+Type of the file. It is a single letter with the following meaning:
+
+@multitable @columnfractions 0.10 0.90
+@item f @tab Regular file
+@item d @tab Directory
+@item l @tab Symbolic link
+@item h @tab Hard link
+@item b @tab Block device
+@item c @tab Character device
+@end multitable
+
+Currently only regular files are supported.
+
+@vrindex TAR_MODE, to-command environment
+@item TAR_MODE
+File mode, an octal number.
+
+@vrindex TAR_FILENAME, to-command environment
+@item TAR_FILENAME
+The name of the file.
+
+@vrindex TAR_REALNAME, to-command environment
+@item TAR_REALNAME
+Name of the file as stored in the archive.
+
+@vrindex TAR_UNAME, to-command environment
+@item TAR_UNAME
+Name of the file owner.
+
+@vrindex TAR_GNAME, to-command environment
+@item TAR_GNAME
+Name of the file owner group.
+
+@vrindex TAR_ATIME, to-command environment
+@item TAR_ATIME
+Time of last access. It is a decimal number, representing seconds
+since the epoch. If the archive provides times with nanosecond
+precision, the nanoseconds are appended to the timestamp after a
+decimal point.
+
+@vrindex TAR_MTIME, to-command environment
+@item TAR_MTIME
+Time of last modification.
+
+@vrindex TAR_CTIME, to-command environment
+@item TAR_CTIME
+Time of last status change.
+
+@vrindex TAR_SIZE, to-command environment
+@item TAR_SIZE
+Size of the file.
+
+@vrindex TAR_UID, to-command environment
+@item TAR_UID
+UID of the file owner.
+
+@vrindex TAR_GID, to-command environment
+@item TAR_GID
+GID of the file owner.
+@end table
+
+In addition to these variables, @env{TAR_VERSION} contains the
+@GNUTAR{} version number.
+
+If @var{command} exits with a non-0 status, @command{tar} will print
+an error message similar to the following:
+
+@smallexample
+tar: 2345: Child returned status 1
+@end smallexample
+
+Here, @samp{2345} is the PID of the finished process.
+
+If this behavior is not wanted, use @option{--ignore-command-error}:
+
+@table @option
+@opindex ignore-command-error
+@item --ignore-command-error
+Ignore exit codes of subprocesses. Notice that if the program
+exits on signal or otherwise terminates abnormally, the error message
+will be printed even if this option is used.
+
+@opindex no-ignore-command-error
+@item --no-ignore-command-error
+Cancel the effect of any previous @option{--ignore-command-error}
+option. This option is useful if you have set
+@option{--ignore-command-error} in @env{TAR_OPTIONS}
+(@pxref{TAR_OPTIONS}) and wish to temporarily cancel it.
+@end table
+
+@node remove files
+@unnumberedsubsubsec Removing Files
+
+@FIXME{the various macros in the front of the manual think that this
+option goes in this section. i have no idea; i only know it's nowhere
+else in the book...}
+
+@table @option
+@opindex remove-files
+@item --remove-files
+Remove files after adding them to the archive.
+@end table
+
+@node Scarce
+@subsection Coping with Scarce Resources
+@UNREVISED
+
+@cindex Small memory
+@cindex Running out of space
+
+@menu
+* Starting File::
+* Same Order::
+@end menu
+
+@node Starting File
+@unnumberedsubsubsec Starting File
+
+@table @option
+@opindex starting-file
+@item --starting-file=@var{name}
+@itemx -K @var{name}
+Starts an operation in the middle of an archive. Use in conjunction
+with @option{--extract} (@option{--get}, @option{-x}) or @option{--list} (@option{-t}).
+@end table
+
+@cindex Middle of the archive, starting in the
+If a previous attempt to extract files failed due to lack of disk
+space, you can use @option{--starting-file=@var{name}} (@option{-K
+@var{name}}) to start extracting only after member @var{name} of the
+archive. This assumes, of course, that there is now free space, or
+that you are now extracting into a different file system. (You could
+also choose to suspend @command{tar}, remove unnecessary files from
+the file system, and then restart the same @command{tar} operation.
+In this case, @option{--starting-file} is not necessary.
+@xref{Incremental Dumps}, @xref{interactive}, and @ref{exclude}.)
+
+@node Same Order
+@unnumberedsubsubsec Same Order
+
+@table @option
+@cindex Large lists of file names on small machines
+@opindex same-order
+@opindex preserve-order
+@item --same-order
+@itemx --preserve-order
+@itemx -s
+To process large lists of file names on machines with small amounts of
+memory. Use in conjunction with @option{--compare} (@option{--diff},
+@option{-d}), @option{--list} (@option{-t}) or @option{--extract}
+(@option{--get}, @option{-x}).
+@end table
+
+The @option{--same-order} (@option{--preserve-order}, @option{-s}) option tells @command{tar} that the list of file
+names to be listed or extracted is sorted in the same order as the
+files in the archive. This allows a large list of names to be used,
+even on a small machine that would not otherwise be able to hold all
+the names in memory at the same time. Such a sorted list can easily be
+created by running @samp{tar -t} on the archive and editing its output.
+
+This option is probably never needed on modern computer systems.
+
+@node backup
+@section Backup options
+
+@cindex backup options
+
+@GNUTAR{} offers options for making backups of files
+before writing new versions. These options control the details of
+these backups. They may apply to the archive itself before it is
+created or rewritten, as well as individual extracted members. Other
+@acronym{GNU} programs (@command{cp}, @command{install}, @command{ln},
+and @command{mv}, for example) offer similar options.
+
+Backup options may prove unexpectedly useful when extracting archives
+containing many members having identical name, or when extracting archives
+on systems having file name limitations, making different members appear
+has having similar names through the side-effect of name truncation.
+(This is true only if we have a good scheme for truncated backup names,
+which I'm not sure at all: I suspect work is needed in this area.)
+When any existing file is backed up before being overwritten by extraction,
+then clashing files are automatically be renamed to be unique, and the
+true name is kept for only the last file of a series of clashing files.
+By using verbose mode, users may track exactly what happens.
+
+At the detail level, some decisions are still experimental, and may
+change in the future, we are waiting comments from our users. So, please
+do not learn to depend blindly on the details of the backup features.
+For example, currently, directories themselves are never renamed through
+using these options, so, extracting a file over a directory still has
+good chances to fail. Also, backup options apply to created archives,
+not only to extracted members. For created archives, backups will not
+be attempted when the archive is a block or character device, or when it
+refers to a remote file.
+
+For the sake of simplicity and efficiency, backups are made by renaming old
+files prior to creation or extraction, and not by copying. The original
+name is restored if the file creation fails. If a failure occurs after a
+partial extraction of a file, both the backup and the partially extracted
+file are kept.
+
+@table @samp
+@item --backup[=@var{method}]
+@opindex backup
+@vindex VERSION_CONTROL
+@cindex backups
+Back up files that are about to be overwritten or removed.
+Without this option, the original versions are destroyed.
+
+Use @var{method} to determine the type of backups made.
+If @var{method} is not specified, use the value of the @env{VERSION_CONTROL}
+environment variable. And if @env{VERSION_CONTROL} is not set,
+use the @samp{existing} method.
+
+@vindex version-control @r{Emacs variable}
+This option corresponds to the Emacs variable @samp{version-control};
+the same values for @var{method} are accepted as in Emacs. This option
+also allows more descriptive names. The valid @var{method}s are:
+
+@table @samp
+@item t
+@itemx numbered
+@cindex numbered @r{backup method}
+Always make numbered backups.
+
+@item nil
+@itemx existing
+@cindex existing @r{backup method}
+Make numbered backups of files that already have them, simple backups
+of the others.
+
+@item never
+@itemx simple
+@cindex simple @r{backup method}
+Always make simple backups.
+
+@end table
+
+@item --suffix=@var{suffix}
+@opindex suffix
+@cindex backup suffix
+@vindex SIMPLE_BACKUP_SUFFIX
+Append @var{suffix} to each backup file made with @option{--backup}. If this
+option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX}
+environment variable is used. And if @env{SIMPLE_BACKUP_SUFFIX} is not
+set, the default is @samp{~}, just as in Emacs.
+
+@end table
+
+Some people express the desire to @emph{always} use the @option{--backup}
+option, by defining some kind of alias or script. This is not as easy
+as one may think, due to the fact that old style options should appear first
+and consume arguments a bit unpredictably for an alias or script. But,
+if you are ready to give up using old style options, you may resort to
+using something like (a Bourne shell function here):
+
+@smallexample
+tar () @{ /usr/local/bin/tar --backup $*; @}
+@end smallexample
+
+@node Applications
+@section Notable @command{tar} Usages
+@UNREVISED
+
+@FIXME{Using Unix file linking capability to recreate directory
+structures---linking files into one subdirectory and then
+@command{tar}ring that directory.}
+
+@FIXME{Nice hairy example using absolute-names, newer, etc.}
+
+@findex uuencode
+You can easily use archive files to transport 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 system, 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 @command{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 @command{tar} program.
+
+For example, here is how you might copy a directory's contents from
+one disk to another, while preserving the dates, modes, owners and
+link-structure of all the files therein. In this case, the transfer
+medium is a @dfn{pipe}, which is one a Unix redirection mechanism:
+
+@smallexample
+$ @kbd{cd sourcedir; tar -cf - . | (cd targetdir; tar -xf -)}
+@end smallexample
+
+@noindent
+The command also works using short option forms:
+
+@smallexample
+$ @w{@kbd{cd sourcedir; tar --create --file=- . | (cd targetdir; tar --extract --file=-)}}
+@end smallexample
+
+@noindent
+This is one of the easiest methods to transfer a @command{tar} archive.
+
+@node looking ahead
+@section Looking Ahead: The Rest of this Manual
+
+You have now seen how to use all eight of the operations available to
+@command{tar}, and a number of the possible options. The next chapter
+explains how to choose and change file and archive names, how to use
+files to store names of other files which you can then call as
+arguments to @command{tar} (this can help you save time if you expect to
+archive the same list of files a number of times), and so forth.
+@FIXME{in case it's not obvious, i'm making this up in some sense
+based on my limited memory of what the next chapter *really* does. i
+just wanted to flesh out this final section a little bit so i'd
+remember to stick it in here. :-)}
+
+If there are too many files to conveniently list on the command line,
+you can list the names in a file, and @command{tar} will read that file.
+@xref{files}.
+
+There are various ways of causing @command{tar} to skip over some files,
+and not archive them. @xref{Choosing}.
+
+@node Backups
+@chapter Performing Backups and Restoring Files
+@UNREVISED
+
+@GNUTAR{} is distributed along with the scripts
+which the Free Software Foundation uses for performing backups. There
+is no corresponding scripts available yet for doing restoration of
+files. Even if there is a good chance those scripts may be satisfying
+to you, they are not the only scripts or methods available for doing
+backups and restore. You may well create your own, or use more
+sophisticated packages dedicated to that purpose.
+
+Some users are enthusiastic about @code{Amanda} (The Advanced Maryland
+Automatic Network Disk Archiver), a backup system developed by James
+da Silva @file{jds@@cs.umd.edu} and available on many Unix systems.
+This is free software, and it is available at these places:
+
+@smallexample
+http://www.cs.umd.edu/projects/amanda/amanda.html
+ftp://ftp.cs.umd.edu/pub/amanda
+@end smallexample
+
+@FIXME{
+
+Here is a possible plan for a future documentation about the backuping
+scripts which are provided within the @GNUTAR{}
+distribution.
+
+@itemize @bullet
+@item dumps
+ @itemize @minus
+ @item what are dumps
+ @item different levels of dumps
+ @itemize +
+ @item full dump = dump everything
+ @item level 1, level 2 dumps etc
+ A level @var{n} dump dumps everything changed since the last level
+ @var{n}-1 dump (?)
+ @end itemize
+ @item how to use scripts for dumps (ie, the concept)
+ @itemize +
+ @item scripts to run after editing backup specs (details)
+ @end itemize
+ @item Backup Specs, what is it.
+ @itemize +
+ @item how to customize
+ @item actual text of script [/sp/dump/backup-specs]
+ @end itemize
+ @item Problems
+ @itemize +
+ @item rsh doesn't work
+ @item rtape isn't installed
+ @item (others?)
+ @end itemize
+ @item the @option{--incremental} option of tar
+ @item tapes
+ @itemize +
+ @item write protection
+ @item types of media, different sizes and types, useful for different things
+ @item files and tape marks
+ one tape mark between files, two at end.
+ @item positioning the tape
+ MT writes two at end of write,
+ backspaces over one when writing again.
+ @end itemize
+ @end itemize
+@end itemize
+}
+
+This chapter documents both the provided shell scripts and @command{tar}
+options which are more specific to usage as a backup tool.
+
+To @dfn{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 accidentally deleted). File system @dfn{backups} are also
+called @dfn{dumps}.
+
+@menu
+* Full Dumps:: Using @command{tar} to Perform Full Dumps
+* Incremental Dumps:: Using @command{tar} to Perform Incremental Dumps
+* Backup Levels:: Levels of Backups
+* Backup Parameters:: Setting Parameters for Backups and Restoration
+* Scripted Backups:: Using the Backup Scripts
+* Scripted Restoration:: Using the Restore Script
+@end menu
+
+@node Full Dumps
+@section Using @command{tar} to Perform Full Dumps
+@UNREVISED
+
+@cindex full dumps
+@cindex dumps, full
+
+@cindex corrupted archives
+Full dumps should only be made when no other people or programs
+are modifying files in the file system. If files are modified while
+@command{tar} is making the backup, they may not be stored properly in
+the archive, in which case you won't be able to restore them if you
+have to. (Files not being modified are written with no trouble, and do
+not corrupt the entire archive.)
+
+You will want to use the @option{--label=@var{archive-label}}
+(@option{-V @var{archive-label}}) option to give the archive a
+volume label, so you can tell what this archive is even if the label
+falls off the tape, or anything like that.
+
+Unless the file system you are dumping is guaranteed to fit on
+one volume, you will need to use the @option{--multi-volume} (@option{-M}) option.
+Make sure you have enough tapes on hand to complete the backup.
+
+If you want to dump each file system separately you will need to use
+the @option{--one-file-system} (@option{-l}) option to prevent
+@command{tar} from crossing file system boundaries when storing
+(sub)directories.
+
+The @option{--incremental} (@option{-G}) (@pxref{Incremental Dumps})
+option is not needed, since this is a complete copy of everything in
+the file system, and a full restore from this backup would only be
+done onto a completely
+empty disk.
+
+Unless you are in a hurry, and trust the @command{tar} program (and your
+tapes), it is a good idea to use the @option{--verify} (@option{-W})
+option, to make sure your files really made it onto the dump properly.
+This will also detect cases where the file was modified while (or just
+after) it was being archived. Not all media (notably cartridge tapes)
+are capable of being verified, unfortunately.
+
+@node Incremental Dumps
+@section Using @command{tar} to Perform Incremental Dumps
+
+@dfn{Incremental backup} is a special form of @GNUTAR{} archive that
+stores additional metadata so that exact state of the file system
+can be restored when extracting the archive.
+
+@GNUTAR{} currently offers two options for handling incremental
+backups: @option{--listed-incremental=@var{snapshot-file}} (@option{-g
+@var{snapshot-file}}) and @option{--incremental} (@option{-G}).
+
+@opindex listed-incremental
+The option @option{--listed-incremental} instructs tar to operate on
+an incremental archive with additional metadata stored in a standalone
+file, called a @dfn{snapshot file}. The purpose of this file is to help
+determine which files have been changed, added or deleted since the
+last backup, so that the next incremental backup will contain only
+modified files. The name of the snapshot file is given as an argument
+to the option:
+
+@table @option
+@item --listed-incremental=@var{file}
+@itemx -g @var{file}
+ Handle incremental backups with snapshot data in @var{file}.
+@end table
+
+To create an incremental backup, you would use
+@option{--listed-incremental} together with @option{--create}
+(@pxref{create}). For example:
+
+@smallexample
+$ @kbd{tar --create \
+ --file=archive.1.tar \
+ --listed-incremental=/var/log/usr.snar \
+ /usr}
+@end smallexample
+
+This will create in @file{archive.1.tar} an incremental backup of
+the @file{/usr} file system, storing additional metadata in the file
+@file{/var/log/usr.snar}. If this file does not exist, it will be
+created. The created archive will then be a @dfn{level 0 backup};
+please see the next section for more on backup levels.
+
+Otherwise, if the file @file{/var/log/usr.snar} exists, it
+determines which files are modified. In this case only these files will be
+stored in the archive. Suppose, for example, that after running the
+above command, you delete file @file{/usr/doc/old} and create
+directory @file{/usr/local/db} with the following contents:
+
+@smallexample
+$ @kbd{ls /usr/local/db}
+/usr/local/db/data
+/usr/local/db/index
+@end smallexample
+
+Some time later you create another incremental backup. You will
+then see:
+
+@smallexample
+$ @kbd{tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar \
+ /usr}
+tar: usr/local/db: Directory is new
+usr/local/db/
+usr/local/db/data
+usr/local/db/index
+@end smallexample
+
+@noindent
+The created archive @file{archive.2.tar} will contain only these
+three members. This archive is called a @dfn{level 1 backup}. Notice
+that @file{/var/log/usr.snar} will be updated with the new data, so if
+you plan to create more @samp{level 1} backups, it is necessary to
+create a working copy of the snapshot file before running
+@command{tar}. The above example will then be modified as follows:
+
+@smallexample
+$ @kbd{cp /var/log/usr.snar /var/log/usr.snar-1}
+$ @kbd{tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar-1 \
+ /usr}
+@end smallexample
+
+Incremental dumps depend crucially on time stamps, so the results are
+unreliable if you modify a file's time stamps during dumping (e.g.,
+with the @option{--atime-preserve=replace} option), or if you set the clock
+backwards.
+
+Metadata stored in snapshot files include device numbers, which,
+obviously is supposed to be a non-volatile value. However, it turns
+out that NFS devices have undependable values when an automounter
+gets in the picture. This can lead to a great deal of spurious
+redumping in incremental dumps, so it is somewhat useless to compare
+two NFS devices numbers over time. The solution implemented currently
+is to considers all NFS devices as being equal when it comes to
+comparing directories; this is fairly gross, but there does not seem
+to be a better way to go.
+
+Note that incremental archives use @command{tar} extensions and may
+not be readable by non-@acronym{GNU} versions of the @command{tar} program.
+
+@opindex listed-incremental, using with @option{--extract}
+@opindex extract, using with @option{--listed-incremental}
+To extract from the incremental dumps, use
+@option{--listed-incremental} together with @option{--extract}
+option (@pxref{extracting files}). In this case, @command{tar} does
+not need to access snapshot file, since all the data necessary for
+extraction are stored in the archive itself. So, when extracting, you
+can give whatever argument to @option{--listed-incremental}, the usual
+practice is to use @option{--listed-incremental=/dev/null}.
+Alternatively, you can use @option{--incremental}, which needs no
+arguments. In general, @option{--incremental} (@option{-G}) can be
+used as a shortcut for @option{--listed-incremental} when listing or
+extracting incremental backups (for more information, regarding this
+option, @pxref{incremental-op}).
+
+When extracting from the incremental backup @GNUTAR{} attempts to
+restore the exact state the file system had when the archive was
+created. In particular, it will @emph{delete} those files in the file
+system that did not exist in their directories when the archive was
+created. If you have created several levels of incremental files,
+then in order to restore the exact contents the file system had when
+the last level was created, you will need to restore from all backups
+in turn. Continuing our example, to restore the state of @file{/usr}
+file system, one would do@footnote{Notice, that since both archives
+were created withouth @option{-P} option (@pxref{absolute}), these
+commands should be run from the root file system.}:
+
+@smallexample
+$ @kbd{tar --extract \
+ --listed-incremental=/dev/null \
+ --file archive.1.tar}
+$ @kbd{tar --extract \
+ --listed-incremental=/dev/null \
+ --file archive.2.tar}
+@end smallexample
+
+To list the contents of an incremental archive, use @option{--list}
+(@pxref{list}), as usual. To obtain more information about the
+archive, use @option{--listed-incremental} or @option{--incremental}
+combined with two @option{--verbose} options@footnote{Two
+@option{--verbose} options were selected to avoid breaking usual
+verbose listing output (@option{--list --verbose}) when using in
+scripts.
+
+@opindex incremental, using with @option{--list}
+@opindex listed-incremental, using with @option{--list}
+@opindex list, using with @option{--incremental}
+@opindex list, using with @option{--listed-incremental}
+Versions of @GNUTAR{} up to 1.15.1 used to dump verbatim binary
+contents of the DUMPDIR header (with terminating nulls) when
+@option{--incremental} or @option{--listed-incremental} option was
+given, no matter what the verbosity level. This behavior, and,
+especially, the binary output it produced were considered incovenient
+and were changed in version 1.16}:
+
+@smallexample
+@kbd{tar --list --incremental --verbose --verbose archive.tar}
+@end smallexample
+
+This command will 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 which is both human-readable and
+unambiguous for a program: each file name is printed as
+
+@smallexample
+@var{x} @var{file}
+@end smallexample
+
+@noindent
+where @var{x} is a letter describing the status of the file: @samp{Y}
+if the file is present in the archive, @samp{N} if the file is not
+included in the archive, or a @samp{D} if the file is a directory (and
+is included in the archive).@FIXME-xref{dumpdir format}. Each such
+line is terminated by a newline character. The last line is followed
+by an additional newline to indicate the end of the data.
+
+@anchor{incremental-op}The option @option{--incremental} (@option{-G})
+gives the same behavior as @option{--listed-incremental} when used
+with @option{--list} and @option{--extract} options. When used with
+@option{--create} option, it creates an incremental archive without
+creating snapshot file. Thus, it is impossible to create several
+levels of incremental backups with @option{--incremental} option.
+
+@node Backup Levels
+@section Levels of Backups
+
+An archive containing all the files in the file system is called a
+@dfn{full backup} or @dfn{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 use @dfn{incremental dumps}. A @dfn{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).
+
+@GNUTAR{} comes with scripts you can use to do full
+and level-one (actually, even level-two and so on) dumps. Using
+scripts (shell programs) to perform backups and restoration is a
+convenient and reliable alternative to typing out file name lists
+and @command{tar} commands by hand.
+
+Before you use these scripts, you need to edit the file
+@file{backup-specs}, which specifies parameters used by the backup
+scripts and by the restore script. This file is usually located
+in @file{/etc/backup} directory. @xref{Backup Parameters}, for its
+detailed description. Once the backup parameters are set, you can
+perform backups or restoration by running the appropriate script.
+
+The name of the backup script is @code{backup}. The name of the
+restore script is @code{restore}. The following sections describe
+their use in detail.
+
+@emph{Please Note:} The backup and 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. @xref{Incremental Dumps}, before
+making such an attempt.
+
+@node Backup Parameters
+@section Setting Parameters for Backups and Restoration
+
+The file @file{backup-specs} specifies backup parameters for the
+backup and restoration scripts provided with @command{tar}. You must
+edit @file{backup-specs} to fit your system configuration and schedule
+before using these scripts.
+
+Syntactically, @file{backup-specs} is a shell script, containing
+mainly variable assignments. However, any valid shell construct
+is allowed in this file. Particularly, you may wish to define
+functions within that script (e.g., see @code{RESTORE_BEGIN} below).
+For more information about shell script syntax, please refer to
+@url{http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
+g_02, the definition of the Shell Command Language}. See also
+@ref{Top,,Bash Features,bashref,Bash Reference Manual}.
+
+The shell variables controlling behavior of @code{backup} and
+@code{restore} are described in the following subsections.
+
+@menu
+* General-Purpose Variables::
+* Magnetic Tape Control::
+* User Hooks::
+* backup-specs example:: An Example Text of @file{Backup-specs}
+@end menu
+
+@node General-Purpose Variables
+@subsection General-Purpose Variables
+
+@defvr {Backup variable} ADMINISTRATOR
+The user name of the backup administrator. @code{Backup} scripts
+sends a backup report to this address.
+@end defvr
+
+@defvr {Backup variable} BACKUP_HOUR
+The hour at which the backups are done. This can be a number from 0
+to 23, or the time specification in form @var{hours}:@var{minutes},
+or the string @samp{now}.
+
+This variable is used by @code{backup}. Its value may be overridden
+using @option{--time} option (@pxref{Scripted Backups}).
+@end defvr
+
+@defvr {Backup variable} TAPE_FILE
+
+The device @command{tar} writes the archive to. If @var{TAPE_FILE}
+is a remote archive (@pxref{remote-dev}), backup script will suppose
+that your @command{mt} is able to access remote devices. If @var{RSH}
+(@pxref{RSH}) is set, @option{--rsh-command} option will be added to
+invocations of @command{mt}.
+@end defvr
+
+@defvr {Backup variable} BLOCKING
+
+The blocking factor @command{tar} will use when writing the dump archive.
+@xref{Blocking Factor}.
+@end defvr
+
+@defvr {Backup variable} BACKUP_DIRS
+
+A list of file systems to be dumped (for @code{backup}), or restored
+(for @code{restore}). 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 @command{tar} on, and should
+normally be the host that actually contains the file system. However,
+the host machine must have @GNUTAR{} 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 @command{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.
+
+If the list of file systems is very long you may wish to put it
+in a separate file. This file is usually named
+@file{/etc/backup/dirs}, but this name may be overridden in
+@file{backup-specs} using @code{DIRLIST} variable.
+@end defvr
+
+@defvr {Backup variable} DIRLIST
+
+A path to the file containing the list of the file systems to backup
+or restore. By default it is @file{/etc/backup/dirs}.
+@end defvr
+
+@defvr {Backup variable} BACKUP_FILES
+
+A list of individual files to be dumped (for @code{backup}), or restored
+(for @code{restore}). These should be accessible from the machine on
+which the backup script is run.
+
+If the list of file systems is very long you may wish to store it
+in a separate file. This file is usually named
+@file{/etc/backup/files}, but this name may be overridden in
+@file{backup-specs} using @code{FILELIST} variable.
+@end defvr
+
+@defvr {Backup variable} FILELIST
+
+A path to the file containing the list of the individual files to backup
+or restore. By default it is @file{/etc/backup/files}.
+@end defvr
+
+@defvr {Backup variable} MT
+
+Full file name of @command{mt} binary.
+@end defvr
+
+@defvr {Backup variable} RSH
+@anchor{RSH}
+Full file name of @command{rsh} binary or its equivalent. You may wish to
+set it to @code{ssh}, to improve security. In this case you will have
+to use public key authentication.
+@end defvr
+
+@defvr {Backup variable} RSH_COMMAND
+
+Full file name of @command{rsh} binary on remote mashines. This will
+be passed via @option{--rsh-command} option to the remote invocation
+of @GNUTAR{}.
+@end defvr
+
+@defvr {Backup variable} VOLNO_FILE
+
+Name of temporary file to hold volume numbers. This needs to be accessible
+by all the machines which have file systems to be dumped.
+@end defvr
+
+@defvr {Backup variable} XLIST
+
+Name of @dfn{exclude file list}. An @dfn{exclude file list} is a file
+located on the remote machine and containing the list of files to
+be excluded from the backup. Exclude file lists are searched in
+/etc/tar-backup directory. A common use for exclude file lists
+is to exclude files containing security-sensitive information
+(e.g., @file{/etc/shadow} from backups).
+
+This variable affects only @code{backup}.
+@end defvr
+
+@defvr {Backup variable} SLEEP_TIME
+
+Time to sleep between dumps of any two successive file systems
+
+This variable affects only @code{backup}.
+@end defvr
+
+@defvr {Backup variable} DUMP_REMIND_SCRIPT
+
+Script to be run when it's time to insert a new tape in for the next
+volume. Administrators may want to tailor this script for their site.
+If this variable isn't set, @GNUTAR{} will display its built-in prompt
+@FIXME-xref{describe it somewhere!}, and will expect confirmation from
+the console.
+@end defvr
+
+@defvr {Backup variable} SLEEP_MESSAGE
+
+Message to display on the terminal while waiting for dump time. Usually
+this will just be some literal text.
+@end defvr
+
+@defvr {Backup variable} TAR
+
+Full file name of the @GNUTAR{} executable. If this is not set, backup
+scripts will search @command{tar} in the current shell path.
+@end defvr
+
+@node Magnetic Tape Control
+@subsection Magnetic Tape Control
+
+Backup scripts access tape device using special @dfn{hook functions}.
+These functions take a single argument -- the name of the tape
+device. Their names are kept in the following variables:
+
+@defvr {Backup variable} MT_BEGIN
+The name of @dfn{begin} function. This function is called before
+accessing the drive. By default it retensions the tape:
+
+@smallexample
+MT_BEGIN=mt_begin
+
+mt_begin() @{
+ mt -f "$1" retension
+@}
+@end smallexample
+@end defvr
+
+@defvr {Backup variable} MT_REWIND
+The name of @dfn{rewind} function. The default definition is as
+follows:
+
+@smallexample
+MT_REWIND=mt_rewind
+
+mt_rewind() @{
+ mt -f "$1" rewind
+@}
+@end smallexample
+
+@end defvr
+
+@defvr {Backup variable} MT_OFFLINE
+The name of the function switching the tape off line. By default
+it is defined as follows:
+
+@smallexample
+MT_OFFLINE=mt_offline
+
+mt_offline() @{
+ mt -f "$1" offl
+@}
+@end smallexample
+@end defvr
+
+@defvr {Backup variable} MT_STATUS
+The name of the function used to obtain the status of the archive device,
+including error count. Default definition:
+
+@smallexample
+MT_STATUS=mt_status
+
+mt_status() @{
+ mt -f "$1" status
+@}
+@end smallexample
+@end defvr
+
+@node User Hooks
+@subsection User Hooks
+
+@dfn{User hooks} are shell functions executed before and after
+each @command{tar} invocation. Thus, there are @dfn{backup
+hooks}, which are executed before and after dumping each file
+system, and @dfn{restore hooks}, executed before and
+after restoring a file system. Each user hook is a shell function
+taking four arguments:
+
+@deffn {User Hook Function} hook @var{level} @var{host} @var{fs} @var{fsname}
+Its arguments are:
+
+@table @var
+@item level
+Current backup or restore level.
+
+@item host
+Name or IP address of the host machine being dumped or restored.
+
+@item fs
+Full path name to the file system being dumped or restored.
+
+@item fsname
+File system name with directory separators replaced with colons. This
+is useful, e.g., for creating unique files.
+@end table
+@end deffn
+
+Following variables keep the names of user hook functions
+
+@defvr {Backup variable} DUMP_BEGIN
+Dump begin function. It is executed before dumping the file system.
+@end defvr
+
+@defvr {Backup variable} DUMP_END
+Executed after dumping the file system.
+@end defvr
+
+@defvr {Backup variable} RESTORE_BEGIN
+Executed before restoring the file system.
+@end defvr
+
+@defvr {Backup variable} RESTORE_END
+Executed after restoring the file system.
+@end defvr
+
+@node backup-specs example
+@subsection An Example Text of @file{Backup-specs}
+
+The following is an example of @file{backup-specs}:
+
+@smallexample
+# site-specific parameters for file system backup.
+
+ADMINISTRATOR=friedman
+BACKUP_HOUR=1
+TAPE_FILE=/dev/nrsmt0
+
+# Use @code{ssh} instead of the less secure @code{rsh}
+RSH=/usr/bin/ssh
+RSH_COMMAND=/usr/bin/ssh
+
+# Override MT_STATUS function:
+my_status() @{
+ mts -t $TAPE_FILE
+@}
+MT_STATUS=my_status
+
+# Disable MT_OFFLINE function
+MT_OFFLINE=:
+
+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]"
+
+@end smallexample
+
+@node Scripted Backups
+@section Using the Backup Scripts
+
+The syntax for running a backup script is:
+
+@smallexample
+backup --level=@var{level} --time=@var{time}
+@end smallexample
+
+The @option{level} option requests the dump level. Thus, to produce
+a full dump, specify @code{--level=0} (this is the default, so
+@option{--level} may be omitted if its value is @code{0}).
+@footnote{For backward compatibility, the @code{backup} will also
+try to deduce the requested dump level from the name of the
+script itself. If the name consists of a string @samp{level-}
+followed by a single decimal digit, that digit is taken as
+the dump level number. Thus, you may create a link from @code{backup}
+to @code{level-1} and then run @code{level-1} whenever you need to
+create a level one dump.}
+
+The @option{--time} option determines when should the backup be
+run. @var{Time} may take three forms:
+
+@table @asis
+@item @var{hh}:@var{mm}
+
+The dump must be run at @var{hh} hours @var{mm} minutes.
+
+@item @var{hh}
+
+The dump must be run at @var{hh} hours
+
+@item now
+
+The dump must be run immediately.
+@end table
+
+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 @code{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 (@pxref{Scripted
+Restoration}).
+
+The backup scripts write two files on the file system. The first is a
+record file in @file{/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. @xref{Snapshot Files}, 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
+@file{log-@var{mm-dd-yyyy}-level-@var{n}}, where @var{mm-dd-yyyy}
+represents current date, and @var{n} represents current dump level number.
+
+The script also prints the name of each system being dumped to the
+standard output.
+
+Following is the full list of options accepted by @code{backup}
+script:
+
+@table @option
+@item -l @var{level}
+@itemx --level=@var{level}
+Do backup level @var{level} (default 0).
+
+@item -f
+@itemx --force
+Force backup even if today's log file already exists.
+
+@item -v[@var{level}]
+@itemx --verbose[=@var{level}]
+Set verbosity level. The higher the level is, the more debugging
+information will be output during execution. Devault @var{level}
+is 100, which means the highest debugging level.
+
+@item -t @var{start-time}
+@itemx --time=@var{start-time}
+Wait till @var{time}, then do backup.
+
+@item -h
+@itemx --help
+Display short help message and exit.
+
+@item -V
+@itemx --version
+Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
+@end table
+
+
+@node Scripted Restoration
+@section Using the Restore Script
+
+To restore files that were archived using a scripted backup, use the
+@code{restore} script. Its usage is quite straightforward. In the
+simplest form, invoke @code{restore --all}, it will
+then restore all the file systems and files specified in
+@file{backup-specs} (@pxref{General-Purpose Variables,BACKUP_DIRS}).
+
+You may select the file systems (and/or files) to restore by
+giving @code{restore} list of @dfn{patterns} in its command
+line. For example, running
+
+@smallexample
+restore 'albert:*'
+@end smallexample
+
+@noindent
+will restore all file systems on the machine @samp{albert}. A more
+complicated example:
+
+@smallexample
+restore 'albert:*' '*:/var'
+@end smallexample
+
+@noindent
+This command will restore all file systems on the machine @samp{albert}
+as well as @file{/var} file system on all machines.
+
+By default @code{restore} will start restoring files from the lowest
+available dump level (usually zero) and will continue through
+all available dump levels. There may be situations where such a
+thorough restore is not necessary. For example, you may wish to
+restore only files from the recent level one backup. To do so,
+use @option{--level} option, as shown in the example below:
+
+@smallexample
+restore --level=1
+@end smallexample
+
+The full list of options accepted by @code{restore} follows:
+
+@table @option
+@item -a
+@itemx --all
+Restore all file systems and files specified in @file{backup-specs}
+
+@item -l @var{level}
+@itemx --level=@var{level}
+Start restoring from the given backup level, instead of the default 0.
+
+@item -v[@var{level}]
+@itemx --verbose[=@var{level}]
+Set verbosity level. The higher the level is, the more debugging
+information will be output during execution. Devault @var{level}
+is 100, which means the highest debugging level.
+
+@item -h
+@itemx --help
+Display short help message and exit.
+
+@item -V
+@itemx --version
+Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
+@end table
+
+You should start the restore script with the media containing the
+first volume of the archive mounted. The script will prompt for other
+volumes as they are needed. If the archive is on tape, you don't need
+to rewind the tape to to its beginning---if the tape head is
+positioned past the beginning of the archive, the script will rewind
+the tape as needed. @FIXME-xref{Media, for a discussion of tape
+positioning.}
+
+@quotation
+@strong{Warning:} The script will delete files from the active file
+system if they were not in the file system when the archive was made.
+@end quotation
+
+@xref{Incremental Dumps}, for an explanation of how the script makes
+that determination.
+
+@node Choosing
+@chapter Choosing Files and Names for @command{tar}
+@UNREVISED
+
+@FIXME{Melissa (still) Doesn't Really Like This ``Intro'' Paragraph!!!}
+
+Certain options to @command{tar} enable you to specify a name for your
+archive. Other options let you decide which files to include or exclude
+from the archive, based on when or whether files were modified, whether
+the file names do or don't match specified patterns, or whether files
+are in specified directories.