|[ < ]||[ > ]||[ << ]||[ Up ]||[ >> ]||[Top]||[Contents]||[Index]||[ ? ]|
A checkpoint is a moment of time before writing nth record to the archive (a write checkpoint), or before reading nth record from the archive (a read checkpoint). Checkpoints allow to periodically execute arbitrary actions.
The checkpoint facility is enabled using the following option:
Schedule checkpoints before writing or reading each nth record. The default value for n is 10.
A list of arbitrary actions can be executed at each checkpoint. These actions include: pausing, displaying textual messages, and executing arbitrary external programs. Actions are defined using the ‘--checkpoint-action’ option.
Execute an action at each checkpoint.
The simplest value of action is ‘echo’. It instructs
tar to display the default message on the standard error
stream upon arriving at each checkpoint. The default message is (in
POSIX locale) ‘Write checkpoint n’, for write
checkpoints, and ‘Read checkpoint n’, for read checkpoints.
Here, n represents ordinal number of the checkpoint.
In another locales, translated versions of this message are used.
This is the default action, so running:
$ tar -c --checkpoint=1000 --checkpoint-action=echo /var
is equivalent to:
$ tar -c --checkpoint=1000 /var
The ‘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.:
--checkpoint-action="echo=Hit %s checkpoint #%u"
The ‘%s’ and ‘%u’ in the above example are meta-characters. The ‘%s’ meta-character is replaced with the type of the checkpoint: ‘write’ or ‘read’ (or a corresponding translated version in locales other than POSIX). The ‘%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 ‘--create’ option:
tar: Hit write checkpoint #10 tar: Hit write checkpoint #20 tar: Hit write checkpoint #30
Aside from meta-character expansion, the message string is subject to unquoting, during which the backslash escape sequences are replaced with their corresponding ASCII characters (see escape sequences). E.g. the following action will produce an audible bell and the message described above at each checkpoint:
--checkpoint-action='echo=\aHit %s checkpoint #%u'
There is also a special action which produces an audible signal: ‘bell’. It is not equivalent to ‘echo='\a'’, because ‘bell’ sends the bell directly to the console (‘/dev/tty’), whereas ‘echo='\a'’ sends it to the standard error.
The ‘ttyout=string’ action outputs string to
‘/dev/tty’, so it can be used even if the standard output is
redirected elsewhere. The string is subject to the same
modifications as with ‘echo’ action. In contrast to the latter,
‘ttyout’ does not prepend
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:
--checkpoint-action="ttyout=\rHit %s checkpoint #%u"
Another available checkpoint action is ‘dot’ (or ‘.’). It
tar to print a single dot on the standard listing
$ tar -c --checkpoint=1000 --checkpoint-action=dot /var ...
For compatibility with previous GNU
tar versions, this action can
be abbreviated by placing a dot in front of the checkpoint frequency,
as shown in the previous section.
Yet another action, ‘sleep’, pauses
tar for a specified
amount of seconds. The following example will stop for 30 seconds at each
$ tar -c --checkpoint=1000 --checkpoint-action=sleep=30
exec action executes a given external program.
$ tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint
This program is executed using
/bin/sh -c, with no
additional arguments. Its exit code is ignored. It gets a copy of
tar's environment plus the following variables:
tar version number.
The name of the archive
tar is processing.
Current blocking factor (see section Blocking).
Number of the checkpoint.
A short option describing the operation
tar is executing.
See section The Five Advanced
tar Operations, for a complete list of subcommand options.
Format of the archive being processed. See section Controlling the Archive Format, for a complete list of archive format names.
Any number of actions can be defined, by supplying several ‘--checkpoint-action’ options in the command line. For example, the command below displays two messages, pauses execution for 30 seconds and executes the ‘/sbin/cpoint’ script:
$ 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'
This example also illustrates the fact that ‘--checkpoint-action’ can be used without ‘--checkpoint’. In this case, the default checkpoint frequency (at each 10th record) is assumed.
|[ < ]||[ > ]||[ << ]||[ Up ]||[ >> ]|
This document was generated by Sergey Poznyakoff on March, 12 2011 using texi2html 1.78.