diff options
Diffstat (limited to 'doc/zutils.info')
| -rw-r--r-- | doc/zutils.info | 202 |
1 files changed, 121 insertions, 81 deletions
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 |