@titlepage
@title @acronym{GNU} tar: an archiver tool
@subtitle @value{RENDITION} @value{VERSION}, @value{UPDATED}
-@author Melissa Weisshaus, Jay Fenlason,
-@author Thomas Bushnell, n/BSG, Amy Gorin
-@c he said to remove it: Fran@,{c}ois Pinard
-@c i'm thinking about how the author page *should* look. -mew 2may96
+@author John Gilmore, Jay Fenlason et al.
@page
@vskip 0pt plus 1filll
* Date input formats::
* Formats::
* Media::
+
+Appendices
+
+* Genfile::
* Free Software Needs Free Documentation::
* Copying This Manual::
* Index::
* Multi-Volume Archives:: Archives Longer than One Tape or Disk
* Tape Files:: Tape Files
+GNU tar test suite
+
+* Genfile::
+
Copying This Manual
* GNU Free Documentation License:: License for copying this manual
this chapter will cover how to use these operations in detail. We will
present the rest of the operations in the next chapter.
-@table @kbd
+@table @option
@item --create
@itemx -c
Create a new @command{tar} archive.
@node file tutorial
@unnumberedsubsec The @option{--file} Option
-@table @kbd
+@table @option
@item --file=@var{archive-name}
@itemx -f @var{archive-name}
Specify the name of an archive file.
@node verbose tutorial
@unnumberedsubsec The @option{--verbose} Option
-@table @kbd
+@table @option
@item --verbose
@itemx -v
Show the files being worked on as @command{tar} is running.
Sometimes, a single instance of @option{--verbose} on the command line
will show a full, @samp{ls} style listing of an archive or files,
-@c FIXME: Describe the exact output format, e.g., how hard links are displayed.
-giving sizes, owners, and similar information. Other times,
-@option{--verbose} will only show files or members that the particular
+giving sizes, owners, and similar information. @FIXME{Describe the
+exact output format, e.g., how hard links are displayed.}
+Other times, @option{--verbose} will only show files or members that the particular
operation is operating on at the time. In the latter case, you can
use @option{--verbose} twice in a command to get a listing such as that
in the former case. For example, instead of saying
@node help tutorial
@unnumberedsubsec Getting Help: Using the @option{--help} Option
-@table @kbd
+@table @option
@item --help
The @option{--help} option to @command{tar} prints out a very brief list of
@command{tar}, to avoid errors).
Note that the part of the command which says,
-@w{@kbd{--file=collection.tar}} is considered to be @emph{one} argument.
+@w{@option{--file=collection.tar}} is considered to be @emph{one} argument.
If you substituted any other string of characters for
@kbd{collection.tar}, then that string would become the name of the
archive file you create.
want placed in the archive. If you do not specify any archive
members, @GNUTAR{} will complain.
-If you now list the contents of the working directory (@kbd{ls}), you will
+If you now list the contents of the working directory (@command{ls}), you will
find the archive file listed as well as the files you saw previously:
@smallexample
-rw-rw-rw- myself user 62 1990-05-23 10:55 folk
@end smallexample
+@cindex listing member and file names
+@anchor{listing member and file names}
+It is important to notice that the output of @kbd{tar --list
+--verbose} does not necessarily match that produced by @kbd{tar
+--create --verbose} while creating the archive. It is because
+@GNUTAR{}, unless told explicitly not to do so, removes some directory
+prefixes from file names before storing them in the archive
+(@xref{absolute}, for more information). In other
+words, in verbose mode @GNUTAR{} shows @dfn{file names} when creating
+an archive and @dfn{member names} when listing it. Consider this
+example:
+
+@smallexample
+@group
+$ @kbd{tar cfv archive /etc/mail}
+tar: Removing leading `/' from member names
+/etc/mail/
+/etc/mail/sendmail.cf
+/etc/mail/aliases
+$ @kbd{tar tf archive}
+etc/mail/
+etc/mail/sendmail.cf
+etc/mail/aliases
+@end group
+@end smallexample
+
+@cindex @option{--show-stored-names} described
+ This default behavior can sometimes be inconvenient. You can force
+@GNUTAR{} show member names when creating archive by supplying
+@option{--show-stored-names} option.
+
+@table @option
+@item --show-stored-names
+Print member (not @emph{file}) names when creating the archive.
+@end table
+
@cindex File name arguments, using @option{--list} with
@cindex @option{--list} with file name arguments
You can specify one or more individual member names as arguments when
@node Operation Summary
@subsection Operations
-@table @kbd
+@table @option
@item --append
@itemx -r
@node Option Summary
@subsection @command{tar} Options
-@table @kbd
+@table @option
@item --absolute-names
@itemx -P
@item --null
When @command{tar} is using the @option{--files-from} option, this option
-instructs @command{tar} to expect filenames terminated with @kbd{NUL}, so
+instructs @command{tar} to expect filenames terminated with @option{NUL}, so
@command{tar} can correctly work with file names that contain newlines.
@FIXME-xref{}
from @var{string} after substituting the following meta-characters:
@multitable @columnfractions .30 .70
-@item Meta-character @tab Replaced By
+@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 pathname.
@item %f @tab The filename of the file, equivalent to the result
following character substitutions have been made:
@multitable @columnfractions .30 .70
-@item Meta-character @tab Replaced By
+@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.
Instructs @command{tar} to mention directories its skipping over when
operating on a @command{tar} archive. @FIXME-xref{}
+@item --show-stored-names
+
+This option has effect only when used in conjunction with one of
+archive creation operations. It instructs tar to list the member names
+stored in the archive, as opposed to the actual file
+names. @xref{listing member and file names}.
+
@item --sparse
@itemx -S
Specifies the length of tapes that @command{tar} is writing as being
@w{@var{num} x 1024} bytes long. @FIXME-xref{}
+@item --test-label
+
+Reads the volume label. If an argument is specified, test whether it
+matches the volume label. @xref{--test-label option}.
+
@item --to-stdout
@itemx -O
Here is an alphabetized list of all of the short option forms, matching
them with the equivalent long option.
-@table @kbd
+@table @option
@item -A
The five operations that we will cover in this chapter are:
-@table @kbd
+@table @option
@item --append
@itemx -r
Add new entries to an archive that already exists.
@node Ignore Failed Read
@subsection Ignore Fail Read
-@table @kbd
+@table @option
@item --ignore-failed-read
Do not exit with nonzero on unreadable files or directories.
@end table
@FIXME{need sentence or so of intro here}
-@table @kbd
+@table @option
@item --read-full-records
@item -B
Use in conjunction with @value{op-extract} to read an archive which
does not write after the end of an archive, but seeks to
maintain compatiblity among archiving utilities.
-@table @kbd
+@table @option
@item --ignore-zeros
@itemx -i
To ignore blocks of zeros (ie.@: end-of-archive entries) which may be
@node Overwrite Old Files
@unnumberedsubsubsec Overwrite Old Files
-@table @kbd
+@table @option
@item --overwrite
Overwrite existing files and directory metadata when extracting files
from an archive.
@node Keep Old Files
@unnumberedsubsubsec Keep Old Files
-@table @kbd
+@table @option
@item --keep-old-files
@itemx -k
Do not replace existing files from archive. The
@node Keep Newer Files
@unnumberedsubsubsec Keep Newer Files
-@table @kbd
+@table @option
@item --keep-newer-files
Do not replace existing files that are newer than their archive
copies. This option is meaningless with @value{op-list}.
@node Unlink First
@unnumberedsubsubsec Unlink First
-@table @kbd
+@table @option
@item --unlink-first
@itemx -U
Remove files before extracting over them.
@node Recursive Unlink
@unnumberedsubsubsec Recursive Unlink
-@table @kbd
+@table @option
@item --recursive-unlink
When this option is specified, try removing files and directory hierarchies
before extracting over them. @emph{This is a dangerous option!}
the files were extracted, use the @value{op-touch} option in
conjunction with @value{op-extract}.
-@table @kbd
+@table @option
@item --touch
@itemx -m
Sets the modification time of extracted archive members to the time
in conjunction with the @value{op-extract} operation. @FIXME{Should be
aliased to ignore-umask.}
-@table @kbd
+@table @option
@item --preserve-permission
@itemx --same-permission
@itemx --ignore-umask
they appear on standard output concatenated, in the order they are
found in the archive.
-@table @kbd
+@table @option
@item --to-stdout
@itemx -O
Writes files to the standard output. Used in conjunction with
option goes in this section. i have no idea; i only know it's nowhere
else in the book...}
-@table @kbd
+@table @option
@item --remove-files
Remove files after adding them to the archive.
@end table
@node Starting File
@unnumberedsubsubsec Starting File
-@table @kbd
+@table @option
@item --starting-file=@var{name}
@itemx -K @var{name}
Starts an operation in the middle of an archive. Use in conjunction
@node Same Order
@unnumberedsubsubsec Same Order
-@table @kbd
+@table @option
@item --same-order
@itemx --preserve-order
@itemx -s
@end defvr
@defvr {Backup variable} TAPE_FILE
-The device @command{tar} writes the archive to. This device should be
-attached to the host on which the dump scripts are run.
+
+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
or restore. By default it is @file{/etc/backup/files}.
@end defvr
-@defvr {Backup variable} RSH
+@defvr {Backup variable} MT
-Path to @code{rsh} binary or its equivalent. You may wish to
+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
-Path to rsh binary on remote mashines. This will be passed via
-@option{--rsh-command} option to the remote invocation of @GNUTAR{}.
+Full file name of @command{rsh} binary on remote mashines. This will
+be passed via @option{--rsh-command} option to the remote invocation
+of @GNUTAR{}.
@end defvr
@defvr {Backup variable} VOLNO_FILE
@defvr {Backup variable} TAR
-Pathname of the @GNUTAR{} executable. If this is not set, backup
+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
option allows you to either specify or name a file to use as the archive
instead of the default archive file location.
-@table @kbd
+@table @option
@item --file=@var{archive-name}
@itemx -f @var{archive-name}
Name the archive to create or operate on. Use in conjunction with
@cindex Standard input and output
@cindex tar to standard input and output
+@anchor{remote-dev}
To specify an archive file on a device attached to a remote machine,
use the following:
newlines. You will frequently use this option when you have generated
the list of files to archive with the @command{find} utility.
-@table @kbd
+@table @option
@item --files-from=@var{file name}
@itemx -T @var{file name}
Get names to extract or create from file @var{file name}.
@end menu
@node nul
-@subsection @kbd{NUL} Terminated File Names
+@subsection @code{NUL} Terminated File Names
-@cindex File names, terminated by @kbd{NUL}
-@cindex @kbd{NUL} terminated file names
+@cindex File names, terminated by @code{NUL}
+@cindex @code{NUL} terminated file names
The @value{op-null} option causes @value{op-files-from} to read file
names terminated by a @code{NUL} instead of a newline, so files whose
names contain newlines can be archived using @option{--files-from}.
-@table @kbd
+@table @option
@item --null
-Only consider @kbd{NUL} terminated file names, instead of files that
+Only consider @code{NUL} terminated file names, instead of files that
terminate in a newline.
@end table
This example shows how to use @command{find} to generate a list of files
larger than 800K in length and put that list into a file called
@file{long-files}. The @option{-print0} option to @command{find} is just
-like @option{-print}, except that it separates files with a @kbd{NUL}
+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 @kbd{NUL} separator between files.
+@command{tar} to recognize the @code{NUL} separator between files.
@smallexample
$ @kbd{find . -size +800 -print0 > long-files}
To avoid operating on files whose names match a particular pattern,
use the @value{op-exclude} or @value{op-exclude-from} options.
-@table @kbd
+@table @option
@item --exclude=@var{pattern}
Causes @command{tar} to ignore files that match the @var{pattern}.
@end table
You may give multiple @option{--exclude} options.
-@table @kbd
+@table @option
@item --exclude-from=@var{file}
@itemx -X @var{file}
Causes @command{tar} to ignore files that match the patterns listed in
@FIXME{do the exclude options files need to have stuff separated by
newlines the same as the files-from option does?}
-@table @kbd
+@table @option
@item --exclude-caches
Causes @command{tar} to ignore directories containing a cache directory tag.
@end table
specify a particular date against which @command{tar} can compare when
deciding whether or not to archive the files.
-@table @kbd
+@table @option
@item --after-date=@var{date}
@itemx --newer=@var{date}
@itemx -N @var{date}
archive; see @ref{files} for more information on using @command{find} with
@command{tar}, or look.
-@table @kbd
+@table @option
@item --no-recursion
Prevents @command{tar} from recursively descending directories.
@command{tar} will still archive files explicitly named on the command line
or through @value{op-files-from}, regardless of where they reside.
-@table @kbd
+@table @option
@item --one-file-system
@itemx -l
Prevents @command{tar} from crossing file system boundaries when
working directory to the directory @var{directory} after that point in
the list.
-@table @kbd
+@table @option
@item --directory=@var{directory}
@itemx -C @var{directory}
Changes the working directory in the middle of a command line.
@subsection Absolute File Names
@UNREVISED
-@table @kbd
+@table @option
@item -P
@itemx --absolute-names
Do not strip leading slashes from file names, and permit file names
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}.
+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 @value{op-absolute-names} option, @command{tar} will do
none of these transformations.
@FIXME{Is write access an issue?}
-@table @kbd
+@table @option
@item --absolute-names
Preserves full file names (including superior directory names) when
archiving files. Preserves leading slash when extracting files.
formats:
@multitable @columnfractions .10 .20 .20 .20 .20
-@item Format @tab UID @tab File Size @tab Path Name @tab Devn
+@headitem Format @tab UID @tab File Size @tab Path Name @tab Devn
@item gnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
@item oldgnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
@item v7 @tab 2097151 @tab 8GB @tab 99 @tab n/a
@cindex Storing archives in compressed format
@GNUTAR{} is able to create and read compressed archives. It supports
-@command{gzip} and @command{bzip2} compression programms. For backward
+@command{gzip} and @command{bzip2} compression programs. For backward
compatibilty, it also supports @command{compress} command, although
we strongly recommend against using it, since there is a patent
covering the algorithm it uses and you could be sued for patent
The following table summarizes compression options used by @GNUTAR{}.
-@table @kbd
+@table @option
@item -z
@itemx --gzip
@itemx --ungzip
@cindex Sparse Files
@UNREVISED
-@table @kbd
+@table @option
@item -S
@itemx --sparse
Handle sparse files efficiently.
@command{tar} ignores the @value{op-sparse} option when reading an archive.
-@table @kbd
+@table @option
@item --sparse
@itemx -S
Files stored sparsely in the file system are represented sparsely in
Handling of file attributes
-@table @kbd
+@table @option
@item --atime-preserve
Preserve access times on files that are read.
This doesn't work for files that
@section Device Selection and Switching
@UNREVISED
-@table @kbd
+@table @option
@item -f [@var{hostname}:]@var{file}
@itemx --file=[@var{hostname}:]@var{file}
Use archive file or device @var{file} on @var{hostname}.
If the file name contains a @samp{:}, it is interpreted as
@samp{hostname:file name}. If the @var{hostname} contains an @dfn{at}
-sign (@kbd{@@}), it is treated as @samp{user@@hostname:file name}. In
+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
too. The installer could also check for @samp{DEFTAPE} in
@file{<sys/mtio.h>}.
-@table @kbd
+@table @option
@item --force-local
Archive file is local even if it contains a colon.
@xref{list}, for more information on the @value{op-list}
operation. @xref{Reading}, for a more detailed explanation of that option.
-@table @kbd
+@table @option
@item --blocking-factor=@var{number}
@itemx -b @var{number}
Specifies the blocking factor of an archive. Can be used with any
Device blocking
-@table @kbd
+@table @option
@item -b @var{blocks}
@itemx --blocking-factor=@var{blocks}
Set record size to @math{@var{blocks} * 512} bytes.
@FIXME{is there any use for record operations?}
-@table @kbd
+@table @option
@item eof
@itemx weof
Writes @var{number} tape marks at the current position on the tape.
successful, 1 if the command was unrecognized, and 2 if an operation
failed.
-@FIXME{New node on how to find an archive?}
-
-If you use @value{op-extract} with the @value{op-label} option specified,
-@command{tar} will read an archive label (the tape head has to be positioned
-on it) and print an error if the archive label doesn't match the
-@var{archive-name} specified. @var{archive-name} can be any regular
-expression. If the labels match, @command{tar} extracts the archive.
-@value{xref-label}.
-@FIXME-xref{Matching Format Parameters}@FIXME{fix cross
-references}@samp{tar --list --label} will cause @command{tar} to print the
-label.
-
-@FIXME{Program to list all the labels on a tape?}
-
@node Using Multiple Tapes
@section Using Multiple Tapes
@UNREVISED
@FIXME{There should be a sample program here, including an exit
before end. Is the exit status even checked in tar? :-(}
-@table @kbd
+@table @option
@item --multi-volume
@itemx -M
Creates a multi-volume archive, when used in conjunction with
@cindex Labels on the archive media
@UNREVISED
-@table @kbd
-@item -V @var{name}
-@itemx --label=@var{name}
-Create archive with volume name @var{name}.
-@end table
-
-This option causes @command{tar} to write out a @dfn{volume header} at
-the beginning of the archive. If @value{op-multi-volume} is used, each
-volume of the archive will have a volume header of @samp{@var{name}
-Volume @var{n}}, where @var{n} is 1 for the first volume, 2 for the
-next, and so on.
-
-@FIXME{Should the arg to --label be a quoted string?? No.}
-
-To avoid problems caused by misplaced paper labels on the archive
+@cindex @option{--label} option introduced
+@cindex @option{-V} option introduced
+ To avoid problems caused by misplaced paper labels on the archive
media, you can include a @dfn{label} entry---an archive member which
contains the name of the archive---in the archive itself. Use the
@value{op-label} option in conjunction with the @value{op-create} operation
to include a label entry in the archive as it is being created.
-If you create an archive using both @value{op-label} and
+@table @option
+@item --label=@var{archive-label}
+@itemx -V @var{archive-label}
+Includes an @dfn{archive-label} at the beginning of the archive when
+the archive is being created, when used in conjunction with the
+@value{op-create} operation. Checks to make sure the archive label
+matches the one specified (when used in conjunction with any other
+operation.
+@end table
+
+ If you create an archive using both @value{op-label} and
@value{op-multi-volume}, each volume of the archive will have an
archive label of the form @samp{@var{archive-label} Volume @var{n}},
where @var{n} is 1 for the first volume, 2 for the next, and so on.
@FIXME-xref{Multi-Volume Archives, for information on creating multiple
volume archives.}
-If you list or extract an archive using @value{op-label}, @command{tar} will
-print an error if the archive label doesn't match the @var{archive-label}
-specified, and will then not list nor extract the archive. In those cases,
-@var{archive-label} argument is interpreted as a globbing-style pattern
-which must match the actual magnetic volume label. @xref{exclude}, for
-a precise description of how match is attempted@footnote{Previous versions
-of @command{tar} used full regular expression matching, or before that, only
-exact string matching, instead of wildcard matchers. We decided for the
-sake of simplicity to use a uniform matching device through @command{tar}.}.
-If the switch @value{op-multi-volume} is being used, the volume label
-matcher will also suffix @var{archive-label} by @w{@samp{ Volume [1-9]*}}
-if the initial match fails, before giving up. Since the volume numbering
-is automatically added in labels at creation time, it sounded logical to
-equally help the user taking care of it when the archive is being read.
-
-The @value{op-label} was once called @option{--volume}, but is not available
-under that name anymore.
-
-To find out an archive's label entry (or to find out if an archive has
-a label at all), use @samp{tar --list --verbose}. @command{tar} will
-print the label first, and then print archive member information, as
-in the example below:
+@cindex Volume label, listing
+@cindex Listing volume label
+ The volume label will be displayed by @option{--list} along with
+the file contents. If verbose display is requested, it will also be
+explicitely marked as in the example below:
@smallexample
+@group
$ @kbd{tar --verbose --list --file=iamanarchive}
V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header--
-rw-rw-rw- ringo user 40 1990-05-21 13:30 iamafilename
+@end group
@end smallexample
-@table @kbd
-@item --label=@var{archive-label}
-@itemx -V @var{archive-label}
-Includes an @dfn{archive-label} at the beginning of the archive when
-the archive is being created, when used in conjunction with the
-@value{op-create} option. Checks to make sure the archive label
-matches the one specified (when used in conjunction with the
-@value{op-extract} option.
-@end table
+@cindex @option{--test-label} option introduced
+@anchor{--test-label option}
+ However, @option{--list} option will cause listing entire
+contents of the archive, which may be undesirable (for example, if the
+archive is stored on a tape). You can request checking only the volume
+by specifying @option{--test-label} option. This option reads only the
+first block of an archive, so it can be used with slow storage
+devices. For example:
+
+@smallexample
+@group
+$ @kbd{tar --test-label --file=iamanarchive}
+iamalabel
+@end group
+@end smallexample
+
+ If @option{--test-label} is used with a single command line
+argument, @command{tar} compares the volume label with the
+argument. It exits with code 0 if the two strings match, and with code
+2 otherwise. In this case no output is displayed. For example:
-To get a common information on all tapes of a series, use the
-@value{op-label} option. For having this information different in each
+@smallexample
+@group
+$ @kbd{tar --test-label --file=iamanarchive 'iamalable'}
+@result{} 0
+$ @kbd{tar --test-label --file=iamanarchive 'iamalable' alabel}
+@result{} 1
+@end group
+@end smallexample
+
+ If you request any operation, other than @option{--create}, along
+with using @option{--label} option, @command{tar} will first check if
+the archive label matches the one specified and will refuse to proceed
+if it does not. Use this as a safety precaution to avoid accidentally
+overwriting existing archives. For example, if you wish to add files
+to @file{archive}, presumably labelled with string @samp{My volume},
+you will get:
+
+@smallexample
+@group
+$ @kbd{tar -rf archive --label 'My volume' .}
+tar: Archive not labeled to match `My volume'
+@end group
+@end smallexample
+
+@noindent
+in case its label does not match. This will work even if
+@file{archive} is not labelled at all.
+
+ Similarly, @command{tar} will refuse to list or extract the
+archive if its label doesn't match the @var{archive-label}
+specified. In those cases, @var{archive-label} argument is interpreted
+as a globbing-style pattern which must match the actual magnetic
+volume label. @xref{exclude}, for a precise description of how match
+is attempted@footnote{Previous versions of @command{tar} used full
+regular expression matching, or before that, only exact string
+matching, instead of wildcard matchers. We decided for the sake of
+simplicity to use a uniform matching device through
+@command{tar}.}. If the switch @value{op-multi-volume} is being used,
+the volume label matcher will also suffix @var{archive-label} by
+@w{@samp{ Volume [1-9]*}} if the initial match fails, before giving
+up. Since the volume numbering is automatically added in labels at
+creation time, it sounded logical to equally help the user taking care
+of it when the archive is being read.
+
+ The @value{op-label} was once called @option{--volume}, but is not available
+under that name anymore.
+
+ You can also use @option{--label} to get a common information on
+all tapes of a series. For having this information different in each
series created through a single script used on a regular basis, just
manage to get some date string as part of the label. For example:
@smallexample
+@group
$ @kbd{tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`"}
$ @kbd{tar --create --file=/dev/tape --multi-volume \
--volume="Daily backup for `date +%Y-%m-%d`"}
+@end group
@end smallexample
-Also note that each label has its own date and time, which corresponds
+ Also note that each label has its own date and time, which corresponds
to when @GNUTAR{} initially attempted to write it,
often soon after the operator launches @command{tar} or types the
carriage return telling that the next tape is ready. Comparing date
rewinding tapes and the operator switching them were negligible, which
is usually not the case.
-@FIXME{was --volume}
-
@node verify
@section Verifying Data as It is Stored
@cindex Verifying a write operation
@cindex Double-checking a write operation
-@table @kbd
+@table @option
@item -W
@itemx --verify
Attempt to verify the archive after writing.
@appendix Free Software Needs Free Documentation
@include freemanuals.texi
+@node Genfile
+@appendix Genfile
+@include genfile.texi
+
@node Copying This Manual
@appendix Copying This Manual