+This option is especially useful when reading damaged archives, since
+it helps pinpoint the damaged sections. It can also be used with
+@value{op-list} when listing a file-system backup tape, allowing you to
+choose among several backup tapes when retrieving a file later, in
+favor of the tape where the file appears earliest (closest to the
+front of the tape). @FIXME-xref{when the node name is set and the
+backup section written.}
+
+@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 @value{op-interactive} option.
+@command{tar} also accepts @option{--confirmation} for this option.
+
+When the @value{op-interactive} 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, @value{op-create}, @value{op-list} and
+@value{op-extract}, are currently presented and described in the tutorial
+chapter of this manual. This section provides some complementary notes
+for these operations.
+
+@table @asis
+@item @value{op-create}
+
+Creating an empty archive would have some kind of elegance. One can
+initialize an empty archive and later use @value{op-append} 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 @value{op-create} option is
+given, there are no arguments besides options, and @value{op-files-from}
+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 @value{op-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
+
+@item @value{op-extract}
+
+A socket is stored, within a @GNUTAR{} archive, as a pipe.
+
+@item @value{op-list}
+
+@GNUTAR{} now shows dates as @samp{1996-08-30},
+while it used to show them as @samp{Aug 30 1996}. (One can revert to
+the old behavior by defining @code{USE_OLD_CTIME} in @file{src/list.c}
+before reinstalling.) But 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 @kbd
+@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
+
+If you want to add files to an existing archive, you don't need to
+create a new archive; you can use @value{op-append}. 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 @value{op-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 @value{op-list}, you will see all of those members
+listed, with their modification times, owners, etc.
+
+Other operations don't deal with these members as perfectly as you might
+prefer; if you were to use @value{op-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 @value{op-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 @value{op-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
+@value{op-append} 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 @value{op-verbose} 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 @value{op-list} operation, you will see that
+@file{rock} has been added to the archive:
+
+@smallexample
+$ @kbd{tar --list --file=collection.tar}
+-rw-rw-rw- me user 28 1996-10-18 16:31 jazz
+-rw-rw-rw- me user 21 1996-09-23 16:44 blues
+-rw-rw-rw- me user 20 1996-09-23 16:44 folk
+-rw-rw-rw- 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 @value{op-append} 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-rw-rw- me user 28 1996-10-18 16:31 jazz
+-rw-rw-rw- me user 21 1996-09-23 16:44 blues
+-rw-rw-rw- me user 20 1996-09-23 16:44 folk
+-rw-rw-rw- me user 20 1996-09-23 16:44 rock
+-rw-rw-rw- 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 @value{op-occurrence} option, as shown in
+the following example:
+
+@smallexample
+$ @kbd{tar --extract -vv --occurrence --file=collection.tar blues}
+-rw-rw-rw- me user 21 1996-09-23 16:44 blues
+@end smallexample
+
+@xref{Writing}, for more information on @value{op-extract} and
+@xref{Option Summary, --occurrence}, for the description of
+@value{op-occurrence} option.
+
+@node update
+@subsection Updating an Archive
+@UNREVISED
+@cindex Updating an archive
+
+In the previous section, you learned how to use @value{op-append} to add
+a file to an existing archive. A related operation is
+@value{op-update}. 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 @value{op-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 @value{op-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 @value{op-update} 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 @value{op-verbose} 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.
+
+@value{op-update} 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
+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
+@value{op-concatenate} operation.
+
+To use @option{--concatenate}, name the archives to be concatenated on the
+command line. (Nothing happens if you don't list any.) The members,
+and their member names, will be copied verbatim from those archives. If
+this causes multiple members to have the same name, it does not delete
+any members; all the members with the same name coexist. @FIXME-ref{For
+information on how this affects reading the archive, Multiple
+Members with the Same 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-rw-rw- melissa user 105 1997-01-21 19:42 blues
+-rw-rw-rw- melissa user 33 1997-01-20 15:34 rock
+$ @kbd{tar -tvf folkjazz.tar}
+-rw-rw-rw- melissa user 20 1996-09-23 16:44 folk
+-rw-rw-rw- 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. @FIXME-pxref{Matching Format Parameters}The new,
+concatenated archive will be called by the same name as the first
+archive listed on the command line. @FIXME{is there a way to specify a
+new name?}
+
+Like @value{op-append}, 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
+@value{op-ignore-zeros} option. @xref{Ignore Zeros}, for further
+information on dealing with archives improperly combined using the
+@command{cat} shell utility.
+
+@FIXME{this shouldn't go here. where should it go?} You must specify
+the source archives using @value{op-file} (@value{pxref-file}). If you
+do not specify the target archive, @command{tar} uses the value of the
+environment variable @env{TAPE}, or, if this has not been set, the
+default archive name.
+
+@node delete
+@subsection Removing Archive Members Using @option{--delete}
+@UNREVISED
+@cindex Deleting files from an archive
+@cindex Removing files from an archive
+
+You can remove members from an archive by using the @value{op-delete}
+option. Specify the name of the archive with @value{op-file} and then
+specify the names of the members to be deleted; if you list no member
+names, nothing will be deleted. The @value{op-verbose} option will
+cause @command{tar} to print the names of the members as they are deleted.
+As with @value{op-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 @value{op-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
+
+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
+
+@noindent
+@FIXME{what does this actually depend on? i'm making a guess,
+here.}Depending on the system where you are running @command{tar} and the
+version you are running, @command{tar} may have a different error message,
+such as:
+
+@smallexample
+funk: does not exist
+@end smallexample
+
+@FIXME-xref{somewhere, for more information about format parameters.
+Melissa says: such as "format variations"? But why? Clearly I don't
+get it yet; I'll deal when I get to that section.}
+
+The spirit behind the @value{op-compare} 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}
+
+The previous chapter described the basics of how to use
+@value{op-create} 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 @kbd
+@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.}
+
+The previous chapter showed how to use @value{op-extract} to extract
+an archive into the filesystem. 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
+@cindex Reading incomplete records
+@cindex Records, incomplete
+@cindex End-of-archive entries, ignoring
+@cindex Ignoring end-of-archive entries
+@cindex Large lists of file names on small machines
+@cindex Small memory
+@cindex Running out of space
+@UNREVISED
+
+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 @value{op-read-full-records} option
+in conjunction with the @value{op-extract} or @value{op-list} operations.
+@value{xref-read-full-records}.
+
+The @value{op-read-full-records} 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 @value{op-read-full-records} and
+@value{op-blocking-factor}, using a blocking factor larger than what the
+archive uses. This lets you avoid having to determine the blocking factor
+of an archive. @value{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 @kbd
+@item --read-full-records
+@item -B
+Use in conjunction with @value{op-extract} 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
+
+Normally, @command{tar} stops reading when it encounters a block of zeros
+between file entries (which usually indicates the end of the archive).
+@value{op-ignore-zeros} allows @command{tar} to completely read an archive
+which contains a block of zeros before the end (i.e.@: a damaged
+archive, or one which was created by concatenating several archives
+together).
+
+The @value{op-ignore-zeros} 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 @kbd
+@item --ignore-zeros
+@itemx -i
+To ignore blocks of zeros (ie.@: end-of-archive entries) which may be
+encountered while reading an archive. Use in conjunction with
+@value{op-extract} or @value{op-list}.
+@end table
+
+@node Writing
+@subsection Changing How @command{tar} Writes Files
+@cindex Overwriting old files, prevention
+@cindex Protecting old files
+@cindex Modification times of extracted files
+@cindex Permissions of extracted files
+@cindex Modes of extracted files
+@cindex Writing extracted files to standard output
+@cindex Standard output, writing extracted files to
+@UNREVISED
+
+@FIXME{need to mention the brand new option, --backup}
+
+@menu
+* Dealing with Old Files::
+* Overwrite Old Files::
+* Keep Old Files::
+* Keep Newer Files::
+* Unlink First::
+* Recursive Unlink::
+* Modification Times::
+* Setting Access Permissions::
+* Writing to Standard Output::
+* remove files::
+@end menu
+
+@node Dealing with Old Files
+@unnumberedsubsubsec Options Controlling the Overwriting of Existing Files
+
+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.
+
+To be even more cautious and prevent existing files from being replaced, use
+the @value{op-keep-old-files} 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.
+
+To be more aggressive about altering existing files, use the
+@value{op-overwrite} option. It causes @command{tar} to overwrite
+existing files and to follow existing symbolic links when extracting.
+
+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 filesystem 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} @value{op-recursive-unlink} is specified
+to allow this behavior. In any case, single files are silently
+removed.
+
+Finally, the @value{op-unlink-first} 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 @kbd
+@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 @value{op-overwrite} option, particularly when
+combined with the @value{op-absolute-names} 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.
+
+@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 @kbd
+@item --keep-old-files
+@itemx -k
+Do not replace existing files from archive. The
+@value{op-keep-old-files} option prevents @command{tar} from replacing
+existing files with files with the same name from the archive.
+The @value{op-keep-old-files} option is meaningless with @value{op-list}.
+Prevents @command{tar} from replacing files in the file system during
+extraction.
+@end table
+
+@node Keep Newer Files
+@unnumberedsubsubsec Keep Newer Files
+
+@table @kbd
+@item --keep-newer-files
+Do not replace existing files that are newer than their archive
+copies. This option is meaningless with @value{op-list}.
+@end table
+
+@node Unlink First
+@unnumberedsubsubsec Unlink First
+
+@table @kbd
+@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 @kbd
+@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 @value{op-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 Modification Times
+@unnumberedsubsubsec Setting Modification Times
+
+Normally, @command{tar} sets the modification times of extracted files to
+the modification times recorded for the files in the archive, but
+limits the permissions of extracted files by the current @code{umask}
+setting.
+
+To set the modification times of extracted files to the time when
+the files were extracted, use the @value{op-touch} option in
+conjunction with @value{op-extract}.
+
+@table @kbd
+@item --touch
+@itemx -m
+Sets the modification time of extracted archive members to the time
+they were extracted, not the time recorded for them in the archive.
+Use in conjunction with @value{op-extract}.
+@end table
+
+@node Setting Access Permissions
+@unnumberedsubsubsec Setting Access Permissions
+
+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 @value{op-extract} operation. @FIXME{Should be
+aliased to ignore-umask.}
+
+@table @kbd
+@item --preserve-permission
+@itemx --same-permission
+@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
+@value{op-extract}.
+@end table
+
+@FIXME{Following paragraph needs to be rewritten: why doesn't this cat
+files together, why is this useful. is it really useful with
+more than one file?}
+
+@node Writing to Standard Output
+@unnumberedsubsubsec Writing to Standard Output
+
+To write the extracted files to the standard output, instead of
+creating the files on the file system, use @value{op-to-stdout} in
+conjunction with @value{op-extract}. This option is useful if you are
+extracting files to send them through a pipe, and do not need to
+preserve them in the file system. If you extract multiple members,
+they appear on standard output concatenated, in the order they are
+found in the archive.
+
+@table @kbd
+@item --to-stdout
+@itemx -O
+Writes files to the standard output. Used in conjunction with
+@value{op-extract}. Extract files to standard output. 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 @value{op-list}.
+@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
+
+@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 @kbd
+@item --remove-files
+Remove files after adding them to the archive.
+@end table
+
+@node Scarce
+@subsection Coping with Scarce Resources
+@cindex Middle of the archive, starting in the
+@cindex Running out of space during extraction
+@cindex Disk space, running out of
+@cindex Space on the disk, recovering from lack of
+@UNREVISED
+
+@menu
+* Starting File::
+* Same Order::
+@end menu
+
+@node Starting File
+@unnumberedsubsubsec Starting File
+
+@table @kbd
+@item --starting-file=@var{name}
+@itemx -K @var{name}
+Starts an operation in the middle of an archive. Use in conjunction
+with @value{op-extract} or @value{op-list}.
+@end table
+
+If a previous attempt to extract files failed due to lack of disk
+space, you can use @value{op-starting-file} 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, @value{op-starting-file} is
+not necessary. @value{xref-incremental}, @value{xref-interactive},
+and @value{ref-exclude}.)
+
+@node Same Order
+@unnumberedsubsubsec Same Order
+
+@table @kbd
+@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 @value{op-compare},
+@value{op-list}
+or @value{op-extract}.
+@end table
+
+@FIXME{we don't need/want --preserve to exist any more (from melissa:
+ie, don't want that *version* of the option to exist, or don't want
+the option to exist in either version?}
+
+@FIXME{i think this explanation is lacking.}
+
+The @value{op-same-order} 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
+@opindex numbered @r{backup method}
+Always make numbered backups.
+
+@item nil
+@itemx existing
+@opindex existing @r{backup method}
+Make numbered backups of files that already have them, simple backups
+of the others.
+
+@item never
+@itemx simple
+@opindex 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 @value{op-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.
+@value{xref-files-from}.
+
+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
+
+@ifclear PUBLISH
+
+Here is a possible plan for a future documentation about the backuping
+scripts which are provided within the @GNUTAR{}
+distribution.
+
+@smallexample
+.* dumps
+. + what are dumps
+
+. + different levels of dumps
+. - full dump = dump everything
+. - level 1, level 2 dumps etc, -
+ A level n dump dumps everything changed since the last level
+ n-1 dump (?)
+
+. + how to use scripts for dumps (ie, the concept)
+. - scripts to run after editing backup specs (details)
+
+. + Backup Specs, what is it.
+. - how to customize
+. - actual text of script [/sp/dump/backup-specs]
+
+. + Problems
+. - rsh doesn't work
+. - rtape isn't installed
+. - (others?)
+
+. + the --incremental option of tar
+
+. + tapes
+. - write protection
+. - types of media
+. : different sizes and types, useful for different things
+. - files and tape marks
+ one tape mark between files, two at end.
+. - positioning the tape
+ MT writes two at end of write,
+ backspaces over one when writing again.
+@end smallexample
+
+@end ifclear
+
+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
+* Inc Dumps:: Using @command{tar} to Perform Incremental Dumps
+* incremental and listed-incremental:: The Incremental Options
+* 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 filesystem. 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 @value{op-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 filesystem you are dumping is guaranteed to fit on
+one volume, you will need to use the @value{op-multi-volume} option.
+Make sure you have enough tapes on hand to complete the backup.
+
+If you want to dump each filesystem separately you will need to use
+the @value{op-one-file-system} option to prevent @command{tar} from crossing
+filesystem boundaries when storing (sub)directories.
+
+The @value{op-incremental} option is not needed, since this is a complete
+copy of everything in the filesystem, and a full restore from this
+backup would only be done onto a completely empty disk.
+
+Unless you are in a hurry, and trust the @command{tar} program (and your
+tapes), it is a good idea to use the @value{op-verify} option, to make
+sure your files really made it onto the dump properly. This will
+also detect cases where the file was modified while (or just after)
+it was being archived. Not all media (notably cartridge tapes) are
+capable of being verified, unfortunately.
+
+@value{op-listed-incremental} take a file name argument always. If the
+file doesn't exist, run a level zero dump, creating the file. If the
+file exists, uses that file to see what has changed.
+
+@value{op-incremental} @FIXME{look it up}
+
+@value{op-incremental} handle old @acronym{GNU}-format incremental backup.
+
+This option should only be used when creating an incremental backup of
+a filesystem. When the @value{op-incremental} option is used, @command{tar}
+writes, at the beginning of the archive, an entry for each of the
+directories that will be operated on. The entry for a directory
+includes a list of all the files in the directory at the time the
+dump was done, and a flag for each file indicating whether the file
+is going to be put in the archive. This information is used when
+doing a complete incremental restore.
+
+Note that this option causes @command{tar} to create a non-standard
+archive that may not be readable by non-@acronym{GNU} versions of the
+@command{tar} program.
+
+The @value{op-incremental} option means the archive is an incremental
+backup. Its meaning depends on the command that it modifies.
+
+If the @value{op-incremental} option is used with @value{op-list},
+@command{tar} will list, for each directory in the archive, the list
+of files in that directory at the time the archive was created. This
+information is put out in a format that is not easy for humans to
+read, but which is unambiguous for a program: each file name is
+preceded by either a @samp{Y} if the file is present in the archive,
+an @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). Each
+file name is terminated by a null character. The last file is
+followed by an additional null and a newline to indicate the end of
+the data.
+
+If the @value{op-incremental} option is used with @value{op-extract}, then
+when the entry for a directory is found, all files that currently
+exist in that directory but are not listed in the archive @emph{are
+deleted from the directory}.
+
+This behavior is convenient when you are restoring a damaged file
+system from a succession of incremental backups: it restores the
+entire state of the file system to that which obtained when the backup
+was made. If you don't use @value{op-incremental}, the file system will
+probably fill up with files that shouldn't exist any more.
+
+@value{op-listed-incremental} handle new @acronym{GNU}-format
+incremental backup. This option handles new @acronym{GNU}-format
+incremental backup. It has much the same effect as
+@value{op-incremental}, but also the time when the dump is done and
+the list of directories dumped is written to the given
+@var{file}. When restoring, only files newer than the saved time are
+restored, and the directory list is used to speed up operations.
+
+@value{op-listed-incremental} acts like @value{op-incremental}, but when
+used in conjunction with @value{op-create} will also cause @command{tar} to
+use the file @var{file}, which contains information about the state
+of the filesystem at the time of the last backup, to decide which
+files to include in the archive being created. That file will then
+be updated by @command{tar}. If the file @var{file} does not exist when
+this option is specified, @command{tar} will create it, and include all
+appropriate files in the archive.
+
+The file, which is archive independent, contains the date it was last
+modified and a list of devices, inode numbers and directory names.
+@command{tar} will archive files with newer mod dates or inode change
+times, and directories with an unchanged inode number and device but
+a changed directory name. The file is updated after the files to
+be archived are determined, but before the new archive is actually
+created.
+
+@node Inc Dumps
+@section Using @command{tar} to Perform Incremental Dumps
+@UNREVISED
+
+@cindex incremental dumps
+@cindex dumps, incremental
+
+Performing incremental dumps is similar to performing full dumps,
+although a few more options will usually be needed.
+
+A standard scheme is to do a @emph{monthly} (full) dump once a month,
+a @emph{weekly} dump once a week of everything since the last monthly
+and a @emph{daily} every day of everything since the last (weekly or
+monthly) dump.
+
+Here is a sample script to dump the directory hierarchies @samp{/usr}
+and @samp{/var}.
+
+@smallexample
+#! /bin/sh
+tar --create \
+ --blocking-factor=126 \
+ --file=/dev/rmt/0 \
+ --label="`hostname` /usr /var `date +%Y-%m-%d`" \
+ --listed-incremental=/var/log/usr-var.snar \
+ --verbose \
+ /usr /var
+@end smallexample
+
+This script uses the file @file{/var/log/usr-var.snar} as a snapshot to
+store information about the previous tar dump.
+
+The blocking factor 126 is an attempt to make the tape drive stream.
+Some tape devices cannot handle 64 kB blocks or larger, and require the
+block size to be a multiple of 1 kB; for these devices, 126 is the
+largest blocking factor that can be used.
+
+@node incremental and listed-incremental
+@section The Incremental Options
+@UNREVISED
+
+@value{op-incremental} is used in conjunction with @value{op-create},
+@value{op-extract} or @value{op-list} when backing up and restoring file
+systems. An archive cannot be extracted or listed with the
+@value{op-incremental} option specified unless it was created with the
+option specified. This option should only be used by a script, not by
+the user, and is usually disregarded in favor of
+@value{op-listed-incremental}, which is described below.
+
+@value{op-incremental} in conjunction with @value{op-create} causes
+@command{tar} to write, at the beginning of the archive, an entry for
+each of the directories that will be archived. The entry for a
+directory includes a list of all the files in the directory at the
+time the archive was created and a flag for each file indicating
+whether or not the file is going to be put in the archive.
+
+Note that this option causes @command{tar} to create a non-standard
+archive that may not be readable by non-@acronym{GNU} versions of the
+@command{tar} program.
+
+@value{op-incremental} in conjunction with @value{op-extract} causes
+@command{tar} to read the lists of directory contents previously stored
+in the archive, @emph{delete} files in the file system that did not
+exist in their directories when the archive was created, and then
+extract the files in the archive.
+
+This behavior is convenient when restoring a damaged file system from
+a succession of incremental backups: it restores the entire state of
+the file system to that which obtained when the backup was made. If
+@value{op-incremental} isn't specified, the file system will probably
+fill up with files that shouldn't exist any more.
+
+@value{op-incremental} in conjunction with @value{op-list} causes
+@command{tar} to print, for each directory in the archive, the list of
+files in that directory at the time the archive was created. This
+information is put out in a format that is not easy for humans to
+read, but which is unambiguous for a program: each file name is
+preceded by either a @samp{Y} if the file is present in the archive,
+an @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). Each
+file name is terminated by a null character. The last file is followed
+by an additional null and a newline to indicate the end of the data.
+
+@value{op-listed-incremental} acts like @value{op-incremental}, but when
+used in conjunction with @value{op-create} will also cause @command{tar}
+to use the file @var{snapshot-file}, which contains information about
+the state of the file system at the time of the last backup, to decide
+which files to include in the archive being created. That file will
+then be updated by @command{tar}. If the file @var{file} does not exist
+when this option is specified, @command{tar} will create it, and include
+all appropriate files in the archive.
+
+The file @var{file}, which is archive independent, contains the date
+it was last modified and a list of devices, inode numbers and
+directory names. @command{tar} will archive files with newer mod dates
+or inode change times, and directories with an unchanged inode number
+and device but a changed directory name. The file is updated after
+the files to be archived are determined, but before the new archive is
+actually created.
+
+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} option), or if you set the clock
+backwards.
+
+Despite it should be obvious that a device has a non-volatile value, NFS
+devices have non-dependable values when an automounter gets in the picture.
+This led to a great deal of spurious redumping in incremental dumps,
+so it is somewhat useless to compare two NFS devices numbers over time.
+So @command{tar} now 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.
+
+@command{tar} doesn't access @var{snapshot-file} when
+@value{op-extract} or @value{op-list} are specified, but the
+@value{op-listed-incremental} option must still be given. A
+placeholder @var{snapshot-file} can be specified, e.g.,
+@file{/dev/null}.
+
+@FIXME{this section needs to be written}
+
+@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. @FIXME-xref{Script Syntax} 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. @value{xref-incremental}, and
+@value{xref-listed-incremental}, 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.
+@value{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 filesystems 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 filesystems 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 filesystems
+
+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 filesystem being dumped or restored.
+
+@item fsname
+Filesystem 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 filesystem.
+@end defvr
+
+@defvr {Backup variable} DUMP_END
+Executed after dumping the filesystem.
+@end defvr
+
+@defvr {Backup variable} RESTORE_BEGIN
+Executed before restoring the filesystem.
+@end defvr
+
+@defvr {Backup variable} RESTORE_END
+Executed after restoring the filesystem.
+@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. @FIXME-xref{incremental and listed-incremental, for a more
+detailed explanation of this file.}
+
+The second file is a log file containing the names of the file systems
+and files dumped, what time the backup was made, and any error
+messages that were generated, as well as how much space was left in
+the media volume after the last volume of the archive was written.
+You should check this log file after every backup. The file name is
+@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 -L
+@itemx --license
+Display program license and exit.
+
+@item -V
+@itemx --version
+Display program version and exit.
+@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 filesystems and files specified in
+@file{backup-specs} (@pxref{General-Purpose Variables,BACKUP_DIRS}).
+
+You may select the filesystems (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 filesystems on the machine @samp{albert}. A more
+complicated example:
+
+@smallexample
+restore 'albert:*' '*:/var'
+@end smallexample
+
+@noindent
+This command will restore all filesystems on the machine @samp{albert}
+as well as @file{/var} filesystem 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 filesystems 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 -L
+@itemx --license
+Display program license and exit.
+
+@item -V
+@itemx --version
+Display program version and exit.
+@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
+
+@value{xref-incremental}, and @value{ref-listed-incremental},
+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.
+
+@menu
+* file:: Choosing the Archive's Name
+* Selecting Archive Members::
+* files:: Reading Names from a File
+* exclude:: Excluding Some Files
+* Wildcards::
+* after:: Operating Only on New Files
+* recurse:: Descending into Directories
+* one:: Crossing Filesystem Boundaries
+@end menu
+
+@node file
+@section Choosing and Naming Archive Files
+@cindex Naming an archive
+@cindex Archive Name
+@cindex Directing output
+@cindex Choosing an archive file
+@cindex Where is the archive?
+@UNREVISED
+
+@FIXME{should the title of this section actually be, "naming an
+archive"?}
+
+By default, @command{tar} uses an archive file name that was compiled when
+it was built on the system; usually this name refers to some physical
+tape drive on the machine. However, the person who installed @command{tar}
+on the system may not set the default to a meaningful value as far as
+most users are concerned. As a result, you will usually want to tell
+@command{tar} where to find (or create) the archive. The @value{op-file}
+option allows you to either specify or name a file to use as the archive
+instead of the default archive file location.
+
+@table @kbd
+@item --file=@var{archive-name}
+@itemx -f @var{archive-name}
+Name the archive to create or operate on. Use in conjunction with
+any operation.
+@end table
+
+For example, in this @command{tar} command,
+
+@smallexample
+$ @kbd{tar -cvf collection.tar blues folk jazz}
+@end smallexample
+
+@noindent
+@file{collection.tar} is the name of the archive. It must directly
+follow the @option{-f} option, since whatever directly follows @option{-f}
+@emph{will} end up naming the archive. If you neglect to specify an
+archive name, you may end up overwriting a file in the working directory
+with the archive you create since @command{tar} will use this file's name
+for the archive name.
+
+An archive can be saved as a file in the file system, sent through a
+pipe or over a network, or written to an I/O device such as a tape,
+floppy disk, or CD write drive.
+
+@cindex Writing new archives
+@cindex Archive creation
+If you do not name the archive, @command{tar} uses the value of the
+environment variable @env{TAPE} as the file name for the archive. If
+that is not available, @command{tar} uses a default, compiled-in archive
+name, usually that for tape unit zero (ie. @file{/dev/tu00}).
+@command{tar} always needs an archive name.
+
+If you use @file{-} as an @var{archive-name}, @command{tar} reads the
+archive from standard input (when listing or extracting files), or
+writes it to standard output (when creating an archive). If you use
+@file{-} as an @var{archive-name} when modifying an archive,
+@command{tar} reads the original archive from its standard input and
+writes the entire new archive to its standard output.
+
+@FIXME{might want a different example here; this is already used in
+"notable tar usages".}
+
+@smallexample
+$ @kbd{cd sourcedir; tar -cf - . | (cd targetdir; tar -xf -)}
+@end smallexample
+
+@FIXME{help!}
+
+@cindex Standard input and output
+@cindex tar to standard input and output
+@anchor{remote-dev}
+To specify an archive file on a device attached to a remote machine,
+use the following:
+
+@smallexample
+@kbd{--file=@var{hostname}:/@var{dev}/@var{file name}}
+@end smallexample
+
+@noindent
+@command{tar} will complete the remote connection, if possible, and
+prompt you for a username and password. If you use
+@option{--file=@@@var{hostname}:/@var{dev}/@var{file name}}, @command{tar}
+will complete the remote connection, if possible, using your username
+as the username on the remote machine.
+
+If the archive file name includes a colon (@samp{:}), then it is assumed
+to be a file on another machine. If the archive file is
+@samp{@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the
+host @var{host}. The remote host is accessed using the @command{rsh}
+program, with a username of @var{user}. If the username is omitted
+(along with the @samp{@@} sign), then your user name will be used.
+(This is the normal @command{rsh} behavior.) It is necessary for the
+remote machine, in addition to permitting your @command{rsh} access, to
+have the @file{rmt} program installed (This command is included in
+the @GNUTAR{} distribution and by default is installed under
+@file{@var{prefix}/libexec/rmt}, were @var{prefix} means your
+installation prefix). If you need to use a file whose name includes a
+colon, then the remote tape drive behavior
+can be inhibited by using the @value{op-force-local} option.
+
+@FIXME{i know we went over this yesterday, but bob (and now i do again,
+too) thinks it's out of the middle of nowhere. it doesn't seem to tie
+into what came before it well enough <<i moved it now, is it better
+here?>>. bob also comments that if Amanda isn't free software, we
+shouldn't mention it..}
+
+When the archive is being created to @file{/dev/null}, @GNUTAR{}
+tries to minimize input and output operations. The
+Amanda backup system, when used with @GNUTAR{}, has
+an initial sizing pass which uses this feature.
+
+@node Selecting Archive Members
+@section Selecting Archive Members
+@cindex Specifying files to act on
+@cindex Specifying archive members
+
+@dfn{File Name arguments} specify which files in the file system
+@command{tar} operates on, when creating or adding to an archive, or which
+archive members @command{tar} operates on, when reading or deleting from
+an archive. @xref{Operations}.
+
+To specify file names, you can include them as the last arguments on
+the command line, as follows:
+@smallexample
+@kbd{tar} @var{operation} [@var{option1} @var{option2} @dots{}] [@var{file name-1} @var{file name-2} @dots{}]
+@end smallexample
+
+If a file name begins with dash (@samp{-}), preceede it with
+@option{--add-file} option to preventit from being treated as an
+option.
+
+If you specify a directory name as a file name argument, all the files
+in that directory are operated on by @command{tar}.
+
+If you do not specify files when @command{tar} is invoked with
+@value{op-create}, @command{tar} operates on all the non-directory files in
+the working directory. If you specify either @value{op-list} or
+@value{op-extract}, @command{tar} operates on all the archive members in the
+archive. If you specify any operation other than one of these three,
+@command{tar} does nothing.
+
+By default, @command{tar} takes file names from the command line. However,
+there are other ways to specify file or member names, or to modify the
+manner in which @command{tar} selects the files or members upon which to
+operate. @FIXME{add xref here}In general, these methods work both for
+specifying the names of files and archive members.
+
+@node files
+@section Reading Names from a File
+
+@cindex Reading file names from a file
+@cindex Lists of file names
+@cindex File Name arguments, alternatives
+Instead of giving the names of files or archive members on the command
+line, you can put the names into a file, and then use the
+@value{op-files-from} option to @command{tar}. Give the name of the file
+which contains the list of files to include as the argument to
+@option{--files-from}. In the list, the file names should be separated by
+newlines. You will frequently use this option when you have generated
+the list of files to archive with the @command{find} utility.
+
+@table @kbd
+@item --files-from=@var{file name}
+@itemx -T @var{file name}
+Get names to extract or create from file @var{file name}.
+@end table
+
+If you give a single dash as a file name for @option{--files-from}, (i.e.,
+you specify either @code{--files-from=-} or @code{-T -}), then the file
+names are read from standard input.
+
+Unless you are running @command{tar} with @option{--create}, you can not use
+both @code{--files-from=-} and @code{--file=-} (@code{-f -}) in the same
+command.
+
+Any number of @option{-T} options can be given in the command line.
+
+@FIXME{add bob's example, from his message on 2-10-97}
+
+The following example shows how to use @command{find} to generate a list of
+files smaller than 400K in length and put that list into a file
+called @file{small-files}. You can then use the @option{-T} option to
+@command{tar} to specify the files from that file, @file{small-files}, to
+create the archive @file{little.tgz}. (The @option{-z} option to
+@command{tar} compresses the archive with @command{gzip}; @pxref{gzip} for
+more information.)
+
+@smallexample
+$ @kbd{find . -size -400 -print > small-files}
+$ @kbd{tar -c -v -z -T small-files -f little.tgz}
+@end smallexample
+
+@noindent
+In the file list given by @option{-T} option, any file name beginning
+with @samp{-} character is considered a @command{tar} option and is
+processed accordingly.@footnote{Versions of @GNUTAR{} up to 1.15.1
+recognized only @option{-C} option in file lists, and only if the
+option and its argument occupied two consecutive lines.} For example,
+the common use of this feature is to change to another directory by
+specifying @option{-C} option:
+
+@smallexample
+@group
+$ @kbd{cat list}
+-C/etc
+passwd
+hosts
+-C/lib
+libc.a
+$ @kbd{tar -c -f foo.tar --files-from list}
+@end group
+@end smallexample
+
+@noindent
+In this example, @command{tar} will first switch to @file{/etc}
+directory and add files @file{passwd} and @file{hosts} to the
+archive. Then it will change to @file{/lib} directory and will archive
+the file @file{libc.a}. Thus, the resulting archive @file{foo.tar} will
+contain:
+
+@smallexample
+@group
+$ @kbd{tar tf foo.tar}
+passwd
+hosts
+libc.a
+@end group
+@end smallexample
+
+@noindent
+Notice that the option parsing algorithm used with @option{-T} is
+stricter than the one used by shell. Namely, when specifying option
+arguments, you should observe the following rules:
+
+@itemize @bullet
+@item
+When using short (single-letter) option form, its argument must
+immediately follow the option letter, without any intervening
+whitespace. For example: @code{-Cdir}.
+
+@item
+When using long option form, the option argument must be separated
+from the option by a single equal sign. No whitespace is allowed on
+any side of the equal sign. For example: @code{--directory=dir}.
+
+@item
+For both short and long option forms, the option argument can be given
+on the next line after the option name, e.g.:
+
+@smallexample
+@group
+--directory
+dir
+@end group
+@end smallexample
+
+@noindent
+and
+
+@smallexample
+@group
+-C
+dir
+@end group
+@end smallexample
+@end itemize
+
+@cindex @option{--add-file}
+If you happen to have a file whose name starts with @samp{-},
+precede it with @option{--add-file} option to prevent it from
+being recognized as an option. For example: @code{--add-file --my-file}.
+
+@menu
+* nul::
+@end menu
+
+@node nul
+@subsection @kbd{NUL} Terminated File Names
+
+@cindex File names, terminated by @kbd{NUL}
+@cindex @kbd{NUL} terminated file names
+The @value{op-null} option causes @value{op-files-from} to read file
+names terminated by a @code{NUL} instead of a newline, so files whose
+names contain newlines can be archived using @option{--files-from}.
+
+@table @kbd
+@item --null
+Only consider @kbd{NUL} terminated file names, instead of files that
+terminate in a newline.
+@end table
+
+The @value{op-null} option is just like the one in @acronym{GNU}
+@command{xargs} and @command{cpio}, and is useful with the
+@option{-print0} predicate of @acronym{GNU} @command{find}. In
+@command{tar}, @value{op-null} also disables special handling for
+file names that begin with dash.
+
+This example shows how to use @command{find} to generate a list of files
+larger than 800K in length and put that list into a file called
+@file{long-files}. The @option{-print0} option to @command{find} is just
+like @option{-print}, except that it separates files with a @kbd{NUL}
+rather than with a newline. You can then run @command{tar} with both the
+@option{--null} and @option{-T} options to specify that @command{tar} get the
+files from that file, @file{long-files}, to create the archive
+@file{big.tgz}. The @option{--null} option to @command{tar} will cause
+@command{tar} to recognize the @kbd{NUL} separator between files.
+
+@smallexample
+$ @kbd{find . -size +800 -print0 > long-files}
+$ @kbd{tar -c -v --null --files-from=long-files --file=big.tar}
+@end smallexample
+
+@FIXME{say anything else here to conclude the section?}
+
+@node exclude
+@section Excluding Some Files
+@cindex File names, excluding files by
+@cindex Excluding files by name and pattern
+@cindex Excluding files by file system
+@UNREVISED
+
+To avoid operating on files whose names match a particular pattern,
+use the @value{op-exclude} or @value{op-exclude-from} options.
+
+@table @kbd
+@item --exclude=@var{pattern}
+Causes @command{tar} to ignore files that match the @var{pattern}.
+@end table
+
+@findex exclude
+The @value{op-exclude} option prevents any file or member whose name
+matches the shell wildcard (@var{pattern}) from being operated on.
+For example, to create an archive with all the contents of the directory
+@file{src} except for files whose names end in @file{.o}, use the
+command @samp{tar -cf src.tar --exclude='*.o' src}.
+
+You may give multiple @option{--exclude} options.
+
+@table @kbd
+@item --exclude-from=@var{file}
+@itemx -X @var{file}
+Causes @command{tar} to ignore files that match the patterns listed in
+@var{file}.
+@end table
+
+@findex exclude-from
+Use the @option{--exclude-from=@var{file-of-patterns}} option to read a
+list of patterns, one per line, from @var{file}; @command{tar} will
+ignore files matching those patterns. Thus if @command{tar} is
+called as @w{@samp{tar -c -X foo .}} and the file @file{foo} contains a
+single line @file{*.o}, no files whose names end in @file{.o} will be
+added to the archive.
+
+@FIXME{do the exclude options files need to have stuff separated by
+newlines the same as the files-from option does?}
+
+@table @kbd
+@item --exclude-caches
+Causes @command{tar} to ignore directories containing a cache directory tag.
+@end table
+
+@findex exclude-caches
+When creating an archive,
+the @option{--exclude-caches} option
+causes @command{tar} to exclude all directories
+that contain a @dfn{cache directory tag}.
+A cache directory tag is a short file
+with the well-known name @file{CACHEDIR.TAG}
+and having a standard header
+specified in @url{http://www.brynosaurus.com/cachedir/spec.html}.
+Various applications write cache directory tags
+into directories they use to hold regenerable, non-precious data,
+so that such data can be more easily excluded from backups.
+
+@menu
+* controlling pattern-patching with exclude::
+* problems with exclude::
+@end menu
+
+@node controlling pattern-patching with exclude
+@unnumberedsubsec Controlling Pattern-Matching with the @code{exclude} Options
+
+Normally, a pattern matches a name if an initial subsequence of the
+name's components matches the pattern, where @samp{*}, @samp{?}, and
+@samp{[...]} are the usual shell wildcards, @samp{\} escapes wildcards,
+and wildcards can match @samp{/}.
+
+Other than optionally stripping leading @samp{/} from names
+(@pxref{absolute}), patterns and names are used as-is. For
+example, trailing @samp{/} is not trimmed from a user-specified name
+before deciding whether to exclude it.
+
+However, this matching procedure can be altered by the options listed
+below. These options accumulate. For example:
+
+@smallexample
+--ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
+@end smallexample
+
+ignores case when excluding @samp{makefile}, but not when excluding
+@samp{readme}.
+
+@table @option
+@item --anchored
+@itemx --no-anchored
+If anchored, a pattern must match an initial subsequence
+of the name's components. Otherwise, the pattern can match any
+subsequence. Default is @option{--no-anchored}.
+
+@item --ignore-case
+@itemx --no-ignore-case
+When ignoring case, upper-case patterns match lower-case names and vice versa.
+When not ignoring case (the default), matching is case-sensitive.
+
+@item --wildcards
+@itemx --no-wildcards
+When using wildcards (the default), @samp{*}, @samp{?}, and @samp{[...]}
+are the usual shell wildcards, and @samp{\} escapes wildcards.
+Otherwise, none of these characters are special, and patterns must match
+names literally.
+
+@item --wildcards-match-slash
+@itemx --no-wildcards-match-slash
+When wildcards match slash (the default), a wildcard like @samp{*} in
+the pattern can match a @samp{/} in the name. Otherwise, @samp{/} is
+matched only by @samp{/}.
+
+@end table
+
+The @option{--recursion} and @option{--no-recursion} options
+(@pxref{recurse}) also affect how exclude patterns are interpreted. If
+recursion is in effect, a pattern excludes a name if it matches any of
+the name's parent directories.
+
+@node problems with exclude
+@unnumberedsubsec Problems with Using the @code{exclude} Options
+
+Some users find @samp{exclude} options confusing. Here are some common
+pitfalls:
+
+@itemize @bullet
+@item
+The main operating mode of @command{tar} does not act on a path name
+explicitly listed on the command line if one of its file name
+components is excluded. In the example above, if
+you create an archive and exclude files that end with @samp{*.o}, but
+explicitly name the file @samp{dir.o/foo} after all the options have been
+listed, @samp{dir.o/foo} will be excluded from the archive.
+
+@item
+You can sometimes confuse the meanings of @value{op-exclude} and
+@value{op-exclude-from}. Be careful: use @value{op-exclude} when files
+to be excluded are given as a pattern on the command line. Use
+@option{--exclude-from=@var{file-of-patterns}} to introduce the name of a
+file which contains a list of patterns, one per line; each of these
+patterns can exclude zero, one, or many files.
+
+@item
+When you use @value{op-exclude}, be sure to quote the @var{pattern}
+parameter, so @GNUTAR{} sees wildcard characters
+like @samp{*}. If you do not do this, the shell might expand the
+@samp{*} itself using files at hand, so @command{tar} might receive a
+list of files instead of one pattern, or none at all, making the
+command somewhat illegal. This might not correspond to what you want.
+
+For example, write:
+
+@smallexample
+$ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}}
+@end smallexample
+
+@noindent
+rather than:
+
+@smallexample
+$ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}}
+@end smallexample
+
+@item
+You must use use shell syntax, or globbing, rather than @code{regexp}
+syntax, when using exclude options in @command{tar}. If you try to use
+@code{regexp} syntax to describe files to be excluded, your command
+might fail.
+
+@item
+In earlier versions of @command{tar}, what is now the
+@option{--exclude-from=@var{file-of-patterns}} option was called
+@option{--exclude=@var{pattern}} instead. Now,
+@option{--exclude=@var{pattern}} applies to patterns listed on the command
+line and @option{--exclude-from=@var{file-of-patterns}} applies to
+patterns listed in a file.
+
+@end itemize
+
+@node Wildcards
+@section Wildcards Patterns and Matching
+
+@dfn{Globbing} is the operation by which @dfn{wildcard} characters,
+@samp{*} or @samp{?} for example, are replaced and expanded into all
+existing files matching the given pattern. However, @command{tar} often
+uses wildcard patterns for matching (or globbing) archive members instead
+of actual files in the filesystem. Wildcard patterns are also used for
+verifying volume labels of @command{tar} archives. This section has the
+purpose of explaining wildcard syntax for @command{tar}.
+
+@FIXME{the next few paragraphs need work.}
+
+A @var{pattern} should be written according to shell syntax, using wildcard
+characters to effect globbing. Most characters in the pattern stand
+for themselves in the matched string, and case is significant: @samp{a}
+will match only @samp{a}, and not @samp{A}. The character @samp{?} in the
+pattern matches any single character in the matched string. The character
+@samp{*} in the pattern matches zero, one, or more single characters in
+the matched string. The character @samp{\} says to take the following
+character of the pattern @emph{literally}; it is useful when one needs to
+match the @samp{?}, @samp{*}, @samp{[} or @samp{\} characters, themselves.
+
+The character @samp{[}, up to the matching @samp{]}, introduces a character
+class. A @dfn{character class} is a list of acceptable characters
+for the next single character of the matched string. For example,
+@samp{[abcde]} would match any of the first five letters of the alphabet.
+Note that within a character class, all of the ``special characters''
+listed above other than @samp{\} lose their special meaning; for example,
+@samp{[-\\[*?]]} would match any of the characters, @samp{-}, @samp{\},
+@samp{[}, @samp{*}, @samp{?}, or @samp{]}. (Due to parsing constraints,
+the characters @samp{-} and @samp{]} must either come @emph{first} or
+@emph{last} in a character class.)
+
+@cindex Excluding characters from a character class
+@cindex Character class, excluding characters from
+If the first character of the class after the opening @samp{[}
+is @samp{!} or @samp{^}, then the meaning of the class is reversed.
+Rather than listing character to match, it lists those characters which
+are @emph{forbidden} as the next single character of the matched string.
+
+Other characters of the class stand for themselves. The special
+construction @samp{[@var{a}-@var{e}]}, using an hyphen between two
+letters, is meant to represent all characters between @var{a} and
+@var{e}, inclusive.
+
+@FIXME{need to add a sentence or so here to make this clear for those
+who don't have dan around.}
+
+Periods (@samp{.}) or forward slashes (@samp{/}) are not considered
+special for wildcard matches. However, if a pattern completely matches
+a directory prefix of a matched string, then it matches the full matched
+string: excluding a directory also excludes all the files beneath it.
+
+@node after
+@section Operating Only on New Files
+@cindex Excluding file by age
+@cindex Modification time, excluding files by
+@cindex Age, excluding files by
+@UNREVISED
+
+The @value{op-after-date} option causes @command{tar} to only work on files
+whose modification or inode-changed times are newer than the @var{date}
+given. If @var{date} starts with @samp{/} or @samp{.}, it is taken to
+be a file name; the last-modified time of that file is used as the date.
+If you use this option when creating or appending to an archive,
+the archive will only include new files. If you use @option{--after-date}
+when extracting an archive, @command{tar} will only extract files newer
+than the @var{date} you specify.
+
+If you only want @command{tar} to make the date comparison based on
+modification of the actual contents of the file (rather than inode
+changes), then use the @value{op-newer-mtime} option.
+
+You may use these options with any operation. Note that these options
+differ from the @value{op-update} operation in that they allow you to
+specify a particular date against which @command{tar} can compare when
+deciding whether or not to archive the files.
+
+@table @kbd
+@item --after-date=@var{date}
+@itemx --newer=@var{date}
+@itemx -N @var{date}
+Only store files newer than @var{date}.
+
+Acts on files only if their modification or inode-changed times are
+later than @var{date}. Use in conjunction with any operation.
+
+If @var{date} starts with @samp{/} or @samp{.}, it is taken to be a file
+name; the last-modified time of that file is used as the date.
+
+@item --newer-mtime=@var{date}
+Acts like @value{op-after-date}, but only looks at modification times.
+@end table
+
+These options limit @command{tar} to only operating on files which have
+been modified after the date specified. A file is considered to have
+changed if the contents have been modified, or if the owner,
+permissions, and so forth, have been changed. (For more information on
+how to specify a date, see @ref{Date input formats}; remember that the
+entire date argument must be quoted if it contains any spaces.)
+
+Gurus would say that @value{op-after-date} tests both the @code{mtime}
+(time the contents of the file were last modified) and @code{ctime}
+(time the file's status was last changed: owner, permissions, etc)
+fields, while @value{op-newer-mtime} tests only @code{mtime} field.
+
+To be precise, @value{op-after-date} checks @emph{both} @code{mtime} and
+@code{ctime} and processes the file if either one is more recent than
+@var{date}, while @value{op-newer-mtime} only checks @code{mtime} and
+disregards @code{ctime}. Neither uses @code{atime} (the last time the
+contents of the file were looked at).
+
+Date specifiers can have embedded spaces. Because of this, you may need
+to quote date arguments to keep the shell from parsing them as separate
+arguments.
+
+@FIXME{Need example of --newer-mtime with quoted argument.}
+
+@quotation
+@strong{Please Note:} @value{op-after-date} and @value{op-newer-mtime}
+should not be used for incremental backups. Some files (such as those
+in renamed directories) are not selected properly by these options.
+@xref{incremental and listed-incremental}.
+@end quotation
+
+@noindent
+@FIXME{which tells -- need to fill this in!}
+
+@node recurse
+@section Descending into Directories
+@cindex Avoiding recursion in directories
+@cindex Descending directories, avoiding
+@cindex Directories, avoiding recursion
+@cindex Recursion in directories, avoiding
+@UNREVISED
+
+@FIXME{arrggh! this is still somewhat confusing to me. :-< }
+
+@FIXME{show dan bob's comments, from 2-10-97}
+
+Usually, @command{tar} will recursively explore all directories (either
+those given on the command line or through the @value{op-files-from}
+option) for the various files they contain. However, you may not always
+want @command{tar} to act this way.
+
+The @value{op-no-recursion} option inhibits @command{tar}'s recursive descent
+into specified directories. If you specify @option{--no-recursion}, you can
+use the @command{find} utility for hunting through levels of directories to
+construct a list of file names which you could then pass to @command{tar}.
+@command{find} allows you to be more selective when choosing which files to
+archive; see @ref{files} for more information on using @command{find} with
+@command{tar}, or look.
+
+@table @kbd
+@item --no-recursion
+Prevents @command{tar} from recursively descending directories.
+
+@item --recursion
+Requires @command{tar} to recursively descend directories.
+This is the default.
+@end table
+
+When you use @option{--no-recursion}, @GNUTAR{} grabs
+directory entries themselves, but does not descend on them
+recursively. Many people use @command{find} for locating files they
+want to back up, and since @command{tar} @emph{usually} recursively
+descends on directories, they have to use the @samp{@w{! -d}} option
+to @command{find} @FIXME{needs more explanation or a cite to another
+info file}as they usually do not want all the files in a directory.
+They then use the @value{op-files-from} option to archive the files
+located via @command{find}.
+
+The problem when restoring files archived in this manner is that the
+directories themselves are not in the archive; so the
+@value{op-same-permissions} option does not affect them---while users
+might really like it to. Specifying @value{op-no-recursion} is a way to
+tell @command{tar} to grab only the directory entries given to it, adding
+no new files on its own.
+
+The @value{op-no-recursion} option also applies when extracting: it
+causes @command{tar} to extract only the matched directory entries, not
+the files under those directories.
+
+The @value{op-no-recursion} option also affects how exclude patterns
+are interpreted (@pxref{controlling pattern-patching with exclude}).
+
+The @option{--no-recursion} and @option{--recursion} options apply to
+later options and operands, and can be overridden by later occurrences
+of @option{--no-recursion} and @option{--recursion}. For example:
+
+@smallexample
+$ @kbd{tar -cf jams.tar --norecursion grape --recursion grape/concord}
+@end smallexample
+
+@noindent
+creates an archive with one entry for @file{grape}, and the recursive
+contents of @file{grape/concord}, but no entries under @file{grape}
+other than @file{grape/concord}.
+
+@node one
+@section Crossing Filesystem Boundaries
+@cindex File system boundaries, not crossing
+@UNREVISED
+
+@command{tar} will normally automatically cross file system boundaries in
+order to archive files which are part of a directory tree. You can
+change this behavior by running @command{tar} and specifying
+@value{op-one-file-system}. This option only affects files that are
+archived because they are in a directory that is being archived;
+@command{tar} will still archive files explicitly named on the command line
+or through @value{op-files-from}, regardless of where they reside.
+
+@table @kbd
+@item --one-file-system
+@itemx -l
+Prevents @command{tar} from crossing file system boundaries when
+archiving. Use in conjunction with any write operation.
+@end table
+
+The @option{--one-file-system} option causes @command{tar} to modify its
+normal behavior in archiving the contents of directories. If a file in
+a directory is not on the same filesystem as the directory itself, then
+@command{tar} will not archive that file. If the file is a directory
+itself, @command{tar} will not archive anything beneath it; in other words,
+@command{tar} will not cross mount points.
+
+It is reported that using this option, the mount point is is archived,
+but nothing under it.
+
+This option is useful for making full or incremental archival backups of
+a file system. If this option is used in conjunction with
+@value{op-verbose}, files that are excluded are mentioned by name on the
+standard error.
+
+@menu
+* directory:: Changing Directory
+* absolute:: Absolute File Names
+@end menu
+
+@node directory
+@subsection Changing the Working Directory
+
+@FIXME{need to read over this node now for continuity; i've switched
+things around some.}
+
+@cindex Changing directory mid-stream
+@cindex Directory, changing mid-stream
+@cindex Working directory, specifying
+@UNREVISED
+
+To change the working directory in the middle of a list of file names,
+either on the command line or in a file specified using
+@value{op-files-from}, use @value{op-directory}. This will change the
+working directory to the directory @var{directory} after that point in
+the list.
+
+@table @kbd
+@item --directory=@var{directory}
+@itemx -C @var{directory}
+Changes the working directory in the middle of a command line.
+@end table
+
+For example,
+
+@smallexample
+$ @kbd{tar -c -f jams.tar grape prune -C food cherry}
+@end smallexample
+
+@noindent
+will place the files @file{grape} and @file{prune} from the current
+directory into the archive @file{jams.tar}, followed by the file
+@file{cherry} from the directory @file{food}. This option is especially
+useful when you have several widely separated files that you want to
+store in the same archive.
+
+Note that the file @file{cherry} is recorded in the archive under the
+precise name @file{cherry}, @emph{not} @file{food/cherry}. Thus, the
+archive will contain three files that all appear to have come from the
+same directory; if the archive is extracted with plain @samp{tar
+--extract}, all three files will be written in the current directory.
+
+Contrast this with the command,
+
+@smallexample
+$ @kbd{tar -c -f jams.tar grape prune -C food red/cherry}
+@end smallexample
+
+@noindent
+which records the third file in the archive under the name
+@file{red/cherry} so that, if the archive is extracted using
+@samp{tar --extract}, the third file will be written in a subdirectory
+named @file{orange-colored}.
+
+You can use the @option{--directory} option to make the archive
+independent of the original name of the directory holding the files.
+The following command places the files @file{/etc/passwd},
+@file{/etc/hosts}, and @file{/lib/libc.a} into the archive
+@file{foo.tar}:
+
+@smallexample
+$ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a}
+@end smallexample
+
+@noindent
+However, the names of the archive members will be exactly what they were
+on the command line: @file{passwd}, @file{hosts}, and @file{libc.a}.
+They will not appear to be related by file name to the original
+directories where those files were located.
+
+Note that @option{--directory} options are interpreted consecutively. If
+@option{--directory} specifies a relative file name, it is interpreted
+relative to the then current directory, which might not be the same as
+the original current working directory of @command{tar}, due to a previous
+@option{--directory} option.
+
+When using @option{--files-from} (@pxref{files}), you can put various
+@command{tar} options (including @option{-C}) in the file list. Notice,
+however, that in this case the option and its argument may not be
+separated by whitespace. If you use short option, its argument must
+either follow the option letter immediately, without any intervening
+whitespace, or occupy the next line. Otherwise, if you use long
+option, separate its argument by an equal sign.
+
+For instance, the file list for the above example will be:
+
+@smallexample
+@group
+-C
+/etc
+passwd
+hosts
+-C
+/lib
+libc.a
+@end group
+@end smallexample
+
+@noindent
+To use it, you would invoke @command{tar} as follows:
+
+@smallexample
+$ @kbd{tar -c -f foo.tar --files-from list}
+@end smallexample
+
+Notice also that you can only use the short option variant in the file
+list, i.e. always use @option{-C}, not @option{--directory}.
+
+The interpretation of @value{op-directory} is disabled by
+@value{op-null} option.
+
+@node absolute
+@subsection Absolute File Names
+@UNREVISED
+
+@table @kbd
+@item -P
+@itemx --absolute-names
+Do not strip leading slashes from file names, and permit file names
+containing a @file{..} file name component.
+@end table
+
+By default, @GNUTAR{} drops a leading @samp{/} on
+input or output, and complains about file names containing a @file{..}
+component. This option turns off this behavior.
+
+When @command{tar} extracts archive members from an archive, it strips any
+leading slashes (@samp{/}) from the member name. This causes absolute
+member names in the archive to be treated as relative file names. This
+allows you to have such members extracted wherever you want, instead of
+being restricted to extracting the member in the exact directory named
+in the archive. For example, if the archive member has the name
+@file{/etc/passwd}, @command{tar} will extract it as if the name were
+really @file{etc/passwd}.
+
+File names containing @file{..} can cause problems when extracting, so
+@command{tar} normally warns you about such files when creating an
+archive, and rejects attempts to extracts such files.
+
+Other @command{tar} programs do not do this. As a result, if you
+create an archive whose member names start with a slash, they will be
+difficult for other people with a non-@GNUTAR{}
+program to use. Therefore, @GNUTAR{} also strips
+leading slashes from member names when putting members into the
+archive. For example, if you ask @command{tar} to add the file
+@file{/bin/ls} to an archive, it will do so, but the member name will
+be @file{bin/ls}.
+
+If you use the @value{op-absolute-names} option, @command{tar} will do
+none of these transformations.
+
+To archive or extract files relative to the root directory, specify
+the @value{op-absolute-names} option.
+
+Normally, @command{tar} acts on files relative to the working
+directory---ignoring superior directory names when archiving, and
+ignoring leading slashes when extracting.
+
+When you specify @value{op-absolute-names}, @command{tar} stores file names
+including all superior directory names, and preserves leading slashes.
+If you only invoked @command{tar} from the root directory you would never
+need the @value{op-absolute-names} option, but using this option may be
+more convenient than switching to root.
+
+@FIXME{Should be an example in the tutorial/wizardry section using this
+to transfer files between systems.}
+
+@FIXME{Is write access an issue?}
+
+@table @kbd
+@item --absolute-names
+Preserves full file names (including superior directory names) when
+archiving files. Preserves leading slash when extracting files.
+
+@end table
+
+@FIXME{this is still horrible; need to talk with dan on monday.}
+
+@command{tar} prints out a message about removing the @samp{/} from
+file names. This message appears once per @GNUTAR{}
+invocation. It represents something which ought to be told; ignoring
+what it means can cause very serious surprises, later.
+
+Some people, nevertheless, do not want to see this message. Wanting to
+play really dangerously, one may of course redirect @command{tar} standard
+error to the sink. For example, under @command{sh}:
+
+@smallexample
+$ @kbd{tar -c -f archive.tar /home 2> /dev/null}
+@end smallexample
+
+@noindent
+Another solution, both nicer and simpler, would be to change to
+the @file{/} directory first, and then avoid absolute notation.
+For example:
+
+@smallexample
+$ @kbd{(cd / && tar -c -f archive.tar home)}
+$ @kbd{tar -c -f archive.tar -C / home}
+@end smallexample
+
+@include getdate.texi
+
+@node Formats
+@chapter Controlling the Archive Format
+
+Due to historical reasons, there are several formats of tar archives.
+All of them are based on the same principles, but have some subtle
+differences that often make them incompatible with each other.
+
+GNU tar is able to create and handle archives in a variety of formats.
+The most frequently used formats are (in alphabetical order):
+
+@table @asis
+@item gnu
+Format used by @GNUTAR{} versions up to 1.13.25. This format derived
+from an early @acronym{POSIX} standard, adding some improvements such as
+sparse file handling and incremental archives. Unfortunately these
+features were implemented in a way incompatible with other archive
+formats.
+
+Archives in @samp{gnu} format are able to hold pathnames of unlimited
+length.
+
+@item oldgnu
+Format used by @GNUTAR{} of versions prior to 1.12.
+
+@item v7
+Archive format, compatible with the V7 implementation of tar. This
+format imposes a number of limitations. The most important of them
+are:
+
+@enumerate
+@item The maximum length of a file name is limited to 99 characters.
+@item The maximum length of a symbolic link is limited to 99 characters.
+@item It is impossible to store special files (block and character
+devices, fifos etc.)
+@item Maximum value of user or group ID is limited to 2097151 (7777777
+octal)
+@item V7 archives do not contain symbolic ownership information (user
+and group name of the file owner).
+@end enumerate
+
+This format has traditionally been used by Automake when producing
+Makefiles. This practice will change in the future, in the meantime,
+however this means that projects containing filenames more than 99
+characters long will not be able to use @GNUTAR{} @value{VERSION} and
+Automake prior to 1.9.
+
+@item ustar
+Archive format defined by @acronym{POSIX.1-1988} specification. It stores
+symbolic ownership information. It is also able to store
+special files. However, it imposes several restrictions as well:
+
+@enumerate
+@item The maximum length of a file name is limited to 256 characters,
+provided that the filename can be split at directory separator in
+two parts, first of them being at most 155 bytes long. So, in most
+cases the maximum file name length will be shorter than 256
+characters.
+@item The maximum length of a symbolic link name is limited to
+100 characters.
+@item Maximum size of a file the archive is able to accomodate
+is 8GB
+@item Maximum value of UID/GID is 2097151.
+@item Maximum number of bits in device major and minor numbers is 21.
+@end enumerate
+
+@item star
+Format used by J@"org Schilling @command{star}
+implementation. @GNUTAR{} is able to read @samp{star} archives but
+currently does not produce them.
+
+@item posix
+Archive format defined by @acronym{POSIX.1-2001} specification. This is the
+most flexible and feature-rich format. It does not impose any
+restrictions on file sizes or filename lengths. This format is quite
+recent, so not all tar implementations are able to handle it properly.
+However, this format is designed in such a way that any tar
+implementation able to read @samp{ustar} archives will be able to read
+most @samp{posix} archives as well, with the only exception that any
+additional information (such as long file names etc.) will in such
+case be extracted as plain text files along with the files it refers to.
+
+This archive format will be the default format for future versions
+of @GNUTAR{}.
+
+@end table
+
+The following table summarizes the limitations of each of these
+formats:
+
+@multitable @columnfractions .10 .20 .20 .20 .20
+@item Format @tab UID @tab File Size @tab Path Name @tab Devn
+@item gnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
+@item oldgnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
+@item v7 @tab 2097151 @tab 8GB @tab 99 @tab n/a
+@item ustar @tab 2097151 @tab 8GB @tab 256 @tab 21
+@item posix @tab Unlimited @tab Unlimited @tab Unlimited @tab Unlimited
+@end multitable
+
+The default format for @GNUTAR{} is defined at compilation
+time. You may check it by running @command{tar --help}, and examining
+the last lines of its output. Usually, @GNUTAR{} is configured
+to create archives in @samp{gnu} format, however, future version will
+switch to @samp{posix}.
+
+@menu
+* Portability:: Making @command{tar} Archives More Portable
+* Compression:: Using Less Space through Compression
+* Attributes:: Handling File Attributes
+* Standard:: The Standard Format
+* Extensions:: @acronym{GNU} Extensions to the Archive Format
+* cpio:: Comparison of @command{tar} and @command{cpio}
+@end menu
+
+@node Portability
+@section Making @command{tar} Archives More Portable
+
+Creating a @command{tar} archive on a particular system that is meant to be
+useful later on many other machines and with other versions of @command{tar}
+is more challenging than you might think. @command{tar} archive formats
+have been evolving since the first versions of Unix. Many such formats
+are around, and are not always compatible with each other. This section
+discusses a few problems, and gives some advice about making @command{tar}
+archives more portable.
+
+One golden rule is simplicity. For example, limit your @command{tar}
+archives to contain only regular files and directories, avoiding
+other kind of special files. Do not attempt to save sparse files or
+contiguous files as such. Let's discuss a few more problems, in turn.
+
+@menu
+* Portable Names:: Portable Names
+* dereference:: Symbolic Links
+* old:: Old V7 Archives
+* ustar:: Ustar Archives
+* gnu:: GNU and old GNU format archives.
+* posix:: @acronym{POSIX} archives
+* Checksumming:: Checksumming Problems
+* Large or Negative Values:: Large files, negative time stamps, etc.
+@end menu
+
+@node Portable Names
+@subsection Portable Names
+
+Use portable file and member names. A name is portable if it contains
+only ASCII letters and digits, @samp{/}, @samp{.}, @samp{_}, and
+@samp{-}; it cannot be empty, start with @samp{-} or @samp{//}, or
+contain @samp{/-}. Avoid deep directory nesting. For portability to
+old Unix hosts, limit your file name components to 14 characters or
+less.
+
+If you intend to have your @command{tar} archives to be read under
+MSDOS, you should not rely on case distinction for file names, and you
+might use the @acronym{GNU} @command{doschk} program for helping you
+further diagnosing illegal MSDOS names, which are even more limited
+than System V's.
+
+@node dereference
+@subsection Symbolic Links
+@cindex File names, using symbolic links
+@cindex Symbolic link as file name
+
+Normally, when @command{tar} archives a symbolic link, it writes a
+block to the archive naming the target of the link. In that way, the
+@command{tar} archive is a faithful record of the filesystem contents.
+@value{op-dereference} is used with @value{op-create}, and causes
+@command{tar} to archive the files symbolic links point to, instead of
+the links themselves. When this option is used, when @command{tar}
+encounters a symbolic link, it will archive the linked-to file,
+instead of simply recording the presence of a symbolic link.
+
+The name under which the file is stored in the file system is not
+recorded in the archive. To record both the symbolic link name and
+the file name in the system, archive the file under both names. If
+all links were recorded automatically by @command{tar}, an extracted file
+might be linked to a file name that no longer exists in the file
+system.
+
+If a linked-to file is encountered again by @command{tar} while creating
+the same archive, an entire second copy of it will be stored. (This
+@emph{might} be considered a bug.)
+
+So, for portable archives, do not archive symbolic links as such,
+and use @value{op-dereference}: many systems do not support
+symbolic links, and moreover, your distribution might be unusable if
+it contains unresolved symbolic links.
+
+@node old
+@subsection Old V7 Archives
+@cindex Format, old style
+@cindex Old style format
+@cindex Old style archives
+
+Certain old versions of @command{tar} cannot handle additional
+information recorded by newer @command{tar} programs. To create an
+archive in V7 format (not ANSI), which can be read by these old
+versions, specify the @value{op-format-v7} option in
+conjunction with the @value{op-create} (@command{tar} also
+accepts @option{--portability} or @samp{op-old-archive} for this
+option). When you specify it,
+@command{tar} leaves out information about directories, pipes, fifos,
+contiguous files, and device files, and specifies file ownership by
+group and user IDs instead of group and user names.
+
+When updating an archive, do not use @value{op-format-v7}
+unless the archive was created using this option.
+
+In most cases, a @emph{new} format archive can be read by an @emph{old}
+@command{tar} program without serious trouble, so this option should
+seldom be needed. On the other hand, most modern @command{tar}s are
+able to read old format archives, so it might be safer for you to
+always use @value{op-format-v7} for your distributions.
+
+@node ustar
+@subsection Ustar Archive Format
+
+Archive format defined by @acronym{POSIX}.1-1988 specification is called
+@code{ustar}. Although it is more flexible than the V7 format, it
+still has many restrictions (@xref{Formats,ustar}, for the detailed
+description of @code{ustar} format). Along with V7 format,
+@code{ustar} format is a good choice for archives intended to be read
+with other implementations of @command{tar}.
+
+To create archive in @code{ustar} format, use @value{op-format-ustar}
+option in conjunction with the @value{op-create}.
+
+@node gnu
+@subsection @acronym{GNU} and old @GNUTAR{} format
+
+@GNUTAR{} was based on an early draft of the
+@acronym{POSIX} 1003.1 @code{ustar} standard. @acronym{GNU} extensions to
+@command{tar}, such as the support for file names longer than 100
+characters, use portions of the @command{tar} header record which were
+specified in that @acronym{POSIX} draft as unused. Subsequent changes in
+@acronym{POSIX} have allocated the same parts of the header record for
+other purposes. As a result, @GNUTAR{} format is
+incompatible with the current @acronym{POSIX} specification, and with
+@command{tar} programs that follow it.
+
+In the majority of cases, @command{tar} will be configured to create
+this format by default. This will change in the future releases, since
+we plan to make @samp{posix} format the default.
+
+To force creation a @GNUTAR{} archive, use option
+@value{op-format-gnu}.
+
+Some @command{tar} options are currently basing on @GNUTAR{}
+format, and can therefore be used only with @samp{gnu}
+or @samp{oldgnu} archive formats. The list of such options follows:
+
+@itemize @bullet
+@item @value{op-label}, when used with @value{op-create}.
+@item @value{op-incremental}
+@item @value{op-multi-volume}
+@end itemize
+
+These options will be re-implemented for the @samp{posix} archive
+format in the future.
+
+@node posix
+@subsection @GNUTAR{} and @acronym{POSIX} @command{tar}
+
+The version @value{VERSION} of @GNUTAR{} is able
+to read and create archives conforming to @acronym{POSIX.1-2001} standard.
+
+A @acronym{POSIX} conformant archive will be created if @command{tar}
+was given @value{op-format-posix} option.
+Notice, that currently @acronym{GNU} extensions are not
+allowed with this format. Following is the list of options that
+cannot be used with @value{op-format-posix}:
+
+@itemize @bullet
+@item @value{op-label}, when used with @value{op-create}.
+@item @value{op-incremental}
+@item @value{op-multi-volume}
+@end itemize
+
+This restriction will disappear in the future versions.
+
+@node Checksumming
+@subsection Checksumming Problems
+
+SunOS and HP-UX @command{tar} fail to accept archives created using
+@GNUTAR{} and containing non-ASCII file names, that
+is, file names having characters with the eight bit set, because they
+use signed checksums, while @GNUTAR{} uses unsigned
+checksums while creating archives, as per @acronym{POSIX} standards. On
+reading, @GNUTAR{} computes both checksums and
+accept any. It is somewhat worrying that a lot of people may go
+around doing backup of their files using faulty (or at least
+non-standard) software, not learning about it until it's time to
+restore their missing files with an incompatible file extractor, or
+vice versa.
+
+@GNUTAR{} compute checksums both ways, and accept
+any on read, so @acronym{GNU} tar can read Sun tapes even with their
+wrong checksums. @GNUTAR{} produces the standard
+checksum, however, raising incompatibilities with Sun. That is to
+say, @GNUTAR{} has not been modified to
+@emph{produce} incorrect archives to be read by buggy @command{tar}'s.
+I've been told that more recent Sun @command{tar} now read standard
+archives, so maybe Sun did a similar patch, after all?
+
+The story seems to be that when Sun first imported @command{tar}
+sources on their system, they recompiled it without realizing that
+the checksums were computed differently, because of a change in
+the default signing of @code{char}'s in their compiler. So they
+started computing checksums wrongly. When they later realized their
+mistake, they merely decided to stay compatible with it, and with
+themselves afterwards. Presumably, but I do not really know, HP-UX
+has chosen that their @command{tar} archives to be compatible with Sun's.
+The current standards do not favor Sun @command{tar} format. In any
+case, it now falls on the shoulders of SunOS and HP-UX users to get
+a @command{tar} able to read the good archives they receive.
+
+@node Large or Negative Values
+@subsection Large or Negative Values
+@cindex large values
+@cindex future time stamps
+@cindex negative time stamps
+
+@acronym{POSIX} @command{tar} format uses fixed-sized unsigned octal strings
+to represent numeric values. User and group IDs and device major and
+minor numbers have unsigned 21-bit representations, and file sizes and
+times have unsigned 33-bit representations. @GNUTAR{}
+generates @acronym{POSIX} representations when possible, but for values
+outside the @acronym{POSIX} range it generates two's-complement base-256
+strings: uids, gids, and device numbers have signed 57-bit
+representations, and file sizes and times have signed 89-bit
+representations. These representations are an extension to @acronym{POSIX}
+@command{tar} format, so they are not universally portable.
+
+The most common portability problems with out-of-range numeric values
+are large files and future or negative time stamps.
+
+Portable archives should avoid members of 8 GB or larger, as @acronym{POSIX}
+@command{tar} format cannot represent them.
+
+Portable archives should avoid time stamps from the future. @acronym{POSIX}
+@command{tar} format can represent time stamps in the range 1970-01-01
+00:00:00 through 2242-03-16 12:56:31 @sc{utc}. However, many current
+hosts use a signed 32-bit @code{time_t}, or internal time stamp format,
+and cannot represent time stamps after 2038-01-19 03:14:07 @sc{utc}; so
+portable archives must avoid these time stamps for many years to come.
+
+Portable archives should also avoid time stamps before 1970. These time
+stamps are a common @acronym{POSIX} extension but their @code{time_t}
+representations are negative. Many traditional @command{tar}
+implementations generate a two's complement representation for negative
+time stamps that assumes a signed 32-bit @code{time_t}; hence they
+generate archives that are not portable to hosts with differing
+@code{time_t} representations. @GNUTAR{} recognizes this
+situation when it is run on host with a signed 32-bit @code{time_t}, but
+it issues a warning, as these time stamps are nonstandard and unportable.
+
+@node Compression
+@section Using Less Space through Compression
+
+@menu
+* gzip:: Creating and Reading Compressed Archives
+* sparse:: Archiving Sparse Files
+@end menu
+
+@node gzip
+@subsection Creating and Reading Compressed Archives
+@cindex Compressed archives
+@cindex Storing archives in compressed format
+
+@GNUTAR{} is able to create and read compressed archives. It supports
+@command{gzip} and @command{bzip2} compression programms. For backward
+compatibilty, it also supports @command{compress} command, although
+we strongly recommend against using it, since there is a patent
+covering the algorithm it uses and you could be sued for patent
+infringement merely by running @command{compress}! Besides, it is less
+effective than @command{gzip} and @command{bzip2}.
+
+Creating a compressed archive is simple: you just specify a
+@dfn{compression option} along with the usual archive creation
+commands. The compression option is @option{-z} (@option{--gzip}) to
+create a @command{gzip} compressed archive, @option{-j}
+(@option{--bzip2}) to create a @command{bzip2} compressed archive, and
+@option{-Z} (@option{--compress}) to use @command{compress} program.
+For example:
+
+@smallexample
+$ @kbd{tar cfz archive.tar.gz .}
+@end smallexample
+
+Reading compressed archive is even simpler: you don't need to specify
+any additional options as @GNUTAR{} recognizes its format
+automatically. Thus, the following commands will list and extract the
+archive created in previous example:
+
+@smallexample
+# List the compressed archive
+$ @kbd{tar tf archive.tar.gz}
+# Extract the compressed archive
+$ @kbd{tar xf archive.tar.gz}
+@end smallexample
+
+The only case when you have to specify a decompression option while
+reading the archive is when reading from a pipe or from a tape drive
+that does not support random access. However, in this case @GNUTAR{}
+will indicate which option you should use. For example:
+
+@smallexample
+$ @kbd{cat archive.tar.gz | tar tf -}
+tar: Archive is compressed. Use -z option
+tar: Error is not recoverable: exiting now
+@end smallexample
+
+If you see such diagnostics, just add the suggested option to the
+invocation of @GNUTAR{}:
+
+@smallexample
+$ @kbd{cat archive.tar.gz | tar tfz -}
+@end smallexample
+
+Notice also, that there are several restrictions on operations on
+compressed archives. First of all, compressed archives cannot be
+modified, i.e. you cannot update (@value{op-update}) them or delete
+(@value{op-delete}) members from them. Likewise, you cannot append
+another @command{tar} archive to a compressed archive using
+@value{op-append}). Secondly, multi-volume archives cannot be
+compressed.
+
+The following table summarizes compression options used by @GNUTAR{}.
+
+@table @kbd
+@item -z
+@itemx --gzip
+@itemx --ungzip
+Filter the archive through @command{gzip}.
+
+You can use @option{--gzip} and @option{--gunzip} on physical devices
+(tape drives, etc.) and remote files as well as on normal files; data
+to or from such devices or remote files is reblocked by another copy
+of the @command{tar} program to enforce the specified (or default) record
+size. The default compression parameters are used; if you need to
+override them, set @env{GZIP} environment variable, e.g.:
+
+@smallexample
+$ @kbd{GZIP=--best tar cfz archive.tar.gz subdir}
+@end smallexample
+
+@noindent
+Another way would be to avoid the @value{op-gzip} option and run
+@command{gzip} explicitly:
+
+@smallexample
+$ @kbd{tar cf - subdir | gzip --best -c - > archive.tar.gz}
+@end smallexample
+
+@cindex corrupted archives
+About corrupted compressed archives: @command{gzip}'ed files have no
+redundancy, for maximum compression. The adaptive nature of the
+compression scheme means that the compression tables are implicitly
+spread all over the archive. If you lose a few blocks, the dynamic
+construction of the compression tables becomes unsynchronized, and there
+is little chance that you could recover later in the archive.
+
+There are pending suggestions for having a per-volume or per-file
+compression in @GNUTAR{}. This would allow for viewing the
+contents without decompression, and for resynchronizing decompression at
+every volume or file, in case of corrupted archives. Doing so, we might
+lose some compressibility. But this would have make recovering easier.
+So, there are pros and cons. We'll see!
+
+@item -j
+@itemx --bzip2
+Filter the archive through @code{bzip2}. Otherwise like @value{op-gzip}.
+
+@item -Z
+@itemx --compress
+@itemx --uncompress
+Filter the archive through @command{compress}. Otherwise like
+@value{op-gzip}.
+
+The @acronym{GNU} Project recommends you not use
+@command{compress}, because there is a patent covering the algorithm it
+uses. You could be sued for patent infringement merely by running
+@command{compress}.
+
+@item --use-compress-program=@var{prog}
+Use external compression program @var{prog}. Use this option if you
+have a compression program that @GNUTAR{} does not support. There
+are two requirements to which @var{prog} should comply:
+
+First, when called without options, it should read data from standard
+input, compress it and output it on standard output.
+
+Secondly, if called with @option{-d} argument, it should do exactly
+the opposite, i.e. read the compressed data from the standard input
+and produce uncompressed data on the standard output.
+@end table
+
+@FIXME{I have one question, or maybe it's a suggestion if there isn't a way
+to do it now. I would like to use @value{op-gzip}, but I'd also like
+the output to be fed through a program like @acronym{GNU}
+@command{ecc} (actually, right now that's @samp{exactly} what I'd like
+to use :-)), basically adding ECC protection on top of compression.
+It seems as if this should be quite easy to do, but I can't work out
+exactly how to go about it. Of course, I can pipe the standard output
+of @command{tar} through @command{ecc}, but then I lose (though I
+haven't started using it yet, I confess) the ability to have
+@command{tar} use @command{rmt} for it's I/O (I think).
+
+I think the most straightforward thing would be to let me specify a
+general set of filters outboard of compression (preferably ordered,
+so the order can be automatically reversed on input operations, and
+with the options they require specifiable), but beggars shouldn't be
+choosers and anything you decide on would be fine with me.
+
+By the way, I like @command{ecc} but if (as the comments say) it can't
+deal with loss of block sync, I'm tempted to throw some time at adding
+that capability. Supposing I were to actually do such a thing and
+get it (apparently) working, do you accept contributed changes to
+utilities like that? (Leigh Clayton @file{loc@@soliton.com}, May 1995).
+
+Isn't that exactly the role of the @value{op-use-compress-prog} option?
+I never tried it myself, but I suspect you may want to write a
+@var{prog} script or program able to filter stdin to stdout to
+way you want. It should recognize the @option{-d} option, for when
+extraction is needed rather than creation.
+
+It has been reported that if one writes compressed data (through the
+@value{op-gzip} or @value{op-compress} options) to a DLT and tries to use
+the DLT compression mode, the data will actually get bigger and one will
+end up with less space on the tape.}
+
+@node sparse
+@subsection Archiving Sparse Files
+@cindex Sparse Files
+@UNREVISED
+
+@table @kbd
+@item -S
+@itemx --sparse
+Handle sparse files efficiently.
+@end table
+
+This option causes all files to be put in the archive to be tested for
+sparseness, and handled specially if they are. The @value{op-sparse}
+option is useful when many @code{dbm} files, for example, are being
+backed up. Using this option dramatically decreases the amount of
+space needed to store such a file.
+
+In later versions, this option may be removed, and the testing and
+treatment of sparse files may be done automatically with any special
+@acronym{GNU} options. For now, it is an option needing to be specified on
+the command line with the creation or updating of an archive.
+
+Files in the filesystem occasionally have ``holes.'' A hole in a file
+is a section of the file's contents which was never written. The
+contents of a hole read as all zeros. On many operating systems,
+actual disk storage is not allocated for holes, but they are counted
+in the length of the file. If you archive such a file, @command{tar}
+could create an archive longer than the original. To have @command{tar}
+attempt to recognize the holes in a file, use @value{op-sparse}. When
+you use the @value{op-sparse} option, then, for any file using less
+disk space than would be expected from its length, @command{tar} searches
+the file for consecutive stretches of zeros. It then records in the
+archive for the file where the consecutive stretches of zeros are, and
+only archives the ``real contents'' of the file. On extraction (using
+@value{op-sparse} is not needed on extraction) any such files have
+holes created wherever the continuous stretches of zeros were found.
+Thus, if you use @value{op-sparse}, @command{tar} archives won't take
+more space than the original.
+
+A file is sparse if it contains blocks of zeros whose existence is
+recorded, but that have no space allocated on disk. When you specify
+the @value{op-sparse} option in conjunction with the @value{op-create}
+operation, @command{tar} tests all files for sparseness while archiving.
+If @command{tar} finds a file to be sparse, it uses a sparse representation of
+the file in the archive. @value{xref-create}, for more information
+about creating archives.
+
+@value{op-sparse} is useful when archiving files, such as dbm files,
+likely to contain many nulls. This option dramatically
+decreases the amount of space needed to store such an archive.
+
+@quotation
+@strong{Please Note:} Always use @value{op-sparse} when performing file
+system backups, to avoid archiving the expanded forms of files stored
+sparsely in the system.
+
+Even if your system has no sparse files currently, some may be
+created in the future. If you use @value{op-sparse} while making file
+system backups as a matter of course, you can be assured the archive
+will never take more space on the media than the files take on disk
+(otherwise, archiving a disk filled with sparse files might take
+hundreds of tapes). @FIXME-xref{incremental when node name is set.}
+@end quotation
+
+@command{tar} ignores the @value{op-sparse} option when reading an archive.
+
+@table @kbd
+@item --sparse
+@itemx -S
+Files stored sparsely in the file system are represented sparsely in
+the archive. Use in conjunction with write operations.
+@end table
+
+However, users should be well aware that at archive creation time,
+@GNUTAR{} still has to read whole disk file to
+locate the @dfn{holes}, and so, even if sparse files use little space
+on disk and in the archive, they may sometimes require inordinate
+amount of time for reading and examining all-zero blocks of a file.
+Although it works, it's painfully slow for a large (sparse) file, even
+though the resulting tar archive may be small. (One user reports that
+dumping a @file{core} file of over 400 megabytes, but with only about
+3 megabytes of actual data, took about 9 minutes on a Sun Sparcstation
+ELC, with full CPU utilization.)
+
+This reading is required in all cases and is not related to the fact
+the @value{op-sparse} option is used or not, so by merely @emph{not}
+using the option, you are not saving time@footnote{Well! We should say
+the whole truth, here. When @value{op-sparse} is selected while creating
+an archive, the current @command{tar} algorithm requires sparse files to be
+read twice, not once. We hope to develop a new archive format for saving
+sparse files in which one pass will be sufficient.}.
+
+Programs like @command{dump} do not have to read the entire file; by
+examining the file system directly, they can determine in advance
+exactly where the holes are and thus avoid reading through them. The
+only data it need read are the actual allocated data blocks.
+@GNUTAR{} uses a more portable and straightforward
+archiving approach, it would be fairly difficult that it does
+otherwise. Elizabeth Zwicky writes to @file{comp.unix.internals}, on
+1990-12-10:
+
+@quotation
+What I did say is that you cannot tell the difference between a hole and an
+equivalent number of nulls without reading raw blocks. @code{st_blocks} at
+best tells you how many holes there are; it doesn't tell you @emph{where}.
+Just as programs may, conceivably, care what @code{st_blocks} is (care
+to name one that does?), they may also care where the holes are (I have
+no examples of this one either, but it's equally imaginable).
+
+I conclude from this that good archivers are not portable. One can
+arguably conclude that if you want a portable program, you can in good
+conscience restore files with as many holes as possible, since you can't
+get it right.
+@end quotation
+
+@node Attributes
+@section Handling File Attributes
+@UNREVISED
+
+When @command{tar} reads files, this causes them to have the access
+times updated. To have @command{tar} attempt to set the access times
+back to what they were before they were read, use the
+@value{op-atime-preserve} option.
+
+Handling of file attributes
+
+@table @kbd
+@item --atime-preserve
+Preserve access times on files that are read.
+This doesn't work for files that
+you don't own, unless you're root, and it doesn't interact with
+incremental dumps nicely (@pxref{Backups}), and it can set access or
+modification times incorrectly if other programs access the file while
+@command{tar} is running; but it is good enough for some purposes.
+
+@item -m
+@itemx --touch
+Do not extract file modified time.
+
+When this option is used, @command{tar} leaves the modification times
+of the files it extracts as the time when the files were extracted,
+instead of setting it to the time recorded in the archive.
+
+This option is meaningless with @value{op-list}.
+
+@item --same-owner
+Create extracted files with the same ownership they have in the
+archive.
+
+This is the default behavior for the superuser,
+so this option is meaningful only for non-root users, when @command{tar}
+is executed on those systems able to give files away. This is
+considered as a security flaw by many people, at least because it
+makes quite difficult to correctly account users for the disk space
+they occupy. Also, the @code{suid} or @code{sgid} attributes of
+files are easily and silently lost when files are given away.
+
+When writing an archive, @command{tar} writes the user id and user name
+separately. If it can't find a user name (because the user id is not
+in @file{/etc/passwd}), then it does not write one. When restoring,
+and doing a @code{chmod} like when you use @value{op-same-permissions},
+@FIXME{same-owner?}it tries to look the name (if one was written)
+up in @file{/etc/passwd}. If it fails, then it uses the user id
+stored in the archive instead.
+
+@item --no-same-owner
+@itemx -o
+Do not attempt to restore ownership when extracting. This is the
+default behavior for ordinary users, so this option has an effect
+only for the superuser.
+
+@item --numeric-owner
+The @value{op-numeric-owner} option allows (ANSI) archives to be written
+without user/group name information or such information to be ignored
+when extracting. It effectively disables the generation and/or use
+of user/group name information. This option forces extraction using
+the numeric ids from the archive, ignoring the names.
+
+This is useful in certain circumstances, when restoring a backup from
+an emergency floppy with different passwd/group files for example.
+It is otherwise impossible to extract files with the right ownerships
+if the password file in use during the extraction does not match the
+one belonging to the filesystem(s) being extracted. This occurs,
+for example, if you are restoring your files after a major crash and
+had booted from an emergency floppy with no password file or put your
+disk into another machine to do the restore.
+
+The numeric ids are @emph{always} saved into @command{tar} archives.
+The identifying names are added at create time when provided by the
+system, unless @value{op-old-archive} is used. Numeric ids could be
+used when moving archives between a collection of machines using
+a centralized management for attribution of numeric ids to users
+and groups. This is often made through using the NIS capabilities.
+
+When making a @command{tar} file for distribution to other sites, it
+is sometimes cleaner to use a single owner for all files in the
+distribution, and nicer to specify the write permission bits of the
+files as stored in the archive independently of their actual value on
+the file system. The way to prepare a clean distribution is usually
+to have some Makefile rule creating a directory, copying all needed
+files in that directory, then setting ownership and permissions as
+wanted (there are a lot of possible schemes), and only then making a
+@command{tar} archive out of this directory, before cleaning
+everything out. Of course, we could add a lot of options to
+@GNUTAR{} for fine tuning permissions and ownership.
+This is not the good way, I think. @GNUTAR{} is
+already crowded with options and moreover, the approach just explained
+gives you a great deal of control already.
+
+@item -p
+@itemx --same-permissions
+@itemx --preserve-permissions
+Extract all protection information.
+
+This option causes @command{tar} to set the modes (access permissions) of
+extracted files exactly as recorded in the archive. If this option
+is not used, the current @code{umask} setting limits the permissions
+on extracted files. This option is by default enabled when
+@command{tar} is executed by a superuser.
+
+
+This option is meaningless with @value{op-list}.
+
+@item --preserve
+Same as both @value{op-same-permissions} and @value{op-same-order}.
+
+The @value{op-preserve} option has no equivalent short option name.
+It is equivalent to @value{op-same-permissions} plus @value{op-same-order}.
+
+@FIXME{I do not see the purpose of such an option. (Neither I. FP.)}
+
+@end table
+
+@node Standard
+@section Basic Tar Format
+@UNREVISED
+
+While an archive may contain many files, the archive itself is a
+single ordinary file. Like any other file, an archive file can be
+written to a storage device such as a tape or disk, sent through a
+pipe or over a network, saved on the active file system, or even
+stored in another archive. An archive file is not easy to read or
+manipulate without using the @command{tar} utility or Tar mode in
+@acronym{GNU} Emacs.
+
+Physically, an archive consists of a series of file entries terminated
+by an end-of-archive entry, which consists of two 512 blocks of zero
+bytes. A file
+entry usually describes one of the files in the archive (an
+@dfn{archive member}), and consists of a file header and the contents
+of the file. File headers contain file names and statistics, checksum
+information which @command{tar} uses to detect file corruption, and
+information about file types.
+
+Archives are permitted to have more than one member with the same
+member name. One way this situation can occur is if more than one
+version of a file has been stored in the archive. For information
+about adding new versions of a file to an archive, see @ref{update}.
+@FIXME-xref{To learn more about having more than one archive member with the
+same name, see -backup node, when it's written.}
+
+In addition to entries describing archive members, an archive may
+contain entries which @command{tar} itself uses to store information.
+@value{xref-label}, for an example of such an archive entry.
+
+A @command{tar} archive file contains a series of blocks. Each block
+contains @code{BLOCKSIZE} bytes. Although this format may be thought
+of as being on magnetic tape, other media are often used.
+
+Each file archived is represented by a header block which describes
+the file, followed by zero or more blocks which give the contents
+of the file. At the end of the archive file there are two 512-byte blocks
+filled with binary zeros as an end-of-file marker. A reasonable system
+should write such end-of-file marker at the end of an archive, but
+must not assume that such a block exists when reading an archive. In
+particular @GNUTAR{} always issues a warning if it does not encounter it.
+
+The blocks may be @dfn{blocked} for physical I/O operations.
+Each record of @var{n} blocks (where @var{n} is set by the
+@value{op-blocking-factor} option to @command{tar}) is written with a single
+@w{@samp{write ()}} operation. On magnetic tapes, the result of
+such a write is a single record. When writing an archive,
+the last record of blocks should be written at the full size, with
+blocks after the zero block containing all zeros. When reading
+an archive, a reasonable system should properly handle an archive
+whose last record is shorter than the rest, or which contains garbage
+records after a zero block.
+
+The header block is defined in C as follows. In the @GNUTAR{}
+distribution, this is part of file @file{src/tar.h}:
+
+@smallexample
+@include header.texi
+@end smallexample
+
+All characters in header blocks are represented by using 8-bit
+characters in the local variant of ASCII. Each field within the
+structure is contiguous; that is, there is no padding used within
+the structure. Each character on the archive medium is stored
+contiguously.
+
+Bytes representing the contents of files (after the header block
+of each file) are not translated in any way and are not constrained
+to represent characters in any character set. The @command{tar} format
+does not distinguish text files from binary files, and no translation
+of file contents is performed.
+
+The @code{name}, @code{linkname}, @code{magic}, @code{uname}, and
+@code{gname} are null-terminated character strings. All other fields
+are zero-filled octal numbers in ASCII. Each numeric field of width
+@var{w} contains @var{w} minus 1 digits, and a null.
+
+The @code{name} field is the file name of the file, with directory names
+(if any) preceding the file name, separated by slashes.
+
+@FIXME{how big a name before field overflows?}
+
+The @code{mode} field provides nine bits specifying file permissions
+and three bits to specify the Set UID, Set GID, and Save Text
+(@dfn{sticky}) modes. Values for these bits are defined above.
+When special permissions are required to create a file with a given
+mode, and the user restoring files from the archive does not hold such
+permissions, the mode bit(s) specifying those special permissions
+are ignored. Modes which are not supported by the operating system
+restoring files from the archive will be ignored. Unsupported modes
+should be faked up when creating or updating an archive; e.g.@: the
+group permission could be copied from the @emph{other} permission.
+
+The @code{uid} and @code{gid} fields are the numeric user and group
+ID of the file owners, respectively. If the operating system does
+not support numeric user or group IDs, these fields should be ignored.
+
+The @code{size} field is the size of the file in bytes; linked files
+are archived with this field specified as zero. @FIXME-xref{Modifiers, in
+particular the @value{op-incremental} option.}
+
+The @code{mtime} field is the modification time of the file at the time
+it was archived. It is the ASCII representation of the octal value of
+the last time the file was modified, represented as an integer number of
+seconds since January 1, 1970, 00:00 Coordinated Universal Time.
+
+The @code{chksum} field is the ASCII representation of the octal value
+of the simple sum of all bytes in the header block. Each 8-bit
+byte in the header is added to an unsigned integer, initialized to
+zero, the precision of which shall be no less than seventeen bits.
+When calculating the checksum, the @code{chksum} field is treated as
+if it were all blanks.
+
+The @code{typeflag} field specifies the type of file archived. If a
+particular implementation does not recognize or permit the specified
+type, the file will be extracted as if it were a regular file. As this
+action occurs, @command{tar} issues a warning to the standard error.
+
+The @code{atime} and @code{ctime} fields are used in making incremental
+backups; they store, respectively, the particular file's access time
+and last inode-change time.
+
+The @code{offset} is used by the @value{op-multi-volume} option, when
+making a multi-volume archive. The offset is number of bytes into
+the file that we need to restart at to continue the file on the next
+tape, i.e., where we store the location that a continued file is
+continued at.
+
+The following fields were added to deal with sparse files. A file
+is @dfn{sparse} if it takes in unallocated blocks which end up being
+represented as zeros, i.e., no useful data. A test to see if a file
+is sparse is to look at the number blocks allocated for it versus the
+number of characters in the file; if there are fewer blocks allocated
+for the file than would normally be allocated for a file of that
+size, then the file is sparse. This is the method @command{tar} uses to
+detect a sparse file, and once such a file is detected, it is treated
+differently from non-sparse files.
+
+Sparse files are often @code{dbm} files, or other database-type files
+which have data at some points and emptiness in the greater part of
+the file. Such files can appear to be very large when an @samp{ls
+-l} is done on them, when in truth, there may be a very small amount
+of important data contained in the file. It is thus undesirable
+to have @command{tar} think that it must back up this entire file, as
+great quantities of room are wasted on empty blocks, which can lead
+to running out of room on a tape far earlier than is necessary.
+Thus, sparse files are dealt with so that these empty blocks are
+not written to the tape. Instead, what is written to the tape is a
+description, of sorts, of the sparse file: where the holes are, how
+big the holes are, and how much data is found at the end of the hole.
+This way, the file takes up potentially far less room on the tape,
+and when the file is extracted later on, it will look exactly the way
+it looked beforehand. The following is a description of the fields
+used to handle a sparse file:
+
+The @code{sp} is an array of @code{struct sparse}. Each @code{struct
+sparse} contains two 12-character strings which represent an offset
+into the file and a number of bytes to be written at that offset.
+The offset is absolute, and not relative to the offset in preceding
+array element.
+
+The header can hold four of these @code{struct sparse} at the moment;
+if more are needed, they are not stored in the header.
+
+The @code{isextended} flag is set when an @code{extended_header}
+is needed to deal with a file. Note that this means that this flag
+can only be set when dealing with a sparse file, and it is only set
+in the event that the description of the file will not fit in the
+allotted room for sparse structures in the header. In other words,
+an extended_header is needed.
+
+The @code{extended_header} structure is used for sparse files which
+need more sparse structures than can fit in the header. The header can
+fit 4 such structures; if more are needed, the flag @code{isextended}
+gets set and the next block is an @code{extended_header}.
+
+Each @code{extended_header} structure contains an array of 21
+sparse structures, along with a similar @code{isextended} flag
+that the header had. There can be an indeterminate number of such
+@code{extended_header}s to describe a sparse file.
+
+@table @asis
+
+@item @code{REGTYPE}
+@itemx @code{AREGTYPE}
+These flags represent a regular file. In order to be compatible
+with older versions of @command{tar}, a @code{typeflag} value of
+@code{AREGTYPE} should be silently recognized as a regular file.
+New archives should be created using @code{REGTYPE}. Also, for
+backward compatibility, @command{tar} treats a regular file whose name
+ends with a slash as a directory.
+
+@item @code{LNKTYPE}
+This flag represents a file linked to another file, of any type,
+previously archived. Such files are identified in Unix by each
+file having the same device and inode number. The linked-to name is
+specified in the @code{linkname} field with a trailing null.
+
+@item @code{SYMTYPE}
+This represents a symbolic link to another file. The linked-to name
+is specified in the @code{linkname} field with a trailing null.
+
+@item @code{CHRTYPE}
+@itemx @code{BLKTYPE}
+These represent character special files and block special files
+respectively. In this case the @code{devmajor} and @code{devminor}
+fields will contain the major and minor device numbers respectively.
+Operating systems may map the device specifications to their own
+local specification, or may ignore the entry.
+
+@item @code{DIRTYPE}
+This flag specifies a directory or sub-directory. The directory
+name in the @code{name} field should end with a slash. On systems where
+disk allocation is performed on a directory basis, the @code{size} field
+will contain the maximum number of bytes (which may be rounded to
+the nearest disk block allocation unit) which the directory may
+hold. A @code{size} field of zero indicates no such limiting. Systems
+which do not support limiting in this manner should ignore the
+@code{size} field.