From: Sergey Poznyakoff <gray@gnu.org.ua>
Date: Tue, 30 Oct 2007 14:09:04 +0000 (+0000)
Subject: Document --hard-dereference and --checkpoint-action options. Improve documentation... 
X-Git-Url: https://git.brokenzipper.com/gitweb?a=commitdiff_plain;h=5099ddf6cc764dcb55c42a5d5a3415ce03ac191c;p=chaz%2Ftar

Document --hard-dereference and --checkpoint-action options. Improve documentation of --check-links.
---

diff --git a/doc/tar.texi b/doc/tar.texi
index 328ed9f..1084e47 100644
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -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,45 @@ 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 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 dot
+@itemx .
+Print a single dot on the standard listing stream.
+
+@item sleep=@var{time}
+Wait for @var{time} seconds.
+
+@item exec=@var{command}
+Execute the given @var{command}.
+@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 +2497,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
@@ -2630,6 +2672,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 +2955,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
@@ -3609,7 +3656,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 +3673,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 +3718,172 @@ 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{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_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 +5105,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 +7166,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
@@ -8462,6 +8680,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 +8738,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
@@ -10314,7 +10627,7 @@ 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