X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;ds=sidebyside;f=doc%2Ftar.texi;h=fe09c1275df27554bbf012ddc63046ea5097774f;hb=be34933b638b75a40513ea2b724c756b1f8e3b85;hp=43970adf3c2913ad8acf1d0da696d2b39973ad80;hpb=57bfbbde90dfcc18ee6b1e27c01ba915ecc56312;p=chaz%2Ftar

diff --git a/doc/tar.texi b/doc/tar.texi
index 43970ad..fe09c12 100644
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -35,7 +35,7 @@ This manual is for @acronym{GNU} @command{tar} (version
 from archives.
 
 Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
-2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -1429,12 +1429,12 @@ example:
 
 @smallexample
 @group
-$ @kbd{tar cfv archive /etc/mail}
+$ @kbd{tar --create --verbose --file archive /etc/mail}
 tar: Removing leading `/' from member names
 /etc/mail/
 /etc/mail/sendmail.cf
 /etc/mail/aliases
-$ @kbd{tar tf archive}
+$ @kbd{tar --test --file archive}
 etc/mail/
 etc/mail/sendmail.cf
 etc/mail/aliases
@@ -1879,15 +1879,14 @@ will act on the entire contents of the archive.
 @cindex return status
 Besides successful exits, @GNUTAR{} may fail for
 many reasons.  Some reasons correspond to bad usage, that is, when the
-@command{tar} command is improperly written.  Errors may be
-encountered later, while encountering an error processing the archive
-or the files.  Some errors are recoverable, in which case the failure
-is delayed until @command{tar} has completed all its work.  Some
-errors are such that it would not meaningful, or at least risky, to
-continue processing: @command{tar} then aborts processing immediately.
-All abnormal exits, whether immediate or delayed, should always be
-clearly diagnosed on @code{stderr}, after a line stating the nature of
-the error.
+@command{tar} command line is improperly written.  Errors may be
+encountered later, while processing the archive or the files.  Some
+errors are recoverable, in which case the failure is delayed until
+@command{tar} has completed all its work.  Some errors are such that
+it would be not meaningful, or at least risky, to continue processing:
+@command{tar} then aborts processing immediately.  All abnormal exits,
+whether immediate or delayed, should always be clearly diagnosed on
+@code{stderr}, after a line stating the nature of the error.
 
 Possible exit codes of @GNUTAR{} are summarized in the following
 table:
@@ -1924,7 +1923,7 @@ remote device (@pxref{Remote Tape Server}).
 allow you to perform a variety of tasks.  You are required to choose
 one operating mode each time you employ the @command{tar} program by
 specifying one, and only one operation as an argument to the
-@command{tar} command (two lists of four operations each may be found
+@command{tar} command (the corresponding options may be found
 at @ref{frequent operations} and @ref{Operations}).  Depending on
 circumstances, you may also wish to customize how the chosen operating
 mode behaves.  For example, you may wish to change the way the output
@@ -2786,7 +2785,6 @@ incremental format.  @xref{Incremental Dumps}.
 
 @opsummary{lzma}
 @item --lzma
-@itemx -J
 
 This option tells @command{tar} to read or write archives through
 @command{lzma}.  @xref{gzip}.
@@ -2905,13 +2903,6 @@ characters set by the previous @option{--quote-chars} option
 With this option, @command{tar} will not recurse into directories.
 @xref{recurse}.
 
-@opsummary{no-transform-symlinks}
-@item --no-transform-symlinks
-Cancel the effect of any prior @command{--transform-symlinks} option
-(see below) and return to the default behavior of applying name
-transformation expression only to the names of files (archive
-members), not to target of symbolic links.
-
 @opsummary{no-same-owner}
 @item --no-same-owner
 @itemx -o
@@ -3292,11 +3283,6 @@ To see transformed member names in verbose listings, use
 @option{--show-transformed-names} option
 (@pxref{show-transformed-names}).
 
-@opsummary{transform-symlinks}
-@item --transform-symlinks
-Apply @command{--transform} option to symbolic link targets
-(@pxref{transform}).
-
 @opsummary{uncompress}
 @item --uncompress
 
@@ -3321,6 +3307,7 @@ name quoting}.
 
 @opsummary{use-compress-program}
 @item --use-compress-program=@var{prog}
+@itemx -I=@var{prog}
 
 Instructs @command{tar} to access the archive through @var{prog}, which is
 presumed to be a compression program of some sort.  @xref{gzip}.
@@ -3370,6 +3357,12 @@ Use wildcards when matching member names with patterns.
 @item --wildcards-match-slash
 Wildcards match @samp{/}.
 @xref{controlling pattern-matching}.
+
+@opsummary{xz}
+@item --xz
+@itemx -J
+Use @command{xz} for compressing or decompressing the archives.  @xref{gzip}.
+
 @end table
 
 @node Short Option Summary
@@ -3391,7 +3384,7 @@ them with the equivalent long option.
 
 @item -G @tab @ref{--incremental}.
 
-@item -J @tab @ref{--lzma}.
+@item -J @tab @ref{--xz}.
 
 @item -K @tab @ref{--starting-file}.
 
@@ -3753,7 +3746,7 @@ If @option{--block-number} (@option{-R}) is used, @command{tar} prints, along wi
 every message it would normally produce, the block number within the
 archive where the message was triggered.  Also, supplementary messages
 are triggered when reading blocks full of NULs, or when hitting end of
-file on the archive.  As of now, if the archive if properly terminated
+file on the archive.  As of now, if the archive is properly terminated
 with a NUL block, the reading of the file may stop before end of file
 is met, so the position of end of file will not usually show when
 @option{--block-number} (@option{-R}) is used.  Note that @GNUTAR{}
@@ -4150,7 +4143,7 @@ The five operations that we will cover in this chapter are:
 @itemx -r
 Add new entries to an archive that already exists.
 @item --update
-@itemx -r
+@itemx -u
 Add more recent copies of archive members to the end of an archive, if
 they exist.
 @item --concatenate
@@ -5358,9 +5351,9 @@ 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.)
+as having similar names through the side-effect of name truncation.
+@FIXME{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.
@@ -7605,8 +7598,8 @@ 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
+If you add the @option{--verbose} (@option{-v}) option to the invocation
+above, 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:
@@ -7631,7 +7624,7 @@ stdlib.h
 @end group
 @end smallexample
 
-Notice that in both cases the file is @file{stdlib.h} extracted to the
+Notice that in both cases the file @file{stdlib.h} is extracted to the
 current working directory, @option{--show-transformed-names} affects
 only the way its name is displayed.
 
@@ -7677,6 +7670,21 @@ 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}.
 
+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/\//-/}.
+
 As in @command{sed}, you can give several replace expressions,
 separated by a semicolon.
 
@@ -7707,21 +7715,41 @@ the interaction is defined to be: ignore matches before the
 
 @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:
+In addition, several @dfn{transformation scope} flags are supported,
+that control to what files transformations apply.  These are:
+
+@table @samp
+@item r
+Apply transformation to regular archive members.
+
+@item R
+Do not apply transformation to regular archive members.
+
+@item s
+Apply transformation to symbolic link targets.
+
+@item S
+Do not apply transformation to symbolic link targets.
+
+@item h
+Apply transformation to hard link targets.
+
+@item H
+Do not apply transformation to hard link targets.
+@end table
+
+Default is @samp{rsh}, which means to apply tranformations to both archive
+members and targets of symbolic and hard links.
+
+Default scope flags can also be changed using @samp{flags=} statement
+in the transform expression.  The flags set this way remain in force
+until next @samp{flags=} statement or end of expression, whichever
+occurs first.  For example:
 
 @smallexample
-@group
-s/one/two/
-s,one,two,
-@end group
+  --transform 'flags=S;s|^|/usr/local/|'
 @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
@@ -7738,61 +7766,59 @@ $ @kbd{tar --transform='s,usr/,usr/local/,' -x -f arch.tar}
 $ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -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
+
 @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:
+@item Archive the @file{/lib} directory, prepending @samp{/usr/local}
+to each archive member:
 
 @smallexample
-$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar}
+$ @kbd{tar --transform 's,^,/usr/local/,S' -c -f arch.tar /lib}
 @end smallexample
-
 @end enumerate
 
-The @option{--transform} option applies only to member names.  It does
-not apply to symbolic link targets.  In many cases, this is the
-desired behavior.  Consider for example, archiving the @file{/lib}
-directory: 
+Notice the use of flags in the last example.  The @file{/lib}
+directory often contains many symbolic links to files within it.
+It may look, for example, like this:
 
 @smallexample
-$ @kbd{tar -vv -c -f archive /lib}
-tar: Removing leading `/' from member names
+$ @kbd{ls -l}
 drwxr-xr-x root/root       0 2008-07-08 16:20 /lib/
 -rwxr-xr-x root/root 1250840 2008-05-25 07:44 /lib/libc-2.3.2.so
 lrwxrwxrwx root/root       0 2008-06-24 17:12 /lib/libc.so.6 -> libc-2.3.2.so
 ...
 @end smallexample
 
-Now, you can use our example above to extract it into @file{/usr/local}:
+Using the expression @samp{s,^,/usr/local/,} would mean adding
+@samp{/usr/local} to both regular archive members and to link
+targets. In this case, @file{/lib/libc.so.6} would become:
 
 @smallexample
-$ @kbd{tar --transform 's,^,/usr/local/,' \
-  --show-transformed -v -x -f archive}
+  /usr/local/lib/libc.so.6 -> /usr/local/libc-2.3.2.so
+@end smallexample
+
+This is definitely not desired.  To avoid this, the @samp{S} flag
+are used, which excludes symbolic link targets from filename
+transformations.  The result is:
+
+@smallexample
+$ @kbd{tar --transform 's,^,/usr/local/,S', -c -v -f arch.tar \
+       --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
 @end smallexample
 
-As you see, it correctly extracts @file{libc.so.6} as a symbolic link
-to @file{libc-2.3.2.so}.
-
-However, sometimes you may need to transform symbolic link targets as
-well.  To do so, @GNUTAR provides an additional option:
-
-@table @option
-@opindex transform-symlinks
-@item --transform-symlinks
-Apply @command{--transform} option to symbolic link targets.
-
-@opindex no-transform-symlinks
-@itemx --no-transform-symlinks
-Cancel the effect of the previous @option{--transform-symlinks} option.
-@end table
-
 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/}
@@ -8384,7 +8410,8 @@ Creating a compressed archive is simple: you just specify a
 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,
-@option{-J} (@option{--lzma}) to create an @asis{LZMA} compressed
+@option{-J} (@option{--xz}) to create an @asis{XZ} archive, 
+@option{--lzma} to create an @asis{LZMA} compressed
 archive, @option{--lzop} to create an @asis{LSOP} archive, and
 @option{-Z} (@option{--compress}) to use @command{compress} program.
 For example:
@@ -8482,6 +8509,7 @@ suffix.  The following suffixes are recognized:
 @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
@@ -8526,13 +8554,17 @@ lose some compressibility.  But this would have make recovering easier.
 So, there are pros and cons.  We'll see!
 
 @opindex bzip2
+@item -J
+@itemx --xz
+Filter the archive through @code{xz}.  Otherwise like
+@option{--gzip}.
+
 @item -j
 @itemx --bzip2
 Filter the archive through @code{bzip2}.  Otherwise like @option{--gzip}.
 
 @opindex lzma
 @item --lzma
-@itemx -J
 Filter the archive through @command{lzma}.  Otherwise like @option{--gzip}.
 
 @opindex lzop
@@ -8549,6 +8581,7 @@ Filter the archive through @command{compress}.  Otherwise like @option{--gzip}.
 
 @opindex use-compress-program
 @item --use-compress-program=@var{prog}
+@itemx -I=@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:
@@ -8587,14 +8620,14 @@ Suppose you name it @file{gpgz} and save it somewhere in your
 archive signed with your private key:
 
 @smallexample
-$ @kbd{tar -cf foo.tar.gpgz --use-compress=gpgz .}
+$ @kbd{tar -cf foo.tar.gpgz -Igpgz .}
 @end smallexample
 
 @noindent
-Likewise, the following command will list its contents:
+Likewise, the command below will list its contents:
 
 @smallexample
-$ @kbd{tar -tf foo.tar.gpgz --use-compress=gpgz .}
+$ @kbd{tar -tf foo.tar.gpgz -Igpgz .}
 @end smallexample
 
 @ignore
@@ -8866,11 +8899,7 @@ This option is meaningless with @option{--list} (@option{-t}).
 @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}
+This option is deprecated, and will be removed in @GNUTAR{} version 1.23.
 
 @end table
 
@@ -9256,7 +9285,7 @@ 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
+accepts 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