Merging upstream version 1.13~rc1.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 91 insertions, 110 deletions

diff --git a/doc/zutils.info b/doc/zutils.info
index a344507..78e5996 100644
--- a/doc/zutils.info
+++ b/doc/zutils.info
@@ -11,7 +11,7 @@ File: zutils.info,  Node: Top,  Next: Introduction,  Up: (dir)
 Zutils Manual
 *************
 
-This manual is for Zutils (version 1.12, 7 January 2023).
+This manual is for Zutils (version 1.13-rc1, 31 December 2023).
 
 * Menu:
 
@@ -43,8 +43,8 @@ Zutils is a collection of utilities able to process any combination of
 compressed and uncompressed files transparently. If any file given,
 including standard input, is compressed, its decompressed content is used.
 Compressed files are decompressed on the fly; no temporary files are
-created. Data format is detected by its magic bytes, not by the file name
-extension.
+created. Data format is detected by its identifier string (magic bytes), not
+by the file name extension. Empty files are considered uncompressed.
 
    These utilities are not wrapper scripts but safer and more efficient C++
 programs. In particular the option '--recursive' is very efficient in those
@@ -60,6 +60,10 @@ is configurable at runtime.
 shell scripts provided by GNU gzip. 'ztest' is unique to zutils. 'zupdate'
 is similar to gzip's znew.
 
+   When 'zcat', 'zcmp', 'zdiff', or 'zgrep' need to try compressed file
+names, the search order is: lzip, gzip, bzip2, zstd, xz.
+(FILE.[lz|gz|bz2|zst|xz]).
+
    NOTE: Bzip2 and lzip provide well-defined values of exit status, which
 makes them safe to use with zutils. Gzip and xz may return ambiguous warning
 values, making them less reliable back ends for zutils. Zstd currently does
@@ -79,22 +83,6 @@ example GNU gzip) must be able to decompress .Z files.
 have been compressed. Decompressed is used to refer to data which have
 undergone the process of decompression.
 
-
-   Numbers given as arguments to options (positions, sizes) may be followed
-by a multiplier and an optional 'B' for "byte".
-
-   Table of SI and binary prefixes (unit multipliers):
-
-Prefix   Value                     |   Prefix   Value
-k        kilobyte  (10^3 = 1000)   |   Ki       kibibyte (2^10 = 1024)
-M        megabyte  (10^6)          |   Mi       mebibyte (2^20)
-G        gigabyte  (10^9)          |   Gi       gibibyte (2^30)
-T        terabyte  (10^12)         |   Ti       tebibyte (2^40)
-P        petabyte  (10^15)         |   Pi       pebibyte (2^50)
-E        exabyte   (10^18)         |   Ei       exbibyte (2^60)
-Z        zettabyte (10^21)         |   Zi       zebibyte (2^70)
-Y        yottabyte (10^24)         |   Yi       yobibyte (2^80)
-
 
 File: zutils.info,  Node: Common options,  Next: Configuration,  Prev: Introduction,  Up: Top
 
@@ -103,7 +91,8 @@ File: zutils.info,  Node: Common options,  Next: Configuration,  Prev: Introduct
 
 The following options: are available in all the utilities. Rather than
 writing identical descriptions for each of the programs, they are described
-here. *Note Argument syntax: (arg_parser)Argument syntax.
+here. Remember to prepend './' to any file name beginning with a hyphen, or
+use '--'. *Note Argument syntax: (arg_parser)Argument syntax.
 
 '-h'
 '--help'
@@ -168,6 +157,24 @@ here. *Note Argument syntax: (arg_parser)Argument syntax.
           otherwise.
 
 
+   Numbers given as arguments to options may be expressed in decimal,
+hexadecimal, or octal (using the same syntax as integer constants in C++),
+and may be followed by a multiplier and an optional 'B' for "byte".
+
+   Table of SI and binary prefixes (unit multipliers):
+
+Prefix   Value                      |   Prefix   Value
+k        kilobyte   (10^3 = 1000)   |   Ki       kibibyte  (2^10 = 1024)
+M        megabyte   (10^6)          |   Mi       mebibyte  (2^20)
+G        gigabyte   (10^9)          |   Gi       gibibyte  (2^30)
+T        terabyte   (10^12)         |   Ti       tebibyte  (2^40)
+P        petabyte   (10^15)         |   Pi       pebibyte  (2^50)
+E        exabyte    (10^18)         |   Ei       exbibyte  (2^60)
+Z        zettabyte  (10^21)         |   Zi       zebibyte  (2^70)
+Y        yottabyte  (10^24)         |   Yi       yobibyte  (2^80)
+R        ronnabyte  (10^27)         |   Ri       robibyte  (2^90)
+Q        quettabyte (10^30)         |   Qi       quebibyte (2^100)
+
 
 File: zutils.info,  Node: Configuration,  Next: Zcat,  Prev: Common options,  Up: Top
 
@@ -204,8 +211,8 @@ File: zutils.info,  Node: Zcat,  Next: Zcmp,  Prev: Configuration,  Up: Top
 file given is compressed, its decompressed content is copied. If a file
 given does not exist, and its name does not end with one of the known
 extensions, 'zcat' tries the compressed file names corresponding to the
-formats supported. If a file fails to decompress, 'zcat' continues copying
-the rest of the files.
+formats supported until one is found. *Note search-order::. If a file fails
+to decompress, 'zcat' continues copying the rest of the files.
 
    If a file is specified as '-', data are read from standard input,
 decompressed if needed, and sent to standard output. Data read from
@@ -248,8 +255,8 @@ Exit status is 0 if no errors occurred, 1 otherwise.
      Force the compressed format given. Valid values for FORMAT are 'bz2',
      'gz', 'lz', 'xz', 'zst', and 'un' for 'uncompressed'. If this option
      is used, the files are passed to the corresponding decompressor (or
-     transmitted unmodified) without verifying their format, and the exact
-     file name must be given. Other names won't be tried.
+     transmitted unmodified) without checking their format, and the exact
+     file name must be given. Other names are not tried.
 
 '-q'
 '--quiet'
@@ -306,15 +313,10 @@ are created.
      zcmp [OPTIONS] FILE1 [FILE2]
 
 This compares FILE1 to FILE2. The standard input is used only if FILE1 or
-FILE2 refers to standard input. If FILE2 is omitted 'zcmp' tries the
-following:
-
-   - If FILE1 is compressed, compares its decompressed contents with the
-     corresponding uncompressed file (the name of FILE1 with the extension
-     removed).
-
-   - If FILE1 is uncompressed, compares it with the decompressed contents
-     of FILE1.[lz|bz2|gz|zst|xz] (the first one that is found).
+FILE2 refers to standard input. If FILE2 is omitted 'zcmp' tries to compare
+FILE1 with the corresponding uncompressed file (if FILE1 is compressed),
+and then with the corresponding compressed files of the remaining formats
+until one is found. *Note search-order::.
 
 An exit status of 0 means no differences were found, 1 means some
 differences were found, and 2 means trouble.
@@ -351,14 +353,13 @@ differences were found, and 2 means trouble.
 
 '-O [FORMAT1][,FORMAT2]'
 '--force-format=[FORMAT1][,FORMAT2]'
-     Force the compressed formats given. Any of FORMAT1 or FORMAT2 may be
-     omitted and the corresponding format will be automatically detected.
-     Valid values for FORMAT are 'bz2', 'gz', 'lz', 'xz', 'zst', and 'un'
-     for 'uncompressed'. If at least one format is specified with this
-     option, the file is passed to the corresponding decompressor (or
-     transmitted unmodified) without verifying its format, and the exact
-     file names of both FILE1 and FILE2 must be given. Other names won't be
-     tried.
+     Force the compressed formats given. If FORMAT1 or FORMAT2 is omitted,
+     the corresponding format is automatically detected. Valid values for
+     FORMAT are 'bz2', 'gz', 'lz', 'xz', 'zst', and 'un' for
+     'uncompressed'. If at least one format is specified with this option,
+     the file is passed to the corresponding decompressor (or transmitted
+     unmodified) without checking its format, and the exact file names of
+     both FILE1 and FILE2 must be given. Other names are not tried.
 
 '-q'
 '--quiet'
@@ -382,22 +383,6 @@ differences were found, and 2 means trouble.
      the verbosity level. *Note version::.
 
 
-   Byte counts given as arguments to options may be expressed in decimal,
-hexadecimal, or octal (using the same syntax as integer constants in C++),
-and may be followed by a multiplier and an optional 'B' for "byte".
-
-   Table of SI and binary prefixes (unit multipliers):
-
-Prefix   Value                     |   Prefix   Value
-k        kilobyte  (10^3 = 1000)   |   Ki       kibibyte (2^10 = 1024)
-M        megabyte  (10^6)          |   Mi       mebibyte (2^20)
-G        gigabyte  (10^9)          |   Gi       gibibyte (2^30)
-T        terabyte  (10^12)         |   Ti       tebibyte (2^40)
-P        petabyte  (10^15)         |   Pi       pebibyte (2^50)
-E        exabyte   (10^18)         |   Ei       exbibyte (2^60)
-Z        zettabyte (10^21)         |   Zi       zebibyte (2^70)
-Y        yottabyte (10^24)         |   Yi       yobibyte (2^80)
-
 
 File: zutils.info,  Node: Zdiff,  Next: Zgrep,  Prev: Zcmp,  Up: Top
 
@@ -416,15 +401,10 @@ specified.
      zdiff [OPTIONS] FILE1 [FILE2]
 
 This compares FILE1 to FILE2. The standard input is used only if FILE1 or
-FILE2 refers to standard input. If FILE2 is omitted 'zdiff' tries the
-following:
-
-   - If FILE1 is compressed, compares its decompressed contents with the
-     corresponding uncompressed file (the name of FILE1 with the extension
-     removed).
-
-   - If FILE1 is uncompressed, compares it with the decompressed contents
-     of FILE1.[lz|bz2|gz|zst|xz] (the first one that is found).
+FILE2 refers to standard input. If FILE2 is omitted 'zdiff' tries to
+compare FILE1 with the corresponding uncompressed file (if FILE1 is
+compressed), and then with the corresponding compressed files of the
+remaining formats until one is found. *Note search-order::.
 
 An exit status of 0 means no differences were found, 1 means some
 differences were found, and 2 means trouble.
@@ -461,18 +441,18 @@ diff program used supports them):
 
 '-i'
 '--ignore-case'
-     Ignore case differences in file contents.
+     Ignore case differences. Consider uppercase and lowercase letters
+     equivalent.
 
 '-O [FORMAT1][,FORMAT2]'
 '--force-format=[FORMAT1][,FORMAT2]'
-     Force the compressed formats given. Any of FORMAT1 or FORMAT2 may be
-     omitted and the corresponding format will be automatically detected.
-     Valid values for FORMAT are 'bz2', 'gz', 'lz', 'xz', 'zst', and 'un'
-     for 'uncompressed'. If at least one format is specified with this
-     option, the file is passed to the corresponding decompressor (or
-     transmitted unmodified) without verifying its format, and the exact
-     file names of both FILE1 and FILE2 must be given. Other names won't be
-     tried.
+     Force the compressed formats given. If FORMAT1 or FORMAT2 is omitted,
+     the corresponding format is automatically detected. Valid values for
+     FORMAT are 'bz2', 'gz', 'lz', 'xz', 'zst', and 'un' for
+     'uncompressed'. If at least one format is specified with this option,
+     the file is passed to the corresponding decompressor (or transmitted
+     unmodified) without checking its format, and the exact file names of
+     both FILE1 and FILE2 must be given. Other names are not tried.
 
 '-p'
 '--show-c-function'
@@ -531,9 +511,9 @@ File: zutils.info,  Node: Zgrep,  Next: Ztest,  Prev: Zdiff,  Up: Top
 on any combination of compressed and uncompressed files. If any file given
 is compressed, its decompressed content is used. If a file given does not
 exist, and its name does not end with one of the known extensions, 'zgrep'
-tries the compressed file names corresponding to the formats supported. If
-a file fails to decompress, 'zgrep' continues searching the rest of the
-files.
+tries the compressed file names corresponding to the formats supported
+until one is found. *Note search-order::. If a file fails to decompress,
+'zgrep' continues searching the rest of the files.
 
    If a file is specified as '-', data are read from standard input,
 decompressed if needed, and fed to grep. Data read from standard input must
@@ -665,8 +645,8 @@ by 'zgrep' and not passed to grep):
      Force the compressed format given. Valid values for FORMAT are 'bz2',
      'gz', 'lz', 'xz', 'zst', and 'un' for 'uncompressed'. If this option
      is used, the files are passed to the corresponding decompressor (or
-     transmitted unmodified) without verifying their format, and the exact
-     file name must be given. Other names won't be tried.
+     transmitted unmodified) without checking their format, and the exact
+     file name must be given. Other names are not tried.
 
 '-P'
 '--perl-regexp'
@@ -735,14 +715,14 @@ File: zutils.info,  Node: Ztest,  Next: Zupdate,  Prev: Zgrep,  Up: Top
 8 Ztest
 *******
 
-'ztest' verifies the integrity of the compressed files specified. It also
+'ztest' checks the integrity of the compressed files specified. It also
 warns if an uncompressed file has a compressed file name extension, or if a
 compressed file has a wrong compressed extension. Uncompressed files are
 otherwise ignored. If a file is specified as '-', the integrity of
-compressed data read from standard input is verified. Data read from
+compressed data read from standard input is checked. Data read from
 standard input must be all in the same compressed format. If a file fails to
 decompress, does not exist, can't be opened, or is a terminal, 'ztest'
-continues verifying the rest of the files. A final diagnostic is shown at
+continues testing the rest of the files. A final diagnostic is shown at
 verbosity level 1 or higher if any file fails the test when testing multiple
 files.
 
@@ -755,17 +735,17 @@ corresponding files are ignored.
 
    Note that error detection in the xz format is broken. First, some xz
 files lack integrity information. Second, not all xz decompressors can
-verify the integrity of all xz files. Third, section 2.1.1.2 'Stream Flags'
+check the integrity of all xz files. Third, section 2.1.1.2 'Stream Flags'
 of the xz format specification allows xz decompressors to produce garbage
 output without issuing any warning. Therefore, xz files can't always be
-verified as reliably as files in the other formats can.
+checked as reliably as files in the other formats can.
 
    The format for running 'ztest' is:
 
      ztest [OPTIONS] [FILES]
 
-Exit status is 0 if all compressed files verify OK, 1 if environmental
-problems (file not found, invalid command line options, I/O errors, etc), 2
+Exit status is 0 if all compressed files check OK, 1 if environmental
+problems (file not found, invalid command-line options, I/O errors, etc), 2
 if any compressed file is corrupt or invalid, or if any file has an
 incorrect file name extension.
 
@@ -775,9 +755,9 @@ incorrect file name extension.
 '--force-format=FORMAT'
      Force the compressed format given. Valid values for FORMAT are 'bz2',
      'gz', 'lz', 'xz', and 'zst'. If this option is used, the files are
-     passed to the corresponding decompressor without verifying their
+     passed to the corresponding decompressor without checking their
      format, and any files in a format that the decompressor can't
-     understand will fail.
+     understand fail the test.
 
 '-q'
 '--quiet'
@@ -796,7 +776,7 @@ incorrect file name extension.
 
 '-v'
 '--verbose'
-     Verbose mode. Show the verify status for each file processed. Further
+     Verbose mode. Show the check status for each file processed. Further
      -v's increase the verbosity level. *Note version::.
 
 
@@ -813,20 +793,20 @@ files are ignored. Compressed files are decompressed and then recompressed
 on the fly; no temporary files are created. If an error happens while
 recompressing a file, 'zupdate' exits immediately without recompressing the
 rest of the files. The lzip format is chosen as destination because it is
-the most appropriate for long-term data archiving.
+the most appropriate for long-term archiving.
 
    If no files are specified, recursive searches examine the current working
 directory, and nonrecursive searches do nothing.
 
-   If the lzip compressed version of a file already exists, the file is
+   If the lzip-compressed version of a file already exists, the file is
 skipped unless the option '--force' is given. In this case, if the
 comparison with the existing lzip version fails, an error is returned and
 the original file is not deleted. The operation of 'zupdate' is meant to be
-safe and not cause any data loss. Therefore, existing lzip compressed files
+safe and not cause any data loss. Therefore, existing lzip-compressed files
 are never overwritten nor deleted.
 
    Combining the options '--force' and '--keep', as in
-'zupdate -f -k *.gz', verifies that there are no differences between each
+'zupdate -f -k *.gz', checks that there are no differences between each
 pair of files in a multiformat set of files.
 
    The names of the original files must have one of the following
@@ -854,7 +834,7 @@ permission bits S_ISUID and S_ISGID are cleared).
 Exit status is 0 if all the compressed files were successfully recompressed
 (if needed), compared, and deleted (if requested). 1 if a non-fatal error
 occurred (file not found or not regular, or has invalid format, or can't be
-deleted). 2 if a fatal error occurred (invalid command line options,
+deleted). 2 if a fatal error occurred (invalid command-line options,
 compressor can't be run, or comparison fails).
 
    'zupdate' supports the following options:
@@ -883,7 +863,7 @@ compressor can't be run, or comparison fails).
 
 '-f'
 '--force'
-     Don't skip a file for which a lzip compressed version already exists.
+     Don't skip a file for which a lzip-compressed version already exists.
      '--force' compares the content of the input file with the content of
      the existing lzip file and deletes the input file if both contents are
      identical.
@@ -984,20 +964,21 @@ Concept index
 
 Tag Table:
 Node: Top217
-Node: Introduction1151
-Node: Common options3998
-Ref: version4484
-Ref: compressor-requirements6435
-Node: Configuration6830
-Node: Zcat7863
-Node: Zcmp10563
-Node: Zdiff14820
-Node: Zgrep18003
-Node: Ztest24111
-Node: Zupdate26910
-Ref: lz-compressor32325
-Node: Problems33026
-Node: Concept index33560
+Node: Introduction1157
+Ref: search-order2309
+Node: Common options3466
+Ref: version4032
+Ref: compressor-requirements5983
+Node: Configuration7372
+Node: Zcat8405
+Node: Zcmp11144
+Node: Zdiff14412
+Node: Zgrep17495
+Node: Ztest23642
+Node: Zupdate26435
+Ref: lz-compressor31843
+Node: Problems32544
+Node: Concept index33078
 
 End Tag Table