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 program. For example:

     $ 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

GNU tar version number.

TAR_ARCHIVE

The name of the archive tar is processing.

TAR_BLOCKING_FACTOR

Current blocking factor (see Blocking).

TAR_CHECKPOINT

Number of the checkpoint.

TAR_SUBCOMMAND

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

TAR_FORMAT

Format of the archive being processed. See Formats, 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.