summaryrefslogtreecommitdiffstats
path: root/doc/zutils.texinfo
diff options
context:
space:
mode:
Diffstat (limited to 'doc/zutils.texinfo')
-rw-r--r--doc/zutils.texinfo744
1 files changed, 0 insertions, 744 deletions
diff --git a/doc/zutils.texinfo b/doc/zutils.texinfo
deleted file mode 100644
index e39b51f..0000000
--- a/doc/zutils.texinfo
+++ /dev/null
@@ -1,744 +0,0 @@
-\input texinfo @c -*-texinfo-*-
-@c %**start of header
-@setfilename zutils.info
-@documentencoding ISO-8859-15
-@settitle Zutils Manual
-@finalout
-@c %**end of header
-
-@set UPDATED 11 October 2013
-@set VERSION 1.2-pre3
-
-@dircategory Data Compression
-@direntry
-* Zutils: (zutils). Utilities dealing with compressed files
-@end direntry
-
-
-@ifnothtml
-@titlepage
-@title Zutils
-@subtitle Utilities dealing with compressed files
-@subtitle for Zutils version @value{VERSION}, @value{UPDATED}
-@author by Antonio Diaz Diaz
-
-@page
-@vskip 0pt plus 1filll
-@end titlepage
-
-@contents
-@end ifnothtml
-
-@node Top
-@top
-
-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
-* Zupdate:: Recompressing files to lzip format
-* Problems:: Reporting bugs
-* Concept index:: Index of concepts
-@end menu
-
-@sp 1
-Copyright @copyright{} 2009, 2010, 2011, 2012, 2013 Antonio Diaz Diaz.
-
-This manual is free documentation: you have unlimited permission
-to copy, distribute and modify it.
-
-
-@node Introduction
-@chapter Introduction
-@cindex introduction
-
-Zutils is a collection of utilities able to deal with any combination of
-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.
-
-These utilities are not wrapper scripts but safer and more efficient C++
-programs. In particular the @samp{--recursive} option is very efficient
-in those utilities supporting it.
-
-@noindent
-The provided utilities are zcat, zcmp, zdiff, zgrep, ztest and zupdate.@*
-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. Zupdate is
-similar to gzip's znew.
-
-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.
-
-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".
-
-Table of SI and binary prefixes (unit multipliers):
-
-@multitable {Prefix} {kilobyte (10^3 = 1000)} {|} {Prefix} {kibibyte (2^10 = 1024)}
-@item Prefix @tab Value @tab | @tab Prefix @tab Value
-@item k @tab kilobyte (10^3 = 1000) @tab | @tab Ki @tab kibibyte (2^10 = 1024)
-@item M @tab megabyte (10^6) @tab | @tab Mi @tab mebibyte (2^20)
-@item G @tab gigabyte (10^9) @tab | @tab Gi @tab gibibyte (2^30)
-@item T @tab terabyte (10^12) @tab | @tab Ti @tab tebibyte (2^40)
-@item P @tab petabyte (10^15) @tab | @tab Pi @tab pebibyte (2^50)
-@item E @tab exabyte (10^18) @tab | @tab Ei @tab exbibyte (2^60)
-@item Z @tab zettabyte (10^21) @tab | @tab Zi @tab zebibyte (2^70)
-@item Y @tab yottabyte (10^24) @tab | @tab Yi @tab yobibyte (2^80)
-@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 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, data is read from standard input,
-decompressed if needed, and sent to standard output. Data read from
-standard input must be of the same type; all uncompressed or all in the
-same compression format.
-
-The format for running zcat is:
-
-@example
-zcat [@var{options}] [@var{files}]
-@end example
-
-@noindent
-Exit status is 0 if no errors occurred, non-zero otherwise.
-
-Zcat supports the following options:
-
-@table @samp
-@item -A
-@itemx --show-all
-Equivalent to @samp{-vET}.
-
-@item -b
-@itemx --number-nonblank
-Number all nonblank output lines, starting with 1. The line count is
-unlimited.
-
-@item -e
-Equivalent to @samp{-vE}.
-
-@item -E
-@itemx --show-ends
-Print a @samp{$} after the end of each line.
-
-@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,
-the exact file name must be given. Other names won't be tried.
-
-@item -n
-@itemx --number
-Number all output lines, starting with 1. The line count is unlimited.
-
-@item -q
-@itemx --quiet
-Quiet operation. Suppress all messages.
-
-@item -r
-@itemx --recursive
-Operate recursively on directories.
-
-@item -s
-@itemx --squeeze-blank
-Replace multiple adjacent blank lines with a single blank line.
-
-@item -t
-Equivalent to @samp{-vT}.
-
-@item -T
-@itemx --show-tabs
-Print TAB characters as @samp{^I}.
-
-@item -v
-@itemx --show-nonprinting
-Print control characters except for LF (newline) and TAB using @samp{^}
-notation and precede characters larger than 127 with @samp{M-} (which
-stands for "meta").
-
-@item --verbose
-Verbose mode. Show error messages.
-
-@end table
-
-
-@node Zcmp
-@chapter Zcmp
-@cindex zcmp
-
-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 decompressed content is used. Compressed files are decompressed on
-the fly; no temporary files are created.
-
-The format for running zcmp is:
-
-@example
-zcmp [@var{options}] @var{file1} [@var{file2}]
-@end example
-
-@noindent
-This compares @var{file1} to @var{file2}. If @var{file2} is omitted zcmp
-tries the following:
-
-@enumerate
-@item
-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 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} with data read from
-standard input.
-@end enumerate
-
-@noindent
-An exit status of 0 means no differences were found, 1 means some
-differences were found, and 2 means trouble.
-
-Zcmp supports the following options:
-
-@table @samp
-@item -b
-@itemx --print-bytes
-Print the differing bytes. Print control bytes as a @samp{^} followed by
-a letter, and precede bytes larger than 127 with @samp{M-} (which stands
-for "meta").
-
-@item --format=[@var{fmt1}][,@var{fmt2}]
-Force the given compression formats. Any of @var{fmt1} or @var{fmt2} may
-be omitted and the corresponding format will be automatically detected.
-Valid values for @var{fmt} are @samp{bz2}, @samp{gz}, @samp{lz} and
-@samp{xz}. If at least one format is specified with this option, the
-exact file names of both @var{file1} and @var{file2} must be given.
-Other names won't be tried.
-
-@item -i @var{size}
-@itemx --ignore-initial=@var{size}
-Ignore any differences in the first @var{size} bytes of the input files.
-Treat files with fewer than @var{size} bytes as if they were empty. If
-@var{size} is in the form @samp{@var{size1},@var{size2}}, ignore the
-first @var{size1} bytes of the first input file and the first
-@var{size2} bytes of the second input file.
-
-@item -l
-@itemx -v
-@itemx --list
-@itemx --verbose
-Print the byte numbers (in decimal) and values (in octal) of all
-differing bytes.
-
-@item -n @var{count}
-@itemx --bytes=@var{count}
-Compare at most @var{count} input bytes.
-
-@item -q
-@itemx -s
-@itemx --quiet
-@itemx --silent
-Do not print anything; only return an exit status indicating whether the
-files differ.
-
-@end table
-
-
-@node Zdiff
-@chapter Zdiff
-@cindex zdiff
-
-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 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.
-
-The format for running zdiff is:
-
-@example
-zdiff [@var{options}] @var{file1} [@var{file2}]
-@end example
-
-@noindent
-This compares @var{file1} to @var{file2}. If @var{file2} is omitted
-zdiff tries the following:
-
-@enumerate
-@item
-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 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} with data read from
-standard input.
-@end enumerate
-
-@noindent
-An exit status of 0 means no differences were found, 1 means some
-differences were found, and 2 means trouble.
-
-Zdiff supports the following options:
-
-@table @samp
-@item -a
-@itemx --text
-Treat all files as text.
-
-@item -b
-@itemx --ignore-space-change
-Ignore changes in the amount of white space.
-
-@item -B
-@itemx --ignore-blank-lines
-Ignore changes whose lines are all blank.
-
-@itemx -c
-Use the context output format.
-
-@item -C @var{n}
-@itemx --context=@var{n}
-Same as -c but use @var{n} lines of context.
-
-@item -d
-@itemx --minimal
-Try hard to find a smaller set of changes.
-
-@item -E
-@itemx --ignore-tab-expansion
-Ignore changes due to tab expansion.
-
-@item --format=[@var{fmt1}][,@var{fmt2}]
-Force the given compression formats. Any of @var{fmt1} or @var{fmt2} may
-be omitted and the corresponding format will be automatically detected.
-Valid values for @var{fmt} are @samp{bz2}, @samp{gz}, @samp{lz} and
-@samp{xz}. If at least one format is specified with this option, the
-exact file names of both @var{file1} and @var{file2} must be given.
-Other names won't be tried.
-
-@item -i
-@itemx --ignore-case
-Ignore case differences in file contents.
-
-@item -p
-@itemx --show-c-function
-Show which C function each change is in.
-
-@item -q
-@itemx --brief
-Output only whether files differ.
-
-@item -s
-@itemx --report-identical-files
-Report when two files are identical.
-
-@item -t
-@itemx --expand-tabs
-Expand tabs to spaces in output.
-
-@item -T
-@itemx --initial-tab
-Make tabs line up by prepending a tab.
-
-@item -u
-Use the unified output format.
-
-@item -U @var{n}
-@itemx --unified=@var{n}
-Same as -u but use @var{n} lines of context.
-
-@item -w
-@itemx --ignore-all-space
-Ignore all white space.
-
-@end table
-
-
-@node Zgrep
-@chapter Zgrep
-@cindex zgrep
-
-Zgrep is a front end to the grep program that allows transparent search
-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 standard input,
-decompressed if needed, and fed to grep. Data read from standard input
-must be of the same type; all uncompressed or all in the same
-compression format.
-
-The format for running zgrep is:
-
-@example
-zgrep [@var{options}] @var{pattern} [@var{files}]
-@end example
-
-@noindent
-An exit status of 0 means at least one match was found, 1 means no
-matches were found, and 2 means trouble.
-
-Zgrep supports the following options:
-
-@table @samp
-@item -a
-@itemx --text
-Treat all files as text.
-
-@item -A @var{n}
-@itemx --after-context=@var{n}
-Print @var{n} lines of trailing context.
-
-@item -b
-@itemx --byte-offset
-Print the byte offset of each line.
-
-@item -B @var{n}
-@itemx --before-context=@var{n}
-Print @var{n} lines of leading context.
-
-@item -c
-@itemx --count
-Only print a count of matching lines per file.
-
-@item -C @var{n}
-@itemx --context=@var{n}
-Print @var{n} lines of output context.
-
-@item -e @var{pattern}
-@itemx --regexp=@var{pattern}
-Use @var{pattern} as the pattern to match.
-
-@item -E
-@itemx --extended-regexp
-Treat @var{pattern} as an extended regular expression.
-
-@item -f @var{file}
-@itemx --file=@var{file}
-Obtain patterns from @var{file}, one per line.
-
-@item -F
-@itemx --fixed-strings
-Treat @var{pattern} as a set of newline-separated strings.
-
-@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,
-the exact file name must be given. Other names won't be tried.
-
-@item -h
-@itemx --no-filename
-Suppress the prefixing of filenames on output when multiple files are
-searched.
-
-@item -H
-@itemx --with-filename
-Print the filename for each match.
-
-@item -i
-@itemx --ignore-case
-Ignore case distinctions.
-
-@item -I
-Ignore binary files.
-
-@item -l
-@itemx --files-with-matches
-Only print names of files containing at least one match.
-
-@item -L
-@itemx --files-without-match
-Only print names of files not containing any matches.
-
-@item -m @var{n}
-@itemx --max-count=@var{n}
-Stop after @var{n} matches.
-
-@item -n
-@itemx --line-number
-Prefix each matched line with its line number in the input file.
-
-@item -o
-@itemx --only-matching
-Show only the part of matching lines that actually matches @var{pattern}.
-
-@item -q
-@itemx --quiet
-Suppress all messages. Exit immediately with zero status if any match is
-found, even if an error was detected.
-
-@item -r
-@itemx --recursive
-Operate recursively on directories.
-
-@item -s
-@itemx --no-messages
-Suppress error messages about nonexistent or unreadable files.
-
-@item -v
-@itemx --invert-match
-Select non-matching lines.
-
-@item --verbose
-Verbose mode. Show error messages.
-
-@item -w
-@itemx --word-regexp
-Match only whole words.
-
-@item -x
-@itemx --line-regexp
-Match only whole lines.
-
-@end table
-
-
-@node Ztest
-@chapter Ztest
-@cindex ztest
-
-Ztest verifies the integrity of the specified compressed files.
-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.
-
-The format for running ztest is:
-
-@example
-ztest [@var{options}] [@var{files}]
-@end example
-
-@noindent
-The exit status is 0 if all compressed files verify OK, 1 if
-environmental problems (file not found, invalid flags, I/O errors, etc),
-2 if any compressed file is corrupt or invalid.
-
-Ztest supports the following options:
-
-@table @samp
-@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,
-all files not in the given format will fail.
-
-@item -q
-@itemx --quiet
-Quiet operation. Suppress all messages.
-
-@item -r
-@itemx --recursive
-Operate recursively on directories.
-
-@item -v
-@itemx --verbose
-Verbose mode. Show the verify status for each file processed.@*
-Further -v's increase the verbosity level.
-
-@end table
-
-
-@node Zupdate
-@chapter Zupdate
-@cindex zupdate
-
-Zupdate recompresses files from bzip2, gzip, and xz formats to lzip
-format. The originals are compared with the new files and then deleted.
-Only regular files with standard file name extensions are recompressed,
-other files are ignored. Compressed files are decompressed and then
-recompressed on the fly; no temporary files are created. The lzip format
-is chosen as destination because it is by far the most appropriate for
-long-term data archiving.
-
-If the lzip compressed version of a file already exists, the file is
-skipped unless the @samp{--force} option is given. In this case, if the
-comparison fails, an error is returned and the original file is not
-deleted. The operation of zupdate is meant to be safe and not produce
-any data loss. Therefore, existing lzip compressed files are never
-overwritten nor deleted.
-
-The names of the original files must have one of the following
-extensions: @samp{.bz2}, @samp{.tbz}, @samp{.tbz2}, @samp{.gz},
-@samp{.tgz}, @samp{.xz}, @samp{.txz}. The files produced have the
-extensions @samp{.lz} or @samp{.tar.lz}.
-
-The format for running zupdate is:
-
-@example
-zupdate [@var{options}] [@var{files}]
-@end example
-
-@noindent
-Exit status is 0 if all the compressed files were successfully
-recompressed (if needed), compared and deleted. Non-zero otherwise.
-
-Zupdate supports the following options:
-
-@table @samp
-@item -f
-@itemx --force
-Do not skip a file for which a lzip compressed version already exists.
-@samp{--force} compares the content of the input file with the content
-of the lzip file and deletes the input file if both contents are
-identical.
-
-@item -k
-@itemx --keep
-Keep (don't delete) the input file after comparing it with the lzip file.
-
-@item -l
-@itemx --lzip-verbose
-Pass a @samp{-v} option to the lzip compressor so that it shows the
-compression ratio for each file processed. Using lzip 1.15 and newer, a
-second @samp{-l} shows the progress of compression. Use it together with
-@samp{-v} to see the name of the file.
-
-@item -q
-@itemx --quiet
-Quiet operation. Suppress all messages.
-
-@item -r
-@itemx --recursive
-Operate recursively on directories.
-
-@item -v
-@itemx --verbose
-Verbose mode. Show the files being processed. A second @samp{-v} also
-shows the files being ignored.
-
-@item -0 .. -9
-Set the compression level of lzip. By default zupdate passes @samp{-9}
-to lzip.
-
-@end table
-
-
-@node Problems
-@chapter Reporting bugs
-@cindex bugs
-@cindex getting help
-
-There are probably bugs in zutils. There are certainly errors and
-omissions in this manual. If you report them, they will get fixed. If
-you don't, no one will ever know about them and they will remain unfixed
-for all eternity, if not longer.
-
-If you find a bug in zutils, please send electronic mail to
-@email{zutils-bug@@nongnu.org}. Include the version number, which you can
-find by running @w{@samp{zcmp --version}}.
-
-
-@node Concept index
-@unnumbered Concept index
-
-@printindex cp
-
-@bye