X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=0425107e6470687b559e455750abefd5a9ffa33b;hb=7efe3850f6e058d33a46ef17cdc95df0469ed887;hp=328ed9f79b701fb889110a565808947793d4db89;hpb=5bfb6c5f9d105850ca9628dae7ef8d4d27687f70;p=chaz%2Ftar

diff --git a/doc/tar.texi b/doc/tar.texi
index 328ed9f..0425107 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
 
@@ -176,6 +176,7 @@ Invoking @GNUTAR{}
 * help::
 * defaults::
 * verbose::
+* checkpoints::
 * interactive::
 
 The Three Option Styles
@@ -330,6 +331,7 @@ Making @command{tar} Archives More Portable
 
 * Portable Names::              Portable Names
 * dereference::                 Symbolic Links
+* hard links::                  Hard Links
 * old::                         Old V7 Archives
 * ustar::                       Ustar Archives
 * gnu::                         GNU and old GNU format archives.
@@ -1801,6 +1803,7 @@ and @option{--interactive} options (@pxref{interactive}).
 * help::
 * defaults::
 * verbose::
+* checkpoints::
 * interactive::
 @end menu
 
@@ -2443,8 +2446,51 @@ This option tells @command{tar} to read or write archives through
 This option directs @command{tar} to print periodic checkpoint
 messages as it reads through the archive.  It is intended for when you
 want a visual indication that @command{tar} is still running, but
-don't want to see @option{--verbose} output.  For a detailed
-description, see @ref{Progress information}.
+don't want to see @option{--verbose} output.  You can also instruct
+@command{tar} to execute a list of actions on each checkpoint, see
+@option{--checklist-action} below.  For a detailed description, see
+@ref{checkpoints}.
+
+@opsummary{checkpoint-action}
+@item --checkpoint-action=@var{action}
+Instruct @command{tar} to execute an action upon hitting a
+breakpoint.  Here we give only a brief outline.  @xref{checkpoints},
+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.
+
+@item echo=@var{string}
+Display @var{string} on the standard error.  Before output, the string
+is subject to meta-character expansion.
+
+@item exec=@var{command}
+Execute the given @var{command}.
+
+@item sleep=@var{time}
+Wait for @var{time} seconds.
+
+@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.
+
+Using @option{--checkpoint-action} without @option{--checkpoint}
+assumes default checkpoint frequency of one checkpoint per 10 records.
 
 @opsummary{check-links}
 @item --check-links
@@ -2457,6 +2503,8 @@ synonym for @option{--one-file-system}.  The current semantics, which
 complies to UNIX98, was introduced with version
 1.15.91. @xref{Changes}, for more information.}.
 
+@xref{hard links}.
+
 @opsummary{compress}
 @opsummary{uncompress}
 @item --compress
@@ -2545,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
@@ -2630,6 +2678,13 @@ This option tells @command{tar} to read or write archives through
 @command{gzip}, allowing @command{tar} to directly operate on several
 kinds of compressed archives transparently.  @xref{gzip}.
 
+@opsummary{hard-dereference}
+@item --hard-dereference
+When creating an archive, dereference hard links and store the files
+they refer to, instead of creating usual hard link members.
+
+@xref{hard links}.
+
 @opsummary{help}
 @item --help
 @itemx -?
@@ -2906,9 +2961,7 @@ Synonym for @option{--format=v7}.
 @item --one-file-system
 Used when creating an archive.  Prevents @command{tar} from recursing into
 directories that are on different file systems from the current
-directory @footnote{Earlier versions of @GNUTAR{} understood @option{-l} as a
-synonym for @option{--one-file-system}.  This has changed in version
-1.15.91. @xref{Changes}, for more information.}.
+directory.
 
 @opsummary{overwrite}
 @item --overwrite
@@ -3387,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 <http://www.gnu.org/licenses/gpl.html>.
 There is NO WARRANTY, to the extent permitted by law.
@@ -3609,7 +3662,6 @@ after finishing the extraction, as well as when receiving signal
 
 @anchor{Progress information}
 @cindex Progress information
-@opindex checkpoint
 The @option{--checkpoint} option prints an occasional message
 as @command{tar} reads or writes the archive.  It is designed for
 those who don't need the more detailed (and voluminous) output of
@@ -3627,13 +3679,19 @@ tar: Write checkpoint 3000
 
 This example shows the default checkpoint message used by
 @command{tar}.  If you place a dot immediately after the equal
-sign, it will print a @samp{.} at each checkpoint.  For example:
+sign, it will print a @samp{.} at each checkpoint@footnote{This is
+actually a shortcut for @option{--checkpoint=@var{n}
+--checkpoint-action=dot}.  @xref{checkpoints, dot}.}.  For example:
 
 @smallexample
 $ @kbd{tar -c --checkpoint=.1000} /var
 ...
 @end smallexample
 
+The @option{--checkpoint} option provides a flexible mechanism for
+executing arbitrary actions upon hitting checkpoints, see the next
+section (@pxref{checkpoints}), for more information on it.
+
 @opindex show-omitted-dirs
 @anchor{show-omitted-dirs}
 The @option{--show-omitted-dirs} option, when reading an archive---with
@@ -3666,6 +3724,196 @@ choose among several backup tapes when retrieving a file later, in
 favor of the tape where the file appears earliest (closest to the
 front of the tape).  @xref{backup}.
 
+@node checkpoints
+@section Checkpoints
+@cindex checkpoints, defined
+@opindex checkpoint
+@opindex checkpoint-action
+
+A @dfn{checkpoint} is a moment of time before writing @var{n}th record to
+the archive (a @dfn{write checkpoint}), or before reading @var{n}th record
+from the archive (a @dfn{read checkpoint}).  Checkpoints allow to
+periodically execute arbitrary actions.
+
+The checkpoint facility is enabled using the following option:
+
+@table @option
+@xopindex{checkpoint, defined}
+@item --checkpoint[=@var{n}]
+Schedule checkpoints before writing or reading each @var{n}th record.
+The default value for @var{n} is 10.
+@end table
+
+A list of arbitrary @dfn{actions} can be executed at each checkpoint.
+These actions include: pausing, displaying textual messages, and
+executing arbitrary external programs.  Actions are defined using
+the @option{--checkpoint-action} option.
+
+@table @option
+@xopindex{checkpoint-action, defined}
+@item --checkpoint-action=@var{action}
+Execute an @var{action} at each checkpoint.
+@end table
+
+@cindex @code{echo}, checkpoint action
+The simplest value of @var{action} is @samp{echo}.  It instructs
+@command{tar} to display the default message on the standard error
+stream upon arriving at each checkpoint.  The default message is (in
+@acronym{POSIX} locale) @samp{Write checkpoint @var{n}}, for write
+checkpoints, and @samp{Read checkpoint @var{n}}, for read checkpoints.
+Here, @var{n} represents ordinal number of the checkpoint.
+
+In another locales, translated versions of this message are used.
+
+This is the default action, so running:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=echo} /var
+@end smallexample
+
+@noindent
+is equivalent to:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000} /var
+@end smallexample
+
+The @samp{echo} action also allows to supply a customized message.
+You do so by placing an equals sign and the message right after it,
+e.g.:
+
+@smallexample
+--checkpoint-action="echo=Hit %s checkpoint #%u"
+@end smallexample
+
+The @samp{%s} and @samp{%u} in the above example are
+@dfn{meta-characters}.  The @samp{%s} meta-character is replaced with
+the @dfn{type} of the checkpoint: @samp{write} or
+@samp{read} (or a corresponding translated version in locales other
+than @acronym{POSIX}).  The @samp{%u} meta-character is replaced with
+the ordinal number of the checkpoint.  Thus, the above example could
+produce the following output when used with the @option{--create}
+option:
+
+@smallexample
+tar: Hit write checkpoint #10
+tar: Hit write checkpoint #20
+tar: Hit write checkpoint #30
+@end smallexample
+
+Aside from meta-character expansion, the message string is subject to
+@dfn{unquoting}, during which the backslash @dfn{escape sequences} are
+replaced with their corresponding @acronym{ASCII} characters
+(@pxref{escape sequences}).  E.g. the following action will produce an
+audible bell and the message described above at each checkpoint:
+
+@smallexample
+--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
+stream, e.g.:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=dot} /var
+...
+@end smallexample
+
+For compatibility with previous @GNUTAR{} versions, this action can
+be abbreviated by placing a dot in front of the checkpoint frequency,
+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:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=sleep=30}
+@end smallexample
+
+@cindex @code{exec}, checkpoint action
+Finally, the @code{exec} action executes a given external program.
+For example:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint}
+@end smallexample
+
+This program is executed using @command{/bin/sh -c}, with no
+additional arguments.  Its exit code is ignored.  It gets a copy of
+@command{tar}'s environment plus the following variables:
+
+@table @env
+@vrindex TAR_VERSION, checkpoint script environment
+@item TAR_VERSION
+@GNUTAR{} version number.
+
+@vrindex TAR_ARCHIVE, checkpoint script environment
+@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.
+
+@vrindex TAR_SUBCOMMAND, checkpoint script environment
+@item TAR_SUBCOMMAND
+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
+@item TAR_FORMAT
+Format of the archive being processed. @xref{Formats}, for a complete
+list of archive format names.
+@end table
+
+Any number of actions can be defined, by supplying several
+@option{--checkpoint-action} options in the command line.  For
+example, the command below displays two messages, pauses
+execution for 30 seconds and executes the @file{/sbin/cpoint} script:
+
+@example
+@group
+$ @kbd{tar -c -f arc.tar \
+       --checkpoint-action='\aecho=Hit %s checkpoint #%u' \
+       --checkpoint-action='echo=Sleeping for 30 seconds' \
+       --checkpoint-action='sleep=30' \
+       --checkpoint-action='exec=/sbin/cpoint'}
+@end group
+@end example
+
+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
@@ -4887,7 +5135,7 @@ option is used.
 The command can obtain the information about the file it processes
 from the following environment variables:
 
-@table @var
+@table @env
 @vrindex TAR_FILETYPE, to-command environment
 @item TAR_FILETYPE
 Type of the file. It is a single letter with the following meaning:
@@ -6948,7 +7196,7 @@ quoting}.  The characters in question are:
 
 @itemize @bullet
 @item Non-printable control characters:
-
+@anchor{escape sequences}
 @multitable @columnfractions 0.20 0.10 0.60
 @headitem Character @tab @acronym{ASCII} @tab Character name
 @item \a @tab 7  @tab Audible bell
@@ -7317,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
@@ -7410,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
@@ -7991,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
@@ -8462,6 +8725,7 @@ archives and archive labels) in GNU and PAX formats.}
 @menu
 * Portable Names::              Portable Names
 * dereference::                 Symbolic Links
+* hard links::                  Hard Links
 * old::                         Old V7 Archives
 * ustar::                       Ustar Archives
 * gnu::                         GNU and old GNU format archives.
@@ -8519,6 +8783,100 @@ and use @option{--dereference} (@option{-h}): many systems do not support
 symbolic links, and moreover, your distribution might be unusable if
 it contains unresolved symbolic links.
 
+@node hard links
+@subsection Hard Links
+@UNREVISED{}
+@cindex File names, using hard links
+@cindex hard links, dereferencing
+@cindex dereferencing hard links
+
+Normally, when @command{tar} archives a hard link, it writes a
+block to the archive naming the target of the link (a @samp{1} type
+block).  In that way, the actual file contents is stored in file only
+once.  For example, consider the following two files:
+
+@smallexample
+@group
+$ ls
+-rw-r--r--   2 gray staff       4 2007-10-30 15:11 one
+-rw-r--r--   2 gray staff       4 2007-10-30 15:11 jeden
+@end group
+@end smallexample
+
+Here, @file{jeden} is a link to @file{one}.  When archiving this
+directory with a verbose level 2, you will get an output similar to
+the following:
+
+@smallexample
+$ tar cfvv ../archive.tar .
+drwxr-xr-x gray/staff        0 2007-10-30 15:13 ./
+-rw-r--r-- gray/staff        4 2007-10-30 15:11 ./jeden
+hrw-r--r-- gray/staff        0 2007-10-30 15:11 ./one link to ./jeden
+@end smallexample
+
+The last line shows that, instead of storing two copies of the file,
+@command{tar} stored it only once, under the name @file{jeden}, and
+stored file @file{one} as a hard link to this file.
+
+It may be important to know that all hard links to the given file are
+stored in the archive.  For example, this may be necessary for exact
+reproduction of the file system.  The following option does that:
+
+@table @option
+@xopindex{check-links, described}
+@item --check-links
+@itemx -l
+Check the number of links dumped for each processed file.  If this
+number does not match the total number of hard links for the file, print
+a warning message.
+@end table
+
+For example, trying to archive only file @file{jeden} with this option
+produces the following diagnostics:
+
+@smallexample
+$ tar -c -f ../archive.tar jeden
+tar: Missing links to `jeden'.
+@end smallexample
+
+Although creating special records for hard links helps keep a faithful
+record of the file system contents and makes archives more compact, it
+may present some difficulties when extracting individual members from
+the archive.  For example, trying to extract file @file{one} from the
+archive created in previous examples produces, in the absense of file
+@file{jeden}:
+
+@smallexample
+$ tar xf archive.tar ./one
+tar: ./one: Cannot hard link to `./jeden': No such file or directory
+tar: Error exit delayed from previous errors
+@end smallexample
+
+The reason for this behavior is that @command{tar} cannot seek back in
+the archive to the previous member (in this case, @file{one}), to
+extract it@footnote{There are plans to fix this in future releases.}.
+If you wish to avoid such problems at the cost of a bigger archive,
+use the following option:
+
+@table @option
+@xopindex{hard-dereference, described}
+@item --hard-dereference
+Dereference hard links and store the files they refer to.
+@end table
+
+For example, trying this option on our two sample files, we get two
+copies in the archive, each of which can then be extracted
+independently of the other:
+
+@smallexample
+@group
+$ tar -c -vv -f ../archive.tar --hard-dereference .
+drwxr-xr-x gray/staff        0 2007-10-30 15:13 ./
+-rw-r--r-- gray/staff        4 2007-10-30 15:11 ./jeden
+-rw-r--r-- gray/staff        4 2007-10-30 15:11 ./one
+@end group
+@end smallexample
+
 @node old
 @subsection Old V7 Archives
 @cindex Format, old style
@@ -8645,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
@@ -10308,13 +10666,17 @@ 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.
 
 @vrindex TAR_SUBCOMMAND, info script environment variable
 @item TAR_SUBCOMMAND
-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, info script environment variable