Import upstream version 1.28
[debian/tar] / doc / tar.info-2
index a6499dd99a2ee6a2d96af461916c14edd56ca8a3..22c9814cd4a72110328e146ef9a1462b4af9ce22 100644 (file)
@@ -1,6 +1,6 @@
 This is tar.info, produced by makeinfo version 4.13 from tar.texi.
 
-This manual is for GNU `tar' (version 1.27.1, 24 September 2013), which
+This manual is for GNU `tar' (version 1.28, 22 July 2014), which
 creates and extracts files from archives.
 
    Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2013 Free Software
@@ -28,6 +28,123 @@ START-INFO-DIR-ENTRY
 * tar: (tar)tar invocation.                     Invoking GNU `tar'.
 END-INFO-DIR-ENTRY
 
+\1f
+File: tar.info,  Node: Time of day items,  Next: Time zone items,  Prev: Calendar date items,  Up: Date input formats
+
+7.3 Time of day items
+=====================
+
+A "time of day item" in date strings specifies the time on a given day.
+Here are some examples, all of which represent the same time:
+
+     20:02:00.000000
+     20:02
+     8:02pm
+     20:02-0500      # In EST (U.S. Eastern Standard Time).
+
+   More generally, the time of day may be given as
+`HOUR:MINUTE:SECOND', where HOUR is a number between 0 and 23, MINUTE
+is a number between 0 and 59, and SECOND is a number between 0 and 59
+possibly followed by `.' or `,' and a fraction containing one or more
+digits.  Alternatively, `:SECOND' can be omitted, in which case it is
+taken to be zero.  On the rare hosts that support leap seconds, SECOND
+may be 60.
+
+   If the time is followed by `am' or `pm' (or `a.m.' or `p.m.'), HOUR
+is restricted to run from 1 to 12, and `:MINUTE' may be omitted (taken
+to be zero).  `am' indicates the first half of the day, `pm' indicates
+the second half of the day.  In this notation, 12 is the predecessor of
+1: midnight is `12am' while noon is `12pm'.  (This is the zero-oriented
+interpretation of `12am' and `12pm', as opposed to the old tradition
+derived from Latin which uses `12m' for noon and `12pm' for midnight.)
+
+   The time may alternatively be followed by a time zone correction,
+expressed as `SHHMM', where S is `+' or `-', HH is a number of zone
+hours and MM is a number of zone minutes.  The zone minutes term, MM,
+may be omitted, in which case the one- or two-digit correction is
+interpreted as a number of hours.  You can also separate HH from MM
+with a colon.  When a time zone correction is given this way, it forces
+interpretation of the time relative to Coordinated Universal Time
+(UTC), overriding any previous specification for the time zone or the
+local time zone.  For example, `+0530' and `+05:30' both stand for the
+time zone 5.5 hours ahead of UTC (e.g., India).  This is the best way to
+specify a time zone correction by fractional parts of an hour.  The
+maximum zone correction is 24 hours.
+
+   Either `am'/`pm' or a time zone correction may be specified, but not
+both.
+
+\1f
+File: tar.info,  Node: Time zone items,  Next: Combined date and time of day items,  Prev: Time of day items,  Up: Date input formats
+
+7.4 Time zone items
+===================
+
+A "time zone item" specifies an international time zone, indicated by a
+small set of letters, e.g., `UTC' or `Z' for Coordinated Universal
+Time.  Any included periods are ignored.  By following a
+non-daylight-saving time zone by the string `DST' in a separate word
+(that is, separated by some white space), the corresponding daylight
+saving time zone may be specified.  Alternatively, a
+non-daylight-saving time zone can be followed by a time zone
+correction, to add the two values.  This is normally done only for
+`UTC'; for example, `UTC+05:30' is equivalent to `+05:30'.
+
+   Time zone items other than `UTC' and `Z' are obsolescent and are not
+recommended, because they are ambiguous; for example, `EST' has a
+different meaning in Australia than in the United States.  Instead,
+it's better to use unambiguous numeric time zone corrections like
+`-0500', as described in the previous section.
+
+   If neither a time zone item nor a time zone correction is supplied,
+time stamps are interpreted using the rules of the default time zone
+(*note Specifying time zone rules::).
+
+\1f
+File: tar.info,  Node: Combined date and time of day items,  Next: Day of week items,  Prev: Time zone items,  Up: Date input formats
+
+7.5 Combined date and time of day items
+=======================================
+
+The ISO 8601 date and time of day extended format consists of an ISO
+8601 date, a `T' character separator, and an ISO 8601 time of day.
+This format is also recognized if the `T' is replaced by a space.
+
+   In this format, the time of day should use 24-hour notation.
+Fractional seconds are allowed, with either comma or period preceding
+the fraction.  ISO 8601 fractional minutes and hours are not supported.
+Typically, hosts support nanosecond timestamp resolution; excess
+precision is silently discarded.
+
+   Here are some examples:
+
+     2012-09-24T20:02:00.052-0500
+     2012-12-31T23:59:59,999999999+1100
+     1970-01-01 00:00Z
+
+\1f
+File: tar.info,  Node: Day of week items,  Next: Relative items in date strings,  Prev: Combined date and time of day items,  Up: Date input formats
+
+7.6 Day of week items
+=====================
+
+The explicit mention of a day of the week will forward the date (only
+if necessary) to reach that day of the week in the future.
+
+   Days of the week may be spelled out in full: `Sunday', `Monday',
+`Tuesday', `Wednesday', `Thursday', `Friday' or `Saturday'.  Days may
+be abbreviated to their first three letters, optionally followed by a
+period.  The special abbreviations `Tues' for `Tuesday', `Wednes' for
+`Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed.
+
+   A number may precede a day of the week item to move forward
+supplementary weeks.  It is best used in expression like `third
+monday'.  In this context, `last DAY' or `next DAY' is also acceptable;
+they move one week before or after the day that DAY by itself would
+represent.
+
+   A comma following a day of the week item is ignored.
+
 \1f
 File: tar.info,  Node: Relative items in date strings,  Next: Pure numbers in date strings,  Prev: Day of week items,  Up: Date input formats
 
@@ -267,7 +384,7 @@ v7
      Makefiles.  This practice will change in the future, in the
      meantime, however this means that projects containing file names
      more than 99 characters long will not be able to use GNU `tar'
-     1.27.1 and Automake prior to 1.9.
+     1.28 and Automake prior to 1.9.
 
 ustar
      Archive format defined by POSIX.1-1988 specification.  It stores
@@ -403,7 +520,7 @@ a list of recognized suffixes).
    Some compression programs are able to handle different compression
 formats.  GNU `tar' uses this, if the principal decompressor for the
 given format is not available.  For example, if `compress' is not
-installed, `tar' will try to use `gzip'.  As of version 1.27.1 the
+installed, `tar' will try to use `gzip'.  As of version 1.28 the
 following alternatives are tried(2):
 
 Format                 Main decompressor      Alternatives
@@ -986,14 +1103,15 @@ File: tar.info,  Node: ustar,  Next: gnu,  Prev: old,  Up: Portability
 8.3.5 Ustar Archive Format
 --------------------------
 
-Archive format defined by POSIX.1-1988 specification is called `ustar'.
-Although it is more flexible than the V7 format, it still has many
-restrictions (*note ustar: Formats, for the detailed description of
-`ustar' format).  Along with V7 format, `ustar' format is a good choice
-for archives intended to be read with other implementations of `tar'.
+The archive format defined by the POSIX.1-1988 specification is called
+`ustar'.  Although it is more flexible than the V7 format, it still has
+many restrictions (*note ustar: Formats, for the detailed description
+of `ustar' format).  Along with V7 format, `ustar' format is a good
+choice for archives intended to be read with other implementations of
+`tar'.
 
-   To create archive in `ustar' format, use `--format=ustar' option in
-conjunction with the `--create' (`-c').
+   To create an archive in `ustar' format, use the `--format=ustar'
+option in conjunction with `--create' (`-c').
 
 \1f
 File: tar.info,  Node: gnu,  Next: posix,  Prev: ustar,  Up: Portability
@@ -1178,22 +1296,22 @@ File: tar.info,  Node: Checksumming,  Next: Large or Negative Values,  Prev: pos
 
 SunOS and HP-UX `tar' fail to accept archives created using GNU `tar'
 and containing non-ASCII file names, that is, file names having
-characters with the eight bit set, because they use signed checksums,
+characters with the eighth bit set, because they use signed checksums,
 while GNU `tar' uses unsigned checksums while creating archives, as per
 POSIX standards.  On reading, GNU `tar' computes both checksums and
-accepts any.  It is somewhat worrying that a lot of people may go
-around doing backup of their files using faulty (or at least
+accepts either of them.  It is somewhat worrying that a lot of people
+may go around doing backup of their files using faulty (or at least
 non-standard) software, not learning about it until it's time to
 restore their missing files with an incompatible file extractor, or
 vice versa.
 
-   GNU `tar' computes checksums both ways, and accept any on read, so
-GNU tar can read Sun tapes even with their wrong checksums.  GNU `tar'
-produces the standard checksum, however, raising incompatibilities with
-Sun.  That is to say, GNU `tar' has not been modified to _produce_
-incorrect archives to be read by buggy `tar''s.  I've been told that
-more recent Sun `tar' now read standard archives, so maybe Sun did a
-similar patch, after all?
+   GNU `tar' computes checksums both ways, and accepts either of them
+on read, so GNU tar can read Sun tapes even with their wrong checksums.
+GNU `tar' produces the standard checksum, however, raising
+incompatibilities with Sun.  That is to say, GNU `tar' has not been
+modified to _produce_ incorrect archives to be read by buggy `tar''s.
+I've been told that more recent Sun `tar' now read standard archives,
+so maybe Sun did a similar patch, after all?
 
    The story seems to be that when Sun first imported `tar' sources on
 their system, they recompiled it without realizing that the checksums
@@ -1201,7 +1319,7 @@ were computed differently, because of a change in the default signing
 of `char''s in their compiler.  So they started computing checksums
 wrongly.  When they later realized their mistake, they merely decided
 to stay compatible with it, and with themselves afterwards.
-Presumably, but I do not really know, HP-UX has chosen that their `tar'
+Presumably, but I do not really know, HP-UX has chosen their `tar'
 archives to be compatible with Sun's.  The current standards do not
 favor Sun `tar' format.  In any case, it now falls on the shoulders of
 SunOS and HP-UX users to get a `tar' able to read the good archives
@@ -3285,7 +3403,7 @@ Appendix A Changes
 ******************
 
 This appendix lists some important user-visible changes between version
-GNU `tar' 1.27.1 and previous versions. An up-to-date version of this
+GNU `tar' 1.28 and previous versions. An up-to-date version of this
 document is available at the GNU `tar' documentation page
 (http://www.gnu.org/software/tar/manual/changes.html).
 
@@ -4353,13 +4471,13 @@ backups (*note Incremental Dumps::).  It contains the status of the
 file system at the time of the dump and is used to determine which
 files were modified since the last backup.
 
-   GNU `tar' version 1.27.1 supports three snapshot file formats.  The
+   GNU `tar' version 1.28 supports three snapshot file formats.  The
 first format, called "format 0", is the one used by GNU `tar' versions
 up to and including 1.15.1. The second format, called "format 1" is an
 extended version of this format, that contains more metadata and allows
 for further extensions. It was used by alpha release version 1.15.90.
 For alpha version 1.15.91 and stable releases version 1.16 up through
-1.27.1, the "format 2" is used.
+1.28, the "format 2" is used.
 
    GNU `tar' is able to read all three formats, but will create
 snapshots only in format 2.
@@ -4418,7 +4536,7 @@ snapshots only in format 2.
   2.   `Format 2' snapshot file begins with a format identifier, as
      described for version 1, e.g.:
 
-          GNU tar-1.27.1-2
+          GNU tar-1.28-2
 
      This line is followed by newline. Rest of file consists of
      records, separated by null (ASCII 0) characters. Thus, in contrast
@@ -4986,7 +5104,8 @@ Appendix G GNU Free Documentation License
 
                      Version 1.3, 3 November 2008
 
-     Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+     Copyright (C) 2000-2002, 2007-2008, 2014 Free Software
+     Foundation, Inc.
      `http://fsf.org/'
 
      Everyone is permitted to copy and distribute verbatim copies
@@ -5478,7 +5597,7 @@ Summary::.
 \0\b[index\0\b]
 * Menu:
 
-* --keep-directory-symlink, summary:     Option Summary.      (line 359)
+* --keep-directory-symlink, summary:     Option Summary.      (line 377)
 * absolute-names:                        absolute.            (line  10)
 * absolute-names, summary:               Option Summary.      (line   6)
 * add-file:                              files.               (line  60)
@@ -5542,24 +5661,30 @@ Summary::.
 * exclude, potential problems with:      problems with exclude.
                                                               (line   6)
 * exclude, summary:                      Option Summary.      (line 181)
-* exclude-backups:                       exclude.             (line  82)
+* exclude-backups:                       exclude.             (line 130)
 * exclude-backups, summary:              Option Summary.      (line 185)
-* exclude-caches:                        exclude.             (line 105)
+* exclude-caches:                        exclude.             (line 153)
 * exclude-caches, summary:               Option Summary.      (line 193)
-* exclude-caches-all:                    exclude.             (line 113)
+* exclude-caches-all:                    exclude.             (line 161)
 * exclude-caches-all, summary:           Option Summary.      (line 206)
-* exclude-caches-under:                  exclude.             (line 109)
+* exclude-caches-under:                  exclude.             (line 157)
 * exclude-caches-under, summary:         Option Summary.      (line 200)
 * exclude-from:                          exclude.             (line   6)
 * exclude-from, summary:                 Option Summary.      (line 188)
-* exclude-tag:                           exclude.             (line 122)
-* exclude-tag, summary:                  Option Summary.      (line 210)
-* exclude-tag-all:                       exclude.             (line 130)
-* exclude-tag-all, summary:              Option Summary.      (line 220)
-* exclude-tag-under:                     exclude.             (line 126)
-* exclude-tag-under, summary:            Option Summary.      (line 215)
-* exclude-vcs:                           exclude.             (line  37)
-* exclude-vcs, summary:                  Option Summary.      (line 224)
+* exclude-ignore:                        exclude.             (line  76)
+* exclude-ignore, summary:               Option Summary.      (line 210)
+* exclude-ignore-recursive:              exclude.             (line  81)
+* exclude-ignore-recursive, summary:     Option Summary.      (line 215)
+* exclude-tag:                           exclude.             (line 170)
+* exclude-tag, summary:                  Option Summary.      (line 220)
+* exclude-tag-all:                       exclude.             (line 178)
+* exclude-tag-all, summary:              Option Summary.      (line 230)
+* exclude-tag-under:                     exclude.             (line 174)
+* exclude-tag-under, summary:            Option Summary.      (line 225)
+* exclude-vcs:                           exclude.             (line  85)
+* exclude-vcs, summary:                  Option Summary.      (line 234)
+* exclude-vcs-ignores:                   exclude.             (line  42)
+* exclude-vcs-ignores, summary:          Option Summary.      (line 240)
 * extract:                               extract.             (line   6)
 * extract, additional options:           extract options.     (line   6)
 * extract, complementary notes:          Basic tar.           (line  48)
@@ -5568,56 +5693,56 @@ Summary::.
                                                               (line 121)
 * file:                                  file.                (line   6)
 * file, short description:               file.                (line  15)
-* file, summary:                         Option Summary.      (line 230)
+* file, summary:                         Option Summary.      (line 248)
 * file, tutorial:                        file tutorial.       (line   6)
 * files-from:                            files.               (line  14)
-* files-from, summary:                   Option Summary.      (line 236)
+* files-from, summary:                   Option Summary.      (line 254)
 * force-local, short description:        Device.              (line  70)
-* force-local, summary:                  Option Summary.      (line 242)
-* format, summary:                       Option Summary.      (line 247)
-* full-time, summary:                    Option Summary.      (line 272)
+* force-local, summary:                  Option Summary.      (line 260)
+* format, summary:                       Option Summary.      (line 265)
+* full-time, summary:                    Option Summary.      (line 290)
 * get, summary:                          Operation Summary.   (line  42)
 * group:                                 override.            (line  88)
-* group, summary:                        Option Summary.      (line 290)
-* gunzip, summary:                       Option Summary.      (line 298)
+* group, summary:                        Option Summary.      (line 308)
+* gunzip, summary:                       Option Summary.      (line 316)
 * gzip:                                  gzip.                (line  91)
-* gzip, summary:                         Option Summary.      (line 298)
+* gzip, summary:                         Option Summary.      (line 316)
 * hard-dereference, described:           hard links.          (line  59)
-* hard-dereference, summary:             Option Summary.      (line 306)
+* hard-dereference, summary:             Option Summary.      (line 324)
 * help:                                  help tutorial.       (line   6)
 * help, introduction:                    help.                (line  26)
-* help, summary:                         Option Summary.      (line 312)
+* help, summary:                         Option Summary.      (line 330)
 * ignore-case:                           controlling pattern-matching.
                                                               (line  86)
-* ignore-case, summary:                  Option Summary.      (line 317)
+* ignore-case, summary:                  Option Summary.      (line 335)
 * ignore-command-error:                  Writing to an External Program.
                                                               (line 110)
-* ignore-command-error, summary:         Option Summary.      (line 321)
+* ignore-command-error, summary:         Option Summary.      (line 339)
 * ignore-failed-read:                    Ignore Failed Read.  (line   7)
-* ignore-failed-read, summary:           Option Summary.      (line 325)
+* ignore-failed-read, summary:           Option Summary.      (line 343)
 * ignore-zeros:                          Ignore Zeros.        (line   6)
 * ignore-zeros, short description:       Blocking Factor.     (line 156)
-* ignore-zeros, summary:                 Option Summary.      (line 329)
-* incremental, summary:                  Option Summary.      (line 334)
+* ignore-zeros, summary:                 Option Summary.      (line 347)
+* incremental, summary:                  Option Summary.      (line 352)
 * incremental, using with --list:        Incremental Dumps.   (line 186)
-* index-file, summary:                   Option Summary.      (line 341)
+* index-file, summary:                   Option Summary.      (line 359)
 * info-script:                           Multi-Volume Archives.
                                                               (line  88)
 * info-script, short description:        Device.              (line 122)
-* info-script, summary:                  Option Summary.      (line 344)
+* info-script, summary:                  Option Summary.      (line 362)
 * interactive:                           interactive.         (line  14)
-* interactive, summary:                  Option Summary.      (line 352)
+* interactive, summary:                  Option Summary.      (line 370)
 * keep-newer-files:                      Keep Newer Files.    (line   6)
-* keep-newer-files, summary:             Option Summary.      (line 372)
+* keep-newer-files, summary:             Option Summary.      (line 390)
 * keep-old-files:                        Keep Old Files.      (line   9)
 * keep-old-files, introduced:            Dealing with Old Files.
                                                               (line  16)
-* keep-old-files, summary:               Option Summary.      (line 376)
+* keep-old-files, summary:               Option Summary.      (line 394)
 * label <1>:                             label.               (line   6)
 * label:                                 Tape Files.          (line   6)
-* label, summary:                        Option Summary.      (line 384)
+* label, summary:                        Option Summary.      (line 402)
 * level, described:                      Incremental Dumps.   (line  76)
-* level, summary:                        Option Summary.      (line 391)
+* level, summary:                        Option Summary.      (line 409)
 * list:                                  list.                (line   6)
 * list, summary:                         Operation Summary.   (line  46)
 * list, using with --incremental:        Incremental Dumps.   (line 186)
@@ -5625,207 +5750,209 @@ Summary::.
 * list, using with --verbose:            list.                (line  30)
 * list, using with file name arguments:  list.                (line  68)
 * listed-incremental, described:         Incremental Dumps.   (line  14)
-* listed-incremental, summary:           Option Summary.      (line 401)
+* listed-incremental, summary:           Option Summary.      (line 419)
 * listed-incremental, using with --extract: Incremental Dumps.
                                                               (line 121)
 * listed-incremental, using with --list: Incremental Dumps.   (line 186)
 * lzip:                                  gzip.                (line 104)
-* lzip, summary:                         Option Summary.      (line 409)
+* lzip, summary:                         Option Summary.      (line 427)
 * lzma:                                  gzip.                (line 107)
-* lzma, summary:                         Option Summary.      (line 413)
+* lzma, summary:                         Option Summary.      (line 431)
 * lzop:                                  gzip.                (line 110)
 * mode:                                  override.            (line  14)
-* mode, summary:                         Option Summary.      (line 421)
+* mode, summary:                         Option Summary.      (line 439)
 * mtime:                                 override.            (line  29)
-* mtime, summary:                        Option Summary.      (line 427)
+* mtime, summary:                        Option Summary.      (line 445)
 * multi-volume:                          Multi-Volume Archives.
                                                               (line   6)
 * multi-volume, short description:       Device.              (line  88)
-* multi-volume, summary:                 Option Summary.      (line 436)
+* multi-volume, summary:                 Option Summary.      (line 454)
 * new-volume-script:                     Multi-Volume Archives.
                                                               (line  88)
 * new-volume-script, short description:  Device.              (line 122)
-* new-volume-script, summary:            Option Summary.      (line 344)
+* new-volume-script, summary:            Option Summary.      (line 362)
 * newer:                                 after.               (line  24)
-* newer, summary:                        Option Summary.      (line 444)
+* newer, summary:                        Option Summary.      (line 462)
 * newer-mtime:                           after.               (line  35)
-* newer-mtime, summary:                  Option Summary.      (line 452)
+* newer-mtime, summary:                  Option Summary.      (line 470)
 * no-anchored:                           controlling pattern-matching.
                                                               (line  79)
-* no-anchored, summary:                  Option Summary.      (line 457)
-* no-auto-compress, summary:             Option Summary.      (line 461)
+* no-anchored, summary:                  Option Summary.      (line 475)
+* no-auto-compress, summary:             Option Summary.      (line 479)
 * no-check-device, described:            Incremental Dumps.   (line 104)
-* no-check-device, summary:              Option Summary.      (line 465)
+* no-check-device, summary:              Option Summary.      (line 483)
 * no-delay-directory-restore:            Directory Modification Times and Permissions.
                                                               (line  68)
-* no-delay-directory-restore, summary:   Option Summary.      (line 470)
+* no-delay-directory-restore, summary:   Option Summary.      (line 488)
 * no-ignore-case:                        controlling pattern-matching.
                                                               (line  86)
-* no-ignore-case, summary:               Option Summary.      (line 476)
+* no-ignore-case, summary:               Option Summary.      (line 494)
 * no-ignore-command-error:               Writing to an External Program.
                                                               (line 115)
-* no-ignore-command-error, summary:      Option Summary.      (line 479)
+* no-ignore-command-error, summary:      Option Summary.      (line 497)
 * no-null, described:                    nul.                 (line  15)
-* no-null, summary:                      Option Summary.      (line 483)
-* no-overwrite-dir, summary:             Option Summary.      (line 488)
-* no-quote-chars, summary:               Option Summary.      (line 492)
+* no-null, summary:                      Option Summary.      (line 501)
+* no-overwrite-dir, summary:             Option Summary.      (line 506)
+* no-quote-chars, summary:               Option Summary.      (line 510)
 * no-recursion:                          recurse.             (line  11)
-* no-recursion, summary:                 Option Summary.      (line 497)
+* no-recursion, summary:                 Option Summary.      (line 515)
 * no-same-owner:                         Attributes.          (line  63)
-* no-same-owner, summary:                Option Summary.      (line 501)
-* no-same-permissions, summary:          Option Summary.      (line 507)
-* no-seek, summary:                      Option Summary.      (line 512)
+* no-same-owner, summary:                Option Summary.      (line 519)
+* no-same-permissions, summary:          Option Summary.      (line 525)
+* no-seek, summary:                      Option Summary.      (line 530)
 * no-unquote:                            Selecting Archive Members.
                                                               (line  42)
-* no-unquote, summary:                   Option Summary.      (line 517)
+* no-unquote, summary:                   Option Summary.      (line 535)
 * no-wildcards:                          controlling pattern-matching.
                                                               (line  41)
-* no-wildcards, summary:                 Option Summary.      (line 521)
+* no-wildcards, summary:                 Option Summary.      (line 539)
 * no-wildcards-match-slash:              controlling pattern-matching.
                                                               (line  92)
-* no-wildcards-match-slash, summary:     Option Summary.      (line 524)
+* no-wildcards-match-slash, summary:     Option Summary.      (line 542)
 * null, described:                       nul.                 (line  11)
-* null, summary:                         Option Summary.      (line 527)
+* null, summary:                         Option Summary.      (line 545)
 * numeric-owner:                         Attributes.          (line  69)
-* numeric-owner, summary:                Option Summary.      (line 533)
+* numeric-owner, summary:                Option Summary.      (line 551)
 * occurrence, described:                 append.              (line  34)
-* occurrence, summary:                   Option Summary.      (line 550)
-* old-archive, summary:                  Option Summary.      (line 564)
+* occurrence, summary:                   Option Summary.      (line 568)
+* old-archive, summary:                  Option Summary.      (line 582)
 * one-file-system:                       one.                 (line  14)
-* one-file-system, summary:              Option Summary.      (line 567)
+* one-file-system, summary:              Option Summary.      (line 585)
+* one-top-level, summary:                Option Summary.      (line 590)
 * overwrite:                             Overwrite Old Files. (line   6)
 * overwrite, introduced:                 Dealing with Old Files.
                                                               (line  32)
-* overwrite, summary:                    Option Summary.      (line 572)
+* overwrite, summary:                    Option Summary.      (line 601)
 * overwrite-dir:                         Overwrite Old Files. (line  28)
 * overwrite-dir, introduced:             Dealing with Old Files.
                                                               (line   6)
-* overwrite-dir, summary:                Option Summary.      (line 576)
+* overwrite-dir, summary:                Option Summary.      (line 605)
 * owner:                                 override.            (line  57)
-* owner, summary:                        Option Summary.      (line 580)
+* owner, summary:                        Option Summary.      (line 609)
 * pax-option:                            PAX keywords.        (line   6)
-* pax-option, summary:                   Option Summary.      (line 588)
-* portability, summary:                  Option Summary.      (line 594)
-* posix, summary:                        Option Summary.      (line 598)
+* pax-option, summary:                   Option Summary.      (line 617)
+* portability, summary:                  Option Summary.      (line 623)
+* posix, summary:                        Option Summary.      (line 627)
 * preserve:                              Attributes.          (line 122)
-* preserve, summary:                     Option Summary.      (line 601)
+* preserve, summary:                     Option Summary.      (line 630)
 * preserve-order:                        Same Order.          (line   6)
-* preserve-order, summary:               Option Summary.      (line 605)
+* preserve-order, summary:               Option Summary.      (line 634)
 * preserve-permissions:                  Setting Access Permissions.
                                                               (line  10)
 * preserve-permissions, short description: Attributes.        (line 109)
-* preserve-permissions, summary:         Option Summary.      (line 608)
-* quote-chars, summary:                  Option Summary.      (line 618)
+* preserve-permissions, summary:         Option Summary.      (line 637)
+* quote-chars, summary:                  Option Summary.      (line 647)
 * quoting-style:                         quoting styles.      (line  38)
-* quoting-style, summary:                Option Summary.      (line 622)
+* quoting-style, summary:                Option Summary.      (line 651)
 * read-full-records <1>:                 read full records.   (line   6)
 * read-full-records:                     Reading.             (line   6)
 * read-full-records, short description:  Blocking Factor.     (line 172)
-* read-full-records, summary:            Option Summary.      (line 629)
-* record-size, summary:                  Option Summary.      (line 634)
+* read-full-records, summary:            Option Summary.      (line 658)
+* record-size, summary:                  Option Summary.      (line 663)
 * recursion:                             recurse.             (line  22)
-* recursion, summary:                    Option Summary.      (line 641)
+* recursion, summary:                    Option Summary.      (line 670)
 * recursive-unlink:                      Recursive Unlink.    (line   6)
-* recursive-unlink, summary:             Option Summary.      (line 645)
+* recursive-unlink, summary:             Option Summary.      (line 674)
 * remove-files:                          remove files.        (line   6)
-* remove-files, summary:                 Option Summary.      (line 650)
-* restrict, summary:                     Option Summary.      (line 654)
-* rmt-command, summary:                  Option Summary.      (line 659)
+* remove-files, summary:                 Option Summary.      (line 679)
+* restrict, summary:                     Option Summary.      (line 683)
+* rmt-command, summary:                  Option Summary.      (line 688)
 * rsh-command:                           Device.              (line  73)
-* rsh-command, summary:                  Option Summary.      (line 663)
+* rsh-command, summary:                  Option Summary.      (line 692)
 * same-order:                            Same Order.          (line   6)
-* same-order, summary:                   Option Summary.      (line 667)
+* same-order, summary:                   Option Summary.      (line 696)
 * same-owner:                            Attributes.          (line  44)
-* same-owner, summary:                   Option Summary.      (line 675)
+* same-owner, summary:                   Option Summary.      (line 704)
 * same-permissions:                      Setting Access Permissions.
                                                               (line  10)
 * same-permissions, short description:   Attributes.          (line 109)
-* same-permissions, summary:             Option Summary.      (line 608)
-* seek, summary:                         Option Summary.      (line 684)
+* same-permissions, summary:             Option Summary.      (line 637)
+* seek, summary:                         Option Summary.      (line 713)
 * show-defaults:                         defaults.            (line   6)
-* show-defaults, summary:                Option Summary.      (line 693)
+* show-defaults, summary:                Option Summary.      (line 722)
 * show-omitted-dirs:                     verbose.             (line 107)
-* show-omitted-dirs, summary:            Option Summary.      (line 705)
+* show-omitted-dirs, summary:            Option Summary.      (line 734)
 * show-snapshot-field-ranges:            Snapshot Files.      (line 113)
-* show-snapshot-field-ranges, summary:   Option Summary.      (line 709)
+* show-snapshot-field-ranges, summary:   Option Summary.      (line 738)
 * show-stored-names:                     list.                (line  60)
-* show-stored-names, summary:            Option Summary.      (line 714)
+* show-stored-names, summary:            Option Summary.      (line 743)
 * show-transformed-names:                transform.           (line  45)
-* show-transformed-names, summary:       Option Summary.      (line 714)
+* show-transformed-names, summary:       Option Summary.      (line 743)
 * skip-old-files, introduced:            Dealing with Old Files.
                                                               (line  28)
-* skip-old-files, summary:               Option Summary.      (line 722)
+* skip-old-files, summary:               Option Summary.      (line 751)
+* sort, summary:                         Option Summary.      (line 763)
 * sparse:                                sparse.              (line  22)
-* sparse, summary:                       Option Summary.      (line 734)
+* sparse, summary:                       Option Summary.      (line 782)
 * sparse-version:                        sparse.              (line  57)
-* sparse-version, summary:               Option Summary.      (line 739)
+* sparse-version, summary:               Option Summary.      (line 787)
 * starting-file:                         Starting File.       (line   6)
-* starting-file, summary:                Option Summary.      (line 744)
+* starting-file, summary:                Option Summary.      (line 792)
 * strip-components:                      transform.           (line  25)
-* strip-components, summary:             Option Summary.      (line 750)
+* strip-components, summary:             Option Summary.      (line 798)
 * suffix:                                backup.              (line  68)
-* suffix, summary:                       Option Summary.      (line 759)
+* suffix, summary:                       Option Summary.      (line 807)
 * tape-length:                           Multi-Volume Archives.
                                                               (line  33)
 * tape-length, short description:        Device.              (line  96)
-* tape-length, summary:                  Option Summary.      (line 763)
+* tape-length, summary:                  Option Summary.      (line 811)
 * test-label:                            label.               (line  35)
-* test-label, summary:                   Option Summary.      (line 772)
+* test-label, summary:                   Option Summary.      (line 820)
 * to-command:                            Writing to an External Program.
                                                               (line   9)
-* to-command, summary:                   Option Summary.      (line 776)
+* to-command, summary:                   Option Summary.      (line 824)
 * to-stdout:                             Writing to Standard Output.
                                                               (line  14)
-* to-stdout, summary:                    Option Summary.      (line 780)
+* to-stdout, summary:                    Option Summary.      (line 828)
 * totals:                                verbose.             (line  46)
-* totals, summary:                       Option Summary.      (line 785)
+* totals, summary:                       Option Summary.      (line 833)
 * touch <1>:                             Attributes.          (line  33)
 * touch:                                 Data Modification Times.
                                                               (line  15)
-* touch, summary:                        Option Summary.      (line 790)
+* touch, summary:                        Option Summary.      (line 838)
 * transform:                             transform.           (line  74)
-* transform, summary:                    Option Summary.      (line 796)
+* transform, summary:                    Option Summary.      (line 844)
 * uncompress:                            gzip.                (line 113)
 * uncompress, summary:                   Option Summary.      (line 153)
 * ungzip:                                gzip.                (line  91)
-* ungzip, summary:                       Option Summary.      (line 298)
+* ungzip, summary:                       Option Summary.      (line 316)
 * unlink-first:                          Unlink First.        (line   6)
 * unlink-first, introduced:              Dealing with Old Files.
                                                               (line  52)
-* unlink-first, summary:                 Option Summary.      (line 816)
+* unlink-first, summary:                 Option Summary.      (line 864)
 * unquote:                               Selecting Archive Members.
                                                               (line  39)
-* unquote, summary:                      Option Summary.      (line 822)
+* unquote, summary:                      Option Summary.      (line 870)
 * update <1>:                            how to update.       (line   6)
 * update:                                update.              (line   6)
 * update, summary:                       Operation Summary.   (line  50)
 * usage:                                 help.                (line  53)
 * use-compress-program:                  gzip.                (line 177)
-* use-compress-program, summary:         Option Summary.      (line 826)
-* utc, summary:                          Option Summary.      (line 831)
+* use-compress-program, summary:         Option Summary.      (line 874)
+* utc, summary:                          Option Summary.      (line 879)
 * verbose:                               verbose.             (line  18)
 * verbose, introduced:                   verbose tutorial.    (line   6)
-* verbose, summary:                      Option Summary.      (line 835)
+* verbose, summary:                      Option Summary.      (line 883)
 * verbose, using with --create:          create verbose.      (line   6)
 * verbose, using with --list:            list.                (line  30)
 * verify, short description:             verify.              (line   8)
-* verify, summary:                       Option Summary.      (line 842)
+* verify, summary:                       Option Summary.      (line 890)
 * verify, using with --create:           verify.              (line  24)
 * version:                               help.                (line   6)
-* version, summary:                      Option Summary.      (line 847)
+* version, summary:                      Option Summary.      (line 895)
 * volno-file:                            Multi-Volume Archives.
                                                               (line  79)
-* volno-file, summary:                   Option Summary.      (line 852)
+* volno-file, summary:                   Option Summary.      (line 900)
 * warning, explained:                    warnings.            (line  12)
-* warning, summary:                      Option Summary.      (line 857)
+* warning, summary:                      Option Summary.      (line 905)
 * wildcards:                             controlling pattern-matching.
                                                               (line  38)
-* wildcards, summary:                    Option Summary.      (line 862)
+* wildcards, summary:                    Option Summary.      (line 910)
 * wildcards-match-slash:                 controlling pattern-matching.
                                                               (line  92)
-* wildcards-match-slash, summary:        Option Summary.      (line 866)
+* wildcards-match-slash, summary:        Option Summary.      (line 914)
 * xform:                                 transform.           (line  74)
-* xform, summary:                        Option Summary.      (line 796)
+* xform, summary:                        Option Summary.      (line 844)
 * xz:                                    gzip.                (line  96)
-* xz, summary:                           Option Summary.      (line 869)
+* xz, summary:                           Option Summary.      (line 917)