[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
tar
progressTypically, tar
performs most operations without reporting any
information to the user except error messages. When using tar
with many options, particularly ones with complicated or
difficult-to-predict behavior, it is possible to make serious mistakes.
tar
provides several options that make observing tar
easier. These options cause tar
to print information as it
progresses in its job, and you might want to use them just for being
more careful about what is going on, or merely for entertaining
yourself. If you have encountered a problem when operating on an
archive, however, you may need more information than just an error
message in order to solve the problem. The following options can be
helpful diagnostic tools.
Normally, the ‘--list’ (‘-t’) command to list an archive
prints just the file names (one per line) and the other commands are
silent. When used with most operations, the ‘--verbose’
(‘-v’) option causes tar
to print the name of each
file or archive member as it is processed. This and the other options
which make tar
print status information can be useful in
monitoring tar
.
With ‘--create’ or ‘--extract’, ‘--verbose’ used
once just prints the names of the files or members as they are processed.
Using it twice causes tar
to print a longer listing
(See verbose member listing, for the description) for each member.
Since ‘--list’ already prints the names of the members,
‘--verbose’ used once with ‘--list’ causes tar
to print an ‘ls -l’ type listing of the files in the archive.
The following examples both extract members with long list output:
$ tar --extract --file=archive.tar --verbose --verbose $ tar xvvf archive.tar
Verbose output appears on the standard output except when an archive is
being written to the standard output, as with ‘tar --create
--file=- --verbose’ (‘tar cvf -’, or even ‘tar cv’—if the
installer let standard output be the default archive). In that case
tar
writes verbose output to the standard error stream.
If ‘--index-file=file’ is specified, tar
sends
verbose output to file rather than to standard output or standard
error.
The ‘--totals’ option causes tar
to print on the
standard error the total amount of bytes transferred when processing
an archive. When creating or appending to an archive, this option
prints the number of bytes written to the archive and the average
speed at which they have been written, e.g.:
$ tar -c -f archive.tar --totals /home Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
When reading an archive, this option displays the number of bytes read:
$ tar -x -f archive.tar --totals Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
Notice, that since tar
operates on records, the number
of bytes reported can be rounded up to the nearest full record. This
can happen, in particular, when the last record in the archive is
partial. See section Blocking.
Finally, when deleting from an archive, the ‘--totals’ option displays both numbers plus number of bytes removed from the archive:
$ tar --delete -f foo.tar --totals --wildcards '*~' Total bytes read: 9543680 (9.2MiB, 201MiB/s) Total bytes written: 3829760 (3.7MiB, 81MiB/s) Total bytes deleted: 1474048
You can also obtain this information on request. When ‘--totals’ is used with an argument, this argument is interpreted as a symbolic name of a signal, upon delivery of which the statistics is to be printed:
Print statistics upon delivery of signal signo. Valid arguments
are: SIGHUP
, SIGQUIT
, SIGINT
, SIGUSR1
and
SIGUSR2
. Shortened names without ‘SIG’ prefix are also
accepted.
Both forms of ‘--totals’ option can be used simultaneously.
Thus, tar -x --totals --totals=USR1 instructs tar
to
extract all members from its default archive and print statistics
after finishing the extraction, as well as when receiving signal
SIGUSR1
.
The ‘--checkpoint’ option prints an occasional message
as tar
reads or writes the archive. It is designed for
those who don’t need the more detailed (and voluminous) output of
‘--block-number’ (‘-R’), but do want visual confirmation
that tar
is actually making forward progress. By default it
prints a message each 10 records read or written. This can be changed
by giving it a numeric argument after an equal sign:
$ tar -c --checkpoint=1000 /var tar: Write checkpoint 1000 tar: Write checkpoint 2000 tar: Write checkpoint 3000
This example shows the default checkpoint message used by
tar
. If you place a dot immediately after the equal
sign, it will print a ‘.’ at each checkpoint(8). For example:
$ tar -c --checkpoint=.1000 /var ...
The ‘--checkpoint’ option provides a flexible mechanism for executing arbitrary actions upon hitting checkpoints, see the next section (see section Checkpoints), for more information on it.
The ‘--show-omitted-dirs’ option, when reading an archive—with ‘--list’ or ‘--extract’, for example—causes a message to be printed for each directory in the archive which is skipped. This happens regardless of the reason for skipping: the directory might not have been named on the command line (implicitly or explicitly), it might be excluded by the use of the ‘--exclude=pattern’ option, or some other reason.
If ‘--block-number’ (‘-R’) is used, tar
prints, along with
every message it would normally produce, the block number within the
archive where the message was triggered. Also, supplementary messages
are triggered when reading blocks full of NULs, or when hitting end of
file on the archive. As of now, if the archive is properly terminated
with a NUL block, the reading of the file may stop before end of file
is met, so the position of end of file will not usually show when
‘--block-number’ (‘-R’) is used. Note that GNU tar
drains the archive before exiting when reading the
archive from a pipe.
This option is especially useful when reading damaged archives, since it helps pinpoint the damaged sections. It can also be used with ‘--list’ (‘-t’) when listing a file-system backup tape, allowing you to choose among several backup tapes when retrieving a file later, in favor of the tape where the file appears earliest (closest to the front of the tape). See section Backup options.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated on August 23, 2023 using texi2html 5.0.