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