3.8 Checkpoints

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:

‘--checkpoint[=n]’

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.

‘--checkpoint-action=action’

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 instructs tar to print a single dot on the standard listing stream, e.g.:

$ 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 checkpoint:

$ tar -c --checkpoint=1000 --checkpoint-action=sleep=30

Finally, the exec action executes a given external command. For example:

$ tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint

The supplied command can be any valid command invocation, with or without additional command line arguments. If it does contain arguments, don’t forget to quote it to prevent it from being split by the shell. See section Running External Commands, for more detail.

The command gets a copy of tar’s environment plus the following variables:

TAR_VERSION

GNU tar version number.

TAR_ARCHIVE

The name of the archive tar is processing.

TAR_BLOCKING_FACTOR

Current blocking factor (see section Blocking).

TAR_CHECKPOINT

Number of the checkpoint.

TAR_SUBCOMMAND

A short option describing the operation tar is executing. See section The Five Advanced tar Operations, for a complete list of subcommand options.

TAR_FORMAT

Format of the archive being processed. See section Controlling the Archive Format, for a complete list of archive format names.

These environment variables can also be passed as arguments to the command, provided that they are properly escaped, for example:

tar -c -f arc.tar \
     --checkpoint-action='exec=/sbin/cpoint $TAR_FILENAME'

Notice single quotes to prevent variable names from being expanded by the shell when invoking tar.

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.

This document was generated on November 1, 2013 using texi2html 5.0.