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