X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=4e382151fbb3a5c3a48d150a6768cb9c59748fad;hb=a16ad3112e12f39e1e8eb41fef5ab9bc0894d1d7;hp=1084e47696f2dbb93508a914eba38510073558a5;hpb=5099ddf6cc764dcb55c42a5d5a3415ce03ac191c;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index 1084e47..4e38215 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 Free Software Foundation, Inc. +2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -45,9 +45,9 @@ Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License". -(a) The FSF's Back-Cover Text is: ``You are free to copy and modify -this GNU Manual. Buying copies from GNU Press supports the FSF in -developing GNU and promoting software freedom.'' +(a) The FSF's Back-Cover Text is: ``You have the freedom to +copy and modify this GNU manual. Buying copies from the FSF +supports it in developing GNU and promoting software freedom.'' @end quotation @end copying @@ -2460,6 +2460,13 @@ for a complete description. The @var{action} argument can be one of the following: @table @asis +@item bell +Produce an audible bell on the console. + +@item dot +@itemx . +Print a single dot on the standard listing stream. + @item echo Display a textual message on the standard error, with the status and number of the checkpoint. This is the default. @@ -2468,20 +2475,19 @@ number of the checkpoint. This is the default. Display @var{string} on the standard error. Before output, the string is subject to meta-character expansion. -@item dot -@itemx . -Print a single dot on the standard listing stream. +@item exec=@var{command} +Execute the given @var{command}. @item sleep=@var{time} Wait for @var{time} seconds. -@item exec=@var{command} -Execute the given @var{command}. +@item ttyout=@var{string} +Output @var{string} on the current console (@file{/dev/tty}). @end table Several @option{--checkpoint-action} options can be specified. The supplied actions will be executed in order of their appearance in the -command line. +command line. Using @option{--checkpoint-action} without @option{--checkpoint} assumes default checkpoint frequency of one checkpoint per 10 records. @@ -2587,7 +2593,7 @@ named @var{file}, but dump the directory node itself. @xref{exclude}. @item --exclude-tag-all=@var{file} Exclude from dump any directory containing file named @var{file}. -@xref{exclude}. +@xref{exclude}. @opsummary{exclude-vcs} @item --exclude-vcs @@ -3434,7 +3440,7 @@ successfully. For example, @w{@samp{tar --version}} might print: @smallexample tar (GNU tar) @value{VERSION} -Copyright (C) 2006 Free Software Foundation, Inc. +Copyright (C) 2008 Free Software Foundation, Inc. This is free software. You may redistribute copies of it under the terms of the GNU General Public License . There is NO WARRANTY, to the extent permitted by law. @@ -3805,6 +3811,26 @@ audible bell and the message described above at each checkpoint: --checkpoint-action='echo=\aHit %s checkpoint #%u' @end smallexample +@cindex @code{bell}, checkpoint action +There is also a special action which produces an audible signal: +@samp{bell}. It is not equivalent to @samp{echo='\a'}, because +@samp{bell} sends the bell directly to the console (@file{/dev/tty}), +whereas @samp{echo='\a'} sends it to the standard error. + +@cindex @code{ttyout}, checkpoint action +The @samp{ttyout=@var{string}} action outputs @var{string} to +@file{/dev/tty}, so it can be used even if the standard output is +redirected elsewhere. The @var{string} is subject to the same +modifications as with @samp{echo} action. In contrast to the latter, +@samp{ttyout} does not prepend @command{tar} executable name to the +string, nor does it output a newline after it. For example, the +following action will print the checkpoint message at the same screen +line, overwriting any previous message: + +@smallexample +--checkpoint-action="ttyout=\rHit %s checkpoint #%u" +@end smallexample + @cindex @code{dot}, checkpoint action Another available checkpoint action is @samp{dot} (or @samp{.}). It instructs @command{tar} to print a single dot on the standard listing @@ -3822,7 +3848,7 @@ as shown in the previous section. @cindex @code{sleep}, checkpoint action Yet another action, @samp{sleep}, pauses @command{tar} for a specified amount of seconds. The following example will stop for 30 seconds at each -checkpoint: +checkpoint: @smallexample $ @kbd{tar -c --checkpoint=1000 --checkpoint-action=sleep=30} @@ -3849,6 +3875,10 @@ additional arguments. Its exit code is ignored. It gets a copy of @item TAR_ARCHIVE 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}. + @vrindex TAR_CHECKPOINT, checkpoint script environment @item TAR_CHECKPOINT The checkpoint number. @@ -3883,7 +3913,7 @@ This example also illustrates the fact that @option{--checkpoint-action} can be used without @option{--checkpoint}. In this case, the default checkpoint frequency (at each 10th record) is assumed. - + @node interactive @section Asking for Confirmation During Operations @cindex Interactive operation @@ -7535,6 +7565,9 @@ 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}. +As in @command{sed}, you can give several replace expressions, +separated by a semicolon. + Supported @var{flags} are: @table @samp @@ -7628,6 +7661,18 @@ If both @option{--strip-components} and @option{--transform} are used together, then @option{--transform} is applied first, and the required number of components is then stripped from its result. +You can use as many @option{--transform} options in a single command +line as you want. The specified expressions will then be applied in +order of their appearance. For example, the following two invocations +are equivalent: + +@smallexample +$ @kbd{tar -cf arch.tar --transform='s,/usr/var,/var/' \ + --transform='s,/usr/local,/usr/,'} +$ @kbd{tar -cf arch.tar \ + --transform='s,/usr/var,/var/;s,/usr/local,/usr/,'} +@end smallexample + @node after @section Operating Only on New Files @UNREVISED @@ -8183,7 +8228,7 @@ 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, -@command{lzma} to create an @asis{LZMA} compressed archive and +@option{--lzma} to create an @asis{LZMA} compressed archive and @option{-Z} (@option{--compress}) to use @command{compress} program. For example: @@ -8209,7 +8254,7 @@ $ @kbd{tar cfa archive.tar.lzma .} @end smallexample For a complete list of file name suffixes recognized by @GNUTAR{}, -@ref{auto-compress}. +@ref{auto-compress}. Reading compressed archive is even simpler: you don't need to specify any additional options as @GNUTAR{} recognizes its format @@ -8958,7 +9003,7 @@ from @var{string} after making the following substitutions: result of the @command{dirname} utility on the translated file name. @item %f @tab The name of the file with the directory information stripped, equivalent to the result of the @command{basename} utility -on the translated file name. +on the translated file name. @item %p @tab The process @acronym{ID} of the @command{tar} process. @item %% @tab A @samp{%} character. @end multitable @@ -10621,6 +10666,10 @@ environment variables: @item TAR_ARCHIVE The name of the archive @command{tar} is processing. +@vrindex TAR_BLOCKING_FACTOR, info script environment variable +@item TAR_BLOCKING_FACTOR +Current blocking factor (@pxref{Blocking}. + @vrindex TAR_VOLUME, info script environment variable @item TAR_VOLUME Ordinal number of the volume @command{tar} is about to start.