+@node Writing
+@subsection Changing How @command{tar} Writes Files
+@UNREVISED
+
+@FIXME{Introductory paragraph}
+
+@menu
+* Dealing with Old Files::
+* Overwrite Old Files::
+* Keep Old Files::
+* Keep Newer Files::
+* Unlink First::
+* Recursive Unlink::
+* Data Modification Times::
+* Setting Access Permissions::
+* Directory Modification Times and Permissions::
+* Writing to Standard Output::
+* Writing to an External Program::
+* remove files::
+@end menu
+
+@node Dealing with Old Files
+@unnumberedsubsubsec Options Controlling the Overwriting of Existing Files
+
+@xopindex{overwrite-dir, introduced}
+When extracting files, if @command{tar} discovers that the extracted
+file already exists, it normally replaces the file by removing it before
+extracting it, to prevent confusion in the presence of hard or symbolic
+links. (If the existing file is a symbolic link, it is removed, not
+followed.) However, if a directory cannot be removed because it is
+nonempty, @command{tar} normally overwrites its metadata (ownership,
+permission, etc.). The @option{--overwrite-dir} option enables this
+default behavior. To be more cautious and preserve the metadata of
+such a directory, use the @option{--no-overwrite-dir} option.
+
+@cindex Overwriting old files, prevention
+@xopindex{keep-old-files, introduced}
+To be even more cautious and prevent existing files from being replaced, use
+the @option{--keep-old-files} (@option{-k}) option. It causes @command{tar} to refuse
+to replace or update a file that already exists, i.e., a file with the
+same name as an archive member prevents extraction of that archive
+member. Instead, it reports an error.
+
+@xopindex{overwrite, introduced}
+To be more aggressive about altering existing files, use the
+@option{--overwrite} option. It causes @command{tar} to overwrite
+existing files and to follow existing symbolic links when extracting.
+
+@cindex Protecting old files
+Some people argue that @GNUTAR{} should not hesitate
+to overwrite files with other files when extracting. When extracting
+a @command{tar} archive, they expect to see a faithful copy of the
+state of the file system when the archive was created. It is debatable
+that this would always be a proper behavior. For example, suppose one
+has an archive in which @file{usr/local} is a link to
+@file{usr/local2}. Since then, maybe the site removed the link and
+renamed the whole hierarchy from @file{/usr/local2} to
+@file{/usr/local}. Such things happen all the time. I guess it would
+not be welcome at all that @GNUTAR{} removes the
+whole hierarchy just to make room for the link to be reinstated
+(unless it @emph{also} simultaneously restores the full
+@file{/usr/local2}, of course!) @GNUTAR{} is indeed
+able to remove a whole hierarchy to reestablish a symbolic link, for
+example, but @emph{only if} @option{--recursive-unlink} is specified
+to allow this behavior. In any case, single files are silently
+removed.
+
+@xopindex{unlink-first, introduced}
+Finally, the @option{--unlink-first} (@option{-U}) option can improve performance in
+some cases by causing @command{tar} to remove files unconditionally
+before extracting them.
+
+@node Overwrite Old Files
+@unnumberedsubsubsec Overwrite Old Files
+
+@table @option
+@opindex overwrite
+@item --overwrite
+Overwrite existing files and directory metadata when extracting files
+from an archive.
+
+This causes @command{tar} to write extracted files into the file system without
+regard to the files already on the system; i.e., files with the same
+names as archive members are overwritten when the archive is extracted.
+It also causes @command{tar} to extract the ownership, permissions,
+and time stamps onto any preexisting files or directories.
+If the name of a corresponding file name is a symbolic link, the file
+pointed to by the symbolic link will be overwritten instead of the
+symbolic link itself (if this is possible). Moreover, special devices,
+empty directories and even symbolic links are automatically removed if
+they are in the way of extraction.
+
+Be careful when using the @option{--overwrite} option, particularly when
+combined with the @option{--absolute-names} (@option{-P}) option, as this combination
+can change the contents, ownership or permissions of any file on your
+system. Also, many systems do not take kindly to overwriting files that
+are currently being executed.
+
+@opindex overwrite-dir
+@item --overwrite-dir
+Overwrite the metadata of directories when extracting files from an
+archive, but remove other files before extracting.
+@end table
+
+@node Keep Old Files
+@unnumberedsubsubsec Keep Old Files
+
+@table @option
+@opindex keep-old-files
+@item --keep-old-files
+@itemx -k
+Do not replace existing files from archive. The
+@option{--keep-old-files} (@option{-k}) option prevents @command{tar}
+from replacing existing files with files with the same name from the
+archive. The @option{--keep-old-files} option is meaningless with
+@option{--list} (@option{-t}). Prevents @command{tar} from replacing
+files in the file system during extraction.
+@end table
+
+@node Keep Newer Files
+@unnumberedsubsubsec Keep Newer Files
+
+@table @option
+@opindex keep-newer-files
+@item --keep-newer-files
+Do not replace existing files that are newer than their archive
+copies. This option is meaningless with @option{--list} (@option{-t}).
+@end table
+
+@node Unlink First
+@unnumberedsubsubsec Unlink First
+
+@table @option
+@opindex unlink-first
+@item --unlink-first
+@itemx -U
+Remove files before extracting over them.
+This can make @command{tar} run a bit faster if you know in advance
+that the extracted files all need to be removed. Normally this option
+slows @command{tar} down slightly, so it is disabled by default.
+@end table
+
+@node Recursive Unlink
+@unnumberedsubsubsec Recursive Unlink
+
+@table @option
+@opindex recursive-unlink
+@item --recursive-unlink
+When this option is specified, try removing files and directory hierarchies
+before extracting over them. @emph{This is a dangerous option!}
+@end table
+
+If you specify the @option{--recursive-unlink} option,
+@command{tar} removes @emph{anything} that keeps you from extracting a file
+as far as current permissions will allow it. This could include removal
+of the contents of a full directory hierarchy.
+
+@node Data Modification Times
+@unnumberedsubsubsec Setting Data Modification Times
+
+@cindex Data modification times of extracted files
+@cindex Modification times of extracted files
+Normally, @command{tar} sets the data modification times of extracted
+files to the corresponding times recorded for the files in the archive, but
+limits the permissions of extracted files by the current @code{umask}
+setting.
+
+To set the data modification times of extracted files to the time when
+the files were extracted, use the @option{--touch} (@option{-m}) option in
+conjunction with @option{--extract} (@option{--get}, @option{-x}).
+
+@table @option
+@opindex touch
+@item --touch
+@itemx -m
+Sets the data modification time of extracted archive members to the time
+they were extracted, not the time recorded for them in the archive.
+Use in conjunction with @option{--extract} (@option{--get}, @option{-x}).
+@end table
+
+@node Setting Access Permissions
+@unnumberedsubsubsec Setting Access Permissions
+
+@cindex Permissions of extracted files
+@cindex Modes of extracted files
+To set the modes (access permissions) of extracted files to those
+recorded for those files in the archive, use @option{--same-permissions}
+in conjunction with the @option{--extract} (@option{--get},
+@option{-x}) operation.
+
+@table @option
+@opindex preserve-permissions
+@opindex same-permissions
+@item --preserve-permissions
+@itemx --same-permissions
+@c @itemx --ignore-umask
+@itemx -p
+Set modes of extracted archive members to those recorded in the
+archive, instead of current umask settings. Use in conjunction with
+@option{--extract} (@option{--get}, @option{-x}).
+@end table
+
+@node Directory Modification Times and Permissions
+@unnumberedsubsubsec Directory Modification Times and Permissions
+
+After successfully extracting a file member, @GNUTAR{} normally
+restores its permissions and modification times, as described in the
+previous sections. This cannot be done for directories, because
+after extracting a directory @command{tar} will almost certainly
+extract files into that directory and this will cause the directory
+modification time to be updated. Moreover, restoring that directory
+permissions may not permit file creation within it. Thus, restoring
+directory permissions and modification times must be delayed at least
+until all files have been extracted into that directory. @GNUTAR{}
+restores directories using the following approach.
+
+The extracted directories are created with the mode specified in the
+archive, as modified by the umask of the user, which gives sufficient
+permissions to allow file creation. The meta-information about the
+directory is recorded in the temporary list of directories. When
+preparing to extract next archive member, @GNUTAR{} checks if the
+directory prefix of this file contains the remembered directory. If
+it does not, the program assumes that all files have been extracted
+into that directory, restores its modification time and permissions
+and removes its entry from the internal list. This approach allows
+to correctly restore directory meta-information in the majority of
+cases, while keeping memory requirements sufficiently small. It is
+based on the fact, that most @command{tar} archives use the predefined
+order of members: first the directory, then all the files and
+subdirectories in that directory.
+
+However, this is not always true. The most important exception are
+incremental archives (@pxref{Incremental Dumps}). The member order in
+an incremental archive is reversed: first all directory members are
+stored, followed by other (non-directory) members. So, when extracting
+from incremental archives, @GNUTAR{} alters the above procedure. It
+remembers all restored directories, and restores their meta-data
+only after the entire archive has been processed. Notice, that you do
+not need to specify any special options for that, as @GNUTAR{}
+automatically detects archives in incremental format.
+
+There may be cases, when such processing is required for normal archives
+too. Consider the following example:
+
+@smallexample
+@group
+$ @kbd{tar --no-recursion -cvf archive \
+ foo foo/file1 bar bar/file foo/file2}
+foo/
+foo/file1
+bar/
+bar/file
+foo/file2
+@end group
+@end smallexample
+
+During the normal operation, after encountering @file{bar}
+@GNUTAR{} will assume that all files from the directory @file{foo}
+were already extracted and will therefore restore its timestamp and
+permission bits. However, after extracting @file{foo/file2} the
+directory timestamp will be offset again.
+
+To correctly restore directory meta-information in such cases, use
+@option{delay-directory-restore} command line option:
+
+@table @option
+@opindex delay-directory-restore
+@item --delay-directory-restore
+Delays restoring of the modification times and permissions of extracted
+directories until the end of extraction. This way, correct
+meta-information is restored even if the archive has unusual member
+ordering.
+
+@opindex no-delay-directory-restore
+@item --no-delay-directory-restore
+Cancel the effect of the previous @option{--delay-directory-restore}.
+Use this option if you have used @option{--delay-directory-restore} in
+@env{TAR_OPTIONS} variable (@pxref{TAR_OPTIONS}) and wish to
+temporarily disable it.
+@end table
+
+@node Writing to Standard Output
+@unnumberedsubsubsec Writing to Standard Output
+
+@cindex Writing extracted files to standard output
+@cindex Standard output, writing extracted files to
+To write the extracted files to the standard output, instead of
+creating the files on the file system, use @option{--to-stdout} (@option{-O}) in
+conjunction with @option{--extract} (@option{--get}, @option{-x}). This option is useful if you are
+extracting files to send them through a pipe, and do not need to
+preserve them in the file system. If you extract multiple members,
+they appear on standard output concatenated, in the order they are
+found in the archive.
+
+@table @option
+@opindex to-stdout
+@item --to-stdout
+@itemx -O
+Writes files to the standard output. Use only in conjunction with
+@option{--extract} (@option{--get}, @option{-x}). When this option is
+used, instead of creating the files specified, @command{tar} writes
+the contents of the files extracted to its standard output. This may
+be useful if you are only extracting the files in order to send them
+through a pipe. This option is meaningless with @option{--list}
+(@option{-t}).
+@end table
+
+This can be useful, for example, if you have a tar archive containing
+a big file and don't want to store the file on disk before processing
+it. You can use a command like this:
+
+@smallexample
+tar -xOzf foo.tgz bigfile | process
+@end smallexample
+
+or even like this if you want to process the concatenation of the files:
+
+@smallexample
+tar -xOzf foo.tgz bigfile1 bigfile2 | process
+@end smallexample
+
+However, @option{--to-command} may be more convenient for use with
+multiple files. See the next section.
+
+@node Writing to an External Program
+@unnumberedsubsubsec Writing to an External Program
+
+You can instruct @command{tar} to send the contents of each extracted
+file to the standard input of an external program:
+
+@table @option
+@opindex to-command
+@item --to-command=@var{command}
+Extract files and pipe their contents to the standard input of
+@var{command}. When this option is used, instead of creating the
+files specified, @command{tar} invokes @var{command} and pipes the
+contents of the files to its standard output. @var{Command} may
+contain command line arguments. The program is executed via
+@code{sh -c}. Notice, that @var{command} is executed once for each regular file
+extracted. Non-regular files (directories, etc.) are ignored when this
+option is used.
+@end table
+
+The command can obtain the information about the file it processes
+from the following environment variables:
+
+@table @env
+@vrindex TAR_FILETYPE, to-command environment
+@item TAR_FILETYPE
+Type of the file. It is a single letter with the following meaning:
+
+@multitable @columnfractions 0.10 0.90
+@item f @tab Regular file
+@item d @tab Directory
+@item l @tab Symbolic link
+@item h @tab Hard link
+@item b @tab Block device
+@item c @tab Character device
+@end multitable
+
+Currently only regular files are supported.
+
+@vrindex TAR_MODE, to-command environment
+@item TAR_MODE
+File mode, an octal number.
+
+@vrindex TAR_FILENAME, to-command environment
+@item TAR_FILENAME
+The name of the file.
+
+@vrindex TAR_REALNAME, to-command environment
+@item TAR_REALNAME
+Name of the file as stored in the archive.
+
+@vrindex TAR_UNAME, to-command environment
+@item TAR_UNAME
+Name of the file owner.
+
+@vrindex TAR_GNAME, to-command environment
+@item TAR_GNAME
+Name of the file owner group.
+
+@vrindex TAR_ATIME, to-command environment
+@item TAR_ATIME
+Time of last access. It is a decimal number, representing seconds
+since the epoch. If the archive provides times with nanosecond
+precision, the nanoseconds are appended to the timestamp after a
+decimal point.
+
+@vrindex TAR_MTIME, to-command environment
+@item TAR_MTIME
+Time of last modification.
+
+@vrindex TAR_CTIME, to-command environment
+@item TAR_CTIME
+Time of last status change.
+
+@vrindex TAR_SIZE, to-command environment
+@item TAR_SIZE
+Size of the file.
+
+@vrindex TAR_UID, to-command environment
+@item TAR_UID
+UID of the file owner.
+
+@vrindex TAR_GID, to-command environment
+@item TAR_GID
+GID of the file owner.
+@end table
+
+In addition to these variables, @env{TAR_VERSION} contains the
+@GNUTAR{} version number.
+
+If @var{command} exits with a non-0 status, @command{tar} will print
+an error message similar to the following:
+
+@smallexample
+tar: 2345: Child returned status 1
+@end smallexample
+
+Here, @samp{2345} is the PID of the finished process.
+
+If this behavior is not wanted, use @option{--ignore-command-error}:
+
+@table @option
+@opindex ignore-command-error
+@item --ignore-command-error
+Ignore exit codes of subprocesses. Notice that if the program
+exits on signal or otherwise terminates abnormally, the error message
+will be printed even if this option is used.
+
+@opindex no-ignore-command-error
+@item --no-ignore-command-error
+Cancel the effect of any previous @option{--ignore-command-error}
+option. This option is useful if you have set
+@option{--ignore-command-error} in @env{TAR_OPTIONS}
+(@pxref{TAR_OPTIONS}) and wish to temporarily cancel it.
+@end table
+
+@node remove files
+@unnumberedsubsubsec Removing Files
+
+@FIXME{The section is too terse. Something more to add? An example,
+maybe?}
+
+@table @option
+@opindex remove-files
+@item --remove-files
+Remove files after adding them to the archive.
+@end table
+
+@node Scarce
+@subsection Coping with Scarce Resources
+@UNREVISED
+
+@cindex Small memory
+@cindex Running out of space
+
+@menu
+* Starting File::
+* Same Order::
+@end menu
+
+@node Starting File
+@unnumberedsubsubsec Starting File
+
+@table @option
+@opindex starting-file
+@item --starting-file=@var{name}
+@itemx -K @var{name}
+Starts an operation in the middle of an archive. Use in conjunction
+with @option{--extract} (@option{--get}, @option{-x}) or @option{--list} (@option{-t}).
+@end table
+
+@cindex Middle of the archive, starting in the
+If a previous attempt to extract files failed due to lack of disk
+space, you can use @option{--starting-file=@var{name}} (@option{-K
+@var{name}}) to start extracting only after member @var{name} of the
+archive. This assumes, of course, that there is now free space, or
+that you are now extracting into a different file system. (You could
+also choose to suspend @command{tar}, remove unnecessary files from
+the file system, and then restart the same @command{tar} operation.
+In this case, @option{--starting-file} is not necessary.
+@xref{Incremental Dumps}, @xref{interactive}, and @ref{exclude}.)
+
+@node Same Order
+@unnumberedsubsubsec Same Order
+
+@table @option
+@cindex Large lists of file names on small machines
+@opindex same-order
+@opindex preserve-order
+@item --same-order
+@itemx --preserve-order
+@itemx -s
+To process large lists of file names on machines with small amounts of
+memory. Use in conjunction with @option{--compare} (@option{--diff},
+@option{-d}), @option{--list} (@option{-t}) or @option{--extract}
+(@option{--get}, @option{-x}).
+@end table
+
+The @option{--same-order} (@option{--preserve-order}, @option{-s}) option tells @command{tar} that the list of file
+names to be listed or extracted is sorted in the same order as the
+files in the archive. This allows a large list of names to be used,
+even on a small machine that would not otherwise be able to hold all
+the names in memory at the same time. Such a sorted list can easily be
+created by running @samp{tar -t} on the archive and editing its output.
+
+This option is probably never needed on modern computer systems.
+
+@node backup
+@section Backup options
+
+@cindex backup options
+
+@GNUTAR{} offers options for making backups of files
+before writing new versions. These options control the details of
+these backups. They may apply to the archive itself before it is
+created or rewritten, as well as individual extracted members. Other
+@acronym{GNU} programs (@command{cp}, @command{install}, @command{ln},
+and @command{mv}, for example) offer similar options.
+
+Backup options may prove unexpectedly useful when extracting archives
+containing many members having identical name, or when extracting archives
+on systems having file name limitations, making different members appear
+has having similar names through the side-effect of name truncation.
+(This is true only if we have a good scheme for truncated backup names,
+which I'm not sure at all: I suspect work is needed in this area.)
+When any existing file is backed up before being overwritten by extraction,
+then clashing files are automatically be renamed to be unique, and the
+true name is kept for only the last file of a series of clashing files.
+By using verbose mode, users may track exactly what happens.
+
+At the detail level, some decisions are still experimental, and may
+change in the future, we are waiting comments from our users. So, please
+do not learn to depend blindly on the details of the backup features.
+For example, currently, directories themselves are never renamed through
+using these options, so, extracting a file over a directory still has
+good chances to fail. Also, backup options apply to created archives,
+not only to extracted members. For created archives, backups will not
+be attempted when the archive is a block or character device, or when it
+refers to a remote file.
+
+For the sake of simplicity and efficiency, backups are made by renaming old
+files prior to creation or extraction, and not by copying. The original
+name is restored if the file creation fails. If a failure occurs after a
+partial extraction of a file, both the backup and the partially extracted
+file are kept.
+
+@table @samp
+@item --backup[=@var{method}]
+@opindex backup
+@vindex VERSION_CONTROL
+@cindex backups
+Back up files that are about to be overwritten or removed.
+Without this option, the original versions are destroyed.
+
+Use @var{method} to determine the type of backups made.
+If @var{method} is not specified, use the value of the @env{VERSION_CONTROL}
+environment variable. And if @env{VERSION_CONTROL} is not set,
+use the @samp{existing} method.
+
+@vindex version-control @r{Emacs variable}
+This option corresponds to the Emacs variable @samp{version-control};
+the same values for @var{method} are accepted as in Emacs. This option
+also allows more descriptive names. The valid @var{method}s are:
+
+@table @samp
+@item t
+@itemx numbered
+@cindex numbered @r{backup method}
+Always make numbered backups.
+
+@item nil
+@itemx existing
+@cindex existing @r{backup method}
+Make numbered backups of files that already have them, simple backups
+of the others.
+
+@item never
+@itemx simple
+@cindex simple @r{backup method}
+Always make simple backups.
+
+@end table
+
+@item --suffix=@var{suffix}
+@opindex suffix
+@cindex backup suffix
+@vindex SIMPLE_BACKUP_SUFFIX
+Append @var{suffix} to each backup file made with @option{--backup}. If this
+option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX}
+environment variable is used. And if @env{SIMPLE_BACKUP_SUFFIX} is not
+set, the default is @samp{~}, just as in Emacs.
+
+@end table
+
+@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
+You can avoid subshells by using @option{-C} option:
+
+@smallexample
+$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xf -}
+@end smallexample
+
+@noindent
+The command also works using short option forms:
+
+@smallexample
+$ @kbd{(cd sourcedir; tar --create --file=- . ) \
+ | (cd targetdir; tar --extract --file=-)}
+# Or:
+$ @kbd{tar --directory sourcedir --create --file=- . ) \
+ | tar --directory targetdir --extract --file=-}
+@end smallexample
+
+@noindent
+This is one of the easiest methods to transfer a @command{tar} archive.
+
+@node looking ahead
+@section Looking Ahead: The Rest of this Manual
+
+You have now seen how to use all eight of the operations available to
+@command{tar}, and a number of the possible options. The next chapter
+explains how to choose and change file and archive names, how to use
+files to store names of other files which you can then call as
+arguments to @command{tar} (this can help you save time if you expect to
+archive the same list of files a number of times), and so forth.
+@FIXME{in case it's not obvious, i'm making this up in some sense
+based on my limited memory of what the next chapter *really* does. i
+just wanted to flesh out this final section a little bit so i'd
+remember to stick it in here. :-)}
+
+If there are too many files to conveniently list on the command line,
+you can list the names in a file, and @command{tar} will read that file.
+@xref{files}.
+
+There are various ways of causing @command{tar} to skip over some files,
+and not archive them. @xref{Choosing}.
+
+@node Backups
+@chapter Performing Backups and Restoring Files
+@UNREVISED
+
+@GNUTAR{} is distributed along with the scripts
+which the Free Software Foundation uses for performing backups. There
+is no corresponding scripts available yet for doing restoration of
+files. Even if there is a good chance those scripts may be satisfying
+to you, they are not the only scripts or methods available for doing
+backups and restore. You may well create your own, or use more
+sophisticated packages dedicated to that purpose.
+
+Some users are enthusiastic about @code{Amanda} (The Advanced Maryland
+Automatic Network Disk Archiver), a backup system developed by James
+da Silva @file{jds@@cs.umd.edu} and available on many Unix systems.
+This is free software, and it is available at these places:
+
+@smallexample
+http://www.cs.umd.edu/projects/amanda/amanda.html
+ftp://ftp.cs.umd.edu/pub/amanda
+@end smallexample
+
+@FIXME{
+
+Here is a possible plan for a future documentation about the backuping
+scripts which are provided within the @GNUTAR{}
+distribution.
+
+@itemize @bullet
+@item dumps
+ @itemize @minus
+ @item what are dumps
+ @item different levels of dumps
+ @itemize +
+ @item full dump = dump everything
+ @item level 1, level 2 dumps etc
+ A level @var{n} dump dumps everything changed since the last level
+ @var{n}-1 dump (?)
+ @end itemize
+ @item how to use scripts for dumps (ie, the concept)
+ @itemize +
+ @item scripts to run after editing backup specs (details)
+ @end itemize
+ @item Backup Specs, what is it.
+ @itemize +
+ @item how to customize
+ @item actual text of script [/sp/dump/backup-specs]
+ @end itemize
+ @item Problems
+ @itemize +
+ @item rsh doesn't work
+ @item rtape isn't installed
+ @item (others?)
+ @end itemize
+ @item the @option{--incremental} option of tar
+ @item tapes
+ @itemize +
+ @item write protection
+ @item types of media, different sizes and types, useful for different things
+ @item files and tape marks
+ one tape mark between files, two at end.
+ @item positioning the tape
+ MT writes two at end of write,
+ backspaces over one when writing again.
+ @end itemize
+ @end itemize
+@end itemize
+}
+
+This chapter documents both the provided shell scripts and @command{tar}
+options which are more specific to usage as a backup tool.
+
+To @dfn{back up} a file system means to create archives that contain
+all the files in that file system. Those archives can then be used to
+restore any or all of those files (for instance if a disk crashes or a
+file is accidentally deleted). File system @dfn{backups} are also
+called @dfn{dumps}.
+
+@menu
+* Full Dumps:: Using @command{tar} to Perform Full Dumps
+* Incremental Dumps:: Using @command{tar} to Perform Incremental Dumps
+* Backup Levels:: Levels of Backups
+* Backup Parameters:: Setting Parameters for Backups and Restoration
+* Scripted Backups:: Using the Backup Scripts
+* Scripted Restoration:: Using the Restore Script
+@end menu
+
+@node Full Dumps
+@section Using @command{tar} to Perform Full Dumps
+@UNREVISED
+
+@cindex full dumps
+@cindex dumps, full
+
+@cindex corrupted archives
+Full dumps should only be made when no other people or programs
+are modifying files in the file system. If files are modified while
+@command{tar} is making the backup, they may not be stored properly in
+the archive, in which case you won't be able to restore them if you
+have to. (Files not being modified are written with no trouble, and do
+not corrupt the entire archive.)
+
+You will want to use the @option{--label=@var{archive-label}}
+(@option{-V @var{archive-label}}) option to give the archive a
+volume label, so you can tell what this archive is even if the label
+falls off the tape, or anything like that.
+
+Unless the file system you are dumping is guaranteed to fit on
+one volume, you will need to use the @option{--multi-volume} (@option{-M}) option.
+Make sure you have enough tapes on hand to complete the backup.
+
+If you want to dump each file system separately you will need to use
+the @option{--one-file-system} option to prevent
+@command{tar} from crossing file system boundaries when storing
+(sub)directories.
+
+The @option{--incremental} (@option{-G}) (@pxref{Incremental Dumps})
+option is not needed, since this is a complete copy of everything in
+the file system, and a full restore from this backup would only be
+done onto a completely
+empty disk.
+
+Unless you are in a hurry, and trust the @command{tar} program (and your
+tapes), it is a good idea to use the @option{--verify} (@option{-W})
+option, to make sure your files really made it onto the dump properly.
+This will also detect cases where the file was modified while (or just
+after) it was being archived. Not all media (notably cartridge tapes)
+are capable of being verified, unfortunately.
+
+@node Incremental Dumps
+@section Using @command{tar} to Perform Incremental Dumps
+
+@dfn{Incremental backup} is a special form of @GNUTAR{} archive that
+stores additional metadata so that exact state of the file system
+can be restored when extracting the archive.
+
+@GNUTAR{} currently offers two options for handling incremental
+backups: @option{--listed-incremental=@var{snapshot-file}} (@option{-g
+@var{snapshot-file}}) and @option{--incremental} (@option{-G}).
+
+@opindex listed-incremental
+The option @option{--listed-incremental} instructs tar to operate on
+an incremental archive with additional metadata stored in a standalone
+file, called a @dfn{snapshot file}. The purpose of this file is to help
+determine which files have been changed, added or deleted since the
+last backup, so that the next incremental backup will contain only
+modified files. The name of the snapshot file is given as an argument
+to the option:
+
+@table @option
+@item --listed-incremental=@var{file}
+@itemx -g @var{file}
+ Handle incremental backups with snapshot data in @var{file}.
+@end table
+
+To create an incremental backup, you would use
+@option{--listed-incremental} together with @option{--create}
+(@pxref{create}). For example:
+
+@smallexample
+$ @kbd{tar --create \
+ --file=archive.1.tar \
+ --listed-incremental=/var/log/usr.snar \
+ /usr}
+@end smallexample
+
+This will create in @file{archive.1.tar} an incremental backup of
+the @file{/usr} file system, storing additional metadata in the file
+@file{/var/log/usr.snar}. If this file does not exist, it will be
+created. The created archive will then be a @dfn{level 0 backup};
+please see the next section for more on backup levels.
+
+Otherwise, if the file @file{/var/log/usr.snar} exists, it
+determines which files are modified. In this case only these files will be
+stored in the archive. Suppose, for example, that after running the
+above command, you delete file @file{/usr/doc/old} and create
+directory @file{/usr/local/db} with the following contents:
+
+@smallexample
+$ @kbd{ls /usr/local/db}
+/usr/local/db/data
+/usr/local/db/index
+@end smallexample
+
+Some time later you create another incremental backup. You will
+then see:
+
+@smallexample
+$ @kbd{tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar \
+ /usr}
+tar: usr/local/db: Directory is new
+usr/local/db/
+usr/local/db/data
+usr/local/db/index
+@end smallexample
+
+@noindent
+The created archive @file{archive.2.tar} will contain only these
+three members. This archive is called a @dfn{level 1 backup}. Notice
+that @file{/var/log/usr.snar} will be updated with the new data, so if
+you plan to create more @samp{level 1} backups, it is necessary to
+create a working copy of the snapshot file before running
+@command{tar}. The above example will then be modified as follows:
+
+@smallexample
+$ @kbd{cp /var/log/usr.snar /var/log/usr.snar-1}
+$ @kbd{tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar-1 \
+ /usr}
+@end smallexample
+
+Incremental dumps depend crucially on time stamps, so the results are
+unreliable if you modify a file's time stamps during dumping (e.g.,
+with the @option{--atime-preserve=replace} option), or if you set the clock
+backwards.
+
+@cindex Device numbers, using in incremental backups
+Metadata stored in snapshot files include device numbers, which,
+obviously is supposed to be a non-volatile value. However, it turns
+out that NFS devices have undependable values when an automounter
+gets in the picture. This can lead to a great deal of spurious
+redumping in incremental dumps, so it is somewhat useless to compare
+two NFS devices numbers over time. The solution implemented currently
+is to considers all NFS devices as being equal when it comes to
+comparing directories; this is fairly gross, but there does not seem
+to be a better way to go.
+
+If you are using the @i{Linux} kernel, the device numbers can also
+change when upgrading to some newer versions of the kernel. This can
+cause the next backup to be full backup on the affected filesystems.
+@xref{Fixing Snapshot Files}, for the information on how to handle this case.
+
+Note that incremental archives use @command{tar} extensions and may
+not be readable by non-@acronym{GNU} versions of the @command{tar} program.
+
+@xopindex{listed-incremental, using with @option{--extract}}
+@xopindex{extract, using with @option{--listed-incremental}}
+To extract from the incremental dumps, use
+@option{--listed-incremental} together with @option{--extract}
+option (@pxref{extracting files}). In this case, @command{tar} does
+not need to access snapshot file, since all the data necessary for
+extraction are stored in the archive itself. So, when extracting, you
+can give whatever argument to @option{--listed-incremental}, the usual
+practice is to use @option{--listed-incremental=/dev/null}.
+Alternatively, you can use @option{--incremental}, which needs no
+arguments. In general, @option{--incremental} (@option{-G}) can be
+used as a shortcut for @option{--listed-incremental} when listing or
+extracting incremental backups (for more information, regarding this
+option, @pxref{incremental-op}).
+
+When extracting from the incremental backup @GNUTAR{} attempts to
+restore the exact state the file system had when the archive was
+created. In particular, it will @emph{delete} those files in the file
+system that did not exist in their directories when the archive was
+created. If you have created several levels of incremental files,
+then in order to restore the exact contents the file system had when
+the last level was created, you will need to restore from all backups
+in turn. Continuing our example, to restore the state of @file{/usr}
+file system, one would do@footnote{Notice, that since both archives
+were created without @option{-P} option (@pxref{absolute}), these
+commands should be run from the root file system.}:
+
+@smallexample
+$ @kbd{tar --extract \
+ --listed-incremental=/dev/null \
+ --file archive.1.tar}
+$ @kbd{tar --extract \
+ --listed-incremental=/dev/null \
+ --file archive.2.tar}
+@end smallexample
+
+To list the contents of an incremental archive, use @option{--list}
+(@pxref{list}), as usual. To obtain more information about the
+archive, use @option{--listed-incremental} or @option{--incremental}
+combined with two @option{--verbose} options@footnote{Two
+@option{--verbose} options were selected to avoid breaking usual
+verbose listing output (@option{--list --verbose}) when using in
+scripts.
+
+@xopindex{incremental, using with @option{--list}}
+@xopindex{listed-incremental, using with @option{--list}}
+@xopindex{list, using with @option{--incremental}}
+@xopindex{list, using with @option{--listed-incremental}}
+Versions of @GNUTAR{} up to 1.15.1 used to dump verbatim binary
+contents of the DUMPDIR header (with terminating nulls) when
+@option{--incremental} or @option{--listed-incremental} option was
+given, no matter what the verbosity level. This behavior, and,
+especially, the binary output it produced were considered inconvenient
+and were changed in version 1.16}:
+
+@smallexample
+@kbd{tar --list --incremental --verbose --verbose archive.tar}
+@end smallexample
+
+This command will print, for each directory in the archive, the list
+of files in that directory at the time the archive was created. This
+information is put out in a format which is both human-readable and
+unambiguous for a program: each file name is printed as
+
+@smallexample
+@var{x} @var{file}
+@end smallexample
+
+@noindent
+where @var{x} is a letter describing the status of the file: @samp{Y}
+if the file is present in the archive, @samp{N} if the file is not
+included in the archive, or a @samp{D} if the file is a directory (and
+is included in the archive). @xref{Dumpdir}, for the detailed
+description of dumpdirs and status codes. Each such
+line is terminated by a newline character. The last line is followed
+by an additional newline to indicate the end of the data.
+
+@anchor{incremental-op}The option @option{--incremental} (@option{-G})
+gives the same behavior as @option{--listed-incremental} when used
+with @option{--list} and @option{--extract} options. When used with
+@option{--create} option, it creates an incremental archive without
+creating snapshot file. Thus, it is impossible to create several
+levels of incremental backups with @option{--incremental} option.
+
+@node Backup Levels
+@section Levels of Backups
+
+An archive containing all the files in the file system is called a
+@dfn{full backup} or @dfn{full dump}. You could insure your data by
+creating a full dump every day. This strategy, however, would waste a
+substantial amount of archive media and user time, as unchanged files
+are daily re-archived.
+
+It is more efficient to do a full dump only occasionally. To back up
+files between full dumps, you can use @dfn{incremental dumps}. A @dfn{level
+one} dump archives all the files that have changed since the last full
+dump.
+
+A typical dump strategy would be to perform a full dump once a week,
+and a level one dump once a day. This means some versions of files
+will in fact be archived more than once, but this dump strategy makes
+it possible to restore a file system to within one day of accuracy by
+only extracting two archives---the last weekly (full) dump and the
+last daily (level one) dump. The only information lost would be in
+files changed or created since the last daily backup. (Doing dumps
+more than once a day is usually not worth the trouble).
+
+@GNUTAR{} comes with scripts you can use to do full
+and level-one (actually, even level-two and so on) dumps. Using
+scripts (shell programs) to perform backups and restoration is a
+convenient and reliable alternative to typing out file name lists
+and @command{tar} commands by hand.
+
+Before you use these scripts, you need to edit the file
+@file{backup-specs}, which specifies parameters used by the backup
+scripts and by the restore script. This file is usually located
+in @file{/etc/backup} directory. @xref{Backup Parameters}, for its
+detailed description. Once the backup parameters are set, you can
+perform backups or restoration by running the appropriate script.
+
+The name of the backup script is @code{backup}. The name of the
+restore script is @code{restore}. The following sections describe
+their use in detail.
+
+@emph{Please Note:} The backup and restoration scripts are
+designed to be used together. While it is possible to restore files by
+hand from an archive which was created using a backup script, and to create
+an archive by hand which could then be extracted using the restore script,
+it is easier to use the scripts. @xref{Incremental Dumps}, before
+making such an attempt.
+
+@node Backup Parameters
+@section Setting Parameters for Backups and Restoration
+
+The file @file{backup-specs} specifies backup parameters for the
+backup and restoration scripts provided with @command{tar}. You must
+edit @file{backup-specs} to fit your system configuration and schedule
+before using these scripts.
+
+Syntactically, @file{backup-specs} is a shell script, containing
+mainly variable assignments. However, any valid shell construct
+is allowed in this file. Particularly, you may wish to define
+functions within that script (e.g., see @code{RESTORE_BEGIN} below).
+For more information about shell script syntax, please refer to
+@url{http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
+g_02, the definition of the Shell Command Language}. See also
+@ref{Top,,Bash Features,bashref,Bash Reference Manual}.
+
+The shell variables controlling behavior of @code{backup} and
+@code{restore} are described in the following subsections.
+
+@menu
+* General-Purpose Variables::
+* Magnetic Tape Control::
+* User Hooks::
+* backup-specs example:: An Example Text of @file{Backup-specs}
+@end menu
+
+@node General-Purpose Variables
+@subsection General-Purpose Variables
+
+@defvr {Backup variable} ADMINISTRATOR
+The user name of the backup administrator. @code{Backup} scripts
+sends a backup report to this address.
+@end defvr
+
+@defvr {Backup variable} BACKUP_HOUR
+The hour at which the backups are done. This can be a number from 0
+to 23, or the time specification in form @var{hours}:@var{minutes},
+or the string @samp{now}.
+
+This variable is used by @code{backup}. Its value may be overridden
+using @option{--time} option (@pxref{Scripted Backups}).
+@end defvr
+
+@defvr {Backup variable} TAPE_FILE
+
+The device @command{tar} writes the archive to. If @var{TAPE_FILE}
+is a remote archive (@pxref{remote-dev}), backup script will suppose
+that your @command{mt} is able to access remote devices. If @var{RSH}
+(@pxref{RSH}) is set, @option{--rsh-command} option will be added to
+invocations of @command{mt}.
+@end defvr
+
+@defvr {Backup variable} BLOCKING
+
+The blocking factor @command{tar} will use when writing the dump archive.
+@xref{Blocking Factor}.
+@end defvr
+
+@defvr {Backup variable} BACKUP_DIRS
+
+A list of file systems to be dumped (for @code{backup}), or restored
+(for @code{restore}). You can include any directory
+name in the list --- subdirectories on that file system will be
+included, regardless of how they may look to other networked machines.
+Subdirectories on other file systems will be ignored.
+
+The host name specifies which host to run @command{tar} on, and should
+normally be the host that actually contains the file system. However,
+the host machine must have @GNUTAR{} installed, and
+must be able to access the directory containing the backup scripts and
+their support files using the same file name that is used on the
+machine where the scripts are run (i.e., 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
+
+The name of the file that contains a list of file systems to backup
+or restore. By default it is @file{/etc/backup/dirs}.
+@end defvr
+
+@defvr {Backup variable} BACKUP_FILES
+
+A list of individual files to be dumped (for @code{backup}), or restored
+(for @code{restore}). These should be accessible from the machine on
+which the backup script is run.
+
+If the list of file systems is very long you may wish to store it
+in a separate file. This file is usually named
+@file{/etc/backup/files}, but this name may be overridden in
+@file{backup-specs} using @code{FILELIST} variable.
+@end defvr
+
+@defvr {Backup variable} FILELIST
+
+The name of the file that contains a list of 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 machines. This will
+be passed via @option{--rsh-command} option to the remote invocation
+of @GNUTAR{}.
+@end defvr
+
+@defvr {Backup variable} VOLNO_FILE
+
+Name of temporary file to hold volume numbers. This needs to be accessible
+by all the machines which have file systems to be dumped.
+@end defvr
+
+@defvr {Backup variable} XLIST
+
+Name of @dfn{exclude file list}. An @dfn{exclude file list} is a file
+located on the remote machine and containing the list of files to
+be excluded from the backup. Exclude file lists are searched in
+/etc/tar-backup directory. A common use for exclude file lists
+is to exclude files containing security-sensitive information
+(e.g., @file{/etc/shadow} from backups).
+
+This variable affects only @code{backup}.
+@end defvr
+
+@defvr {Backup variable} SLEEP_TIME
+
+Time to sleep between dumps of any two successive file systems
+
+This variable affects only @code{backup}.
+@end defvr
+
+@defvr {Backup variable} DUMP_REMIND_SCRIPT
+
+Script to be run when it's time to insert a new tape in for the next
+volume. Administrators may want to tailor this script for their site.
+If this variable isn't set, @GNUTAR{} will display its built-in
+prompt, and will expect confirmation from the console. For the
+description of the default prompt, see @ref{change volume prompt}.
+
+@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 file name of the file system being dumped or restored.
+
+@item fsname
+File system name with directory separators replaced with colons. This
+is useful, e.g., for creating unique files.
+@end table
+@end deffn
+
+Following variables keep the names of user hook functions
+
+@defvr {Backup variable} DUMP_BEGIN
+Dump begin function. It is executed before dumping the file system.
+@end defvr
+
+@defvr {Backup variable} DUMP_END
+Executed after dumping the file system.
+@end defvr
+
+@defvr {Backup variable} RESTORE_BEGIN
+Executed before restoring the file system.
+@end defvr
+
+@defvr {Backup variable} RESTORE_END
+Executed after restoring the file system.
+@end defvr
+
+@node backup-specs example
+@subsection An Example Text of @file{Backup-specs}
+
+The following is an example of @file{backup-specs}:
+
+@smallexample
+# site-specific parameters for file system backup.
+
+ADMINISTRATOR=friedman
+BACKUP_HOUR=1
+TAPE_FILE=/dev/nrsmt0
+
+# Use @code{ssh} instead of the less secure @code{rsh}
+RSH=/usr/bin/ssh
+RSH_COMMAND=/usr/bin/ssh
+
+# Override MT_STATUS function:
+my_status() @{
+ mts -t $TAPE_FILE
+@}
+MT_STATUS=my_status
+
+# Disable MT_OFFLINE function
+MT_OFFLINE=:
+
+BLOCKING=124
+BACKUP_DIRS="
+ albert:/fs/fsf
+ apple-gunkies:/gd
+ albert:/fs/gd2
+ albert:/fs/gp
+ geech:/usr/jla
+ churchy:/usr/roland
+ albert:/
+ albert:/usr
+ apple-gunkies:/
+ apple-gunkies:/usr
+ gnu:/hack
+ gnu:/u
+ apple-gunkies:/com/mailer/gnu
+ apple-gunkies:/com/archive/gnu"
+
+BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
+
+@end smallexample
+
+@node Scripted Backups
+@section Using the Backup Scripts
+
+The syntax for running a backup script is:
+
+@smallexample
+backup --level=@var{level} --time=@var{time}
+@end smallexample
+
+The @option{level} option requests the dump level. Thus, to produce
+a full dump, specify @code{--level=0} (this is the default, so
+@option{--level} may be omitted if its value is @code{0}).
+@footnote{For backward compatibility, the @code{backup} will also
+try to deduce the requested dump level from the name of the
+script itself. If the name consists of a string @samp{level-}
+followed by a single decimal digit, that digit is taken as
+the dump level number. Thus, you may create a link from @code{backup}
+to @code{level-1} and then run @code{level-1} whenever you need to
+create a level one dump.}
+
+The @option{--time} option determines when should the backup be
+run. @var{Time} may take three forms:
+
+@table @asis
+@item @var{hh}:@var{mm}
+
+The dump must be run at @var{hh} hours @var{mm} minutes.
+
+@item @var{hh}
+
+The dump must be run at @var{hh} hours
+
+@item now
+
+The dump must be run immediately.
+@end table
+
+You should start a script with a tape or disk mounted. Once you
+start a script, it prompts you for new tapes or disks as it
+needs them. Media volumes don't have to correspond to archive
+files --- a multi-volume archive can be started in the middle of a
+tape that already contains the end of another multi-volume archive.
+The @code{restore} script prompts for media by its archive volume,
+so to avoid an error message you should keep track of which tape
+(or disk) contains which volume of the archive (@pxref{Scripted
+Restoration}).
+
+The backup scripts write two files on the file system. The first is a
+record file in @file{/etc/tar-backup/}, which is used by the scripts
+to store and retrieve information about which files were dumped. This
+file is not meant to be read by humans, and should not be deleted by
+them. @xref{Snapshot Files}, for a more detailed explanation of this
+file.
+
+The second file is a log file containing the names of the file systems
+and files dumped, what time the backup was made, and any error
+messages that were generated, as well as how much space was left in
+the media volume after the last volume of the archive was written.
+You should check this log file after every backup. The file name is
+@file{log-@var{mm-dd-yyyy}-level-@var{n}}, where @var{mm-dd-yyyy}
+represents current date, and @var{n} represents current dump level number.
+
+The script also prints the name of each system being dumped to the
+standard output.
+
+Following is the full list of options accepted by @code{backup}
+script:
+
+@table @option
+@item -l @var{level}
+@itemx --level=@var{level}
+Do backup level @var{level} (default 0).
+
+@item -f
+@itemx --force
+Force backup even if today's log file already exists.
+
+@item -v[@var{level}]
+@itemx --verbose[=@var{level}]
+Set verbosity level. The higher the level is, the more debugging
+information will be output during execution. Default @var{level}
+is 100, which means the highest debugging level.
+
+@item -t @var{start-time}
+@itemx --time=@var{start-time}
+Wait till @var{time}, then do backup.
+
+@item -h
+@itemx --help
+Display short help message and exit.
+
+@item -V
+@itemx --version
+Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
+@end table
+
+
+@node Scripted Restoration
+@section Using the Restore Script
+
+To restore files that were archived using a scripted backup, use the
+@code{restore} script. Its usage is quite straightforward. In the
+simplest form, invoke @code{restore --all}, it will
+then restore all the file systems and files specified in
+@file{backup-specs} (@pxref{General-Purpose Variables,BACKUP_DIRS}).
+
+You may select the file systems (and/or files) to restore by
+giving @code{restore} list of @dfn{patterns} in its command
+line. For example, running
+
+@smallexample
+restore 'albert:*'
+@end smallexample
+
+@noindent
+will restore all file systems on the machine @samp{albert}. A more
+complicated example:
+
+@smallexample
+restore 'albert:*' '*:/var'
+@end smallexample
+
+@noindent
+This command will restore all file systems on the machine @samp{albert}
+as well as @file{/var} file system on all machines.
+
+By default @code{restore} will start restoring files from the lowest
+available dump level (usually zero) and will continue through
+all available dump levels. There may be situations where such a
+thorough restore is not necessary. For example, you may wish to
+restore only files from the recent level one backup. To do so,
+use @option{--level} option, as shown in the example below:
+
+@smallexample
+restore --level=1
+@end smallexample
+
+The full list of options accepted by @code{restore} follows:
+
+@table @option
+@item -a
+@itemx --all
+Restore all file systems and files specified in @file{backup-specs}
+
+@item -l @var{level}
+@itemx --level=@var{level}
+Start restoring from the given backup level, instead of the default 0.
+
+@item -v[@var{level}]
+@itemx --verbose[=@var{level}]
+Set verbosity level. The higher the level is, the more debugging
+information will be output during execution. Default @var{level}
+is 100, which means the highest debugging level.
+
+@item -h
+@itemx --help
+Display short help message and exit.
+
+@item -V
+@itemx --version
+Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
+@end table
+
+You should start the restore script with the media containing the
+first volume of the archive mounted. The script will prompt for other
+volumes as they are needed. If the archive is on tape, you don't need
+to rewind the tape to to its beginning---if the tape head is
+positioned past the beginning of the archive, the script will rewind
+the tape as needed. @xref{Tape Positioning}, for a discussion of tape
+positioning.
+
+@quotation
+@strong{Warning:} The script will delete files from the active file
+system if they were not in the file system when the archive was made.
+@end quotation
+
+@xref{Incremental Dumps}, for an explanation of how the script makes
+that determination.
+
+@node Choosing
+@chapter Choosing Files and Names for @command{tar}
+@UNREVISED
+
+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.
+
+This chapter discusses these options in detail.
+
+@menu
+* file:: Choosing the Archive's Name
+* Selecting Archive Members::
+* files:: Reading Names from a File
+* exclude:: Excluding Some Files
+* wildcards:: Wildcards Patterns and Matching
+* quoting styles:: Ways of Quoting Special Characters in Names
+* transform:: Modifying File and Member Names
+* after:: Operating Only on New Files
+* recurse:: Descending into Directories
+* one:: Crossing File System Boundaries
+@end menu
+
+@node file
+@section Choosing and Naming Archive Files
+@UNREVISED
+
+@cindex Naming an archive
+@cindex Archive Name
+@cindex Choosing an archive file
+@cindex Where is the 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 have 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
+@option{--file=@var{archive-name}} (@option{-f @var{archive-name}})
+option allows you to either specify or name a file to use as the archive
+instead of the default archive file location.
+
+@table @option
+@xopindex{file, short description}
+@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 (i.e., @file{/dev/tu00}).
+
+@cindex Standard input and output
+@cindex tar to standard input and output
+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.
+
+The following example is a convenient way of copying directory
+hierarchy from @file{sourcedir} to @file{targetdir}.
+
+@smallexample
+$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)}
+@end smallexample
+
+The @option{-C} option allows to avoid using subshells:
+
+@smallexample
+$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xpf -}
+@end smallexample
+
+In both examples above, the leftmost @command{tar} invocation archives
+the contents of @file{sourcedir} to the standard output, while the
+rightmost one reads this archive from its standard input and
+extracts it. The @option{-p} option tells it to restore permissions
+of the extracted files.
+
+@cindex Remote devices
+@cindex tar to a remote device
+@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.
+
+@cindex Local and remote archives
+@anchor{local and remote archives}
+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 @option{--force-local} option.
+
+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{-}), precede it with
+@option{--add-file} option to prevent it from being treated as an
+option.
+
+@anchor{input name quoting}
+By default @GNUTAR{} attempts to @dfn{unquote} each file or member
+name, replacing @dfn{escape sequences} according to the following
+table:
+
+@multitable @columnfractions 0.20 0.60
+@headitem Escape @tab Replaced with
+@item \a @tab Audible bell (@acronym{ASCII} 7)
+@item \b @tab Backspace (@acronym{ASCII} 8)
+@item \f @tab Form feed (@acronym{ASCII} 12)
+@item \n @tab New line (@acronym{ASCII} 10)
+@item \r @tab Carriage return (@acronym{ASCII} 13)
+@item \t @tab Horizontal tabulation (@acronym{ASCII} 9)
+@item \v @tab Vertical tabulation (@acronym{ASCII} 11)
+@item \? @tab @acronym{ASCII} 127
+@item \@var{n} @tab @acronym{ASCII} @var{n} (@var{n} should be an octal number
+ of up to 3 digits)
+@end multitable
+
+A backslash followed by any other symbol is retained.
+
+This default behavior is controlled by the following command line
+option:
+
+@table @option
+@opindex unquote
+@item --unquote
+Enable unquoting input file or member names (default).
+
+@opindex no-unquote
+@item --no-unquote
+Disable unquoting input file or member names.
+@end table
+
+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, @command{tar} behavior differs depending
+on the operation mode as described below:
+
+When @command{tar} is invoked with @option{--create} (@option{-c}),
+@command{tar} will stop immediately, reporting the following:
+
+@smallexample
+@group
+$ @kbd{tar cf a.tar}
+tar: Cowardly refusing to create an empty archive
+Try `tar --help' or `tar --usage' for more information.
+@end group
+@end smallexample
+
+If you specify either @option{--list} (@option{-t}) or
+@option{--extract} (@option{--get}, @option{-x}), @command{tar}
+operates on all the archive members in the archive.
+
+If run with @option{--diff} option, tar will compare the archive with
+the contents of the current working directory.
+
+If you specify any other operation, @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. 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
+@option{--files-from=@var{file-of-names}} (@option{-T
+@var{file-of-names}}) 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 @option
+@opindex files-from
+@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.
+
+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
+@xopindex{directory, using in @option{--files-from} argument}
+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
+
+@opindex 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 @code{NUL} Terminated File Names
+
+@cindex File names, terminated by @code{NUL}
+@cindex @code{NUL} terminated file names
+The @option{--null} option causes
+@option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}})
+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 @option
+@opindex null
+@item --null
+Only consider @code{NUL} terminated file names, instead of files that
+terminate in a newline.
+@end table
+
+The @option{--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}, @option{--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 @code{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 @code{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
+@UNREVISED
+
+@cindex File names, excluding files by
+@cindex Excluding files by name and pattern
+@cindex Excluding files by file system
+To avoid operating on files whose names match a particular pattern,
+use the @option{--exclude} or @option{--exclude-from} options.
+
+@table @option
+@opindex exclude
+@item --exclude=@var{pattern}
+Causes @command{tar} to ignore files that match the @var{pattern}.
+@end table
+
+@findex exclude
+The @option{--exclude=@var{pattern}} 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 @option
+@opindex exclude-from
+@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} 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.
+
+Notice, that lines from @var{file} are read verbatim. One of the
+frequent errors is leaving some extra whitespace after a file name,
+which is difficult to catch using text editors.
+
+However, empty lines are OK.
+
+@cindex version control system, excluding files
+@cindex VCS, excluding files
+@cindex SCCS, excluding files
+@cindex RCS, excluding files
+@cindex CVS, excluding files
+@cindex SVN, excluding files
+@cindex git, excluding files
+@table @option
+@opindex exclude-vcs
+@item --exclude-vcs
+Exclude files and directories used by some version control systems.
+@end table
+
+As of version @value{VERSION}, the following files are excluded:
+
+@itemize @bullet
+@item @file{CVS/}, and everything under it
+@item @file{RCS/}, and everything under it
+@item @file{SCCS/}, and everything under it
+@item @file{.git/}, and everything under it
+@item @file{.gitignore}
+@item @file{.cvsignore}
+@item @file{.svn/}, and everything under it
+@item @file{.arch-ids/}, and everything under it
+@item @file{@{arch@}/}, and everything under it
+@item @file{=RELEASE-ID}
+@item @file{=meta-update}
+@item @file{=update}
+@end itemize
+
+@findex exclude-caches
+When creating an archive, the @option{--exclude-caches} option family
+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.
+
+There are three @samp{exclude-caches} options, each providing a different
+exclusion semantics:
+
+@table @option
+@opindex exclude-caches
+@item --exclude-caches
+Do not archive the contents of the directory, but archive the
+directory itself and the @file{CACHEDIR.TAG} file.
+
+@opindex exclude-caches-under
+@item --exclude-caches-under
+Do not archive the contents of the directory, nor the
+@file{CACHEDIR.TAG} file, archive only the directory itself.
+
+@opindex exclude-caches-all
+@item --exclude-caches-all
+Omit directories containing @file{CACHEDIR.TAG} file entirely.
+@end table
+
+@findex exclude-tag
+Another option family, @option{--exclude-tag}, provides a generalization of
+this concept. It takes a single argument, a file name to look for.
+Any directory that contains this file will be excluded from the dump.
+Similarly to @samp{exclude-caches}, there are three options in this
+option family:
+
+@table @option
+@opindex exclude-tag
+@item --exclude-tag=@var{file}
+Do not dump the contents of the directory, but dump the
+directory itself and the @var{file}.
+
+@opindex exclude-tag-under
+@item --exclude-tag-under=@var{file}
+Do not dump the contents of the directory, nor the
+@var{file}, archive only the directory itself.
+
+@opindex exclude-tag-all
+@item --exclude-tag-all=@var{file}
+Omit directories containing @var{file} file entirely.
+@end table
+
+Multiple @option{--exclude-tag*} options can be given.
+
+For example, given this directory:
+
+@smallexample
+@group
+$ @kbd{find dir}
+dir
+dir/blues
+dir/jazz
+dir/folk
+dir/folk/tagfile
+dir/folk/sanjuan
+dir/folk/trote
+@end group
+@end smallexample
+
+The @option{--exclude-tag} will produce the following:
+
+@smallexample
+$ @kbd{tar -cf archive.tar --exclude-tag=tagfile -v dir}
+dir/
+dir/blues
+dir/jazz
+dir/folk/
+tar: dir/folk/: contains a cache directory tag tagfile;
+ contents not dumped
+dir/folk/tagfile
+@end smallexample
+
+Both the @file{dir/folk} directory and its tagfile are preserved in
+the archive, however the rest of files in this directory are not.
+
+Now, using the @option{--exclude-tag-under} option will exclude
+@file{tagfile} from the dump, while still preserving the directory
+itself, as shown in this example:
+
+@smallexample
+$ @kbd{tar -cf archive.tar --exclude-tag-under=tagfile -v dir}
+dir/
+dir/blues
+dir/jazz
+dir/folk/
+./tar: dir/folk/: contains a cache directory tag tagfile;
+ contents not dumped
+@end smallexample
+
+Finally, using @option{--exclude-tag-all} omits the @file{dir/folk}
+directory entirely:
+
+@smallexample
+$ @kbd{tar -cf archive.tar --exclude-tag-all=tagfile -v dir}
+dir/
+dir/blues
+dir/jazz
+./tar: dir/folk/: contains a cache directory tag tagfile;
+ directory not dumped
+@end smallexample
+
+@menu
+* problems with exclude::
+@end menu
+
+@node problems with exclude
+@unnumberedsubsec Problems with Using the @code{exclude} Options
+
+@xopindex{exclude, potential problems with}
+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 file 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 @option{--exclude} and
+@option{--exclude-from}. Be careful: use @option{--exclude} when files
+to be excluded are given as a pattern on the command line. Use
+@option{--exclude-from} 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 @option{--exclude=@var{pattern}}, 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
+# @emph{Wrong!}
+$ @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
+@FIXME{The change in semantics must have occurred before 1.11,
+so I doubt if it is worth mentioning at all. Anyway, should at
+least specify in which version the semantics changed.}
+In earlier versions of @command{tar}, what is now the
+@option{--exclude-from} option was called @option{--exclude} instead.
+Now, @option{--exclude} applies to patterns listed on the command
+line and @option{--exclude-from} 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. @GNUTAR{} can use wildcard
+patterns for matching (or globbing) archive members when extracting
+from or listing an archive. 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: thus, excluding a directory also excludes all the files beneath it.
+
+@menu
+* controlling pattern-matching::
+@end menu
+
+@node controlling pattern-matching
+@unnumberedsubsec Controlling Pattern-Matching
+
+For the purposes of this section, we call @dfn{exclusion members} all
+member names obtained while processing @option{--exclude} and
+@option{--exclude-from} options, and @dfn{inclusion members} those
+member names that were given in the command line or read from the file
+specified with @option{--files-from} option.
+
+These two pairs of member lists are used in the following operations:
+@option{--diff}, @option{--extract}, @option{--list},
+@option{--update}.
+
+There are no inclusion members in create mode (@option{--create} and
+@option{--append}), since in this mode the names obtained from the
+command line refer to @emph{files}, not archive members.
+
+By default, inclusion members are compared with archive members
+literally @footnote{Notice that earlier @GNUTAR{} versions used
+globbing for inclusion members, which contradicted to UNIX98
+specification and was not documented. @xref{Changes}, for more
+information on this and other changes.} and exclusion members are
+treated as globbing patterns. For example:
+
+@smallexample
+@group
+$ @kbd{tar tf foo.tar}
+a.c
+b.c
+a.txt
+[remarks]
+# @i{Member names are used verbatim:}
+$ @kbd{tar -xf foo.tar -v '[remarks]'}
+[remarks]
+# @i{Exclude member names are globbed:}
+$ @kbd{tar -xf foo.tar -v --exclude '*.c'}
+a.txt
+[remarks]
+@end group
+@end smallexample
+
+This behavior can be altered by using the following options:
+
+@table @option
+@opindex wildcards
+@item --wildcards
+Treat all member names as wildcards.
+
+@opindex no-wildcards
+@item --no-wildcards
+Treat all member names as literal strings.
+@end table
+
+Thus, to extract files whose names end in @samp{.c}, you can use:
+
+@smallexample
+$ @kbd{tar -xf foo.tar -v --wildcards '*.c'}
+a.c
+b.c
+@end smallexample
+
+@noindent
+Notice quoting of the pattern to prevent the shell from interpreting
+it.
+
+The effect of @option{--wildcards} option is canceled by
+@option{--no-wildcards}. This can be used to pass part of
+the command line arguments verbatim and other part as globbing
+patterns. For example, the following invocation:
+
+@smallexample
+$ @kbd{tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'}
+@end smallexample
+
+@noindent
+instructs @command{tar} to extract from @file{foo.tar} all files whose
+names end in @samp{.txt} and the file named @file{[remarks]}.
+
+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
+
+@noindent
+ignores case when excluding @samp{makefile}, but not when excluding
+@samp{readme}.
+
+@table @option
+@opindex anchored
+@opindex no-anchored
+@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} for exclusion members
+and @option{--anchored} inclusion members.
+
+@opindex ignore-case
+@opindex no-ignore-case
+@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.
+
+@opindex wildcards-match-slash
+@opindex no-wildcards-match-slash
+@item --wildcards-match-slash
+@itemx --no-wildcards-match-slash
+When wildcards match slash (the default for exclusion members), 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 member patterns are interpreted. If
+recursion is in effect, a pattern matches a name if it matches any of
+the name's parent directories.
+
+The following table summarizes pattern-matching default values:
+
+@multitable @columnfractions .3 .7
+@headitem Members @tab Default settings
+@item Inclusion @tab @option{--no-wildcards --anchored --no-wildcards-match-slash}
+@item Exclusion @tab @option{--wildcards --no-anchored --wildcards-match-slash}
+@end multitable
+
+@node quoting styles
+@section Quoting Member Names
+
+When displaying member names, @command{tar} takes care to avoid
+ambiguities caused by certain characters. This is called @dfn{name
+quoting}. The characters in question are:
+
+@itemize @bullet
+@item Non-printable control characters:
+@anchor{escape sequences}
+@multitable @columnfractions 0.20 0.10 0.60
+@headitem Character @tab @acronym{ASCII} @tab Character name
+@item \a @tab 7 @tab Audible bell
+@item \b @tab 8 @tab Backspace
+@item \f @tab 12 @tab Form feed
+@item \n @tab 10 @tab New line
+@item \r @tab 13 @tab Carriage return
+@item \t @tab 9 @tab Horizontal tabulation
+@item \v @tab 11 @tab Vertical tabulation
+@end multitable
+
+@item Space (@acronym{ASCII} 32)
+
+@item Single and double quotes (@samp{'} and @samp{"})
+
+@item Backslash (@samp{\})
+@end itemize
+
+The exact way @command{tar} uses to quote these characters depends on
+the @dfn{quoting style}. The default quoting style, called
+@dfn{escape} (see below), uses backslash notation to represent control
+characters, space and backslash. Using this quoting style, control
+characters are represented as listed in column @samp{Character} in the
+above table, a space is printed as @samp{\ } and a backslash as @samp{\\}.
+
+@GNUTAR{} offers seven distinct quoting styles, which can be selected
+using @option{--quoting-style} option:
+
+@table @option
+@item --quoting-style=@var{style}
+@opindex quoting-style
+
+Sets quoting style. Valid values for @var{style} argument are:
+literal, shell, shell-always, c, escape, locale, clocale.
+@end table
+
+These styles are described in detail below. To illustrate their
+effect, we will use an imaginary tar archive @file{arch.tar}
+containing the following members:
+
+@smallexample
+@group
+# 1. Contains horizontal tabulation character.
+a tab
+# 2. Contains newline character
+a
+newline
+# 3. Contains a space
+a space
+# 4. Contains double quotes
+a"double"quote
+# 5. Contains single quotes
+a'single'quote
+# 6. Contains a backslash character:
+a\backslash
+@end group
+@end smallexample
+
+Here is how usual @command{ls} command would have listed them, if they
+had existed in the current working directory:
+
+@smallexample
+@group
+$ @kbd{ls}
+a\ttab
+a\nnewline
+a\ space
+a"double"quote
+a'single'quote
+a\\backslash
+@end group
+@end smallexample
+
+Quoting styles:
+
+@table @samp
+@item literal
+No quoting, display each character as is:
+
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=literal}
+./
+./a space
+./a'single'quote
+./a"double"quote
+./a\backslash
+./a tab
+./a
+newline
+@end group
+@end smallexample
+
+@item shell
+Display characters the same way Bourne shell does:
+control characters, except @samp{\t} and @samp{\n}, are printed using
+backslash escapes, @samp{\t} and @samp{\n} are printed as is, and a
+single quote is printed as @samp{\'}. If a name contains any quoted
+characters, it is enclosed in single quotes. In particular, if a name
+contains single quotes, it is printed as several single-quoted strings:
+
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=shell}
+./
+'./a space'
+'./a'\''single'\''quote'
+'./a"double"quote'
+'./a\backslash'
+'./a tab'
+'./a
+newline'
+@end group
+@end smallexample
+
+@item shell-always
+Same as @samp{shell}, but the names are always enclosed in single
+quotes:
+
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=shell-always}
+'./'
+'./a space'
+'./a'\''single'\''quote'
+'./a"double"quote'
+'./a\backslash'
+'./a tab'
+'./a
+newline'
+@end group
+@end smallexample
+
+@item c
+Use the notation of the C programming language. All names are
+enclosed in double quotes. Control characters are quoted using
+backslash notations, double quotes are represented as @samp{\"},
+backslash characters are represented as @samp{\\}. Single quotes and
+spaces are not quoted:
+
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=c}
+"./"
+"./a space"
+"./a'single'quote"
+"./a\"double\"quote"
+"./a\\backslash"
+"./a\ttab"
+"./a\nnewline"
+@end group
+@end smallexample
+
+@item escape
+Control characters are printed using backslash notation, a space is
+printed as @samp{\ } and a backslash as @samp{\\}. This is the
+default quoting style, unless it was changed when configured the
+package.
+
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=escape}
+./
+./a space
+./a'single'quote
+./a"double"quote
+./a\\backslash
+./a\ttab
+./a\nnewline
+@end group
+@end smallexample
+
+@item locale
+Control characters, single quote and backslash are printed using
+backslash notation. All names are quoted using left and right
+quotation marks, appropriate to the current locale. If it does not
+define quotation marks, use @samp{`} as left and @samp{'} as right
+quotation marks. Any occurrences of the right quotation mark in a
+name are escaped with @samp{\}, for example:
+
+For example:
+
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=locale}
+`./'
+`./a space'
+`./a\'single\'quote'
+`./a"double"quote'
+`./a\\backslash'
+`./a\ttab'
+`./a\nnewline'
+@end group
+@end smallexample
+
+@item clocale
+Same as @samp{locale}, but @samp{"} is used for both left and right
+quotation marks, if not provided by the currently selected locale:
+
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=clocale}
+"./"
+"./a space"
+"./a'single'quote"
+"./a\"double\"quote"
+"./a\\backslash"
+"./a\ttab"
+"./a\nnewline"
+@end group
+@end smallexample
+@end table
+
+You can specify which characters should be quoted in addition to those
+implied by the current quoting style:
+
+@table @option
+@item --quote-chars=@var{string}
+Always quote characters from @var{string}, even if the selected
+quoting style would not quote them.
+@end table
+
+For example, using @samp{escape} quoting (compare with the usual
+escape listing above):
+
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=escape --quote-chars=' "'}
+./
+./a\ space
+./a'single'quote
+./a\"double\"quote
+./a\\backslash
+./a\ttab
+./a\nnewline
+@end group
+@end smallexample
+
+To disable quoting of such additional characters, use the following
+option:
+
+@table @option
+@item --no-quote-chars=@var{string}
+Remove characters listed in @var{string} from the list of quoted
+characters set by the previous @option{--quote-chars} option.
+@end table
+
+This option is particularly useful if you have added
+@option{--quote-chars} to your @env{TAR_OPTIONS} (@pxref{TAR_OPTIONS})
+and wish to disable it for the current invocation.
+
+Note, that @option{--no-quote-chars} does @emph{not} disable those
+characters that are quoted by default in the selected quoting style.
+
+@node transform
+@section Modifying File and Member Names
+
+@command{Tar} archives contain detailed information about files stored
+in them and full file names are part of that information. When
+storing file to an archive, its file name is recorded in the archive
+along with the actual file contents. When restoring from an archive,
+a file is created on disk with exactly the same name as that stored
+in the archive. In the majority of cases this is the desired behavior
+of a file archiver. However, there are some cases when it is not.
+
+First of all, it is often unsafe to extract archive members with
+absolute file names or those that begin with a @file{../}. @GNUTAR{}
+takes special precautions when extracting such names and provides a
+special option for handling them, which is described in
+@ref{absolute}.
+
+Secondly, you may wish to extract file names without some leading
+directory components, or with otherwise modified names. In other
+cases it is desirable to store files under differing names in the
+archive.
+
+@GNUTAR{} provides two options for these needs.
+
+@table @option
+@opindex strip-components
+@item --strip-components=@var{number}
+Strip given @var{number} of leading components from file names before
+extraction.
+@end table
+
+For example, suppose you have archived whole @file{/usr} hierarchy to
+a tar archive named @file{usr.tar}. Among other files, this archive
+contains @file{usr/include/stdlib.h}, which you wish to extract to
+the current working directory. To do so, you type:
+
+@smallexample
+$ @kbd{tar -xf usr.tar --strip=2 usr/include/stdlib.h}
+@end smallexample
+
+The option @option{--strip=2} instructs @command{tar} to strip the
+two leading components (@file{usr/} and @file{include/}) off the file
+name.
+
+If you add to the above invocation @option{--verbose} (@option{-v})
+option, you will note that the verbose listing still contains the
+full file name, with the two removed components still in place. This
+can be inconvenient, so @command{tar} provides a special option for
+altering this behavior:
+
+@anchor{show-transformed-names}
+@table @option
+@opindex show-transformed-names
+@item --show-transformed-names
+Display file or member names with all requested transformations
+applied.
+@end table
+
+@noindent
+For example:
+
+@smallexample
+@group
+$ @kbd{tar -xf usr.tar -v --strip=2 usr/include/stdlib.h}
+usr/include/stdlib.h
+$ @kbd{tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h}
+stdlib.h
+@end group
+@end smallexample
+
+Notice that in both cases the file is @file{stdlib.h} extracted to the
+current working directory, @option{--show-transformed-names} affects
+only the way its name is displayed.
+
+This option is especially useful for verifying whether the invocation
+will have the desired effect. Thus, before running
+
+@smallexample
+$ @kbd{tar -x --strip=@var{n}}
+@end smallexample
+
+@noindent
+it is often advisable to run
+
+@smallexample
+$ @kbd{tar -t -v --show-transformed --strip=@var{n}}
+@end smallexample
+
+@noindent
+to make sure the command will produce the intended results.
+
+In case you need to apply more complex modifications to the file name,
+@GNUTAR{} provides a general-purpose transformation option:
+
+@table @option
+@opindex transform
+@item --transform=@var{expression}
+Modify file names using supplied @var{expression}.
+@end table
+
+@noindent
+The @var{expression} is a @command{sed}-like replace expression of the
+form:
+
+@smallexample
+s/@var{regexp}/@var{replace}/[@var{flags}]
+@end smallexample
+
+@noindent
+where @var{regexp} is a @dfn{regular expression}, @var{replace} is a
+replacement for each file name part that matches @var{regexp}. Both
+@var{regexp} and @var{replace} are described in detail in
+@ref{The "s" Command, The "s" Command, The `s' Command, sed, GNU sed}.
+
+Supported @var{flags} are:
+
+@table @samp
+@item g
+Apply the replacement to @emph{all} matches to the @var{regexp}, not
+just the first.
+
+@item i
+Use case-insensitive matching
+
+@item x
+@var{regexp} is an @dfn{extended regular expression} (@pxref{Extended
+regexps, Extended regular expressions, Extended regular expressions,
+sed, GNU sed}).
+
+@item @var{number}
+Only replace the @var{number}th match of the @var{regexp}.
+
+Note: the @var{posix} standard does not specify what should happen
+when you mix the @samp{g} and @var{number} modifiers. @GNUTAR{}
+follows the GNU @command{sed} implementation in this regard, so
+the interaction is defined to be: ignore matches before the
+@var{number}th, and then match and replace all matches from the
+@var{number}th on.
+
+@end table
+
+Any delimiter can be used in lieue of @samp{/}, the only requirement being
+that it be used consistently throughout the expression. For example,
+the following two expressions are equivalent:
+
+@smallexample
+@group
+s/one/two/
+s,one,two,
+@end group
+@end smallexample
+
+Changing delimiters is often useful when the @var{regex} contains
+slashes. For example, it is more convenient to write @code{s,/,-,} than
+@code{s/\//-/}.
+
+Here are several examples of @option{--transform} usage:
+
+@enumerate
+@item Extract @file{usr/} hierarchy into @file{usr/local/}:
+
+@smallexample
+$ @kbd{tar --transform='s,usr/,usr/local/,' -x -f arch.tar}
+@end smallexample
+
+@item Strip two leading directory components (equivalent to
+@option{--strip-components=2}):
+
+@smallexample
+$ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar}
+@end smallexample
+
+@item Prepend @file{/prefix/} to each file name:
+
+@smallexample
+$ @kbd{tar --transform 's,^,/prefix/,' -x -f arch.tar}
+@end smallexample
+
+@item Convert each file name to lower case:
+
+@smallexample
+$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar}
+@end smallexample
+
+@end enumerate
+
+Unlike @option{--strip-components}, @option{--transform} can be used
+in any @GNUTAR{} operation mode. For example, the following command
+adds files to the archive while replacing the leading @file{usr/}
+component with @file{var/}:
+
+@smallexample
+$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' /}
+@end smallexample
+
+To test @option{--transform} effect we suggest using
+@option{--show-transformed-names} option:
+
+@smallexample
+$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' \
+ --verbose --show-transformed-names /}
+@end smallexample
+
+If both @option{--strip-components} and @option{--transform} are used
+together, then @option{--transform} is applied first, and the required
+number of components is then stripped from its result.
+
+@node after
+@section Operating Only on New Files
+@UNREVISED
+
+@cindex Excluding file by age
+@cindex Data Modification time, excluding files by
+@cindex Modification time, excluding files by
+@cindex Age, excluding files by
+The @option{--after-date=@var{date}} (@option{--newer=@var{date}},
+@option{-N @var{date}}) option causes @command{tar} to only work on
+files whose data modification or status change 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 data modification 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 file's data (rather than status
+changes), then use the @option{--newer-mtime=@var{date}} option.
+
+You may use these options with any operation. Note that these options
+differ from the @option{--update} (@option{-u}) 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 @option
+@opindex after-date
+@opindex newer
+@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 data modification or status change 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 data modification time of that file is used as the date.
+
+@opindex newer-mtime
+@item --newer-mtime=@var{date}
+Acts like @option{--after-date}, but only looks at data modification times.
+@end table
+
+These options limit @command{tar} to operate only on files which have
+been modified after the date specified. A file's status is considered to have
+changed if its contents have been modified, or if its 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 @option{--after-date} tests both the data
+modification time (@code{mtime}, the time the contents of the file
+were last modified) and the status change time (@code{ctime}, the time
+the file's status was last changed: owner, permissions, etc.@:)
+fields, while @option{--newer-mtime} tests only the @code{mtime}
+field.
+
+To be precise, @option{--after-date} checks @emph{both} @code{mtime} and
+@code{ctime} and processes the file if either one is more recent than
+@var{date}, while @option{--newer-mtime} only checks @code{mtime} and
+disregards @code{ctime}. Neither does it use @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. For example, the following command will add to the archive
+all the files modified less than two days ago:
+
+@smallexample
+$ @kbd{tar -cf foo.tar --newer-mtime '2 days ago'}
+@end smallexample
+
+When any of these options is used with the option @option{--verbose}
+(@pxref{verbose tutorial}) @GNUTAR{} will try to convert the specified
+date back to its textual representation and compare that with the
+one given with the option. If the two dates differ, @command{tar} will
+print a warning saying what date it will use. This is to help user
+ensure he is using the right date. For example:
+
+@smallexample
+@group
+$ @kbd{tar -c -f archive.tar --after-date='10 days ago' .}
+tar: Option --after-date: Treating date `10 days ago' as 2006-06-11
+13:19:37.232434
+@end group
+@end smallexample
+
+@quotation
+@strong{Please Note:} @option{--after-date} and @option{--newer-mtime}
+should not be used for incremental backups. @xref{Incremental Dumps},
+for proper way of creating incremental backups.
+@end quotation
+
+@node recurse
+@section Descending into Directories
+@UNREVISED
+@cindex Avoiding recursion in directories
+@cindex Descending directories, avoiding
+@cindex Directories, avoiding recursion
+@cindex Recursion in directories, avoiding
+
+@FIXME{arrggh! this is still somewhat confusing to me. :-< }
+
+Usually, @command{tar} will recursively explore all directories (either
+those given on the command line or through the @option{--files-from}
+option) for the various files they contain. However, you may not always
+want @command{tar} to act this way.
+
+@opindex no-recursion
+The @option{--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 @option
+@item --no-recursion
+Prevents @command{tar} from recursively descending directories.
+
+@opindex recursion
+@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{-not -type d}}
+test in their @command{find} invocation (@pxref{Type, Type, Type test,
+find, Finding Files}), as they usually do not want all the files in a
+directory. They then use the @option{--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
+@option{--same-permissions} (@option{--preserve-permissions},
+@option{-p}) option does not affect them---while users might really
+like it to. Specifying @option{--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. To summarize, if you use @command{find} to
+create a list of files to be stored in an archive, use it as follows:
+
+@smallexample
+@group
+$ @kbd{find @var{dir} @var{tests} | \
+ tar -cf @var{archive} -T - --no-recursion}
+@end group
+@end smallexample
+
+The @option{--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 @option{--no-recursion} option also affects how globbing patterns
+are interpreted (@pxref{controlling pattern-matching}).
+
+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 --no-recursion 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 File System 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
+@option{--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 @option{--files-from}, regardless of where they reside.
+
+@table @option
+@opindex one-file-system
+@item --one-file-system
+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 file system 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.
+
+This option is useful for making full or incremental archival backups of
+a file system. If this option is used in conjunction with
+@option{--verbose} (@option{-v}), 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
+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
+@option{--files-from} (@option{-T}), use @option{--directory} (@option{-C}).
+This will change the working directory to the specified directory
+after that point in the list.
+
+@table @option
+@opindex directory
+@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
+--directory=/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
+
+The interpretation of @option{--directory} is disabled by
+@option{--null} option.
+
+@node absolute
+@subsection Absolute File Names
+@UNREVISED
+
+@table @option
+@opindex absolute-names
+@item --absolute-names
+@itemx -P
+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}.@footnote{A side effect of this is that when
+@option{--create} is used with @option{--verbose} the resulting output
+is not, generally speaking, the same as the one you'd get running
+@kbd{tar --list} command. This may be important if you use some
+scripts for comparing both outputs. @xref{listing member and file names},
+for the information on how to handle this case.}
+
+If you use the @option{--absolute-names} (@option{-P}) option,
+@command{tar} will do none of these transformations.
+
+To archive or extract files relative to the root directory, specify
+the @option{--absolute-names} (@option{-P}) 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 @option{--absolute-names} (@option{-P}),
+@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
+@option{--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 @option
+@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)}
+# @i{or}:
+$ @kbd{tar -c -f archive.tar -C / home}
+@end smallexample
+
+@include getdate.texi
+
+@node Formats
+@chapter Controlling the Archive Format
+
+@cindex Tar archive formats
+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 file names 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 @acronym{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 file names 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 file name can be split at a 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 accommodate
+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 file name 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
+@headitem Format @tab UID @tab File Size @tab File 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
+* Compression:: Using Less Space through Compression
+* Attributes:: Handling File Attributes
+* Portability:: Making @command{tar} Archives More Portable
+* cpio:: Comparison of @command{tar} and @command{cpio}
+@end menu
+
+@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}, @command{bzip2} and @command{lzma} compression
+programs. For backward compatibility, it also supports
+@command{compress} command, although we strongly recommend against
+using it, because it is by far less effective than other compression
+programs@footnote{It also had patent problems in the past.}.
+
+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,
+@command{lzma} to create an @asis{LZMA} compressed archive and
+@option{-Z} (@option{--compress}) to use @command{compress} program.
+For example:
+
+@smallexample
+$ @kbd{tar cfz archive.tar.gz .}
+@end smallexample
+
+You can also let @GNUTAR{} select the compression program basing on
+the suffix of the archive file name. This is done using
+@option{--auto-compress} (@option{-a}) command line option. For
+example, the following invocation will use @command{bzip2} for
+compression:
+
+@smallexample
+$ @kbd{tar cfa archive.tar.bz2 .}
+@end smallexample
+
+@noindent
+whereas the following one will use @command{lzma}:
+
+@smallexample
+$ @kbd{tar cfa archive.tar.lzma .}
+@end smallexample
+
+For a complete list of file name suffixes recognized by @GNUTAR{},
+@ref{auto-compress}.
+
+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 (@option{--update} (@option{-u})) them or delete
+(@option{--delete}) members from them. Likewise, you cannot append
+another @command{tar} archive to a compressed archive using
+@option{--append} (@option{-r})). Secondly, multi-volume archives cannot be
+compressed.
+
+The following table summarizes compression options used by @GNUTAR{}.
+
+@table @option
+@anchor{auto-compress}
+@opindex auto-compress
+@item --auto-compress
+@itemx -a
+Select a compression program to use by the archive file name
+suffix. The following suffixes are recognized:
+
+@multitable @columnfractions 0.3 0.6
+@headitem Suffix @tab Compression program
+@item @samp{.gz} @tab @command{gzip}
+@item @samp{.tgz} @tab @command{gzip}
+@item @samp{.taz} @tab @command{gzip}
+@item @samp{.Z} @tab @command{compress}
+@item @samp{.taZ} @tab @command{compress}
+@item @samp{.bz2} @tab @command{bzip2}
+@item @samp{.tz2} @tab @command{bzip2}
+@item @samp{.tbz2} @tab @command{bzip2}
+@item @samp{.tbz} @tab @command{bzip2}
+@item @samp{.lzma} @tab @command{lzma}
+@item @samp{.tlz} @tab @command{lzma}
+@end multitable
+
+@opindex gzip
+@opindex ungzip
+@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 @option{--gzip} (@option{--gunzip}, @option{--ungzip}, @option{-z}) 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!
+
+@opindex bzip2
+@item -j
+@itemx --bzip2
+Filter the archive through @code{bzip2}. Otherwise like @option{--gzip}.
+
+@opindex lzma
+@item --lzma
+Filter the archive through @command{lzma}. Otherwise like @option{--gzip}.
+
+@opindex compress
+@opindex uncompress
+@item -Z
+@itemx --compress
+@itemx --uncompress
+Filter the archive through @command{compress}. Otherwise like @option{--gzip}.
+
+@opindex use-compress-program
+@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
+
+@cindex gpg, using with tar
+@cindex gnupg, using with tar
+@cindex Using encrypted archives
+The @option{--use-compress-program} option, in particular, lets you
+implement your own filters, not necessarily dealing with
+compression/decompression. For example, suppose you wish to implement
+PGP encryption on top of compression, using @command{gpg} (@pxref{Top,
+gpg, gpg ---- encryption and signing tool, gpg, GNU Privacy Guard
+Manual}). The following script does that:
+
+@smallexample
+@group
+#! /bin/sh
+case $1 in
+-d) gpg --decrypt - | gzip -d -c;;
+'') gzip -c | gpg -s ;;
+*) echo "Unknown option $1">&2; exit 1;;
+esac
+@end group
+@end smallexample
+
+Suppose you name it @file{gpgz} and save it somewhere in your
+@env{PATH}. Then the following command will create a compressed
+archive signed with your private key:
+
+@smallexample
+$ @kbd{tar -cf foo.tar.gpgz --use-compress=gpgz .}
+@end smallexample
+
+@noindent
+Likewise, the following command will list its contents:
+
+@smallexample
+$ @kbd{tar -tf foo.tar.gpgz --use-compress=gpgz .}
+@end smallexample
+
+@ignore
+The above is based on the following discussion:
+
+ 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 @option{--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
+ @option{--use-compress-prog=@var{program}} 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
+ @option{--gzip} or @option{--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.
+@end ignore
+
+@node sparse
+@subsection Archiving Sparse Files
+@cindex Sparse Files
+
+Files in the file system occasionally have @dfn{holes}. A @dfn{hole}
+in a file is a section of the file's contents which was never written.
+The contents of a hole reads 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 @option{--sparse}
+(@option{-S}). When you use this 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 @option{--sparse} is not needed on extraction) any
+such files have holes created wherever the continuous stretches of zeros
+were found. Thus, if you use @option{--sparse}, @command{tar} archives
+won't take more space than the original.
+
+@table @option
+@opindex sparse
+@item -S
+@itemx --sparse
+This option instructs @command{tar} to test each file for sparseness
+before attempting to archive it. If the file is found to be sparse it
+is treated specially, thus allowing to decrease the amount of space
+used by its image in the archive.
+
+This option is meaningful only when creating or updating archives. It
+has no effect on extraction.
+@end table
+
+Consider using @option{--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 @option{--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). @xref{Incremental Dumps}.
+
+However, be aware that @option{--sparse} option presents a serious
+drawback. Namely, in order to determine if the file is sparse
+@command{tar} has to read it before trying to archive it, so in total
+the file is read @strong{twice}. So, always bear in mind that the
+time needed to process all files with this option is roughly twice
+the time needed to archive them without it.
+@FIXME{A technical note:
+
+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
+}
+
+@cindex sparse formats, defined
+When using @samp{POSIX} archive format, @GNUTAR{} is able to store
+sparse files using in three distinct ways, called @dfn{sparse
+formats}. A sparse format is identified by its @dfn{number},
+consisting, as usual of two decimal numbers, delimited by a dot. By
+default, format @samp{1.0} is used. If, for some reason, you wish to
+use an earlier format, you can select it using
+@option{--sparse-version} option.
+
+@table @option
+@opindex sparse-version
+@item --sparse-version=@var{version}
+
+Select the format to store sparse files in. Valid @var{version} values
+are: @samp{0.0}, @samp{0.1} and @samp{1.0}. @xref{Sparse Formats},
+for a detailed description of each format.
+@end table
+
+Using @option{--sparse-format} option implies @option{--sparse}.
+
+@node Attributes
+@section Handling File Attributes
+@UNREVISED
+
+When @command{tar} reads files, it updates their access times. To
+avoid this, use the @option{--atime-preserve[=METHOD]} option, which can either
+reset the access time retroactively or avoid changing it in the first
+place.
+
+Handling of file attributes
+
+@table @option
+@opindex atime-preserve
+@item --atime-preserve
+@itemx --atime-preserve=replace
+@itemx --atime-preserve=system
+Preserve the access times of files that are read. This works only for
+files that you own, unless you have superuser privileges.
+
+@option{--atime-preserve=replace} works on most systems, but it also
+restores the data modification time and updates the status change
+time. Hence it doesn't interact with incremental dumps nicely
+(@pxref{Incremental Dumps}), and it can set access or data modification times
+incorrectly if other programs access the file while @command{tar} is
+running.
+
+@option{--atime-preserve=system} avoids changing the access time in
+the first place, if the operating system supports this.
+Unfortunately, this may or may not work on any given operating system
+or file system. If @command{tar} knows for sure it won't work, it
+complains right away.
+
+Currently @option{--atime-preserve} with no operand defaults to
+@option{--atime-preserve=replace}, but this is intended to change to
+@option{--atime-preserve=system} when the latter is better-supported.
+
+@opindex touch
+@item -m
+@itemx --touch
+Do not extract data modification time.
+
+When this option is used, @command{tar} leaves the data modification times
+of the files it extracts as the times when the files were extracted,
+instead of setting it to the times recorded in the archive.
+
+This option is meaningless with @option{--list} (@option{-t}).
+
+@opindex same-owner
+@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 @acronym{ID} and user name
+separately. If it can't find a user name (because the user @acronym{ID} is not
+in @file{/etc/passwd}), then it does not write one. When restoring,
+it tries to look the name (if one was written) up in
+@file{/etc/passwd}. If it fails, then it uses the user @acronym{ID} stored in
+the archive instead.
+
+@opindex no-same-owner
+@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.
+
+@opindex numeric-owner
+@item --numeric-owner
+The @option{--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 file system(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 @option{--old-archive} (@option{-o}) 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.
+
+@xopindex{same-permissions, short description}
+@xopindex{preserve-permissions, short description}
+@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 @option{--list} (@option{-t}).
+
+@opindex preserve
+@item --preserve
+Same as both @option{--same-permissions} and @option{--same-order}.
+
+The @option{--preserve} option has no equivalent short option name.
+It is equivalent to @option{--same-permissions} plus @option{--same-order}.
+
+@FIXME{I do not see the purpose of such an option. (Neither I. FP.)
+Neither do I. --Sergey}
+
+@end table
+
+@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.
+
+@FIXME{Discuss GNU extensions (incremental backups, multi-volume
+archives and archive labels) in GNU and PAX formats.}
+
+@menu
+* Portable Names:: Portable Names
+* dereference:: Symbolic Links
+* hard links:: Hard 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.
+* Other Tars:: How to Extract GNU-Specific Data Using
+ Other @command{tar} Implementations
+@end menu
+
+@node Portable Names
+@subsection Portable Names
+
+Use portable file and member names. A name is portable if it contains
+only @acronym{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
+
+@opindex dereference
+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 file system contents.
+@option{--dereference} (@option{-h}) is used with @option{--create} (@option{-c}), 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 @option{--dereference} (@option{-h}): many systems do not support
+symbolic links, and moreover, your distribution might be unusable if
+it contains unresolved symbolic links.
+
+@node hard links
+@subsection Hard Links
+@UNREVISED{}
+@cindex File names, using hard links
+@cindex hard links, dereferencing
+@cindex dereferencing hard links
+
+Normally, when @command{tar} archives a hard link, it writes a
+block to the archive naming the target of the link (a @samp{1} type
+block). In that way, the actual file contents is stored in file only
+once. For example, consider the following two files:
+
+@smallexample
+@group
+$ ls
+-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one
+-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden
+@end group
+@end smallexample
+
+Here, @file{jeden} is a link to @file{one}. When archiving this
+directory with a verbose level 2, you will get an output similar to
+the following:
+
+@smallexample
+$ tar cfvv ../archive.tar .
+drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
+-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
+hrw-r--r-- gray/staff 0 2007-10-30 15:11 ./one link to ./jeden
+@end smallexample
+
+The last line shows that, instead of storing two copies of the file,
+@command{tar} stored it only once, under the name @file{jeden}, and
+stored file @file{one} as a hard link to this file.
+
+It may be important to know that all hard links to the given file are
+stored in the archive. For example, this may be necessary for exact
+reproduction of the file system. The following option does that:
+
+@table @option
+@xopindex{check-links, described}
+@item --check-links
+@itemx -l
+Check the number of links dumped for each processed file. If this
+number does not match the total number of hard links for the file, print
+a warning message.
+@end table
+
+For example, trying to archive only file @file{jeden} with this option
+produces the following diagnostics:
+
+@smallexample
+$ tar -c -f ../archive.tar jeden
+tar: Missing links to `jeden'.
+@end smallexample
+
+Although creating special records for hard links helps keep a faithful
+record of the file system contents and makes archives more compact, it
+may present some difficulties when extracting individual members from
+the archive. For example, trying to extract file @file{one} from the
+archive created in previous examples produces, in the absense of file
+@file{jeden}:
+
+@smallexample
+$ tar xf archive.tar ./one
+tar: ./one: Cannot hard link to `./jeden': No such file or directory
+tar: Error exit delayed from previous errors
+@end smallexample
+
+The reason for this behavior is that @command{tar} cannot seek back in
+the archive to the previous member (in this case, @file{one}), to
+extract it@footnote{There are plans to fix this in future releases.}.
+If you wish to avoid such problems at the cost of a bigger archive,
+use the following option:
+
+@table @option
+@xopindex{hard-dereference, described}
+@item --hard-dereference
+Dereference hard links and store the files they refer to.
+@end table
+
+For example, trying this option on our two sample files, we get two
+copies in the archive, each of which can then be extracted
+independently of the other:
+
+@smallexample
+@group
+$ tar -c -vv -f ../archive.tar --hard-dereference .
+drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
+-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
+-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./one
+@end group
+@end smallexample
+
+@node old
+@subsection Old V7 Archives
+@cindex Format, old style
+@cindex Old style format
+@cindex Old style archives
+@cindex v7 archive format
+
+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 @option{--format=v7} option in
+conjunction with the @option{--create} (@option{-c}) (@command{tar} also
+accepts @option{--portability} or @option{--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 @option{--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 @option{--format=v7} for your distributions. Notice,
+however, that @samp{ustar} format is a better alternative, as it is
+free from many of @samp{v7}'s drawbacks.
+
+@node ustar
+@subsection Ustar Archive Format
+
+@cindex 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 @option{--format=ustar}
+option in conjunction with the @option{--create} (@option{-c}).
+
+@node gnu
+@subsection @acronym{GNU} and old @GNUTAR{} format
+
+@cindex GNU archive format
+@cindex Old GNU archive 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 future releases, since
+we plan to make @samp{POSIX} format the default.
+
+To force creation a @GNUTAR{} archive, use option
+@option{--format=gnu}.
+
+@node posix
+@subsection @GNUTAR{} and @acronym{POSIX} @command{tar}
+
+@cindex POSIX archive format
+@cindex PAX archive format
+Starting from version 1.14 @GNUTAR{} features full support for
+@acronym{POSIX.1-2001} archives.
+
+A @acronym{POSIX} conformant archive will be created if @command{tar}
+was given @option{--format=posix} (@option{--format=pax}) option. No
+special option is required to read and extract from a @acronym{POSIX}
+archive.
+
+@menu
+* PAX keywords:: Controlling Extended Header Keywords.
+@end menu
+
+@node PAX keywords
+@subsubsection Controlling Extended Header Keywords
+
+@table @option
+@opindex pax-option
+@item --pax-option=@var{keyword-list}
+Handle keywords in @acronym{PAX} extended headers. This option is
+equivalent to @option{-o} option of the @command{pax} utility.
+@end table
+
+@var{Keyword-list} is a comma-separated
+list of keyword options, each keyword option taking one of
+the following forms:
+
+@table @code
+@item delete=@var{pattern}
+When used with one of archive-creation commands,
+this option instructs @command{tar} to omit from extended header records
+that it produces any keywords matching the string @var{pattern}.
+
+When used in extract or list mode, this option instructs tar
+to ignore any keywords matching the given @var{pattern} in the extended
+header records. In both cases, matching is performed using the pattern
+matching notation described in @acronym{POSIX 1003.2}, 3.13
+(@pxref{wildcards}). For example:
+
+@smallexample
+--pax-option delete=security.*
+@end smallexample
+
+would suppress security-related information.
+
+@item exthdr.name=@var{string}
+
+This keyword allows user control over the name that is written into the
+ustar header blocks for the extended headers. The name is obtained
+from @var{string} after making the following substitutions:
+
+@multitable @columnfractions .25 .55
+@headitem Meta-character @tab Replaced By
+@item %d @tab The directory name of the file, equivalent to the
+result of the @command{dirname} utility on the translated file name.
+@item %f @tab The name of the file with the directory information
+stripped, equivalent to the result of the @command{basename} utility
+on the translated file name.
+@item %p @tab The process @acronym{ID} of the @command{tar} process.
+@item %% @tab A @samp{%} character.
+@end multitable
+
+Any other @samp{%} characters in @var{string} produce undefined
+results.
+
+If no option @samp{exthdr.name=string} is specified, @command{tar}
+will use the following default value:
+
+@smallexample
+%d/PaxHeaders.%p/%f
+@end smallexample
+
+@item globexthdr.name=@var{string}
+This keyword allows user control over the name that is written into
+the ustar header blocks for global extended header records. The name
+is obtained from the contents of @var{string}, after making
+the following substitutions:
+
+@multitable @columnfractions .25 .55
+@headitem Meta-character @tab Replaced By
+@item %n @tab An integer that represents the
+sequence number of the global extended header record in the archive,
+starting at 1.
+@item %p @tab The process @acronym{ID} of the @command{tar} process.
+@item %% @tab A @samp{%} character.
+@end multitable
+
+Any other @samp{%} characters in @var{string} produce undefined results.
+
+If no option @samp{globexthdr.name=string} is specified, @command{tar}
+will use the following default value:
+
+@smallexample
+$TMPDIR/GlobalHead.%p.%n
+@end smallexample
+
+@noindent
+where @samp{$TMPDIR} represents the value of the @var{TMPDIR}
+environment variable. If @var{TMPDIR} is not set, @command{tar}
+uses @samp{/tmp}.
+
+@item @var{keyword}=@var{value}
+When used with one of archive-creation commands, these keyword/value pairs
+will be included at the beginning of the archive in a global extended
+header record. When used with one of archive-reading commands,
+@command{tar} will behave as if it has encountered these keyword/value
+pairs at the beginning of the archive in a global extended header
+record.
+
+@item @var{keyword}:=@var{value}
+When used with one of archive-creation commands, these keyword/value pairs
+will be included as records at the beginning of an extended header for
+each file. This is effectively equivalent to @var{keyword}=@var{value}
+form except that it creates no global extended header records.
+
+When used with one of archive-reading commands, @command{tar} will
+behave as if these keyword/value pairs were included as records at the
+end of each extended header; thus, they will override any global or
+file-specific extended header record keywords of the same names.
+For example, in the command:
+
+@smallexample
+tar --format=posix --create \
+ --file archive --pax-option gname:=user .
+@end smallexample
+
+the group name will be forced to a new value for all files
+stored in the archive.
+@end table
+
+@node Checksumming
+@subsection Checksumming Problems
+
+SunOS and HP-UX @command{tar} fail to accept archives created using
+@GNUTAR{} and containing non-@acronym{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
+@UNREVISED{}
+
+The above sections suggest to use @samp{oldest possible} archive
+format if in doubt. However, sometimes it is not possible. If you
+attempt to archive a file whose metadata cannot be represented using
+required format, @GNUTAR{} will print error message and ignore such a
+file. You will than have to switch to a format that is able to
+handle such values. The format summary table (@pxref{Formats}) will
+help you to do so.
+
+In particular, when trying to archive files larger than 8GB or with
+timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16
+12:56:31 @sc{utc}, you will have to chose between @acronym{GNU} and
+@acronym{POSIX} archive formats. When considering which format to
+choose, bear in mind that the @acronym{GNU} format uses
+two's-complement base-256 notation to store values that do not fit
+into standard @acronym{ustar} range. Such archives can generally be
+read only by a @GNUTAR{} implementation. Moreover, they sometimes
+cannot be correctly restored on another hosts even by @GNUTAR{}. For
+example, using two's complement representation for negative time
+stamps that assumes a signed 32-bit @code{time_t} generates archives
+that are not portable to hosts with differing @code{time_t}
+representations.
+
+On the other hand, @acronym{POSIX} archives, generally speaking, can
+be extracted by any tar implementation that understands older
+@acronym{ustar} format. The only exception are files larger than 8GB.
+
+@FIXME{Describe how @acronym{POSIX} archives are extracted by non
+POSIX-aware tars.}
+
+@node Other Tars
+@subsection How to Extract GNU-Specific Data Using Other @command{tar} Implementations
+
+In previous sections you became acquainted with various quirks
+necessary to make your archives portable. Sometimes you may need to
+extract archives containing GNU-specific members using some
+third-party @command{tar} implementation or an older version of
+@GNUTAR{}. Of course your best bet is to have @GNUTAR{} installed,
+but if it is for some reason impossible, this section will explain
+how to cope without it.
+
+When we speak about @dfn{GNU-specific} members we mean two classes of
+them: members split between the volumes of a multi-volume archive and
+sparse members. You will be able to always recover such members if
+the archive is in PAX format. In addition split members can be
+recovered from archives in old GNU format. The following subsections
+describe the required procedures in detail.
+
+@menu
+* Split Recovery:: Members Split Between Volumes
+* Sparse Recovery:: Sparse Members
+@end menu
+
+@node Split Recovery
+@subsubsection Extracting Members Split Between Volumes
+
+@cindex Mutli-volume archives, extracting using non-GNU tars
+If a member is split between several volumes of an old GNU format archive
+most third party @command{tar} implementation will fail to extract
+it. To extract it, use @command{tarcat} program (@pxref{Tarcat}).
+This program is available from
+@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/tarcat.html, @GNUTAR{}
+home page}. It concatenates several archive volumes into a single
+valid archive. For example, if you have three volumes named from
+@file{vol-1.tar} to @file{vol-3.tar}, you can do the following to
+extract them using a third-party @command{tar}:
+
+@smallexample
+$ @kbd{tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf -}
+@end smallexample
+
+@cindex Mutli-volume archives in PAX format, extracting using non-GNU tars
+You could use this approach for most (although not all) PAX
+format archives as well. However, extracting split members from a PAX
+archive is a much easier task, because PAX volumes are constructed in
+such a way that each part of a split member is extracted to a
+different file by @command{tar} implementations that are not aware of
+GNU extensions. More specifically, the very first part retains its
+original name, and all subsequent parts are named using the pattern:
+
+@smallexample
+%d/GNUFileParts.%p/%f.%n
+@end smallexample
+
+@noindent
+where symbols preceeded by @samp{%} are @dfn{macro characters} that
+have the following meaning:
+
+@multitable @columnfractions .25 .55
+@headitem Meta-character @tab Replaced By
+@item %d @tab The directory name of the file, equivalent to the
+result of the @command{dirname} utility on its full name.
+@item %f @tab The file name of the file, equivalent to the result
+of the @command{basename} utility on its full name.
+@item %p @tab The process @acronym{ID} of the @command{tar} process that
+created the archive.
+@item %n @tab Ordinal number of this particular part.
+@end multitable
+
+For example, if the file @file{var/longfile} was split during archive
+creation between three volumes, and the creator @command{tar} process
+had process @acronym{ID} @samp{27962}, then the member names will be:
+
+@smallexample
+var/longfile
+var/GNUFileParts.27962/longfile.1
+var/GNUFileParts.27962/longfile.2
+@end smallexample
+
+When you extract your archive using a third-party @command{tar}, these
+files will be created on your disk, and the only thing you will need
+to do to restore your file in its original form is concatenate them in
+the proper order, for example:
+
+@smallexample
+@group
+$ @kbd{cd var}
+$ @kbd{cat GNUFileParts.27962/longfile.1 \
+ GNUFileParts.27962/longfile.2 >> longfile}
+$ rm -f GNUFileParts.27962
+@end group
+@end smallexample
+
+Notice, that if the @command{tar} implementation you use supports PAX
+format archives, it will probably emit warnings about unknown keywords
+during extraction. They will look like this:
+
+@smallexample
+@group
+Tar file too small
+Unknown extended header keyword 'GNU.volume.filename' ignored.
+Unknown extended header keyword 'GNU.volume.size' ignored.
+Unknown extended header keyword 'GNU.volume.offset' ignored.
+@end group
+@end smallexample
+
+@noindent
+You can safely ignore these warnings.
+
+If your @command{tar} implementation is not PAX-aware, you will get
+more warnings and more files generated on your disk, e.g.:
+
+@smallexample
+@group
+$ @kbd{tar xf vol-1.tar}
+var/PaxHeaders.27962/longfile: Unknown file type 'x', extracted as
+normal file
+Unexpected EOF in archive
+$ @kbd{tar xf vol-2.tar}
+tmp/GlobalHead.27962.1: Unknown file type 'g', extracted as normal file
+GNUFileParts.27962/PaxHeaders.27962/sparsefile.1: Unknown file type
+'x', extracted as normal file
+@end group
+@end smallexample
+
+Ignore these warnings. The @file{PaxHeaders.*} directories created
+will contain files with @dfn{extended header keywords} describing the
+extracted files. You can delete them, unless they describe sparse
+members. Read further to learn more about them.
+
+@node Sparse Recovery
+@subsubsection Extracting Sparse Members
+
+@cindex sparse files, extracting with non-GNU tars
+Any @command{tar} implementation will be able to extract sparse members from a
+PAX archive. However, the extracted files will be @dfn{condensed},
+i.e., any zero blocks will be removed from them. When we restore such
+a condensed file to its original form, by adding zero blocks (or
+@dfn{holes}) back to their original locations, we call this process
+@dfn{expanding} a compressed sparse file.
+
+@pindex xsparse
+To expand a file, you will need a simple auxiliary program called
+@command{xsparse}. It is available in source form from
+@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/xsparse.html, @GNUTAR{}
+home page}.
+
+@cindex sparse files v.1.0, extracting with non-GNU tars
+Let's begin with archive members in @dfn{sparse format
+version 1.0}@footnote{@xref{PAX 1}.}, which are the easiest to expand.
+The condensed file will contain both file map and file data, so no
+additional data will be needed to restore it. If the original file
+name was @file{@var{dir}/@var{name}}, then the condensed file will be
+named @file{@var{dir}/@/GNUSparseFile.@var{n}/@/@var{name}}, where
+@var{n} is a decimal number@footnote{technically speaking, @var{n} is a
+@dfn{process @acronym{ID}} of the @command{tar} process which created the
+archive (@pxref{PAX keywords}).}.
+
+To expand a version 1.0 file, run @command{xsparse} as follows:
+
+@smallexample
+$ @kbd{xsparse @file{cond-file}}
+@end smallexample
+
+@noindent
+where @file{cond-file} is the name of the condensed file. The utility
+will deduce the name for the resulting expanded file using the
+following algorithm:
+
+@enumerate 1
+@item If @file{cond-file} does not contain any directories,
+@file{../cond-file} will be used;
+
+@item If @file{cond-file} has the form
+@file{@var{dir}/@var{t}/@var{name}}, where both @var{t} and @var{name}
+are simple names, with no @samp{/} characters in them, the output file
+name will be @file{@var{dir}/@var{name}}.
+
+@item Otherwise, if @file{cond-file} has the form
+@file{@var{dir}/@var{name}}, the output file name will be
+@file{@var{name}}.
+@end enumerate
+
+In the unlikely case when this algorithm does not suit your needs,
+you can explicitly specify output file name as a second argument to
+the command:
+
+@smallexample
+$ @kbd{xsparse @file{cond-file} @file{out-file}}
+@end smallexample
+
+It is often a good idea to run @command{xsparse} in @dfn{dry run} mode
+first. In this mode, the command does not actually expand the file,
+but verbosely lists all actions it would be taking to do so. The dry
+run mode is enabled by @option{-n} command line argument:
+
+@smallexample
+@group
+$ @kbd{xsparse -n /home/gray/GNUSparseFile.6058/sparsefile}
+Reading v.1.0 sparse map
+Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
+`/home/gray/sparsefile'
+Finished dry run
+@end group
+@end smallexample
+
+To actually expand the file, you would run:
+
+@smallexample
+$ @kbd{xsparse /home/gray/GNUSparseFile.6058/sparsefile}
+@end smallexample
+
+@noindent
+The program behaves the same way all UNIX utilities do: it will keep
+quiet unless it has simething important to tell you (e.g. an error
+condition or something). If you wish it to produce verbose output,
+similar to that from the dry run mode, use @option{-v} option:
+
+@smallexample
+@group
+$ @kbd{xsparse -v /home/gray/GNUSparseFile.6058/sparsefile}
+Reading v.1.0 sparse map
+Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
+`/home/gray/sparsefile'
+Done
+@end group
+@end smallexample
+
+Additionally, if your @command{tar} implementation has extracted the
+@dfn{extended headers} for this file, you can instruct @command{xstar}
+to use them in order to verify the integrity of the expanded file.
+The option @option{-x} sets the name of the extended header file to
+use. Continuing our example:
+
+@smallexample
+@group
+$ @kbd{xsparse -v -x /home/gray/PaxHeaders.6058/sparsefile \
+ /home/gray/GNUSparseFile.6058/sparsefile}
+Reading extended header file
+Found variable GNU.sparse.major = 1
+Found variable GNU.sparse.minor = 0
+Found variable GNU.sparse.name = sparsefile
+Found variable GNU.sparse.realsize = 217481216
+Reading v.1.0 sparse map
+Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
+`/home/gray/sparsefile'
+Done
+@end group
+@end smallexample
+
+@anchor{extracting sparse v.0.x}
+@cindex sparse files v.0.1, extracting with non-GNU tars
+@cindex sparse files v.0.0, extracting with non-GNU tars
+An @dfn{extended header} is a special @command{tar} archive header
+that precedes an archive member and contains a set of
+@dfn{variables}, describing the member properties that cannot be
+stored in the standard @code{ustar} header. While optional for
+expanding sparse version 1.0 members, the use of extended headers is
+mandatory when expanding sparse members in older sparse formats: v.0.0
+and v.0.1 (The sparse formats are described in detail in @ref{Sparse
+Formats}.) So, for these formats, the question is: how to obtain
+extended headers from the archive?
+
+If you use a @command{tar} implementation that does not support PAX
+format, extended headers for each member will be extracted as a
+separate file. If we represent the member name as
+@file{@var{dir}/@var{name}}, then the extended header file will be
+named @file{@var{dir}/@/PaxHeaders.@var{n}/@/@var{name}}, where
+@var{n} is an integer number.
+
+Things become more difficult if your @command{tar} implementation
+does support PAX headers, because in this case you will have to
+manually extract the headers. We recommend the following algorithm:
+
+@enumerate 1
+@item
+Consult the documentation of your @command{tar} implementation for an
+option that prints @dfn{block numbers} along with the archive
+listing (analogous to @GNUTAR{}'s @option{-R} option). For example,
+@command{star} has @option{-block-number}.
+
+@item
+Obtain verbose listing using the @samp{block number} option, and
+find block numbers of the sparse member in question and the member
+immediately following it. For example, running @command{star} on our
+archive we obtain:
+
+@smallexample
+@group
+$ @kbd{star -t -v -block-number -f arc.tar}
+@dots{}
+star: Unknown extended header keyword 'GNU.sparse.size' ignored.
+star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored.
+star: Unknown extended header keyword 'GNU.sparse.name' ignored.
+star: Unknown extended header keyword 'GNU.sparse.map' ignored.
+block 56: 425984 -rw-r--r-- gray/users Jun 25 14:46 2006 GNUSparseFile.28124/sparsefile
+block 897: 65391 -rw-r--r-- gray/users Jun 24 20:06 2006 README
+@dots{}
+@end group
+@end smallexample
+
+@noindent
+(as usual, ignore the warnings about unknown keywords.)
+
+@item
+Let @var{size} be the size of the sparse member, @var{Bs} be its block number
+and @var{Bn} be the block number of the next member.
+Compute:
+
+@smallexample
+@var{N} = @var{Bs} - @var{Bn} - @var{size}/512 - 2
+@end smallexample
+
+@noindent
+This number gives the size of the extended header part in tar @dfn{blocks}.
+In our example, this formula gives: @code{897 - 56 - 425984 / 512 - 2
+= 7}.
+
+@item
+Use @command{dd} to extract the headers:
+
+@smallexample
+@kbd{dd if=@var{archive} of=@var{hname} bs=512 skip=@var{Bs} count=@var{N}}
+@end smallexample
+
+@noindent
+where @var{archive} is the archive name, @var{hname} is a name of the
+file to store the extended header in, @var{Bs} and @var{N} are
+computed in previous steps.
+
+In our example, this command will be
+
+@smallexample
+$ @kbd{dd if=arc.tar of=xhdr bs=512 skip=56 count=7}
+@end smallexample
+@end enumerate
+
+Finally, you can expand the condensed file, using the obtained header:
+
+@smallexample
+@group
+$ @kbd{xsparse -v -x xhdr GNUSparseFile.6058/sparsefile}
+Reading extended header file
+Found variable GNU.sparse.size = 217481216
+Found variable GNU.sparse.numblocks = 208
+Found variable GNU.sparse.name = sparsefile
+Found variable GNU.sparse.map = 0,2048,1050624,2048,@dots{}
+Expanding file `GNUSparseFile.28124/sparsefile' to `sparsefile'
+Done
+@end group
+@end smallexample
+
+@node cpio
+@section Comparison of @command{tar} and @command{cpio}
+@UNREVISED
+
+@FIXME{Reorganize the following material}
+
+The @command{cpio} archive formats, like @command{tar}, do have maximum
+file name lengths. The binary and old @acronym{ASCII} formats have a maximum file
+length of 256, and the new @acronym{ASCII} and @acronym{CRC ASCII} formats have a max
+file length of 1024. @acronym{GNU} @command{cpio} can read and write archives
+with arbitrary file name lengths, but other @command{cpio} implementations
+may crash unexplainedly trying to read them.
+
+@command{tar} handles symbolic links in the form in which it comes in @acronym{BSD};
+@command{cpio} doesn't handle symbolic links in the form in which it comes
+in System V prior to SVR4, and some vendors may have added symlinks
+to their system without enhancing @command{cpio} to know about them.
+Others may have enhanced it in a way other than the way I did it
+at Sun, and which was adopted by AT&T (and which is, I think, also
+present in the @command{cpio} that Berkeley picked up from AT&T and put
+into a later @acronym{BSD} release---I think I gave them my changes).
+
+(SVR4 does some funny stuff with @command{tar}; basically, its @command{cpio}
+can handle @command{tar} format input, and write it on output, and it
+probably handles symbolic links. They may not have bothered doing
+anything to enhance @command{tar} as a result.)
+
+@command{cpio} handles special files; traditional @command{tar} doesn't.
+
+@command{tar} comes with V7, System III, System V, and @acronym{BSD} source;
+@command{cpio} comes only with System III, System V, and later @acronym{BSD}
+(4.3-tahoe and later).
+
+@command{tar}'s way of handling multiple hard links to a file can handle
+file systems that support 32-bit inumbers (e.g., the @acronym{BSD} file system);
+@command{cpio}s way requires you to play some games (in its ``binary''
+format, i-numbers are only 16 bits, and in its ``portable @acronym{ASCII}'' format,
+they're 18 bits---it would have to play games with the "file system @acronym{ID}"
+field of the header to make sure that the file system @acronym{ID}/i-number pairs
+of different files were always different), and I don't know which
+@command{cpio}s, if any, play those games. Those that don't might get
+confused and think two files are the same file when they're not, and
+make hard links between them.
+
+@command{tar}s way of handling multiple hard links to a file places only
+one copy of the link on the tape, but the name attached to that copy
+is the @emph{only} one you can use to retrieve the file; @command{cpio}s
+way puts one copy for every link, but you can retrieve it using any
+of the names.
+
+@quotation
+What type of check sum (if any) is used, and how is this calculated.
+@end quotation
+
+See the attached manual pages for @command{tar} and @command{cpio} format.
+@command{tar} uses a checksum which is the sum of all the bytes in the
+@command{tar} header for a file; @command{cpio} uses no checksum.
+
+@quotation
+If anyone knows why @command{cpio} was made when @command{tar} was present
+at the unix scene,
+@end quotation
+
+It wasn't. @command{cpio} first showed up in PWB/UNIX 1.0; no
+generally-available version of UNIX had @command{tar} at the time. I don't
+know whether any version that was generally available @emph{within AT&T}
+had @command{tar}, or, if so, whether the people within AT&T who did
+@command{cpio} knew about it.
+
+On restore, if there is a corruption on a tape @command{tar} will stop at
+that point, while @command{cpio} will skip over it and try to restore the
+rest of the files.
+
+The main difference is just in the command syntax and header format.
+
+@command{tar} is a little more tape-oriented in that everything is blocked
+to start on a record boundary.
+
+@quotation
+Is there any differences between the ability to recover crashed
+archives between the two of them. (Is there any chance of recovering
+crashed archives at all.)
+@end quotation
+
+Theoretically it should be easier under @command{tar} since the blocking
+lets you find a header with some variation of @samp{dd skip=@var{nn}}.
+However, modern @command{cpio}'s and variations have an option to just
+search for the next file header after an error with a reasonable chance
+of resyncing. However, lots of tape driver software won't allow you to
+continue past a media error which should be the only reason for getting
+out of sync unless a file changed sizes while you were writing the
+archive.
+
+@quotation
+If anyone knows why @command{cpio} was made when @command{tar} was present
+at the unix scene, please tell me about this too.
+@end quotation
+
+Probably because it is more media efficient (by not blocking everything
+and using only the space needed for the headers where @command{tar}
+always uses 512 bytes per file header) and it knows how to archive
+special files.
+
+You might want to look at the freely available alternatives. The
+major ones are @command{afio}, @GNUTAR{}, and
+@command{pax}, each of which have their own extensions with some
+backwards compatibility.
+
+Sparse files were @command{tar}red as sparse files (which you can
+easily test, because the resulting archive gets smaller, and
+@acronym{GNU} @command{cpio} can no longer read it).
+
+@node Media
+@chapter Tapes and Other Archive Media
+@UNREVISED
+
+A few special cases about tape handling warrant more detailed
+description. These special cases are discussed below.
+
+Many complexities surround the use of @command{tar} on tape drives. Since
+the creation and manipulation of archives located on magnetic tape was
+the original purpose of @command{tar}, it contains many features making
+such manipulation easier.
+
+Archives are usually written on dismountable media---tape cartridges,
+mag tapes, or floppy disks.
+
+The amount of data a tape or disk holds depends not only on its size,
+but also on how it is formatted. A 2400 foot long reel of mag tape
+holds 40 megabytes of data when formatted at 1600 bits per inch. The
+physically smaller EXABYTE tape cartridge holds 2.3 gigabytes.
+
+Magnetic media are re-usable---once the archive on a tape is no longer
+needed, the archive can be erased and the tape or disk used over.
+Media quality does deteriorate with use, however. Most tapes or disks
+should be discarded when they begin to produce data errors. EXABYTE
+tape cartridges should be discarded when they generate an @dfn{error
+count} (number of non-usable bits) of more than 10k.
+
+Magnetic media are written and erased using magnetic fields, and
+should be protected from such fields to avoid damage to stored data.
+Sticking a floppy disk to a filing cabinet using a magnet is probably
+not a good idea.
+
+@menu
+* Device:: Device selection and switching
+* Remote Tape Server::
+* Common Problems and Solutions::
+* Blocking:: Blocking
+* Many:: Many archives on one tape
+* Using Multiple Tapes:: Using Multiple Tapes
+* label:: Including a Label in the Archive
+* verify::
+* Write Protection::
+@end menu
+
+@node Device
+@section Device Selection and Switching
+@UNREVISED
+
+@table @option
+@item -f [@var{hostname}:]@var{file}
+@itemx --file=[@var{hostname}:]@var{file}
+Use archive file or device @var{file} on @var{hostname}.
+@end table
+
+This option is used to specify the file name of the archive @command{tar}
+works on.
+
+If the file name is @samp{-}, @command{tar} reads the archive from standard
+input (when listing or extracting), or writes it to standard output
+(when creating). If the @samp{-} file name is given when updating an
+archive, @command{tar} will read the original archive from its standard
+input, and will write the entire new archive to its standard output.
+
+If the file name contains a @samp{:}, it is interpreted as
+@samp{hostname:file name}. If the @var{hostname} contains an @dfn{at}
+sign (@samp{@@}), it is treated as @samp{user@@hostname:file name}. In
+either case, @command{tar} will invoke the command @command{rsh} (or
+@command{remsh}) to start up an @command{/usr/libexec/rmt} on the remote
+machine. If you give an alternate login name, it will be given to the
+@command{rsh}.
+Naturally, the remote machine must have an executable
+@command{/usr/libexec/rmt}. This program is free software from the
+University of California, and a copy of the source code can be found
+with the sources for @command{tar}; it's compiled and installed by default.
+The exact path to this utility is determined when configuring the package.
+It is @file{@var{prefix}/libexec/rmt}, where @var{prefix} stands for
+your installation prefix. This location may also be overridden at
+runtime by using @option{rmt-command=@var{command}} option (@xref{Option Summary,
+---rmt-command}, for detailed description of this option. @xref{Remote
+Tape Server}, for the description of @command{rmt} command).
+
+If this option is not given, but the environment variable @env{TAPE}
+is set, its value is used; otherwise, old versions of @command{tar}
+used a default archive name (which was picked when @command{tar} was
+compiled). The default is normally set up to be the @dfn{first} tape
+drive or other transportable I/O medium on the system.
+
+Starting with version 1.11.5, @GNUTAR{} uses
+standard input and standard output as the default device, and I will
+not try anymore supporting automatic device detection at installation
+time. This was failing really in too many cases, it was hopeless.
+This is now completely left to the installer to override standard
+input and standard output for default device, if this seems
+preferable. Further, I think @emph{most} actual usages of
+@command{tar} are done with pipes or disks, not really tapes,
+cartridges or diskettes.
+
+Some users think that using standard input and output is running
+after trouble. This could lead to a nasty surprise on your screen if
+you forget to specify an output file name---especially if you are going
+through a network or terminal server capable of buffering large amounts
+of output. We had so many bug reports in that area of configuring
+default tapes automatically, and so many contradicting requests, that
+we finally consider the problem to be portably intractable. We could
+of course use something like @samp{/dev/tape} as a default, but this
+is @emph{also} running after various kind of trouble, going from hung
+processes to accidental destruction of real tapes. After having seen
+all this mess, using standard input and output as a default really
+sounds like the only clean choice left, and a very useful one too.
+
+@GNUTAR{} reads and writes archive in records, I
+suspect this is the main reason why block devices are preferred over
+character devices. Most probably, block devices are more efficient
+too. The installer could also check for @samp{DEFTAPE} in
+@file{<sys/mtio.h>}.
+
+@table @option
+@xopindex{force-local, short description}
+@item --force-local
+Archive file is local even if it contains a colon.
+
+@opindex rsh-command
+@item --rsh-command=@var{command}
+Use remote @var{command} instead of @command{rsh}. This option exists
+so that people who use something other than the standard @command{rsh}
+(e.g., a Kerberized @command{rsh}) can access a remote device.
+
+When this command is not used, the shell command found when
+the @command{tar} program was installed is used instead. This is
+the first found of @file{/usr/ucb/rsh}, @file{/usr/bin/remsh},
+@file{/usr/bin/rsh}, @file{/usr/bsd/rsh} or @file{/usr/bin/nsh}.
+The installer may have overridden this by defining the environment
+variable @env{RSH} @emph{at installation time}.
+
+@item -[0-7][lmh]
+Specify drive and density.
+
+@xopindex{multi-volume, short description}
+@item -M
+@itemx --multi-volume
+Create/list/extract multi-volume archive.
+
+This option causes @command{tar} to write a @dfn{multi-volume} archive---one
+that may be larger than will fit on the medium used to hold it.
+@xref{Multi-Volume Archives}.
+
+@xopindex{tape-length, short description}
+@item -L @var{num}
+@itemx --tape-length=@var{num}
+Change tape after writing @var{num} x 1024 bytes.
+
+This option might be useful when your tape drivers do not properly
+detect end of physical tapes. By being slightly conservative on the
+maximum tape length, you might avoid the problem entirely.
+
+@xopindex{info-script, short description}
+@xopindex{new-volume-script, short description}
+@item -F @var{file}
+@itemx --info-script=@var{file}
+@itemx --new-volume-script=@var{file}
+Execute @file{file} at end of each tape. This implies
+@option{--multi-volume} (@option{-M}). @xref{info-script}, for a detailed
+description of this option.
+@end table
+
+@node Remote Tape Server
+@section The Remote Tape Server
+
+@cindex remote tape drive
+@pindex rmt
+In order to access the tape drive on a remote machine, @command{tar}
+uses the remote tape server written at the University of California at
+Berkeley. The remote tape server must be installed as
+@file{@var{prefix}/libexec/rmt} on any machine whose tape drive you
+want to use. @command{tar} calls @command{rmt} by running an
+@command{rsh} or @command{remsh} to the remote machine, optionally
+using a different login name if one is supplied.
+
+A copy of the source for the remote tape server is provided. It is
+Copyright @copyright{} 1983 by the Regents of the University of
+California, but can be freely distributed. It is compiled and
+installed by default.
+
+@cindex absolute file names
+Unless you use the @option{--absolute-names} (@option{-P}) option,
+@GNUTAR{} will not allow you to create an archive that contains
+absolute file names (a file name beginning with @samp{/}.) If you try,
+@command{tar} will automatically remove the leading @samp{/} from the
+file names it stores in the archive. It will also type a warning
+message telling you what it is doing.
+
+When reading an archive that was created with a different
+@command{tar} program, @GNUTAR{} automatically
+extracts entries in the archive which have absolute file names as if
+the file names were not absolute. This is an important feature. A
+visitor here once gave a @command{tar} tape to an operator to restore;
+the operator used Sun @command{tar} instead of @GNUTAR{},
+and the result was that it replaced large portions of
+our @file{/bin} and friends with versions from the tape; needless to
+say, we were unhappy about having to recover the file system from
+backup tapes.
+
+For example, if the archive contained a file @file{/usr/bin/computoy},
+@GNUTAR{} would extract the file to @file{usr/bin/computoy},
+relative to the current directory. If you want to extract the files in
+an archive to the same absolute names that they had when the archive
+was created, you should do a @samp{cd /} before extracting the files
+from the archive, or you should either use the @option{--absolute-names}
+option, or use the command @samp{tar -C / @dots{}}.
+
+@cindex Ultrix 3.1 and write failure
+Some versions of Unix (Ultrix 3.1 is known to have this problem),
+can claim that a short write near the end of a tape succeeded,
+when it actually failed. This will result in the -M option not
+working correctly. The best workaround at the moment is to use a
+significantly larger blocking factor than the default 20.
+
+In order to update an archive, @command{tar} must be able to backspace the
+archive in order to reread or rewrite a record that was just read (or
+written). This is currently possible only on two kinds of files: normal
+disk files (or any other file that can be backspaced with @samp{lseek}),
+and industry-standard 9-track magnetic tape (or any other kind of tape
+that can be backspaced with the @code{MTIOCTOP} @code{ioctl}.
+
+This means that the @option{--append}, @option{--concatenate}, and
+@option{--delete} commands will not work on any other kind of file.
+Some media simply cannot be backspaced, which means these commands and
+options will never be able to work on them. These non-backspacing
+media include pipes and cartridge tape drives.
+
+Some other media can be backspaced, and @command{tar} will work on them
+once @command{tar} is modified to do so.
+
+Archives created with the @option{--multi-volume}, @option{--label}, and
+@option{--incremental} (@option{-G}) options may not be readable by other version
+of @command{tar}. In particular, restoring a file that was split over
+a volume boundary will require some careful work with @command{dd}, if
+it can be done at all. Other versions of @command{tar} may also create
+an empty file whose name is that of the volume header. Some versions
+of @command{tar} may create normal files instead of directories archived
+with the @option{--incremental} (@option{-G}) option.
+
+@node Common Problems and Solutions
+@section Some Common Problems and their Solutions
+
+@ifclear PUBLISH
+
+@format
+errors from system:
+permission denied
+no such file or directory
+not owner
+
+errors from @command{tar}:
+directory checksum error
+header format error
+
+errors from media/system:
+i/o error
+device busy
+@end format
+
+@end ifclear
+
+@node Blocking
+@section Blocking
+@UNREVISED
+
+@dfn{Block} and @dfn{record} terminology is rather confused, and it
+is also confusing to the expert reader. On the other hand, readers
+who are new to the field have a fresh mind, and they may safely skip
+the next two paragraphs, as the remainder of this manual uses those
+two terms in a quite consistent way.
+
+John Gilmore, the writer of the public domain @command{tar} from which
+@GNUTAR{} was originally derived, wrote (June 1995):
+
+@quotation
+The nomenclature of tape drives comes from IBM, where I believe
+they were invented for the IBM 650 or so. On IBM mainframes, what
+is recorded on tape are tape blocks. The logical organization of
+data is into records. There are various ways of putting records into
+blocks, including @code{F} (fixed sized records), @code{V} (variable
+sized records), @code{FB} (fixed blocked: fixed size records, @var{n}
+to a block), @code{VB} (variable size records, @var{n} to a block),
+@code{VSB} (variable spanned blocked: variable sized records that can
+occupy more than one block), etc. The @code{JCL} @samp{DD RECFORM=}
+parameter specified this to the operating system.
+
+The Unix man page on @command{tar} was totally confused about this.
+When I wrote @code{PD TAR}, I used the historically correct terminology
+(@command{tar} writes data records, which are grouped into blocks).
+It appears that the bogus terminology made it into @acronym{POSIX} (no surprise
+here), and now Fran@,{c}ois has migrated that terminology back
+into the source code too.
+@end quotation
+
+The term @dfn{physical block} means the basic transfer chunk from or
+to a device, after which reading or writing may stop without anything
+being lost. In this manual, the term @dfn{block} usually refers to
+a disk physical block, @emph{assuming} that each disk block is 512
+bytes in length. It is true that some disk devices have different
+physical blocks, but @command{tar} ignore these differences in its own
+format, which is meant to be portable, so a @command{tar} block is always
+512 bytes in length, and @dfn{block} always mean a @command{tar} block.
+The term @dfn{logical block} often represents the basic chunk of
+allocation of many disk blocks as a single entity, which the operating
+system treats somewhat atomically; this concept is only barely used
+in @GNUTAR{}.
+
+The term @dfn{physical record} is another way to speak of a physical
+block, those two terms are somewhat interchangeable. In this manual,
+the term @dfn{record} usually refers to a tape physical block,
+@emph{assuming} that the @command{tar} archive is kept on magnetic tape.
+It is true that archives may be put on disk or used with pipes,
+but nevertheless, @command{tar} tries to read and write the archive one
+@dfn{record} at a time, whatever the medium in use. One record is made
+up of an integral number of blocks, and this operation of putting many
+disk blocks into a single tape block is called @dfn{reblocking}, or
+more simply, @dfn{blocking}. The term @dfn{logical record} refers to
+the logical organization of many characters into something meaningful
+to the application. The term @dfn{unit record} describes a small set
+of characters which are transmitted whole to or by the application,
+and often refers to a line of text. Those two last terms are unrelated
+to what we call a @dfn{record} in @GNUTAR{}.
+
+When writing to tapes, @command{tar} writes the contents of the archive
+in chunks known as @dfn{records}. To change the default blocking
+factor, use the @option{--blocking-factor=@var{512-size}} (@option{-b
+@var{512-size}}) option. Each record will then be composed of
+@var{512-size} blocks. (Each @command{tar} block is 512 bytes.
+@xref{Standard}.) Each file written to the archive uses at least one
+full record. As a result, using a larger record size can result in
+more wasted space for small files. On the other hand, a larger record
+size can often be read and written much more efficiently.
+
+Further complicating the problem is that some tape drives ignore the
+blocking entirely. For these, a larger record size can still improve
+performance (because the software layers above the tape drive still
+honor the blocking), but not as dramatically as on tape drives that
+honor blocking.
+
+When reading an archive, @command{tar} can usually figure out the
+record size on itself. When this is the case, and a non-standard
+record size was used when the archive was created, @command{tar} will
+print a message about a non-standard blocking factor, and then operate
+normally. On some tape devices, however, @command{tar} cannot figure
+out the record size itself. On most of those, you can specify a
+blocking factor (with @option{--blocking-factor}) larger than the
+actual blocking factor, and then use the @option{--read-full-records}
+(@option{-B}) option. (If you specify a blocking factor with
+@option{--blocking-factor} and don't use the
+@option{--read-full-records} option, then @command{tar} will not
+attempt to figure out the recording size itself.) On some devices,
+you must always specify the record size exactly with
+@option{--blocking-factor} when reading, because @command{tar} cannot
+figure it out. In any case, use @option{--list} (@option{-t}) before
+doing any extractions to see whether @command{tar} is reading the archive
+correctly.
+
+@command{tar} blocks are all fixed size (512 bytes), and its scheme for
+putting them into records is to put a whole number of them (one or
+more) into each record. @command{tar} records are all the same size;
+at the end of the file there's a block containing all zeros, which
+is how you tell that the remainder of the last record(s) are garbage.
+
+In a standard @command{tar} file (no options), the block size is 512
+and the record size is 10240, for a blocking factor of 20. What the
+@option{--blocking-factor} option does is sets the blocking factor,
+changing the record size while leaving the block size at 512 bytes.
+20 was fine for ancient 800 or 1600 bpi reel-to-reel tape drives;
+most tape drives these days prefer much bigger records in order to
+stream and not waste tape. When writing tapes for myself, some tend
+to use a factor of the order of 2048, say, giving a record size of
+around one megabyte.
+
+If you use a blocking factor larger than 20, older @command{tar}
+programs might not be able to read the archive, so we recommend this
+as a limit to use in practice. @GNUTAR{}, however,
+will support arbitrarily large record sizes, limited only by the
+amount of virtual memory or the physical characteristics of the tape
+device.
+
+@menu
+* Format Variations:: Format Variations
+* Blocking Factor:: The Blocking Factor of an Archive
+@end menu
+
+@node Format Variations
+@subsection Format Variations
+@cindex Format Parameters
+@cindex Format Options
+@cindex Options, archive format specifying
+@cindex Options, format specifying
+@UNREVISED
+
+Format parameters specify how an archive is written on the archive
+media. The best choice of format parameters will vary depending on
+the type and number of files being archived, and on the media used to
+store the archive.
+
+To specify format parameters when accessing or creating an archive,
+you can use the options described in the following sections.
+If you do not specify any format parameters, @command{tar} uses
+default parameters. You cannot modify a compressed archive.
+If you create an archive with the @option{--blocking-factor} option
+specified (@pxref{Blocking Factor}), you must specify that
+blocking-factor when operating on the archive. @xref{Formats}, for other
+examples of format parameter considerations.
+
+@node Blocking Factor
+@subsection The Blocking Factor of an Archive
+@cindex Blocking Factor
+@cindex Record Size
+@cindex Number of blocks per record
+@cindex Number of bytes per record
+@cindex Bytes per record
+@cindex Blocks per record
+@UNREVISED
+
+@opindex blocking-factor
+The data in an archive is grouped into blocks, which are 512 bytes.
+Blocks are read and written in whole number multiples called
+@dfn{records}. The number of blocks in a record (i.e., the size of a
+record in units of 512 bytes) is called the @dfn{blocking factor}.
+The @option{--blocking-factor=@var{512-size}} (@option{-b
+@var{512-size}}) option specifies the blocking factor of an archive.
+The default blocking factor is typically 20 (i.e., 10240 bytes), but
+can be specified at installation. To find out the blocking factor of
+an existing archive, use @samp{tar --list --file=@var{archive-name}}.
+This may not work on some devices.
+
+Records are separated by gaps, which waste space on the archive media.
+If you are archiving on magnetic tape, using a larger blocking factor
+(and therefore larger records) provides faster throughput and allows you
+to fit more data on a tape (because there are fewer gaps). If you are
+archiving on cartridge, a very large blocking factor (say 126 or more)
+greatly increases performance. A smaller blocking factor, on the other
+hand, may be useful when archiving small files, to avoid archiving lots
+of nulls as @command{tar} fills out the archive to the end of the record.
+In general, the ideal record size depends on the size of the
+inter-record gaps on the tape you are using, and the average size of the
+files you are archiving. @xref{create}, for information on
+writing archives.
+
+@FIXME{Need example of using a cartridge with blocking factor=126 or more.}
+
+Archives with blocking factors larger than 20 cannot be read
+by very old versions of @command{tar}, or by some newer versions
+of @command{tar} running on old machines with small address spaces.
+With @GNUTAR{}, the blocking factor of an archive is limited
+only by the maximum record size of the device containing the archive,
+or by the amount of available virtual memory.
+
+Also, on some systems, not using adequate blocking factors, as sometimes
+imposed by the device drivers, may yield unexpected diagnostics. For
+example, this has been reported:
+
+@smallexample
+Cannot write to /dev/dlt: Invalid argument
+@end smallexample
+
+@noindent
+In such cases, it sometimes happen that the @command{tar} bundled by
+the system is aware of block size idiosyncrasies, while @GNUTAR{}
+requires an explicit specification for the block size,
+which it cannot guess. This yields some people to consider
+@GNUTAR{} is misbehaving, because by comparison,
+@cite{the bundle @command{tar} works OK}. Adding @w{@kbd{-b 256}},
+for example, might resolve the problem.
+
+If you use a non-default blocking factor when you create an archive, you
+must specify the same blocking factor when you modify that archive. Some
+archive devices will also require you to specify the blocking factor when
+reading that archive, however this is not typically the case. Usually, you
+can use @option{--list} (@option{-t}) without specifying a blocking factor---@command{tar}
+reports a non-default record size and then lists the archive members as
+it would normally. To extract files from an archive with a non-standard
+blocking factor (particularly if you're not sure what the blocking factor
+is), you can usually use the @option{--read-full-records} (@option{-B}) option while
+specifying a blocking factor larger then the blocking factor of the archive
+(i.e., @samp{tar --extract --read-full-records --blocking-factor=300}.
+@xref{list}, for more information on the @option{--list} (@option{-t})
+operation. @xref{Reading}, for a more detailed explanation of that option.
+
+@table @option
+@item --blocking-factor=@var{number}
+@itemx -b @var{number}
+Specifies the blocking factor of an archive. Can be used with any
+operation, but is usually not necessary with @option{--list} (@option{-t}).
+@end table