Version 1.23.90

[chaz/tar] / doc / tar.texi

diff --git a/doc/tar.texi b/doc/tar.texi
index 5ced6d122c76dbd1db9906da62c9e33982b85877..30fa61fcd35180f872ae9bcb5f654d008f2bf55a 100644 (file)
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -330,6 +330,10 @@ Using Less Space through Compression
 * gzip::                        Creating and Reading Compressed Archives
 * sparse::                      Archiving Sparse Files
 
 * 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
 Making @command{tar} Archives More Portable
 
 * Portable Names::              Portable Names


@@ -2684,6 +2688,30 @@ Creates a @acronym{POSIX.1-2001 archive}.
 
 @xref{Formats}, for a detailed discussion of these formats.
 
 
 @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}
 
 @opsummary{group}
 @item --group=@var{group}
 


@@ -8677,7 +8705,7 @@ For example:
 $ @kbd{tar cfz archive.tar.gz .}
 @end smallexample
 
 $ @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
 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


@@ -8742,34 +8770,9 @@ cannot append another @command{tar} archive to a compressed archive using
 @option{--concatenate} (@option{-A}).  Secondly, multi-volume
 archives cannot be compressed.
 
 @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
 
 @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
 @opindex gzip
 @opindex ungzip
 @item -z


@@ -8777,69 +8780,110 @@ suffix.  The following suffixes are recognized:
 @itemx --ungzip
 Filter the archive through @command{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
+@opindex xz

 @item -J
 @itemx --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
 
 @item -j
 @itemx --bzip2

-Filter the archive through @code{bzip2}.  Otherwise like @option{--gzip}.
+Filter the archive through @code{bzip2}.

 
 @opindex lzip
 @item --lzip
 
 @opindex lzip
 @item --lzip

-Filter the archive through @command{lzip}.  Otherwise like @option{--gzip}.
+Filter the archive through @command{lzip}.

 
 @opindex lzma
 @item --lzma
 
 @opindex lzma
 @item --lzma

-Filter the archive through @command{lzma}.  Otherwise like @option{--gzip}.
+Filter the archive through @command{lzma}.

 
 @opindex lzop
 @item --lzop
 
 @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
 
 @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}
 
 @opindex use-compress-program
 @item --use-compress-program=@var{prog}


@@ -8933,6 +8977,45 @@ The above is based on the following discussion:
   end up with less space on the tape.
 @end ignore
 
   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
 @node sparse
 @subsection Archiving Sparse Files
 @cindex Sparse Files


@@ -11355,15 +11438,16 @@ will usually see lots of spurious messages.
 @cindex Labeling an archive
 @cindex Labels on the archive media
 @cindex Labeling multi-volume archives
 @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
 
 @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{--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}
 
 @table @option
 @item --label=@var{archive-label}


@@ -11402,7 +11486,7 @@ V--------- 0 0        0 1992-03-07 12:01 iamalabel--Volume Header--
   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
   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:
 
 first block of an archive, so it can be used with slow storage
 devices.  For example:
 


@@ -11413,16 +11497,35 @@ iamalabel
 @end group
 @end smallexample
 
 @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
 
 @smallexample
 @group

-$ @kbd{tar --test-label --file=iamanarchive 'iamalable'}
+$ @kbd{tar --test-label --file=iamanarchive 'iamalabel'}

 @result{} 0
 @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
 @result{} 1
 @end group
 @end smallexample


@@ -11462,9 +11565,6 @@ 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.
 
 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
   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


@@ -11478,13 +11578,19 @@ $ @kbd{tar --create --file=/dev/tape --multi-volume \
 @end group
 @end smallexample
 
 @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
 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
 
 @node verify
 @section Verifying Data as It is Stored