tar: checkpoints
1
1 3.8 Checkpoints
1 ===============
1
1 A "checkpoint" is a moment of time before writing Nth record to the
1 archive (a "write checkpoint"), or before reading Nth record from the
1 archive (a "read checkpoint"). Checkpoints allow to periodically
1 execute arbitrary actions.
1
1 The checkpoint facility is enabled using the following option:
1
1 '--checkpoint[=N]'
1 Schedule checkpoints before writing or reading each Nth record.
1 The default value for N is 10.
1
1 A list of arbitrary "actions" can be executed at each checkpoint.
1 These actions include: pausing, displaying textual messages, and
1 executing arbitrary external programs. Actions are defined using the
1 '--checkpoint-action' option.
1
1 '--checkpoint-action=ACTION'
1 Execute an ACTION at each checkpoint.
1
1 The simplest value of ACTION is 'echo'. It instructs 'tar' to
1 display the default message on the standard error stream upon arriving
1 at each checkpoint. The default message is (in POSIX locale) 'Write
1 checkpoint N', for write checkpoints, and 'Read checkpoint N', for read
1 checkpoints. Here, N represents ordinal number of the checkpoint.
1
1 In another locales, translated versions of this message are used.
1
1 This is the default action, so running:
1
1 $ tar -c --checkpoint=1000 --checkpoint-action=echo /var
1
1 is equivalent to:
1
1 $ tar -c --checkpoint=1000 /var
1
1 The 'echo' action also allows to supply a customized message. You do
1 so by placing an equals sign and the message right after it, e.g.:
1
1 --checkpoint-action="echo=Hit %s checkpoint #%u"
1
1 The '%s' and '%u' in the above example are "format specifiers". The
1 '%s' specifier is replaced with the "type" of the checkpoint: 'write' or
1 'read' (or a corresponding translated version in locales other than
1 POSIX). The '%u' specifier is replaced with the ordinal number of the
1 checkpoint. Thus, the above example could produce the following output
1 when used with the '--create' option:
1
1 tar: Hit write checkpoint #10
1 tar: Hit write checkpoint #20
1 tar: Hit write checkpoint #30
1
1 The complete list of available format specifiers follows. Some of
1 them can take optional arguments. These arguments, if given, are
1 supplied in curly braces between the percent sign and the specifier
1 letter.
1
1 '%s'
1 Print type of the checkpoint ('write' or 'read').
1
1 '%u'
1 Print number of the checkpoint.
1
1 '%{r,w,d}T'
1 Print number of bytes transferred so far and approximate transfer
1 speed. Optional arguments supply prefixes to be used before number
1 of bytes read, written and deleted, correspondingly. If absent,
1 they default to 'R'. 'W', 'D'. Any or all of them can be omitted,
1 so, that e.g. '%{}T' means to print corresponding statistics
1 without any prefixes. Any surplus arguments, if present, are
1 silently ignored.
1
1 $ tar --delete -f f.tar --checkpoint-action=echo="#%u: %T" main.c
1 tar: #1: R: 0 (0B, 0B/s),W: 0 (0B, 0B/s),D: 0
1 tar: #2: R: 10240 (10KiB, 19MiB/s),W: 0 (0B, 0B/s),D: 10240
1
1 See also the 'totals' action, described below.
1
1 '%{FMT}t'
11 Output current local time using FMT as format for 'strftime' (⇒
strftime (strftime(3))strftime.). The '{FMT}' part is optional.
1 If not present, the default format is '%c', i.e. the preferred
1 date and time representation for the current locale.
1
1 '%{N}*'
1 Pad output with spaces to the Nth column. If the '{N}' part is
1 omitted, the current screen width is assumed.
1
1 '%c'
1 This is a shortcut for '%{%Y-%m-%d %H:%M:%S}t: %ds,
1 %{read,wrote}T%*\r', intended mainly for use with 'ttyout' action
1 (see below).
1
1 Aside from format expansion, the message string is subject to
1 "unquoting", during which the backslash "escape sequences" are replaced
1 with their corresponding ASCII characters (⇒escape sequences).
1 E.g. the following action will produce an audible bell and the message
1 described above at each checkpoint:
1
1 --checkpoint-action='echo=\aHit %s checkpoint #%u'
1
1 There is also a special action which produces an audible signal:
1 'bell'. It is not equivalent to 'echo='\a'', because 'bell' sends the
1 bell directly to the console ('/dev/tty'), whereas 'echo='\a'' sends it
1 to the standard error.
1
1 The 'ttyout=STRING' action outputs STRING to '/dev/tty', so it can be
1 used even if the standard output is redirected elsewhere. The STRING is
1 subject to the same modifications as with 'echo' action. In contrast to
1 the latter, 'ttyout' does not prepend 'tar' executable name to the
1 string, nor does it output a newline after it. For example, the
1 following action will print the checkpoint message at the same screen
1 line, overwriting any previous message:
1
1 --checkpoint-action="ttyout=Hit %s checkpoint #%u%*\r"
1
1 Notice the use of '%*' specifier to clear out any eventual remains of
1 the prior output line. As as more complex example, consider this:
1
1 --checkpoint-action=ttyout='%{%Y-%m-%d %H:%M:%S}t (%d sec): #%u, %T%*\r'
1
1 This prints the current local time, number of seconds expired since tar
1 was started, the checkpoint ordinal number, transferred bytes and
1 average computed I/O speed.
1
1 Another available checkpoint action is 'dot' (or '.'). It instructs
1 'tar' to print a single dot on the standard listing stream, e.g.:
1
1 $ tar -c --checkpoint=1000 --checkpoint-action=dot /var
1 ...
1
1 For compatibility with previous GNU 'tar' versions, this action can
1 be abbreviated by placing a dot in front of the checkpoint frequency, as
1 shown in the previous section.
1
1 The 'totals' action prints the total number of bytes transferred so
1 far. The format of the data is the same as for the '--totals' option
1 (⇒totals). See also '%T' format specifier of the 'echo' or
1 'ttyout' action.
1
1 Yet another action, 'sleep', pauses 'tar' for a specified amount of
1 seconds. The following example will stop for 30 seconds at each
1 checkpoint:
1
1 $ tar -c --checkpoint=1000 --checkpoint-action=sleep=30
1
1 Finally, the 'exec' action executes a given external command. For
1 example:
1
1 $ tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint
1
1 The supplied command can be any valid command invocation, with or
1 without additional command line arguments. If it does contain
1 arguments, don't forget to quote it to prevent it from being split by
1 the shell. ⇒Running External Commands external, for more detail.
1
1 The command gets a copy of 'tar''s environment plus the following
1 variables:
1
1 'TAR_VERSION'
1 GNU 'tar' version number.
1
1 'TAR_ARCHIVE'
1 The name of the archive 'tar' is processing.
1
1 'TAR_BLOCKING_FACTOR'
1 Current blocking factor (⇒Blocking).
1
1 'TAR_CHECKPOINT'
1 Number of the checkpoint.
1
1 'TAR_SUBCOMMAND'
11 A short option describing the operation 'tar' is executing. ⇒
Operations, for a complete list of subcommand options.
1
1 'TAR_FORMAT'
1 Format of the archive being processed. ⇒Formats, for a
1 complete list of archive format names.
1
1 These environment variables can also be passed as arguments to the
1 command, provided that they are properly escaped, for example:
1
1 tar -c -f arc.tar \
1 --checkpoint-action='exec=/sbin/cpoint $TAR_CHECKPOINT'
1
1 Notice single quotes to prevent variable names from being expanded by
1 the shell when invoking 'tar'.
1
1 Any number of actions can be defined, by supplying several
1 '--checkpoint-action' options in the command line. For example, the
1 command below displays two messages, pauses execution for 30 seconds and
1 executes the '/sbin/cpoint' script:
1
1 $ tar -c -f arc.tar \
1 --checkpoint-action='\aecho=Hit %s checkpoint #%u' \
1 --checkpoint-action='echo=Sleeping for 30 seconds' \
1 --checkpoint-action='sleep=30' \
1 --checkpoint-action='exec=/sbin/cpoint'
1
1 This example also illustrates the fact that '--checkpoint-action' can
1 be used without '--checkpoint'. In this case, the default checkpoint
1 frequency (at each 10th record) is assumed.
1