X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=210639e03faac6d25210f7a16198d26822f04189;hb=7b68ef3d918603f3afb03e939ba72f5cad10edf4;hp=72d6aeeb0a8d77a42d306e9b2da4c11b31b12768;hpb=c9a7297a8a135c0afd8f984b91578a822ba3b04c;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index 72d6aee..210639e 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -2880,6 +2880,13 @@ Use case-sensitive matching. Print warnings about subprocesses that terminated with a nonzero exit code. @xref{Writing to an External Program}. +@opsummary{no-null} +@item --no-null + +If the @option{--null} option was given previously, this option +cancels its effect, so that any following @option{--files-from} +options will expect their file lists to be newline-terminated. + @opsummary{no-overwrite-dir} @item --no-overwrite-dir @@ -3259,8 +3266,9 @@ rather than the data modification time stored in the archive. @xref{Data Modification Times}. @opsummary{transform} +@opsummary{xform} @item --transform=@var{sed-expr} - +@itemx --xform=@var{sed-expr} Transform file or member names using @command{sed} replacement expression @var{sed-expr}. For example, @@ -3301,6 +3309,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}. @@ -3901,15 +3910,15 @@ The name of the archive @command{tar} is processing. @vrindex TAR_BLOCKING_FACTOR, checkpoint script environment @item TAR_BLOCKING_FACTOR -Current blocking factor (@pxref{Blocking}. +Current blocking factor (@pxref{Blocking}). @vrindex TAR_CHECKPOINT, checkpoint script environment @item TAR_CHECKPOINT -The checkpoint number. +Number of the checkpoint. @vrindex TAR_SUBCOMMAND, checkpoint script environment @item TAR_SUBCOMMAND -A short option describing the operation @command{tar} is executing +A short option describing the operation @command{tar} is executing. @xref{Operations}, for a complete list of subcommand options. @vrindex TAR_FORMAT, checkpoint script environment @@ -6747,10 +6756,14 @@ files whose names contain newlines can be archived using @option{--files-from}. @table @option -@opindex null +@xopindex{null, described} @item --null Only consider @code{NUL} terminated file names, instead of files that terminate in a newline. + +@xopindex{no-null, described} +@item --no-null +Undo the effect of any previous @option{--null} option. @end table The @option{--null} option is just like the one in @acronym{GNU} @@ -6774,7 +6787,37 @@ $ @kbd{find . -size +800 -print0 > long-files} $ @kbd{tar -c -v --null --files-from=long-files --file=big.tar} @end smallexample -@FIXME{say anything else here to conclude the section?} +The @option{--no-null} option can be used if you need to read both +zero-terminated and newline-terminated files on the same command line. +For example, if @file{flist} is a newline-terminated file, then the +following command can be used to combine it with the above command: + +@smallexample +@group +$ @kbd{find . -size +800 -print0 | + tar -c -f big.tar --null -T - --no-null -T flist} +@end group +@end smallexample + +This example uses short options for typographic reasons, to avoid +very long lines. + +@GNUTAR is able to automatically detect null-terminated file lists, so +it is safe to use them even without the @option{--null} option. In +this case @command{tar} will print a warning and continue reading such +a file as if @option{--null} were actually given: + +@smallexample +@group +$ @kbd{find . -size +800 -print0 | tar -c -f big.tar -T -} +tar: -: file name read contains nul character +@end group +@end smallexample + +The null terminator, however, remains in effect only for this +particular file, any following @option{-T} options will assume +newline termination. Of course, the null autodetection applies +to these eventual surplus @option{-T} options as well. @node exclude @section Excluding Some Files @@ -7512,7 +7555,7 @@ characters that are quoted by default in the selected quoting style. @command{Tar} archives contain detailed information about files stored in them and full file names are part of that information. When -storing file to an archive, its file name is recorded in the archive +storing file to an archive, its file name is recorded in it, along with the actual file contents. When restoring from an archive, a file is created on disk with exactly the same name as that stored in the archive. In the majority of cases this is the desired behavior @@ -7529,7 +7572,7 @@ directory components, or with otherwise modified names. In other cases it is desirable to store files under differing names in the archive. -@GNUTAR{} provides two options for these needs. +@GNUTAR{} provides several options for these needs. @table @option @opindex strip-components @@ -7551,8 +7594,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: @@ -7577,7 +7620,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. @@ -7603,7 +7646,9 @@ In case you need to apply more complex modifications to the file name, @table @option @opindex transform +@opindex xform @item --transform=@var{expression} +@itemx --xform=@var{expression} Modify file names using supplied @var{expression}. @end table @@ -7621,6 +7666,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. @@ -7642,7 +7702,7 @@ sed, GNU sed}). @item @var{number} Only replace the @var{number}th match of the @var{regexp}. -Note: the @var{posix} standard does not specify what should happen +Note: the @acronym{POSIX} standard does not specify what should happen when you mix the @samp{g} and @var{number} modifiers. @GNUTAR{} follows the GNU @command{sed} implementation in this regard, so the interaction is defined to be: ignore matches before the @@ -7651,21 +7711,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 @@ -7682,20 +7762,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 +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{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 + +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 + /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 + 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/} @@ -8140,9 +8259,7 @@ the @file{/} directory first, and then avoid absolute notation. For example: @smallexample -$ @kbd{(cd / && tar -c -f archive.tar home)} -# @i{or}: -$ @kbd{tar -c -f archive.tar -C / home} +$ @kbd{tar -c -f archive.tar -C / home} @end smallexample @include getdate.texi @@ -8454,6 +8571,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: @@ -8492,14 +8610,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