two frequently used options (@samp{file} and @samp{verbose}). The other
chapters do not refer to the tutorial frequently; however, if a section
discusses something which is a complex variant of a basic concept, there
-may be a cross reference to that basic concept. (The entire book,
+may be a cross-reference to that basic concept. (The entire book,
including the tutorial, assumes that the reader understands some basic
concepts of using a Unix-type operating system; @pxref{Tutorial}.)
Here is an example of what you can see using this option:
@smallexample
-$ tar --show-defaults
+$ @kbd{tar --show-defaults}
--format=gnu -f- -b20 --quoting-style=escape
--rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
@end smallexample
@opsummary{uncompress}
@item --uncompress
-(See @option{--compress}. @pxref{gzip})
+(See @option{--compress}, @pxref{gzip})
@opsummary{ungzip}
@item --ungzip
-(See @option{--gzip}. @pxref{gzip})
+(See @option{--gzip}, @pxref{gzip})
@opsummary{unlink-first}
@item --unlink-first
@end smallexample
@xref{Writing}, for more information on @option{--extract} and
-@xref{Option Summary, --occurrence}, for the description of
+see @ref{Option Summary, --occurrence}, for a description of
@option{--occurrence} option.
@node update
@file{classical}, in your practice directory, and some extra text to the
file @file{blues}, using any text editor. Then invoke @command{tar} with
the @samp{update} operation and the @option{--verbose} (@option{-v})
-option specified, using the names of all the files in the practice
+option specified, using the names of all the files in the @file{practice}
directory as file name arguments:
@smallexample
@option{--file} option and name the rest of archives to be
concatenated on the command line. The members, and their member
names, will be copied verbatim from those archives to the first
-one@footnote{This can cause multiple members to have the same name, for
-information on how this affects reading the archive, @ref{multiple}.}.
+one@footnote{This can cause multiple members to have the same name. For
+information on how this affects reading the archive, see @ref{multiple}.}.
The new, concatenated archive will be called by the same name as the
one given with the @option{--file} option. As usual, if you omit
@option{--file}, @command{tar} will use the value of the environment
The spirit behind the @option{--compare} (@option{--diff},
@option{-d}) option is to check whether the archive represents the
current state of files on disk, more than validating the integrity of
-the archive media. For this latter goal, @xref{verify}.
+the archive media. For this latter goal, see @ref{verify}.
@node create options
@section Options Used by @option{--create}
with @samp{/} or @samp{.}. In the latter case, the modification time
of that file will be used.
-The following example will set the modification date to 00:00:00 UTC,
+The following example will set the modification date to 00:00:00,
January 1, 1970:
@smallexample
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}.)
+the file system, and then resume the same @command{tar} operation.
+In this case, @option{--starting-file} is not necessary.) See also
+@ref{interactive}, and @ref{exclude}.
@node Same Order
@unnumberedsubsubsec Same Order
The command also works using long option forms:
@smallexample
+@group
$ @kbd{(cd sourcedir; tar --create --file=- . ) \
| (cd targetdir; tar --extract --file=-)}
+@end group
@end smallexample
@noindent
or
@smallexample
-$ @kbd{tar --directory sourcedir --create --file=- . ) \
+@group
+$ @kbd{tar --directory sourcedir --create --file=- . \
| tar --directory targetdir --extract --file=-}
+@end group
@end smallexample
@noindent
--show-transformed /lib}
drwxr-xr-x root/root 0 2008-07-08 16:20 /usr/local/lib/
-rwxr-xr-x root/root 1250840 2008-05-25 07:44 /usr/local/lib/libc-2.3.2.so
-lrwxrwxrwx root/root 0 2008-06-24 17:12 /usr/local/lib/libc.so.6 ->
-libc-2.3.2.so
+lrwxrwxrwx root/root 0 2008-06-24 17:12 /usr/local/lib/libc.so.6 \
+ -> libc-2.3.2.so
@end smallexample
Unlike @option{--strip-components}, @option{--transform} can be used
@end smallexample
For a complete list of file name suffixes recognized by @GNUTAR{},
-@ref{auto-compress}.
+see @ref{auto-compress}.
Reading compressed archive is even simpler: you don't need to specify
any additional options as @GNUTAR{} recognizes its format
special byte sequences in the beginning of file, that are specific for
certain compression formats. If this approach fails, @command{tar}
falls back to using archive name suffix to determine its format
-(@xref{auto-compress}, for a list of recognized suffixes).
+(@pxref{auto-compress}, for a list of recognized suffixes).
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
@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
+still has many restrictions (@pxref{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}.
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
+@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}).}.
@option{--multi-volume} (@pxref{Using Multiple Tapes}), then the
volume label will have @samp{Volume @var{nnn}} appended to the name
you give, where @var{nnn} is the number of the volume of the archive.
-If you use the @option{--label=@var{volume-label}}) option when
+If you use the @option{--label=@var{volume-label}} option when
reading an archive, it checks to make sure the label on the tape
-matches the one you give. @xref{label}.
+matches the one you gave. @xref{label}.
When @command{tar} writes an archive to tape, it creates a single
tape file. If multiple archives are written to the same tape, one
@cindex Labeling an archive
@cindex Labels on the archive media
@cindex Labeling multi-volume archives
-@UNREVISED
@opindex label
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
+media, you can include a @dfn{label} entry --- an archive member which
+contains the name of the archive --- in the archive itself. Use the
@option{--label=@var{archive-label}} (@option{-V @var{archive-label}})
-option in conjunction with the @option{--create} operation to include
-a label entry in the archive as it is being created.
+option@footnote{Until version 1.10, that option was called
+@option{--volume}, but is not available under that name anymore.} in
+conjunction with the @option{--create} operation to include a label
+entry in the archive as it is being created.
@table @option
@item --label=@var{archive-label}
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
+label 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:
@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:
+ If @option{--test-label} is used with one or more command line
+arguments, @command{tar} compares the volume label with each
+argument. It exits with code 0 if a match is found, and with code 1
+otherwise@footnote{Note that @GNUTAR{} versions up to 1.23 indicated
+mismatch with an exit code 2 and printed a spurious diagnostics on
+stderr.}. No output is displayed, unless you also used the
+@option{--verbose} option. For example:
+
+@smallexample
+@group
+$ @kbd{tar --test-label --file=iamanarchive 'iamalabel'}
+@result{} 0
+$ @kbd{tar --test-label --file=iamanarchive 'alabel'}
+@result{} 1
+@end group
+@end smallexample
+
+ When used with the @option{--verbose} option, @command{tar}
+prints the actual volume label (if any), and a verbose diagnostics in
+case of a mismatch:
@smallexample
@group
-$ @kbd{tar --test-label --file=iamanarchive 'iamalable'}
+$ @kbd{tar --test-label --verbose --file=iamanarchive 'iamalabel'}
+iamalabel
@result{} 0
-$ @kbd{tar --test-label --file=iamanarchive 'iamalable' alabel}
+$ @kbd{tar --test-label --verbose --file=iamanarchive 'alabel'}
+iamalabel
+tar: Archive label mismatch
@result{} 1
@end group
@end smallexample
creation time, it sounded logical to equally help the user taking care
of it when the archive is being read.
- The @option{--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
@end group
@end smallexample
- Also note that each label has its own date and time, which corresponds
-to when @GNUTAR{} initially attempted to write it,
+ Some more notes about volume labels:
+
+@itemize @bullet
+@item Each label has its own date and time, which corresponds
+to the time 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
-labels does give an idea of tape throughput only if the delays for
-rewinding tapes and the operator switching them were negligible, which
-is usually not the case.
+carriage return telling that the next tape is ready.
+
+@item Comparing date labels to get an idea of tape throughput is
+unreliable. It gives correct results only if the delays for rewinding
+tapes and the operator switching them were negligible, which is
+usually not the case.
+@end itemize
@node verify
@section Verifying Data as It is Stored
This appendix contains an index of all @GNUTAR{} long command line
options. The options are listed without the preceding double-dash.
-For a cross-reference of short command line options, @ref{Short Option Summary}.
+For a cross-reference of short command line options, see
+@ref{Short Option Summary}.
@printindex op
projects / chaz / tar / blobdiff