doc: correct a diagnostic in man page to match actual
[debian/gzip] / gzip.1
diff --git a/gzip.1 b/gzip.1
index 6fa79862bfc661b53ee2f886489db8e88c75380f..07995ea99366a1ae049e1e79168804b099734a62 100644 (file)
--- a/gzip.1
+++ b/gzip.1
@@ -1,11 +1,10 @@
-.PU
 .TH GZIP 1 local
 .SH NAME
 gzip, gunzip, zcat \- compress or expand files
 .SH SYNOPSIS
 .ll +8
 .B gzip
-.RB [ " \-acdfhlLnNrtvV19 " ]
+.RB [ " \-acdfhklLnNrtvV19 " ]
 .RB [ \-S\ suffix ]
 [
 .I "name \&..."
@@ -13,7 +12,7 @@ gzip, gunzip, zcat \- compress or expand files
 .ll -8
 .br
 .B gunzip
-.RB [ " \-acfhlLnNrtvV " ]
+.RB [ " \-acfhklLnNrtvV " ]
 .RB [ \-S\ suffix ]
 [
 .I "name \&..."
@@ -29,7 +28,7 @@ gzip, gunzip, zcat \- compress or expand files
 reduces the size of the named files using Lempel-Ziv coding (LZ77).
 Whenever possible,
 each file is replaced by one with the extension
-.B "\&.gz,"
+.BR "\&.gz" ,
 while keeping the same ownership modes, access and modification times.
 (The default extension is
 .B "\-gz"
@@ -66,14 +65,14 @@ Compressed files can be restored to their original form using
 or
 .I gunzip
 or
-.I zcat.
+.IR zcat .
 If the original name saved in the compressed file is not suitable for its
 file system, a new name is constructed from the original one to make it
 legal.
 .PP
 .I gunzip
 takes a list of files on its command line and replaces each
-file whose name ends with .gz, -gz, .z, -z, _z or .Z
+file whose name ends with .gz, -gz, .z, -z, or _z (ignoring case)
 and which begins with the correct magic number with an uncompressed
 file without the original extension.
 .I gunzip
@@ -96,14 +95,19 @@ extension.
 .PP
 .I gunzip
 can currently decompress files created by
-.I gzip, zip, compress, compress -H
+.IR gzip ,
+.IR zip ,
+.IR compress ,
+.I "compress -H"
 or
-.I pack.
+.IR pack .
 The detection of the input format is automatic.  When using
 the first two formats,
 .I gunzip
 checks a 32 bit CRC. For
-.I pack, gunzip
+.I pack
+and
+.I gunzip
 checks the uncompressed length. The standard
 .I compress
 format was not designed to allow consistency checks. However
@@ -122,22 +126,28 @@ Files created by
 .I zip
 can be uncompressed by gzip only if they have a single member compressed
 with the 'deflation' method. This feature is only intended to help
-conversion of tar.zip files to the tar.gz format. To extract zip files
+conversion of tar.zip files to the tar.gz format.  To extract a
+.I zip
+file with a single member, use a command like
+.I "gunzip <foo.zip"
+or
+.IR "gunzip -S .zip foo.zip" .
+To extract zip files
 with several members, use
 .I unzip
 instead of
-.I gunzip.
+.IR gunzip .
 .PP
 .I zcat
 is identical to
 .I gunzip
-.B \-c.
+.BR \-c .
 (On some systems,
 .I zcat
 may be installed as
 .I gzcat
 to preserve the original link to
-.I compress.)
+.IR compress .)
 .I zcat
 uncompresses either a list of files on the command line or its
 standard input and writes the uncompressed data on standard output.
@@ -156,7 +166,7 @@ input and the distribution of common substrings.
 Typically, text such as source code or English
 is reduced by 60\-70%.
 Compression is generally much better than that achieved by
-LZW (as used in 
+LZW (as used in
 .IR compress ),
 Huffman coding (as used in
 .IR pack ),
@@ -171,7 +181,6 @@ number of used disk blocks almost never increases.
 .I gzip
 preserves the mode, ownership and timestamps of files when compressing
 or decompressing.
-
 .SH OPTIONS
 .TP
 .B \-a --ascii
@@ -193,12 +202,12 @@ Force compression or decompression even if the file has multiple links
 or the corresponding file already exists, or if the compressed data
 is read from or written to a terminal. If the input data is not in
 a format recognized by
-.I gzip,
+.IR gzip ,
 and if the option --stdout is also given, copy the input data without change
-to the standard ouput: let
+to the standard output: let
 .I zcat
 behave as
-.I cat.
+.IR cat .
 If
 .B \-f
 is not given,
@@ -209,6 +218,9 @@ prompts to verify whether an existing file should be overwritten.
 .B \-h --help
 Display a help screen and quit.
 .TP
+.B \-k --keep
+Keep (don't delete) input files during compression or decompression.
+.TP
 .B \-l --list
 For each compressed file, list the following fields:
 
@@ -268,7 +280,7 @@ Suppress all warnings.
 .TP
 .B \-r --recursive
 Travel the directory structure recursively. If any of the file names
-specified on the command line are directories, 
+specified on the command line are directories,
 .I gzip
 will descend into the directory and compress all the files it finds there
 (or decompress them in the case of
@@ -276,16 +288,13 @@ will descend into the directory and compress all the files it finds there
 ).
 .TP
 .B \-S .suf   --suffix .suf
-Use suffix .suf instead of .gz. Any suffix can be given, but suffixes
+When compressing, use suffix .suf instead of .gz.
+Any non-empty suffix can be given, but suffixes
 other than .z and .gz should be avoided to avoid confusion when files
-are transferred to other systems.  A null suffix forces gunzip to  try
-decompression on all given files regardless of suffix, as in:
-
-    gunzip -S "" *       (*.* for MSDOS)
+are transferred to other systems.
 
-Previous versions of gzip used
-the .z suffix. This was changed to avoid a conflict with
-.IR pack "(1)".
+When decompressing, add .suf to the beginning of the list of
+suffixes to try, when deriving an output file name from an input file name.
 .TP
 .B \-t --test
 Test. Check the compressed file integrity.
@@ -322,6 +331,7 @@ will extract all members at once. For example:
       gzip -c file2 >> foo.gz
 
 Then
+
       gunzip -c foo
 
 is equivalent to
@@ -354,99 +364,107 @@ such as tar or zip. GNU tar supports the -z option to invoke gzip
 transparently. gzip is designed as a complement to tar, not as a
 replacement.
 .SH "ENVIRONMENT"
-The environment variable
+The obsolescent environment variable
 .B GZIP
 can hold a set of default options for
-.I gzip.
-These options are interpreted first and can be overwritten by
-explicit command line parameters. For example:
-      for sh:    GZIP="-8v --name"; export GZIP
-      for csh:   setenv GZIP "-8v --name"
-      for MSDOS: set GZIP=-8v --name
+.IR gzip .
+These options are interpreted first and can be overwritten by explicit
+command line parameters.  As this can cause problems when using
+scripts, this feature is supported only for options that are
+reasonably likely to not cause too much harm, and
+.I gzip
+warns if it is used.
+This feature will be removed in a future release of
+.IR gzip .
+.PP
+You can use an alias or script instead.  For example, if
+.I gzip
+is in the directory
+.B /usr/bin
+you can prepend
+.B $HOME/bin
+to your
+.B PATH
+and create an executable script
+.B $HOME/bin/gzip
+containing the following:
+
+      #! /bin/sh
+      export PATH=/usr/bin
+      exec gzip \-9 "$@"
 
-On Vax/VMS, the name of the environment variable is GZIP_OPT, to
+On VMS, the name of the obsolescent environment variable is GZIP_OPT, to
 avoid a conflict with the symbol set for invocation of the program.
 .SH "SEE ALSO"
-znew(1), zcmp(1), zmore(1), zforce(1), gzexe(1), zip(1), unzip(1), compress(1),
-pack(1), compact(1)
+znew(1), zcmp(1), zmore(1), zforce(1), gzexe(1), zip(1), unzip(1), compress(1)
+.PP
+The
+.I gzip
+file format is specified in P. Deutsch, \s-1GZIP\s0 file format
+specification version 4.3,
+.BR <http://www.ietf.org/rfc/rfc1952.txt> ,
+Internet RFC 1952 (May 1996).
+The
+.I zip
+deflation format is specified in P. Deutsch, \s-1DEFLATE\s0 Compressed
+Data Format Specification version 1.3,
+.BR <http://www.ietf.org/rfc/rfc1951.txt> ,
+Internet RFC 1951 (May 1996).
 .SH "DIAGNOSTICS"
 Exit status is normally 0;
 if an error occurs, exit status is 1. If a warning occurs, exit status is 2.
-.PP
-Usage: gzip [-cdfhlLnNrtvV19] [-S suffix] [file ...]
-.in +8
+.TP
+Usage: gzip [-cdfhklLnNrtvV19] [-S suffix] [file ...]
 Invalid options were specified on the command line.
-.in -8
-.IR file :
-not in gzip format
-.in +8
+.TP
+\fIfile\fP\^: not in gzip format
 The file specified to
 .I gunzip
 has not been compressed.
-.in -8
-.IR file:
-Corrupt input. Use zcat to recover some data.
-.in +8
+.TP
+\fIfile\fP\^: Corrupt input. Use zcat to recover some data.
 The compressed file has been damaged. The data up to the point of failure
 can be recovered using
-.in +8
-zcat file > recover
-.in -16
-.IR file :
-compressed with 
-.I xx
-bits, can only handle 
-.I yy
-bits
-.in +8
+
+      zcat \fIfile\fP > recover
+.TP
+\fIfile\fP\^: compressed with \fIxx\fP bits, can only handle \fIyy\fP bits
 .I File
 was compressed (using LZW) by a program that could deal with
-more 
+more
 .I bits
 than the decompress code on this machine.
 Recompress the file with gzip, which compresses better and uses
 less memory.
-.in -8
-.IR file :
-already has .gz suffix -- no change
-.in +8
+.TP
+\fIfile\fP\^: already has .gz suffix -- unchanged
 The file is assumed to be already compressed.
 Rename the file and try again.
-.in -8
-.I file
-already exists; do you wish to overwrite (y or n)?
-.in +8
+.TP
+\fIfile\fP already exists; do you wish to overwrite (y or n)?
 Respond "y" if you want the output file to be replaced; "n" if not.
-.in -8
+.TP
 gunzip: corrupt input
-.in +8
 A SIGSEGV violation was detected which usually means that the input file has
 been corrupted.
-.in -8
-.I "xx.x%"
-.in +8
-Percentage of the input saved by compression.
+.TP
+\fIxx.x%\fP Percentage of the input saved by compression.
 (Relevant only for
 .BR \-v
 and
 .BR \-l \.)
-.in -8
+.TP
 -- not a regular file or directory: ignored
-.in +8
 When the input file is not a regular file or directory,
 (e.g. a symbolic link, socket, FIFO, device file), it is
 left unaltered.
-.in -8
--- has 
-.I xx 
-other links: unchanged
-.in +8
+.TP
+-- has \fIxx\fP other links: unchanged
 The input file has links; it is left unchanged.  See
 .IR ln "(1)"
 for more information. Use the
 .B \-f
 flag to force compression of multiply-linked files.
-.in -8
 .SH CAVEATS
 When writing compressed data to a tape, it is generally necessary to
 pad the output with zeroes up to a block boundary. When the data is
@@ -455,19 +473,17 @@ read and the whole block is passed to
 for decompression,
 .I gunzip
 detects that there is extra trailing garbage after the compressed data
-and emits a warning by default. You have to use the --quiet option to
-suppress the warning. This option can be set in the
-.B GZIP
-environment variable as in:
-  for sh:  GZIP="-q"  tar -xfz --block-compress /dev/rst0
-  for csh: (setenv GZIP -q; tar -xfz --block-compr /dev/rst0
-
-In the above example, gzip is invoked implicitly by the -z option of
-GNU tar. Make sure that the same block size (-b option of tar) is used
-for reading and writing compressed data on tapes.  (This example
-assumes you are using the GNU version of tar.)
+and emits a warning by default.  You can use the --quiet option to
+suppress the warning.
 .SH BUGS
-The --list option reports incorrect sizes if they exceed 2 gigabytes.
+The gzip format represents the input size modulo 2^32, so the
+--list option reports incorrect uncompressed sizes and compression
+ratios for uncompressed files 4 GB and larger.  To work around this
+problem, you can use the following command to discover a large
+uncompressed file's true size:
+
+      zcat file.gz | wc -c
+
 The --list option reports sizes as -1 and crc as ffffffff if the
 compressed file is on a non seekable media.
 
@@ -475,4 +491,29 @@ In some rare cases, the --best option gives worse compression than
 the default compression level (-6). On some highly redundant files,
 .I compress
 compresses better than
-.I gzip.
+.IR gzip .
+.SH "COPYRIGHT NOTICE"
+Copyright \(co 1998-1999, 2001-2002, 2012, 2015-2016 Free Software Foundation,
+Inc.
+.br
+Copyright \(co 1992, 1993 Jean-loup Gailly
+.PP
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+.ig
+Permission is granted to process this file through troff and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+..
+.PP
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+.PP
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Foundation.