diff options
author | Daniel Baumann <mail@daniel-baumann.ch> | 2015-11-08 04:26:56 +0000 |
---|---|---|
committer | Daniel Baumann <mail@daniel-baumann.ch> | 2015-11-08 04:26:56 +0000 |
commit | d7d5dfbcf513f94115990102c56eccf177417889 (patch) | |
tree | 7b47cf460832a31d6e0c34444e7bf1cddacfd02f /doc | |
parent | Adding debian version 1.0-1. (diff) | |
download | zutils-d7d5dfbcf513f94115990102c56eccf177417889.tar.xz zutils-d7d5dfbcf513f94115990102c56eccf177417889.zip |
Merging upstream version 1.1~rc2.
Signed-off-by: Daniel Baumann <mail@daniel-baumann.ch>
Diffstat (limited to '')
-rw-r--r-- | doc/zcat.1 | 21 | ||||
-rw-r--r-- | doc/zcmp.1 | 32 | ||||
-rw-r--r-- | doc/zdiff.1 | 32 | ||||
-rw-r--r-- | doc/zgrep.1 | 21 | ||||
-rw-r--r-- | doc/ztest.1 | 23 | ||||
-rw-r--r-- | doc/zutils.info | 202 | ||||
-rw-r--r-- | doc/zutils.texinfo | 179 |
7 files changed, 335 insertions, 175 deletions
@@ -1,5 +1,5 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.37.1. -.TH ZCAT "1" "May 2013" "Zcat (zutils) 1.0" "User Commands" +.TH ZCAT "1" "July 2013" "Zcat (zutils) 1.1-rc2" "User Commands" .SH NAME Zcat \- decompress and concatenate files to standard output .SH SYNOPSIS @@ -7,7 +7,7 @@ Zcat \- decompress and concatenate files to standard output [\fIoptions\fR] [\fIfiles\fR] .SH DESCRIPTION Zcat copies each given file ("\-" means standard input), to standard -output. If any given file is compressed, its uncompressed content is +output. If any given file is compressed, its decompressed content is used. If a given file does not exist, and its name does not end with one of the known extensions, zcat tries the compressed file names corresponding to the supported formats. If no files are specified, @@ -17,7 +17,7 @@ all uncompressed or all in the same compression format. .PP The supported formats are bzip2, gzip, lzip and xz. .PP -Exit status is 0 if no errors occurred, 1 otherwise. +Exit status is 0 if no errors occurred, non\-zero otherwise. .SH OPTIONS .TP \fB\-h\fR, \fB\-\-help\fR @@ -44,6 +44,9 @@ force given format (bz2, gz, lz, xz) \fB\-n\fR, \fB\-\-number\fR number all output lines .TP +\fB\-N\fR, \fB\-\-no\-rcfile\fR +don't read runtime configuration file +.TP \fB\-q\fR, \fB\-\-quiet\fR suppress all messages .TP @@ -64,6 +67,18 @@ use '^' and 'M\-' notation, except for LF and TAB .TP \fB\-\-verbose\fR verbose mode (show error messages) +.TP +\fB\-\-bz2=\fR<command> +set compressor and options for bzip2 format +.TP +\fB\-\-gz=\fR<command> +set compressor and options for gzip format +.TP +\fB\-\-lz=\fR<command> +set compressor and options for lzip format +.TP +\fB\-\-xz=\fR<command> +set compressor and options for xz format .SH "REPORTING BUGS" Report bugs to zutils\-bug@nongnu.org .br @@ -1,5 +1,5 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.37.1. -.TH ZCMP "1" "May 2013" "Zcmp (zutils) 1.0" "User Commands" +.TH ZCMP "1" "July 2013" "Zcmp (zutils) 1.1-rc2" "User Commands" .SH NAME Zcmp \- decompress and compare two files byte by byte .SH SYNOPSIS @@ -9,19 +9,22 @@ Zcmp \- decompress and compare two files byte by byte Zcmp compares two files ("\-" means standard input), and if they differ, tells the first byte and line number where they differ. Bytes and lines are numbered starting with 1. If any given file is compressed, -its uncompressed content is used. Compressed files are uncompressed on +its decompressed content is used. Compressed files are decompressed on the fly; no temporary files are created. .PP The supported formats are bzip2, gzip, lzip and xz. .PP Compares <file1> to <file2>. If <file2> is omitted zcmp tries the following: -If <file1> is compressed, compares <file1> to the file with the -corresponding decompressed file name (removes the extension from -<file1>). -If <file1> is not compressed, compares <file1> to the uncompressed +.IP +1. If <file1> is compressed, compares its decompressed contents with +the corresponding uncompressed file (the name of <file1> with the +extension removed). +.IP +2. If <file1> is uncompressed, compares it with the decompressed contents of <file1>.[lz|bz2|gz|xz] (the first one that is found). -If no suitable file is found, compares <file1> to data read from +.IP +3. If no suitable file is found, compares <file1> with data read from standard input. .PP Exit status is 0 if inputs are identical, 1 if different, 2 if trouble. @@ -48,6 +51,9 @@ list position, value of all differing bytes \fB\-n\fR, \fB\-\-bytes=\fR<n> compare at most <n> bytes .TP +\fB\-N\fR, \fB\-\-no\-rcfile\fR +don't read runtime configuration file +.TP \fB\-q\fR, \fB\-\-quiet\fR suppress all messages .TP @@ -56,6 +62,18 @@ suppress all messages .TP \fB\-v\fR, \fB\-\-verbose\fR verbose mode (same as \fB\-\-list\fR) +.TP +\fB\-\-bz2=\fR<command> +set compressor and options for bzip2 format +.TP +\fB\-\-gz=\fR<command> +set compressor and options for gzip format +.TP +\fB\-\-lz=\fR<command> +set compressor and options for lzip format +.TP +\fB\-\-xz=\fR<command> +set compressor and options for xz format .PP Numbers may be followed by a multiplier: k = kB = 10^3 = 1000, Ki = KiB = 2^10 = 1024, M = 10^6, Mi = 2^20, G = 10^9, Gi = 2^30, etc... diff --git a/doc/zdiff.1 b/doc/zdiff.1 index be9d335..260d8dd 100644 --- a/doc/zdiff.1 +++ b/doc/zdiff.1 @@ -1,5 +1,5 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.37.1. -.TH ZDIFF "1" "May 2013" "Zdiff (zutils) 1.0" "User Commands" +.TH ZDIFF "1" "July 2013" "Zdiff (zutils) 1.1-rc2" "User Commands" .SH NAME Zdiff \- decompress and compare two files line by line .SH SYNOPSIS @@ -8,7 +8,7 @@ Zdiff \- decompress and compare two files line by line .SH DESCRIPTION Zdiff compares two files ("\-" means standard input), and if they differ, shows the differences line by line. If any given file is -compressed, its uncompressed content is used. Zdiff is a front end to +compressed, its decompressed content is used. Zdiff is a front end to the diff program and has the limitation that messages from diff refer to temporary filenames instead of those specified. .PP @@ -16,12 +16,15 @@ The supported formats are bzip2, gzip, lzip and xz. .PP Compares <file1> to <file2>. If <file2> is omitted zdiff tries the following: -If <file1> is compressed, compares <file1> to the file with the -corresponding decompressed file name (removes the extension from -<file1>). -If <file1> is not compressed, compares <file1> to the uncompressed +.IP +1. If <file1> is compressed, compares its decompressed contents with +the corresponding uncompressed file (the name of <file1> with the +extension removed). +.IP +2. If <file1> is uncompressed, compares it with the decompressed contents of <file1>.[lz|bz2|gz|xz] (the first one that is found). -If no suitable file is found, compares <file1> to data read from +.IP +3. If no suitable file is found, compares <file1> with data read from standard input. .PP Exit status is 0 if inputs are identical, 1 if different, 2 if trouble. @@ -60,6 +63,9 @@ force given formats (bz2, gz, lz, xz) \fB\-i\fR, \fB\-\-ignore\-case\fR ignore case differences in file contents .TP +\fB\-N\fR, \fB\-\-no\-rcfile\fR +don't read runtime configuration file +.TP \fB\-p\fR, \fB\-\-show\-c\-function\fR show which C function each change is in .TP @@ -83,6 +89,18 @@ same as \fB\-u\fR but use <n> lines of context .TP \fB\-w\fR, \fB\-\-ignore\-all\-space\fR ignore all white space +.TP +\fB\-\-bz2=\fR<command> +set compressor and options for bzip2 format +.TP +\fB\-\-gz=\fR<command> +set compressor and options for gzip format +.TP +\fB\-\-lz=\fR<command> +set compressor and options for lzip format +.TP +\fB\-\-xz=\fR<command> +set compressor and options for xz format .PP Numbers may be followed by a multiplier: k = kB = 10^3 = 1000, Ki = KiB = 2^10 = 1024, M = 10^6, Mi = 2^20, G = 10^9, Gi = 2^30, etc... diff --git a/doc/zgrep.1 b/doc/zgrep.1 index 452c26d..cc85d0a 100644 --- a/doc/zgrep.1 +++ b/doc/zgrep.1 @@ -1,5 +1,5 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.37.1. -.TH ZGREP "1" "May 2013" "Zgrep (zutils) 1.0" "User Commands" +.TH ZGREP "1" "July 2013" "Zgrep (zutils) 1.1-rc2" "User Commands" .SH NAME Zgrep \- search compressed files for a regular expression .SH SYNOPSIS @@ -7,8 +7,8 @@ Zgrep \- search compressed files for a regular expression [\fIoptions\fR] \fI<pattern> \fR[\fIfiles\fR] .SH DESCRIPTION Zgrep is a front end to the grep program that allows transparent search -on any combination of compressed and non\-compressed files. If any given -file is compressed, its uncompressed content is used. If a given file +on any combination of compressed and uncompressed files. If any given +file is compressed, its decompressed content is used. If a given file does not exist, and its name does not end with one of the known extensions, zgrep tries the compressed file names corresponding to the supported formats. If no files are specified, data is read from @@ -84,6 +84,9 @@ stop after <n> matches \fB\-n\fR, \fB\-\-line\-number\fR print the line number of each line .TP +\fB\-N\fR, \fB\-\-no\-rcfile\fR +don't read runtime configuration file +.TP \fB\-o\fR, \fB\-\-only\-matching\fR show only the part of a line matching <pattern> .TP @@ -107,6 +110,18 @@ match only whole words .TP \fB\-x\fR, \fB\-\-line\-regexp\fR match only whole lines +.TP +\fB\-\-bz2=\fR<command> +set compressor and options for bzip2 format +.TP +\fB\-\-gz=\fR<command> +set compressor and options for gzip format +.TP +\fB\-\-lz=\fR<command> +set compressor and options for lzip format +.TP +\fB\-\-xz=\fR<command> +set compressor and options for xz format .SH "REPORTING BUGS" Report bugs to zutils\-bug@nongnu.org .br diff --git a/doc/ztest.1 b/doc/ztest.1 index 7169021..f9c4825 100644 --- a/doc/ztest.1 +++ b/doc/ztest.1 @@ -1,5 +1,5 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.37.1. -.TH ZTEST "1" "May 2013" "Ztest (zutils) 1.0" "User Commands" +.TH ZTEST "1" "July 2013" "Ztest (zutils) 1.1-rc2" "User Commands" .SH NAME Ztest \- verify integrity of compressed files .SH SYNOPSIS @@ -7,9 +7,9 @@ Ztest \- verify integrity of compressed files [\fIoptions\fR] [\fIfiles\fR] .SH DESCRIPTION Ztest verifies the integrity of the specified compressed files. -Non\-compressed files are ignored. If no files are specified, the -integrity of compressed data read from standard input is verified. Data -read from standard input must be all in the same compression format. +Uncompressed files are ignored. If no files are specified, the integrity +of compressed data read from standard input is verified. Data read from +standard input must be all in the same compression format. .PP The supported formats are bzip2, gzip, lzip and xz. .PP @@ -30,6 +30,9 @@ output version information and exit \fB\-\-format=\fR<fmt> force given format (bz2, gz, lz, xz) .TP +\fB\-N\fR, \fB\-\-no\-rcfile\fR +don't read runtime configuration file +.TP \fB\-q\fR, \fB\-\-quiet\fR suppress all messages .TP @@ -38,6 +41,18 @@ operate recursively on directories .TP \fB\-v\fR, \fB\-\-verbose\fR be verbose (a 2nd \fB\-v\fR gives more) +.TP +\fB\-\-bz2=\fR<command> +set compressor and options for bzip2 format +.TP +\fB\-\-gz=\fR<command> +set compressor and options for gzip format +.TP +\fB\-\-lz=\fR<command> +set compressor and options for lzip format +.TP +\fB\-\-xz=\fR<command> +set compressor and options for xz format .SH "REPORTING BUGS" Report bugs to zutils\-bug@nongnu.org .br diff --git a/doc/zutils.info b/doc/zutils.info index 77e2035..866d975 100644 --- a/doc/zutils.info +++ b/doc/zutils.info @@ -12,18 +12,20 @@ File: zutils.info, Node: Top, Next: Introduction, Up: (dir) Zutils Manual ************* -This manual is for Zutils (version 1.0, 31 May 2013). +This manual is for Zutils (version 1.1-rc2, 7 July 2013). * Menu: * Introduction:: Purpose and features of zutils +* Common options:: Common options +* The zutilsrc file:: The zutils configuration file * Zcat:: Concatenating compressed files * Zcmp:: Comparing compressed files byte by byte * Zdiff:: Comparing compressed files line by line * Zgrep:: Searching inside compressed files * Ztest:: Testing integrity of compressed files * Problems:: Reporting bugs -* Concept Index:: Index of concepts +* Concept index:: Index of concepts Copyright (C) 2008, 2009, 2010, 2011, 2012, 2013 Antonio Diaz Diaz. @@ -32,14 +34,14 @@ This manual is for Zutils (version 1.0, 31 May 2013). copy, distribute and modify it. -File: zutils.info, Node: Introduction, Next: Zcat, Prev: Top, Up: Top +File: zutils.info, Node: Introduction, Next: Common options, Prev: Top, Up: Top 1 Introduction ************** Zutils is a collection of utilities able to deal with any combination of -compressed and non-compressed files transparently. If any given file, -including standard input, is compressed, its uncompressed content is +compressed and uncompressed files transparently. If any given file, +including standard input, is compressed, its decompressed content is used. Compressed files are decompressed on the fly; no temporary files are created. @@ -49,6 +51,7 @@ in those utilities supporting it. The provided utilities are zcat, zcmp, zdiff, zgrep and ztest. The supported formats are bzip2, gzip, lzip and xz. +The compressor to be used for each format is configurable at runtime. Zcat, zcmp, zdiff, and zgrep are improved replacements for the shell scripts provided with GNU gzip. Ztest is unique to zutils. @@ -57,6 +60,10 @@ scripts provided with GNU gzip. Ztest is unique to zutils. which makes them safe to use with zutils. Gzip and xz may return ambiguous warning values, making them less reliable backends for zutils. + LANGUAGE NOTE: Uncompressed = not compressed = plain data; it may +never have been compressed. Decompressed is used to refer to data which +has 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". @@ -74,13 +81,81 @@ Z zettabyte (10^21) | Zi zebibyte (2^70) Y yottabyte (10^24) | Yi yobibyte (2^80) -File: zutils.info, Node: Zcat, Next: Zcmp, Prev: Introduction, Up: Top +File: zutils.info, Node: Common options, Next: The zutilsrc file, Prev: Introduction, Up: Top + +2 Common options +**************** + +The following options are available in all the utilities. Rather than +writing identical descriptions for each of the programs, they are +described here. + +`-h' +`--help' + Print an informative help message describing the options and exit. + Zgrep only supports the `--help' form of this option. + +`-V' +`--version' + Print the version number on the standard output and exit. + +`-N' +`--no-rcfile' + Don't read the runtime configuration file `zutilsrc'. + +`--bz2=COMMAND' +`--gz=COMMAND' +`--lz=COMMAND' +`--xz=COMMAND' + Set program (may include arguments) to be used as (de)compressor + for the given format. These options override the values set in + `zutilsrc'. The compression program used must meet three + requirements: + + 1. When called with the `-d' option, it must read compressed + data from the standard input and produce decompressed data on + the standard output. + + 2. If the `-q' option is passed to zutils, the compression + program must also accept it. + + 3. It must return 0 if no errors occurred, and a non-zero value + otherwise. -2 Zcat + + +File: zutils.info, Node: The zutilsrc file, Next: Zcat, Prev: Common options, Up: Top + +3 The zutilsrc file +******************* + +`zutilsrc' is the runtime configuration file for zutils. In it you may +define the compressor name and options to be used for each format. The +`zutilsrc' file is optional; you do not need to install it in order to +run zutils. + + The compressors specified in the command line override those +specified in the `zutilsrc' file. + + You may copy the system `zutilsrc' file `${sysconfdir}/zutilsrc' to +`$HOME/.zutilsrc' and customize these options as you like. The file +syntax is fairly obvious (and there are further instructions in it): + + 1. Any line beginning with `#' is a comment line. + + 2. Each non-comment line defines the command to be used for the given + format, with the syntax: + <format> = <compressor> [options] + where <format> is one of `bz2', `gz', `lz' or `xz'. + + +File: zutils.info, Node: Zcat, Next: Zcmp, Prev: The zutilsrc file, Up: Top + +4 Zcat ****** Zcat copies each given file (`-' means standard input), to standard -output. If any given file is compressed, its uncompressed content is +output. If any given file is compressed, its decompressed content is used. If a given file does not exist, and its name does not end with one of the known extensions, zcat tries the compressed file names corresponding to the supported formats. @@ -94,18 +169,10 @@ same compression format. zcat [OPTIONS] [FILES] -Exit status is 0 if no errors occurred, 1 otherwise. +Exit status is 0 if no errors occurred, non-zero otherwise. Zcat supports the following options: -`-h' -`--help' - Print an informative help message describing the options and exit. - -`-V' -`--version' - Print the version number of zcat on the standard output and exit. - `-A' `--show-all' Equivalent to `-vET'. @@ -164,13 +231,13 @@ Exit status is 0 if no errors occurred, 1 otherwise. File: zutils.info, Node: Zcmp, Next: Zdiff, Prev: Zcat, Up: Top -3 Zcmp +5 Zcmp ****** Zcmp compares two files (`-' means standard input), and if they differ, tells the first byte and line number where they differ. Bytes and lines are numbered starting with 1. If any given file is compressed, its -uncompressed content is used. Compressed files are decompressed on the +decompressed content is used. Compressed files are decompressed on the fly; no temporary files are created. The format for running zcmp is: @@ -180,14 +247,14 @@ fly; no temporary files are created. This compares FILE1 to FILE2. If FILE2 is omitted zcmp tries the following: - 1. If FILE1 is compressed, compares FILE1 to the file with the - corresponding decompressed file name (removes the extension from - FILE1). + 1. If FILE1 is compressed, compares its decompressed contents with + the corresponding uncompressed file (the name of FILE1 with the + extension removed). - 2. If FILE1 is not compressed, compares FILE1 to the uncompressed + 2. If FILE1 is uncompressed, compares it with the decompressed contents of FILE1.[lz|bz2|gz|xz] (the first one that is found). - 3. If no suitable file is found, compares FILE1 to data read from + 3. If no suitable file is found, compares FILE1 with data read from standard input. An exit status of 0 means no differences were found, 1 means some @@ -195,14 +262,6 @@ differences were found, and 2 means trouble. Zcmp supports the following options: -`-h' -`--help' - Print an informative help message describing the options and exit. - -`-V' -`--version' - Print the version number of zcmp on the standard output and exit. - `-b' `--print-bytes' Print the differing bytes. Print control bytes as a `^' followed by @@ -247,12 +306,12 @@ differences were found, and 2 means trouble. File: zutils.info, Node: Zdiff, Next: Zgrep, Prev: Zcmp, Up: Top -4 Zdiff +6 Zdiff ******* Zdiff compares two files (`-' means standard input), and if they differ, shows the differences line by line. If any given file is -compressed, its uncompressed content is used. Zdiff is a front end to +compressed, its decompressed content is used. Zdiff is a front end to the diff program and has the limitation that messages from diff refer to temporary filenames instead of those specified. @@ -263,14 +322,14 @@ temporary filenames instead of those specified. This compares FILE1 to FILE2. If FILE2 is omitted zdiff tries the following: - 1. If FILE1 is compressed, compares FILE1 to the file with the - corresponding decompressed file name (removes the extension from - FILE1). + 1. If FILE1 is compressed, compares its decompressed contents with + the corresponding uncompressed file (the name of FILE1 with the + extension removed). - 2. If FILE1 is not compressed, compares FILE1 to the uncompressed + 2. If FILE1 is uncompressed, compares it with the decompressed contents of FILE1.[lz|bz2|gz|xz] (the first one that is found). - 3. If no suitable file is found, compares FILE1 to data read from + 3. If no suitable file is found, compares FILE1 with data read from standard input. An exit status of 0 means no differences were found, 1 means some @@ -278,14 +337,6 @@ differences were found, and 2 means trouble. Zdiff supports the following options: -`-h' -`--help' - Print an informative help message describing the options and exit. - -`-V' -`--version' - Print the version number of zdiff on the standard output and exit. - `-a' `--text' Treat all files as text. @@ -360,12 +411,12 @@ differences were found, and 2 means trouble. File: zutils.info, Node: Zgrep, Next: Ztest, Prev: Zdiff, Up: Top -5 Zgrep +7 Zgrep ******* Zgrep is a front end to the grep program that allows transparent search -on any combination of compressed and non-compressed files. If any given -file is compressed, its uncompressed content is used. If a given file +on any combination of compressed and uncompressed files. If any given +file is compressed, its decompressed content is used. If a given file does not exist, and its name does not end with one of the known extensions, zgrep tries the compressed file names corresponding to the supported formats. @@ -384,13 +435,6 @@ matches were found, and 2 means trouble. Zgrep supports the following options: -`--help' - Print an informative help message describing the options and exit. - -`-V' -`--version' - Print the version number of zgrep on the standard output and exit. - `-a' `--text' Treat all files as text. @@ -503,13 +547,13 @@ matches were found, and 2 means trouble. File: zutils.info, Node: Ztest, Next: Problems, Prev: Zgrep, Up: Top -6 Ztest +8 Ztest ******* Ztest verifies the integrity of the specified compressed files. -Non-compressed files are ignored. If no files are specified, the -integrity of compressed data read from standard input is verified. Data -read from standard input must be all in the same compression format. +Uncompressed files are ignored. If no files are specified, the integrity +of compressed data read from standard input is verified. Data read from +standard input must be all in the same compression format. Note that some xz files lack integrity information, and therefore can't be verified as reliably as the other formats can. @@ -524,14 +568,6 @@ environmental problems (file not found, invalid flags, I/O errors, etc), Ztest supports the following options: -`-h' -`--help' - Print an informative help message describing the options and exit. - -`-V' -`--version' - Print the version number of ztest on the standard output and exit. - `--format=FMT' Force the given compression format. Valid values for FMT are `bz2', `gz', `lz' and `xz'. If this option is used, all files not @@ -552,9 +588,9 @@ environmental problems (file not found, invalid flags, I/O errors, etc), -File: zutils.info, Node: Problems, Next: Concept Index, Prev: Ztest, Up: Top +File: zutils.info, Node: Problems, Next: Concept index, Prev: Ztest, Up: Top -7 Reporting Bugs +9 Reporting Bugs **************** There are probably bugs in zutils. There are certainly errors and @@ -567,17 +603,19 @@ for all eternity, if not longer. by running `zutils --version'. -File: zutils.info, Node: Concept Index, Prev: Problems, Up: Top +File: zutils.info, Node: Concept index, Prev: Problems, Up: Top -Concept Index +Concept index ************* * Menu: * bugs: Problems. (line 6) +* common options: Common options. (line 6) * getting help: Problems. (line 6) * introduction: Introduction. (line 6) +* the zutilsrc file: The zutilsrc file. (line 6) * zcat: Zcat. (line 6) * zcmp: Zcmp. (line 6) * zdiff: Zdiff. (line 6) @@ -588,14 +626,16 @@ Concept Index Tag Table: Node: Top224 -Node: Introduction1000 -Node: Zcat2794 -Node: Zcmp4880 -Node: Zdiff7366 -Node: Zgrep10032 -Node: Ztest13043 -Node: Problems14447 -Node: Concept Index14976 +Node: Introduction1097 +Node: Common options3155 +Node: The zutilsrc file4404 +Node: Zcat5330 +Node: Zcmp7252 +Node: Zdiff9576 +Node: Zgrep12079 +Node: Ztest14916 +Node: Problems16141 +Node: Concept index16670 End Tag Table diff --git a/doc/zutils.texinfo b/doc/zutils.texinfo index ed65997..61a8762 100644 --- a/doc/zutils.texinfo +++ b/doc/zutils.texinfo @@ -6,8 +6,8 @@ @finalout @c %**end of header -@set UPDATED 31 May 2013 -@set VERSION 1.0 +@set UPDATED 7 July 2013 +@set VERSION 1.1-rc2 @dircategory Data Compression @direntry @@ -36,13 +36,15 @@ This manual is for Zutils (version @value{VERSION}, @value{UPDATED}). @menu * Introduction:: Purpose and features of zutils +* Common options:: Common options +* The zutilsrc file:: The zutils configuration file * Zcat:: Concatenating compressed files * Zcmp:: Comparing compressed files byte by byte * Zdiff:: Comparing compressed files line by line * Zgrep:: Searching inside compressed files * Ztest:: Testing integrity of compressed files * Problems:: Reporting bugs -* Concept Index:: Index of concepts +* Concept index:: Index of concepts @end menu @sp 1 @@ -58,8 +60,8 @@ to copy, distribute and modify it. @cindex introduction Zutils is a collection of utilities able to deal with any combination of -compressed and non-compressed files transparently. If any given file, -including standard input, is compressed, its uncompressed content is +compressed and uncompressed files transparently. If any given file, +including standard input, is compressed, its decompressed content is used. Compressed files are decompressed on the fly; no temporary files are created. @@ -69,7 +71,8 @@ in those utilities supporting it. @noindent The provided utilities are zcat, zcmp, zdiff, zgrep and ztest.@* -The supported formats are bzip2, gzip, lzip and xz. +The supported formats are bzip2, gzip, lzip and xz.@* +The compressor to be used for each format is configurable at runtime. Zcat, zcmp, zdiff, and zgrep are improved replacements for the shell scripts provided with GNU gzip. Ztest is unique to zutils. @@ -78,6 +81,10 @@ 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 backends for zutils. +LANGUAGE NOTE: Uncompressed = not compressed = plain data; it may never +have been compressed. Decompressed is used to refer to data which has +undergone the process of decompression. + @sp 1 Numbers given as arguments to options (positions, sizes) may be followed by a multiplier and an optional @samp{B} for "byte". @@ -97,12 +104,85 @@ Table of SI and binary prefixes (unit multipliers): @end multitable +@node Common options +@chapter Common options +@cindex common options + +The following options are available in all the utilities. Rather than +writing identical descriptions for each of the programs, they are +described here. + +@table @samp +@item -h +@itemx --help +Print an informative help message describing the options and exit. Zgrep +only supports the @samp{--help} form of this option. + +@item -V +@itemx --version +Print the version number on the standard output and exit. + +@item -N +@itemx --no-rcfile +Don't read the runtime configuration file @samp{zutilsrc}. + +@item --bz2=@var{command} +@itemx --gz=@var{command} +@itemx --lz=@var{command} +@itemx --xz=@var{command} +Set program (may include arguments) to be used as (de)compressor for the +given format. These options override the values set in @file{zutilsrc}. +The compression program used must meet three requirements: + +@enumerate +@item +When called with the @samp{-d} option, it must read compressed data from +the standard input and produce decompressed data on the standard output. +@item +If the @samp{-q} option is passed to zutils, the compression program +must also accept it. +@item +It must return 0 if no errors occurred, and a non-zero value otherwise. +@end enumerate + +@end table + + +@node The zutilsrc file +@chapter The zutilsrc file +@cindex the zutilsrc file + +@file{zutilsrc} is the runtime configuration file for zutils. In it you +may define the compressor name and options to be used for each format. +The @file{zutilsrc} file is optional; you do not need to install it in +order to run zutils. + +The compressors specified in the command line override those specified +in the @file{zutilsrc} file. + +You may copy the system @file{zutilsrc} file +@file{$@{sysconfdir@}/zutilsrc} to @file{$HOME/.zutilsrc} and customize +these options as you like. The file syntax is fairly obvious (and there +are further instructions in it): + +@enumerate +@item +Any line beginning with @samp{#} is a comment line. +@item +Each non-comment line defines the command to be used for the given +format, with the syntax: +@example +<format> = <compressor> [options] +@end example +where <format> is one of @samp{bz2}, @samp{gz}, @samp{lz} or @samp{xz}. +@end enumerate + @node Zcat @chapter Zcat @cindex zcat Zcat copies each given file (@samp{-} means standard input), to standard -output. If any given file is compressed, its uncompressed content is +output. If any given file is compressed, its decompressed content is used. If a given file does not exist, and its name does not end with one of the known extensions, zcat tries the compressed file names corresponding to the supported formats. @@ -119,19 +199,11 @@ zcat [@var{options}] [@var{files}] @end example @noindent -Exit status is 0 if no errors occurred, 1 otherwise. +Exit status is 0 if no errors occurred, non-zero otherwise. Zcat supports the following options: @table @samp -@item -h -@itemx --help -Print an informative help message describing the options and exit. - -@item -V -@itemx --version -Print the version number of zcat on the standard output and exit. - @item -A @itemx --show-all Equivalent to @samp{-vET}. @@ -195,7 +267,7 @@ Verbose mode. Show error messages. Zcmp compares two files (@samp{-} means standard input), and if they differ, tells the first byte and line number where they differ. Bytes and lines are numbered starting with 1. If any given file is compressed, -its uncompressed content is used. Compressed files are decompressed on +its decompressed content is used. Compressed files are decompressed on the fly; no temporary files are created. The format for running zcmp is: @@ -210,15 +282,14 @@ tries the following: @enumerate @item -If @var{file1} is compressed, compares @var{file1} to the file with the -corresponding decompressed file name (removes the extension from -@var{file1}). +If @var{file1} is compressed, compares its decompressed contents with +the corresponding uncompressed file (the name of @var{file1} with the +extension removed). @item -If @var{file1} is not compressed, compares @var{file1} to the -uncompressed contents of @var{file1}.[lz|bz2|gz|xz] (the first one that -is found). +If @var{file1} is uncompressed, compares it with the decompressed +contents of @var{file1}.[lz|bz2|gz|xz] (the first one that is found). @item -If no suitable file is found, compares @var{file1} to data read from +If no suitable file is found, compares @var{file1} with data read from standard input. @end enumerate @@ -229,14 +300,6 @@ differences were found, and 2 means trouble. Zcmp supports the following options: @table @samp -@item -h -@itemx --help -Print an informative help message describing the options and exit. - -@item -V -@itemx --version -Print the version number of zcmp on the standard output and exit. - @item -b @itemx --print-bytes Print the differing bytes. Print control bytes as a @samp{^} followed by @@ -286,7 +349,7 @@ files differ. Zdiff compares two files (@samp{-} means standard input), and if they differ, shows the differences line by line. If any given file is -compressed, its uncompressed content is used. Zdiff is a front end to +compressed, its decompressed content is used. Zdiff is a front end to the diff program and has the limitation that messages from diff refer to temporary filenames instead of those specified. @@ -302,15 +365,14 @@ zdiff tries the following: @enumerate @item -If @var{file1} is compressed, compares @var{file1} to the file with the -corresponding decompressed file name (removes the extension from -@var{file1}). +If @var{file1} is compressed, compares its decompressed contents with +the corresponding uncompressed file (the name of @var{file1} with the +extension removed). @item -If @var{file1} is not compressed, compares @var{file1} to the -uncompressed contents of @var{file1}.[lz|bz2|gz|xz] (the first one that -is found). +If @var{file1} is uncompressed, compares it with the decompressed +contents of @var{file1}.[lz|bz2|gz|xz] (the first one that is found). @item -If no suitable file is found, compares @var{file1} to data read from +If no suitable file is found, compares @var{file1} with data read from standard input. @end enumerate @@ -321,14 +383,6 @@ differences were found, and 2 means trouble. Zdiff supports the following options: @table @samp -@item -h -@itemx --help -Print an informative help message describing the options and exit. - -@item -V -@itemx --version -Print the version number of zdiff on the standard output and exit. - @item -a @itemx --text Treat all files as text. @@ -407,8 +461,8 @@ Ignore all white space. @cindex zgrep Zgrep is a front end to the grep program that allows transparent search -on any combination of compressed and non-compressed files. If any given -file is compressed, its uncompressed content is used. If a given file +on any combination of compressed and uncompressed files. If any given +file is compressed, its decompressed content is used. If a given file does not exist, and its name does not end with one of the known extensions, zgrep tries the compressed file names corresponding to the supported formats. @@ -431,13 +485,6 @@ matches were found, and 2 means trouble. Zgrep supports the following options: @table @samp -@item --help -Print an informative help message describing the options and exit. - -@item -V -@itemx --version -Print the version number of zgrep on the standard output and exit. - @item -a @itemx --text Treat all files as text. @@ -554,9 +601,9 @@ Match only whole lines. @cindex ztest Ztest verifies the integrity of the specified compressed files. -Non-compressed files are ignored. If no files are specified, the -integrity of compressed data read from standard input is verified. Data -read from standard input must be all in the same compression format. +Uncompressed files are ignored. If no files are specified, the integrity +of compressed data read from standard input is verified. Data read from +standard input must be all in the same compression format. Note that some xz files lack integrity information, and therefore can't be verified as reliably as the other formats can. @@ -575,14 +622,6 @@ environmental problems (file not found, invalid flags, I/O errors, etc), Ztest supports the following options: @table @samp -@item -h -@itemx --help -Print an informative help message describing the options and exit. - -@item -V -@itemx --version -Print the version number of ztest on the standard output and exit. - @item --format=@var{fmt} Force the given compression format. Valid values for @var{fmt} are @samp{bz2}, @samp{gz}, @samp{lz} and @samp{xz}. If this option is used, @@ -619,8 +658,8 @@ If you find a bug in zutils, please send electronic mail to find by running @w{@samp{zutils --version}}. -@node Concept Index -@unnumbered Concept Index +@node Concept index +@unnumbered Concept index @printindex cp |