summaryrefslogtreecommitdiffstats
path: root/doc/zutils.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/zutils.texi')
-rw-r--r--doc/zutils.texi869
1 files changed, 869 insertions, 0 deletions
diff --git a/doc/zutils.texi b/doc/zutils.texi
new file mode 100644
index 0000000..789643a
--- /dev/null
+++ b/doc/zutils.texi
@@ -0,0 +1,869 @@
+\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 1 January 2019
+@set VERSION 1.8
+
+@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:: Options common to all utilities
+* 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 the 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-2019 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 process 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 utilities provided are zcat, zcmp, zdiff, zgrep, ztest and zupdate.@*
+The formats supported are bzip2, gzip, lzip and xz.@*
+Zutils uses external compressors. 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 by 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.
+@xref{compressor-requirements}.
+
+FORMAT NOTE 1: The @samp{--format} option allows the processing of a
+subset of formats in recursive mode and when trying compressed file
+names: @w{@samp{zgrep foo -r --format=bz2,lz somedir somefile.tar}}.
+
+FORMAT NOTE 2: If the @samp{--force-format} option is given, the files
+are passed to the corresponding decompressor without verifying their
+format, allowing for example the processing of compress'd (.Z) files
+with gzip: @w{@samp{zcmp --force-format=gz file.Z file.lz}}.
+
+LANGUAGE NOTE: Uncompressed = not compressed = plain data; it may never
+have been compressed. Decompressed is used to refer to data which have
+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 @code
+@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.
+This version number should be included in all bug reports.
+
+@item -M @var{format_list}
+@itemx --format=@var{format_list}
+Process only the formats listed in the comma-separated
+@var{format_list}. Valid formats are @samp{bz2}, @samp{gz}, @samp{lz},
+@samp{xz} and @samp{un} for @samp{uncompressed}, meaning "any file name
+without a known extension". This option excludes files based on
+extension, instead of format, because it is more efficient. The
+exclusion only applies to names generated automatically (for example
+when adding extensions to a file name or when operating recursively on
+directories). Files given in the command line are always processed.
+
+Each format in @var{format_list} enables file names with the following
+extensions:
+
+@multitable {bz2} {enables} {any other file name}
+@item bz2 @tab enables @tab .bz2 .tbz .tbz2
+@item gz @tab enables @tab .gz .tgz
+@item lz @tab enables @tab .lz .tlz
+@item xz @tab enables @tab .xz .txz
+@item un @tab enables @tab any other file name
+@end multitable
+
+@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. The name of the program can't begin with @samp{-}. These
+options override the values set in @file{zutilsrc}. The compression
+program used must meet three requirements:
+
+@anchor{compressor-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 don't 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 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 formats supported.
+If a file fails to decompress, zcat continues copying the rest of the
+files.
+
+If a file is specified as @samp{-}, data are 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.
+
+If no files are specified, recursive searches examine the current
+working directory, and nonrecursive searches read standard input.
+
+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 @code
+@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 -n
+@itemx --number
+Number all output lines, starting with 1. The line count is unlimited.
+
+@item -O @var{format}
+@itemx --force-format=@var{format}
+Force the given compression format. Valid values for @var{format} are
+@samp{bz2}, @samp{gz}, @samp{lz} and @samp{xz}. If this option is used,
+the files are passed to the corresponding decompressor without verifying
+their format, and the exact file name must be given. Other names won't
+be tried.
+
+@item -q
+@itemx --quiet
+Quiet operation. Suppress all messages.
+
+@item -r
+@itemx --recursive
+For each directory operand, read and process all files in that
+directory, recursively. Follow symbolic links in the command line, but
+skip symlinks that are encountered recursively.
+
+@item -R
+@itemx --dereference-recursive
+For each directory operand, read and process all files in that
+directory, recursively, following all symbolic links.
+
+@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 @code
+@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 -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 -O [@var{format1}][,@var{format2}]
+@itemx --force-format=[@var{format1}][,@var{format2}]
+Force the given compression formats. Any of @var{format1} or
+@var{format2} may be omitted and the corresponding format will be
+automatically detected. Valid values for @var{format} are @samp{bz2},
+@samp{gz}, @samp{lz} and @samp{xz}. If at least one format is specified
+with this option, the file is passed to the corresponding decompressor
+without verifying its format, and the exact file names of both
+@var{file1} and @var{file2} must be given. Other names won't be tried.
+
+@item -q
+@itemx -s
+@itemx --quiet
+@itemx --silent
+Don't 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 file names 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 (some options only work if the diff
+program used supports them):
+
+@table @code
+@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 -i
+@itemx --ignore-case
+Ignore case differences in file contents.
+
+@item -O [@var{format1}][,@var{format2}]
+@itemx --force-format=[@var{format1}][,@var{format2}]
+Force the given compression formats. Any of @var{format1} or
+@var{format2} may be omitted and the corresponding format will be
+automatically detected. Valid values for @var{format} are @samp{bz2},
+@samp{gz}, @samp{lz} and @samp{xz}. If at least one format is specified
+with this option, the file is passed to the corresponding decompressor
+without verifying its format, and the exact file names of both
+@var{file1} and @var{file2} must be given. Other names won't be tried.
+
+@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
+formats supported. If a file fails to decompress, zgrep continues
+searching the rest of the files.
+
+If a file is specified as @samp{-}, data are 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.
+
+If no files are specified, recursive searches examine the current
+working directory, and nonrecursive searches read standard input.
+
+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 (some options only work if the grep
+program used supports them):
+
+@table @code
+@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 --color[=@var{when}]
+Show matched strings in color. @var{when} is @samp{never}, @samp{always}
+or @samp{auto}.
+
+@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.@*
+When searching in several files at once, command substitution can be
+used with @code{-e} to read @var{file} only once, for example if
+@var{file} is not a regular file:
+@w{@code{zgrep -e "$(cat @var{file})" file1.lz file2.gz}}
+
+@item -F
+@itemx --fixed-strings
+Treat @var{pattern} as a set of newline-separated strings.
+
+@item -h
+@itemx --no-filename
+Suppress the prefixing of file names on output when multiple files are
+searched.
+
+@item -H
+@itemx --with-filename
+Print the file name 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 -O @var{format}
+@itemx --force-format=@var{format}
+Force the given compression format. Valid values for @var{format} are
+@samp{bz2}, @samp{gz}, @samp{lz} and @samp{xz}. If this option is used,
+the files are passed to the corresponding decompressor without verifying
+their format, and the exact file name must be given. Other names won't
+be tried.
+
+@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
+For each directory operand, read and process all files in that
+directory, recursively. Follow symbolic links in the command line, but
+skip symlinks that are encountered recursively.
+
+@item -R
+@itemx --dereference-recursive
+For each directory operand, read and process all files in that
+directory, recursively, following all symbolic links.
+
+@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 a file is specified as @samp{-}, the
+integrity of compressed data read from standard input is verified. Data
+read from standard input must be all in the same compression format. If
+a file fails to decompress, ztest continues verifying the rest of the
+files.
+
+If no files are specified, recursive searches examine the current
+working directory, and nonrecursive searches read standard input.
+
+Note that error detection in the xz format is broken. First, some xz
+files lack integrity information. Second, not all xz decompressors can
+@uref{http://www.nongnu.org/lzip/xz_inadequate.html#fragmented,,verify the integrity}
+of all xz files. Third, section 2.1.1.2 'Stream Flags' of the
+@uref{http://tukaani.org/xz/xz-file-format.txt,,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.
+@c We can only hope that xz is soon abandoned.
+
+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 @code
+@item -O @var{format}
+@itemx --force-format=@var{format}
+Force the given compression format. Valid values for @var{format} are
+@samp{bz2}, @samp{gz}, @samp{lz} and @samp{xz}. If this option is used,
+the files are passed to the corresponding decompressor without verifying
+their format, and any files in a format that the decompressor can't
+understand will fail. For example, @samp{--force-format=gz} can test
+gzipped (.gz) and compress'd (.Z) files if the compressor used is GNU
+gzip.
+
+@item -q
+@itemx --quiet
+Quiet operation. Suppress all messages.
+
+@item -r
+@itemx --recursive
+For each directory operand, read and process all files in that
+directory, recursively. Follow symbolic links in the command line, but
+skip symlinks that are encountered recursively.
+
+@item -R
+@itemx --dereference-recursive
+For each directory operand, read and process all files in that
+directory, recursively, following all symbolic links.
+
+@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. Each original is compared with the new file 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. 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.
+
+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
+skipped unless the @samp{--force} option 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 produce any data loss. Therefore, existing lzip
+compressed files are never overwritten nor deleted.
+
+Combining the @samp{--force} and @samp{--keep} options, as in
+@w{@code{zupdate -f -k *.gz}}, verifies 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
+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}.
+
+Recompressing a file is much like copying or moving it; therefore
+zupdate preserves the access and modification dates, permissions, and,
+when possible, ownership of the file just as @samp{cp -p} does. (If the user
+ID or the group ID can't be duplicated, the file permission bits S_ISUID
+and S_ISGID are cleared).
+
+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 (if requested). Non-zero
+otherwise.
+
+zupdate supports the following options:
+
+@table @code
+@item -f
+@itemx --force
+Don't 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 existing 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
+For each directory operand, read and process all files in that
+directory, recursively. Follow symbolic links in the command line, but
+skip symlinks that are encountered recursively.
+
+@item -R
+@itemx --dereference-recursive
+For each directory operand, read and process all files in that
+directory, recursively, following all symbolic links.
+
+@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{@code{zupdate --version}}.
+
+
+@node Concept index
+@unnumbered Concept index
+
+@printindex cp
+
+@bye