| [ << ] | [ < ] | [ 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 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.
Print type of the checkpoint (‘write’ or ‘read’).
Print number of the checkpoint.
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.
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.
Pad output with spaces to the nth column. If the ‘{n}’ part is omitted, the current screen width is assumed.
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 section 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 section Running External Commands, for more detail.
The command gets a copy of tar’s environment plus the
following variables:
TAR_VERSIONGNU tar version number.
TAR_ARCHIVEThe name of the archive tar is processing.
TAR_BLOCKING_FACTORCurrent blocking factor (see section Blocking).
TAR_CHECKPOINTNumber of the checkpoint.
TAR_SUBCOMMANDA short option describing the operation tar is executing.
See section The Five Advanced tar Operations, for a complete list of subcommand options.
TAR_FORMATFormat 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_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.
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated on August 23, 2023 using texi2html 5.0.