@smallbook
@c %**end of header
-@include config.texi
@include rendition.texi
@include value.texi
document. The rest of the menu lists all the lower level nodes.
@end ifnottex
-@c The master menu, created with texinfo-master-menu, goes here.
-@c FIXME: Submenus for getdate.texi and intern.texi are interpolated by hand.
+@c The master menu goes here.
+@c
+@c NOTE: To update it from within Emacs, make sure mastermenu.el is
+@c loaded and run texinfo-master-menu.
+@c To update it from the command line, run
+@c
+@c make master-menu
@menu
* Introduction::
* directory:: Changing Directory
* absolute:: Absolute File Names
-Controlling the Archive Format
-
-* Portability:: Making @command{tar} Archives More Portable
-* Compression:: Using Less Space through Compression
-* Attributes:: Handling File Attributes
-* cpio:: Comparison of @command{tar} and @command{cpio}
-
Date input formats
* General date syntax:: Common rules.
* Calendar date items:: 19 Dec 1994.
* Time of day items:: 9:20pm.
-* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}, ...
+* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}.
* Day of week items:: Monday and others.
* Relative items in date strings:: next tuesday, 2 years ago.
* Pure numbers in date strings:: 19931219, 1440.
* Seconds since the Epoch:: @@1078100502.
+* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
+Controlling the Archive Format
+
+* Portability:: Making @command{tar} Archives More Portable
+* Compression:: Using Less Space through Compression
+* Attributes:: Handling File Attributes
+* cpio:: Comparison of @command{tar} and @command{cpio}
+
Making @command{tar} Archives More Portable
* Portable Names:: Portable Names
* Tape Files:: Tape Files
* Tarcat:: Concatenate Volumes into a Single Archive
-GNU tar internals and development
-* Genfile::
-* Tar Internals::
-* Standard::
-* Extensions::
+Genfile
+
+* Generate Mode:: File Generation Mode.
+* Status Mode:: File Status Mode.
+* Exec Mode:: Synchronous Execution mode.
+
+Tar Internals
+
+* Standard:: Basic Tar Format
+* Extensions:: @acronym{GNU} Extensions to the Archive Format
* Snapshot Files::
* Dumpdir::
than to the file system. @xref{Writing to Standard Output}.
@opindex totals, summary
-@item --totals
+@item --totals[=@var{signo}]
-Displays the total number of bytes written after creating an archive.
-@xref{verbose}.
+Displays the total number of bytes transferred when processing an
+archive. If an argument is given, these data are displayed on
+request, when signal @var{signo} is delivered to @command{tar}.
+@xref{totals}.
@opindex touch, summary
@item --touch
verbose output to @var{file} rather than to standard output or standard
error.
+@anchor{totals}
@cindex Obtaining total status information
@opindex totals
-The @option{--totals} option---which is only meaningful when used with
-@option{--create} (@option{-c})---causes @command{tar} to print the total
-amount written to the archive, after it has been fully created.
+The @option{--totals} option causes @command{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.:
+
+@smallexample
+@group
+$ @kbd{tar -c -f archive.tar --totals /home}
+Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
+@end group
+@end smallexample
+
+When reading an archive, this option displays the number of bytes
+read:
+
+@smallexample
+@group
+$ @kbd{tar -x -f archive.tar --totals}
+Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
+@end group
+@end smallexample
+
+Finally, when deleting from an archive, the @option{--totals} option
+displays both numbers plus number of bytes removed from the archive:
+
+@smallexample
+@group
+$ @kbd{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
+@end group
+@end smallexample
+
+You can also obtain this information on request. When
+@option{--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:
+
+@table @option
+@item --totals=@var{signo}
+Print statistics upon delivery of signal @var{signo}. Valid arguments
+are: @code{SIGHUP}, @code{SIGQUIT}, @code{SIGINT}, @code{SIGUSR1} and
+@code{SIGUSR2}. Shortened names without @samp{SIG} prefix are also
+accepted.
+@end table
+
+Both forms of @option{--totals} option can be used simultaneously.
+Thus, @kbd{tar -x --totals --totals=USR1} instructs @command{tar} to
+extract all members from its default archive and print statistics
+after finishing the extraction, as well as when receiving signal
+@code{SIGUSR1}.
@anchor{Progress information}
@cindex Progress information
projects / chaz / tar / blobdiff