* gzip:: Creating and Reading Compressed Archives
* sparse:: Archiving Sparse Files
+Creating and Reading Compressed Archives
+
+* lbzip2:: Using lbzip2 with @GNUTAR{}.
+
Making @command{tar} Archives More Portable
* Portable Names:: Portable Names
@xref{Formats}, for a detailed discussion of these formats.
+@opsummary{full-time}
+@item --full-time
+This option instructs @command{tar} to print file times to their full
+resolution. Usually this means 1-second resolution, but that depends
+on the underlying file system. The @option{--full-time} option takes
+effect only when detailed output (verbosity level 2 or higher) has
+been requested using the @option{--verbose} option, e.g., when listing
+or extracting archives:
+
+@smallexample
+$ @kbd{tar -t -v --full-time -f archive.tar}
+@end smallexample
+
+@noindent
+or, when creating an archive:
+
+@smallexample
+$ @kbd{tar -c -vv --full-time -f archive.tar .}
+@end smallexample
+
+Notice, thar when creating the archive you need to specify
+@option{--verbose} twice to get a detailed output (@pxref{verbose
+tutorial}).
+
@opsummary{group}
@item --group=@var{group}
$ @kbd{tar cfz archive.tar.gz .}
@end smallexample
-You can also let @GNUTAR{} select the compression program basing on
+You can also let @GNUTAR{} select the compression program based 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
@option{--concatenate} (@option{-A}). Secondly, multi-volume
archives cannot be compressed.
-The following table summarizes compression options used by @GNUTAR{}.
+The following options allow to select a particular compressor program:
@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{.lz} @tab @command{lzip}
-@item @samp{.lzma} @tab @command{lzma}
-@item @samp{.tlz} @tab @command{lzma}
-@item @samp{.lzo} @tab @command{lzop}
-@item @samp{.xz} @tab @command{xz}
-@end multitable
-
@opindex gzip
@opindex ungzip
@item -z
@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
+@opindex xz
@item -J
@itemx --xz
-Filter the archive through @code{xz}. Otherwise like
-@option{--gzip}.
+Filter the archive through @code{xz}.
@item -j
@itemx --bzip2
-Filter the archive through @code{bzip2}. Otherwise like @option{--gzip}.
+Filter the archive through @code{bzip2}.
@opindex lzip
@item --lzip
-Filter the archive through @command{lzip}. Otherwise like @option{--gzip}.
+Filter the archive through @command{lzip}.
@opindex lzma
@item --lzma
-Filter the archive through @command{lzma}. Otherwise like @option{--gzip}.
+Filter the archive through @command{lzma}.
@opindex lzop
@item --lzop
-Filter the archive through @command{lzop}. Otherwise like
-@option{--gzip}.
+Filter the archive through @command{lzop}.
@opindex compress
@opindex uncompress
@item -Z
@itemx --compress
@itemx --uncompress
-Filter the archive through @command{compress}. Otherwise like @option{--gzip}.
+Filter the archive through @command{compress}.
+@end table
+
+When any of these options is given, @GNUTAR{} searches the compressor
+binary in the current path and invokes it. The name of the compressor
+program is specified at compilation time using a corresponding
+@option{--with-@var{compname}} option to @command{configure}, e.g.
+@option{--with-bzip2} to select a specific @command{bzip2} binary.
+@xref{lbzip2}, for a detailed discussion.
+
+The output produced by @command{tar --help} shows the actual
+compressor names along with each of these options.
+
+You can use any of these options 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. Most compression
+programs allow to override these by setting a program-specific
+environment variable. For example, when using @command{gzip} you can
+use @env{GZIP} as in the example below:
+
+@smallexample
+$ @kbd{GZIP=--best tar cfz archive.tar.gz subdir}
+@end smallexample
+
+@noindent
+Another way would be to use the @option{-I} option instead (see
+below), e.g.:
+
+@smallexample
+$ @kbd{tar -cf archive.tar.gz -I 'gzip --best' subdir}
+@end smallexample
+
+@noindent
+Finally, the third, traditional, way to achieve the same result is to
+use pipe:
+
+@smallexample
+$ @kbd{tar cf - subdir | gzip --best -c - > archive.tar.gz}
+@end smallexample
+
+@cindex corrupted archives
+About corrupted compressed archives: compressed 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.
+
+Another compression options provide a better control over creating
+compressed archives. These are:
+
+@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{.lz} @tab @command{lzip}
+@item @samp{.lzma} @tab @command{lzma}
+@item @samp{.tlz} @tab @command{lzma}
+@item @samp{.lzo} @tab @command{lzop}
+@item @samp{.xz} @tab @command{xz}
+@end multitable
@opindex use-compress-program
@item --use-compress-program=@var{prog}
end up with less space on the tape.
@end ignore
+@menu
+* lbzip2:: Using lbzip2 with @GNUTAR{}.
+@end menu
+
+@node lbzip2
+@subsubsection Using lbzip2 with @GNUTAR{}.
+@cindex lbzip2
+@cindex Laszlo Ersek
+ @command{Lbzip2} is a multithreaded utility for handling
+@samp{bzip2} compression, written by Laszlo Ersek. It makes use of
+multiple processors to speed up its operation and in general works
+considerably faster than @command{bzip2}. For a detailed description
+of @command{lbzip2} see @uref{http://freshmeat.net/@/projects/@/lbzip2} and
+@uref{http://www.linuxinsight.com/@/lbzip2-parallel-bzip2-utility.html,
+lbzip2: parallel bzip2 utility}.
+
+ Recent versions of @command{lbzip2} are mostly command line compatible
+with @command{bzip2}, which makes it possible to automatically invoke
+it via the @option{--bzip2} @GNUTAR{} command line option. To do so,
+@GNUTAR{} must be configured with the @option{--with-bzip2} command
+line option, like this:
+
+@smallexample
+$ @kbd{./configure --with-bzip2=lbzip2 [@var{other-options}]}
+@end smallexample
+
+ Once configured and compiled this way, @command{tar --help} will show the
+following:
+
+@smallexample
+@group
+$ @kbd{tar --help | grep -- --bzip2}
+ -j, --bzip2 filter the archive through lbzip2
+@end group
+@end smallexample
+
+@noindent
+which means that running @command{tar --bzip2} will invoke @command{lbzip2}.
+
@node sparse
@subsection Archiving Sparse Files
@cindex Sparse Files
@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 'iamalable'}
+$ @kbd{tar --test-label --file=iamanarchive 'iamalabel'}
@result{} 0
-$ @kbd{tar --test-label --file=iamanarchive 'iamalable' alabel}
+$ @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 --verbose --file=iamanarchive 'iamalabel'}
+iamalabel
+@result{} 0
+$ @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
projects / chaz / tar / blobdiff