Annotation of src/usr.bin/compress/compress.1, Revision 1.18
1.18 ! deraadt 1: .\" $OpenBSD: compress.1,v 1.17 2003/06/10 09:12:09 jmc Exp $
1.1 deraadt 2: .\" $NetBSD: compress.1,v 1.5 1995/03/26 09:44:34 glass Exp $
3: .\"
4: .\" Copyright (c) 1986, 1990, 1993
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" This code is derived from software contributed to Berkeley by
8: .\" James A. Woods, derived from original work by Spencer Thomas
9: .\" and Joseph Orost.
10: .\"
11: .\" Redistribution and use in source and binary forms, with or without
12: .\" modification, are permitted provided that the following conditions
13: .\" are met:
14: .\" 1. Redistributions of source code must retain the above copyright
15: .\" notice, this list of conditions and the following disclaimer.
16: .\" 2. Redistributions in binary form must reproduce the above copyright
17: .\" notice, this list of conditions and the following disclaimer in the
18: .\" documentation and/or other materials provided with the distribution.
1.16 millert 19: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 20: .\" may be used to endorse or promote products derived from this software
21: .\" without specific prior written permission.
22: .\"
23: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33: .\" SUCH DAMAGE.
34: .\"
35: .\" @(#)compress.1 8.2 (Berkeley) 4/18/94
36: .\"
37: .Dd April 18, 1994
38: .Dt COMPRESS 1
1.7 aaron 39: .Os
1.1 deraadt 40: .Sh NAME
41: .Nm compress ,
1.18 ! deraadt 42: .Nm uncompress ,
! 43: .Nm gzip ,
! 44: .Nm gunzip
1.1 deraadt 45: .Nd compress and expand data
46: .Sh SYNOPSIS
47: .Nm compress
1.14 mickey 48: .Op Fl LV
49: .Nm compress
1.15 millert 50: .Op Fl cdfgOqrtv123456789
1.1 deraadt 51: .Op Fl b Ar bits
1.18 ! deraadt 52: .Op Fl S Ar suffix
1.4 mickey 53: .Op Fl o Ar filename
1.1 deraadt 54: .Op Ar
55: .Nm uncompress
1.18 ! deraadt 56: .Op Fl cfqrtv
! 57: .Op Fl o Ar filename
! 58: .Op Ar
! 59: .Pp
! 60: .Nm gzip
! 61: .Op Fl LV
! 62: .Nm gzip
! 63: .Op Fl cdfgOqrtv123456789
! 64: .Op Fl b Ar bits
! 65: .Op Fl S Ar suffix
! 66: .Op Fl o Ar filename
! 67: .Op Ar
! 68: .Nm gunzip
! 69: .Op Fl cfqrtv
1.4 mickey 70: .Op Fl o Ar filename
1.7 aaron 71: .Op Ar
1.18 ! deraadt 72: .Pp
1.12 mickey 73: .Nm zcat
1.15 millert 74: .Op Fl fqr
1.12 mickey 75: .Op Ar
1.1 deraadt 76: .Sh DESCRIPTION
1.9 aaron 77: The
1.18 ! deraadt 78: .Nm compress
! 79: and
! 80: .Nm gzip
! 81: utilities
! 82: reduce the size of the named files using adaptive Lempel-Ziv coding.
! 83: They are functionally identical, except that if invoked as
! 84: .Nm gzip
! 85: the deflate mode of compression is chosen by default (see the
! 86: .Fl g
! 87: flag).
1.1 deraadt 88: Each
89: .Ar file
90: is renamed to the same name plus the extension
1.17 jmc 91: .Dq .Z ,
1.14 mickey 92: or
1.17 jmc 93: .Dq .gz
1.14 mickey 94: (in deflate mode).
1.1 deraadt 95: As many of the modification time, access time, file flags, file mode,
96: user ID, and group ID as allowed by permissions are retained in the
97: new file.
98: If compression would not reduce the size of a
99: .Ar file ,
1.17 jmc 100: the file is ignored (unless
1.14 mickey 101: .Fl f
102: is used).
1.1 deraadt 103: .Pp
1.9 aaron 104: The
1.6 aaron 105: .Nm uncompress
1.18 ! deraadt 106: and
! 107: .Nm gunzip
! 108: utilities restore compressed files to their original form, renaming the
1.9 aaron 109: files by removing the
1.1 deraadt 110: .Dq .Z
1.14 mickey 111: or
112: .Dq .gz
1.1 deraadt 113: extension.
1.12 mickey 114: .Pp
115: The
116: .Nm zcat
1.13 mickey 117: command is equivalent in functionality to
1.12 mickey 118: .Nm uncompress
1.13 mickey 119: .Fl c .
1.1 deraadt 120: .Pp
121: If renaming the files would cause files to be overwritten and the standard
122: input device is a terminal, the user is prompted (on the standard error
123: output) for confirmation.
124: If prompting is not possible or confirmation is not received, the files
125: are not overwritten.
126: .Pp
127: If no files are specified, the standard input is compressed or uncompressed
128: to the standard output.
1.9 aaron 129: If either the input or output files are not regular files, the checks for
1.1 deraadt 130: reduction in size and file overwriting are not performed, the input file is
131: not removed, and the attributes of the input file are not retained.
132: .Pp
133: The options are as follows:
134: .Bl -tag -width Ds
1.14 mickey 135: .It Fl V
136: Display the program version (RCS Ids of the source files) and exit.
1.6 aaron 137: .It Fl b Ar bits
1.1 deraadt 138: Specify the
139: .Ar bits
140: code limit (see below).
141: .It Fl c
142: Compressed or uncompressed output is written to the standard output.
1.17 jmc 143: No files are modified (force
1.14 mickey 144: .Nm zcat
145: mode).
1.4 mickey 146: .It Fl d
1.14 mickey 147: Decompress the source files instead of compressing them (force
148: .Nm uncompress
149: mode).
1.1 deraadt 150: .It Fl f
151: Force compression of
152: .Ar file ,
153: even if it is not actually reduced in size.
154: Additionally, files are overwritten without prompting for confirmation.
1.4 mickey 155: .It Fl g
1.14 mickey 156: Use deflate scheme which reportedly provides better compression rates (force
1.17 jmc 157: .Nm gzip
1.14 mickey 158: mode).
1.18 ! deraadt 159: This flag need not be specified when invoked as
! 160: .Nm gzip .
1.14 mickey 161: .It Fl 1...9
162: Use deflate scheme with compression factor of one to nine.
1.4 mickey 163: .It Fl O
1.14 mickey 164: Use old compression method.
1.6 aaron 165: .It Fl o Ar filename
1.4 mickey 166: Set the output file name.
1.14 mickey 167: .It Fl S Ar suffix
168: Set suffix for compressed files.
1.4 mickey 169: .It Fl t
1.6 aaron 170: Test the integrity of each file leaving any files intact.
1.15 millert 171: .It Fl r
172: Recursive mode,
173: .Nm
174: will descend into specified directories.
1.4 mickey 175: .It Fl q
1.14 mickey 176: Be quiet, suppress all messages.
1.1 deraadt 177: .It Fl v
1.14 mickey 178: Print the percentage reduction of each file and other information.
1.1 deraadt 179: .El
180: .Pp
1.14 mickey 181: In normal mode,
1.8 aaron 182: .Nm
1.1 deraadt 183: uses a modified Lempel-Ziv algorithm.
184: Common substrings in the file are first replaced by 9-bit codes 257 and up.
185: When code 512 is reached, the algorithm switches to 10-bit codes and
186: continues to use more bits until the
187: limit specified by the
188: .Fl b
1.9 aaron 189: flag is reached.
1.6 aaron 190: .Ar bits
1.9 aaron 191: must be between 9 and 16 (the default is 16).
1.10 aaron 192: .\" XXX - use .br here to work-around an apparent bug in mdoc
193: .br
1.1 deraadt 194: .Pp
195: After the
196: .Ar bits
197: limit is reached,
1.8 aaron 198: .Nm
1.1 deraadt 199: periodically checks the compression ratio.
200: If it is increasing,
1.8 aaron 201: .Nm
1.1 deraadt 202: continues to use the existing code dictionary.
203: However, if the compression ratio decreases,
1.8 aaron 204: .Nm
1.11 aaron 205: discards the table of substrings and rebuilds it from scratch.
206: This allows the algorithm to adapt to the next
1.8 aaron 207: .Dq block
208: of the file.
1.1 deraadt 209: .Pp
1.18 ! deraadt 210: .Nm gzip
! 211: uses a slightly different version of the Lempel-Ziv algorithm,
! 212: which can achieve even better compression.
! 213: .Pp
1.1 deraadt 214: The
215: .Fl b
216: flag is omitted for
1.3 deraadt 217: .Nm uncompress
1.18 ! deraadt 218: or
! 219: .Nm gunzip
1.1 deraadt 220: since the
221: .Ar bits
222: parameter specified during compression
223: is encoded within the output, along with
224: a magic number to ensure that neither decompression of random data nor
225: recompression of compressed data is attempted.
226: .Pp
227: The amount of compression obtained depends on the size of the
228: input, the number of
229: .Ar bits
230: per code, and the distribution of common substrings.
231: Typically, text such as source code or English is reduced by 50\-60%.
232: Compression is generally much better than that achieved by Huffman
233: coding (as used in the historical command pack), or adaptive Huffman
234: coding (as used in the historical command compact), and takes less
235: time to compute.
236: .Pp
237: The
1.8 aaron 238: .Nm
1.18 ! deraadt 239: and
! 240: .Nm gzip
! 241: utilities exit with 0 on success, 1 if an error occurred, or 2 if one or
1.5 denny 242: more files were not compressed because they would have grown in
1.6 aaron 243: size (and
244: .Fl f
1.9 aaron 245: was not specified).
1.1 deraadt 246: .Sh SEE ALSO
247: .Rs
248: .%A Welch, Terry A.
249: .%D June, 1984
250: .%T "A Technique for High Performance Data Compression"
251: .%J "IEEE Computer"
252: .%V 17:6
253: .%P pp. 8-19
254: .Re
1.5 denny 255: .Sh STANDARDS
256: The
1.8 aaron 257: .Nm
1.5 denny 258: utility is compliant with the
259: .St -p1003.2-92
260: specification.
1.1 deraadt 261: .Sh HISTORY
262: The
263: .Nm
264: command appeared in
265: .Bx 4.3 .
1.6 aaron 266: The deflate compression support was added in
1.4 mickey 267: .Ox 2.1 .