checkpoints (GNU tar 1.35)

### 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 format specifiers. The ‘`%s`’ specifier is replaced with the type of the checkpoint: ‘`write`’ or ‘`read`’ (or a corresponding translated version in locales other than POSIX). The ‘`%u`’ specifier 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

The complete list of available format specifiers follows. Some of them can take optional arguments. These arguments, if given, are supplied in curly braces between the percent sign and the specifier letter.

‘`%s`’

  Print type of the checkpoint (‘`write`’ or ‘`read`’).

‘`%u`’

  Print number of the checkpoint.

‘`%{r,w,d}T`’

  Print number of bytes transferred so far and approximate transfer speed. Optional arguments supply prefixes to be used before number of bytes read, written and deleted, correspondingly. If absent, they default to ‘`R`’. ‘`W`’, ‘`D`’. Any or all of them can be omitted, so, that e.g. ‘`%{}T`’ means to print corresponding statistics without any prefixes. Any surplus arguments, if present, are silently ignored.

      $ tar --delete -f f.tar --checkpoint-action=echo="#%u: %T" main.c
      tar: #1: R: 0 (0B, 0B/s),W: 0 (0B, 0B/s),D: 0
      tar: #2: R: 10240 (10KiB, 19MiB/s),W: 0 (0B, 0B/s),D: 10240

  See also the ‘`totals`’ action, described below.

‘`%{fmt}t`’

  Output current local time using fmt as format for `strftime` (see strftime in strftime(3) man page). The ‘`{fmt}`’ part is optional. If not present, the default format is ‘`%c`’, i.e. the preferred date and time representation for the current locale.

‘`%{n}*`’

  Pad output with spaces to the nth column. If the ‘`{n}`’ part is omitted, the current screen width is assumed.

‘`%c`’

  This is a shortcut for ‘`%{%Y-%m-%d %H:%M:%S}t: %ds, %{read,wrote}T%*\r`’, intended mainly for use with ‘`ttyout`’ action (see below).

Aside from format 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=Hit %s checkpoint #%u%*\r"

Notice the use of ‘`%*`’ specifier to clear out any eventual remains of the prior output line. As as more complex example, consider this:

    --checkpoint-action=ttyout='%{%Y-%m-%d %H:%M:%S}t (%d sec): #%u, %T%*\r'

This prints the current local time, number of seconds expired since tar was started, the checkpoint ordinal number, transferred bytes and average computed I/O speed.

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.

The ‘`totals`’ action prints the total number of bytes transferred so far. The format of the data is the same as for the `--totals` option (see totals). See also ‘`%T`’ format specifier of the ‘`echo`’ or ‘`ttyout`’ action.

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

The `wait=signo` action stops further execution until the signal signo is delivered. Valid values for signo are: `SIGHUP`, `SIGQUIT`, `SIGINT`, `SIGUSR1` and `SIGUSR2`. The ‘`SIG`’ prefix is optional. For example:

    $ tar -c -f arc --checkpoint=1000 --checkpoint-action wait=USR1 .

In this example, GNU `tar` will stop archivation at each 1000th checkpoint. wait until the ‘`SIGUSR1`’ signal is delivered, and resume processing.

This action is used by the `genfile` utility to perform modifications on the input files upon hitting certain checkpoints (see genfile).

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 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 Blocking).

`TAR_CHECKPOINT`

  Number of the checkpoint.

`TAR_SUBCOMMAND`

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

`TAR_FORMAT`

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

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.