Annotation of src/usr.bin/compress/compress.1, Revision 1.43
1.43 ! naddy 1: .\" $OpenBSD: compress.1,v 1.42 2009/02/10 19:24:17 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: .\"
1.43 ! naddy 37: .Dd $Mdocdate: February 10 2009 $
1.1 deraadt 38: .Dt COMPRESS 1
1.7 aaron 39: .Os
1.1 deraadt 40: .Sh NAME
41: .Nm compress ,
1.18 deraadt 42: .Nm uncompress ,
1.35 jmc 43: .Nm zcat
44: .Nd compress and expand data (compress mode)
1.1 deraadt 45: .Sh SYNOPSIS
46: .Nm compress
1.35 jmc 47: .Op Fl 123456789cdfghLlNnOqrtVv
1.1 deraadt 48: .Op Fl b Ar bits
1.30 jmc 49: .Op Fl o Ar filename
1.18 deraadt 50: .Op Fl S Ar suffix
1.1 deraadt 51: .Op Ar
52: .Nm uncompress
1.43 ! naddy 53: .Op Fl cfhlNnqrtVv
1.18 deraadt 54: .Op Fl o Ar filename
55: .Op Ar
1.12 mickey 56: .Nm zcat
1.28 jmc 57: .Op Fl fghqr
58: .Op Ar
1.1 deraadt 59: .Sh DESCRIPTION
1.9 aaron 60: The
1.35 jmc 61: .Nm
62: utility
63: reduces the size of the named files using adaptive Lempel-Ziv coding,
64: in compress mode.
1.19 jmc 65: If invoked as
1.28 jmc 66: .Nm compress Fl g ,
1.35 jmc 67: the deflate mode of compression is chosen;
68: see
69: .Xr gzip 1
70: for more information.
71: Each file is renamed to the same name plus the extension
72: .Dq .Z .
1.1 deraadt 73: As many of the modification time, access time, file flags, file mode,
74: user ID, and group ID as allowed by permissions are retained in the
75: new file.
1.35 jmc 76: If compression would not reduce the size of a file,
1.17 jmc 77: the file is ignored (unless
1.14 mickey 78: .Fl f
79: is used).
1.1 deraadt 80: .Pp
1.9 aaron 81: The
1.6 aaron 82: .Nm uncompress
1.35 jmc 83: utility restores compressed files to their original form, renaming the
1.24 millert 84: files by removing the extension (or by using the stored name if the
85: .Fl N
86: flag is specified).
1.35 jmc 87: It has the ability to restore files compressed by both
88: .Nm
89: and
90: .Xr gzip 1 ,
91: recognising the following extensions:
1.24 millert 92: .Dq .Z ,
93: .Dq -Z ,
94: .Dq _Z ,
95: .Dq .gz ,
96: .Dq -gz ,
97: .Dq _gz ,
98: .Dq .tgz ,
99: .Dq -tgz ,
100: .Dq _tgz ,
101: .Dq .taz ,
102: .Dq -taz ,
103: and
104: .Dq _taz .
1.25 jmc 105: Extensions ending in
1.24 millert 106: .Dq tgz
107: and
108: .Dq taz
109: are not removed when decompressing, instead they are converted to
110: .Dq tar .
1.12 mickey 111: .Pp
112: The
113: .Nm zcat
1.13 mickey 114: command is equivalent in functionality to
1.12 mickey 115: .Nm uncompress
1.13 mickey 116: .Fl c .
1.1 deraadt 117: .Pp
118: If renaming the files would cause files to be overwritten and the standard
119: input device is a terminal, the user is prompted (on the standard error
120: output) for confirmation.
121: If prompting is not possible or confirmation is not received, the files
122: are not overwritten.
123: .Pp
124: If no files are specified, the standard input is compressed or uncompressed
125: to the standard output.
1.9 aaron 126: If either the input or output files are not regular files, the checks for
1.1 deraadt 127: reduction in size and file overwriting are not performed, the input file is
128: not removed, and the attributes of the input file are not retained.
129: .Pp
1.36 millert 130: By default, when compressing using the deflate scheme
131: .Pf ( Fl g ) ,
1.37 jmc 132: the original file name and time stamp are stored in the compressed file.
1.36 millert 133: When uncompressing, this information is not used.
134: Instead, the uncompressed file inherits the time stamp of the
135: compressed version and the uncompressed file name is generated from
136: the name of the compressed file as described above.
137: These defaults may be overridden by the
138: .Fl N
139: and
140: .Fl n
141: flags, described below.
142: .Pp
1.1 deraadt 143: The options are as follows:
144: .Bl -tag -width Ds
1.30 jmc 145: .It Fl 1...9
1.35 jmc 146: Use the deflate scheme, with compression factor of
1.30 jmc 147: .Fl 1
148: to
149: .Fl 9 .
150: Compression factor
151: .Fl 1
152: is the fastest, but provides a poorer level of compression.
153: Compression factor
154: .Fl 9
155: provides the best level of compression, but is relatively slow.
156: The default is
157: .Fl 6 .
158: This option implies
159: .Fl g .
1.6 aaron 160: .It Fl b Ar bits
1.1 deraadt 161: Specify the
162: .Ar bits
1.23 jmc 163: code limit
164: .Pq see below .
1.1 deraadt 165: .It Fl c
166: Compressed or uncompressed output is written to the standard output.
1.17 jmc 167: No files are modified (force
1.14 mickey 168: .Nm zcat
169: mode).
1.4 mickey 170: .It Fl d
1.14 mickey 171: Decompress the source files instead of compressing them (force
172: .Nm uncompress
173: mode).
1.1 deraadt 174: .It Fl f
175: Force compression of
176: .Ar file ,
177: even if it is not actually reduced in size.
178: Additionally, files are overwritten without prompting for confirmation.
1.27 tedu 179: If the input data is not in a format recognized by
180: .Nm
181: and if the option
182: .Fl c
183: is also given, copy the input data without change
1.29 jmc 184: to the standard output: let
1.27 tedu 185: .Nm zcat
186: behave as
1.28 jmc 187: .Xr cat 1 .
1.4 mickey 188: .It Fl g
1.35 jmc 189: Use the deflate scheme, which reportedly provides better compression rates
190: (force
191: .Xr gzip 1
1.14 mickey 192: mode).
1.20 millert 193: .It Fl h
194: Print a short help message.
1.35 jmc 195: .It Fl L
196: Print the license.
1.21 millert 197: .It Fl l
198: List information for the specified compressed files.
199: The following information is listed:
1.23 jmc 200: .Bl -tag -width "compression ratio"
1.21 millert 201: .It compressed size
1.23 jmc 202: Size of the compressed file.
1.21 millert 203: .It uncompressed size
1.23 jmc 204: Size of the file when uncompressed.
1.21 millert 205: .It compression ratio
1.23 jmc 206: Ratio of the difference between the compressed and uncompressed
1.21 millert 207: sizes to the uncompressed size.
208: .It uncompressed name
1.23 jmc 209: Name the file will be saved as when uncompressing.
1.21 millert 210: .El
211: .Pp
212: If the
213: .Fl v
214: option is specified, the following additional information is printed:
1.23 jmc 215: .Bl -tag -width "compression method"
1.21 millert 216: .It compression method
1.23 jmc 217: Name of the method used to compress the file.
1.21 millert 218: .It crc
1.23 jmc 219: 32-bit CRC
220: .Pq cyclic redundancy code
221: of the uncompressed file.
1.21 millert 222: .It "time stamp"
1.23 jmc 223: Date and time corresponding to the last data modification time
1.21 millert 224: (mtime) of the compressed file (if the
225: .Fl n
226: option is specified, the time stamp stored in the compressed file
227: is printed instead).
228: .El
1.30 jmc 229: .It Fl N
230: When uncompressing or listing, use the time stamp and file name stored
231: in the compressed file, if any, for the uncompressed version.
1.36 millert 232: This information is only available when the deflate scheme
1.35 jmc 233: .Pf ( Fl g )
234: is used.
1.36 millert 235: .It Fl n
236: When compressing, do not store the original file name and time stamp
237: in the header of the compressed file.
1.4 mickey 238: .It Fl O
1.35 jmc 239: Use compress mode
240: (the default).
1.6 aaron 241: .It Fl o Ar filename
1.4 mickey 242: Set the output file name.
1.30 jmc 243: .It Fl q
1.35 jmc 244: Be quiet: suppress all messages.
1.30 jmc 245: .It Fl r
1.35 jmc 246: Recursive mode:
1.30 jmc 247: .Nm
248: will descend into specified directories.
1.14 mickey 249: .It Fl S Ar suffix
1.35 jmc 250: Set the suffix for compressed files.
1.4 mickey 251: .It Fl t
1.6 aaron 252: Test the integrity of each file leaving any files intact.
1.30 jmc 253: .It Fl V
254: Display the program version
255: .Pq RCS IDs of the source files
256: and exit.
1.1 deraadt 257: .It Fl v
1.14 mickey 258: Print the percentage reduction of each file and other information.
1.1 deraadt 259: .El
260: .Pp
1.8 aaron 261: .Nm
1.19 jmc 262: uses a modified Lempel-Ziv algorithm
263: .Pq LZW .
1.1 deraadt 264: Common substrings in the file are first replaced by 9-bit codes 257 and up.
265: When code 512 is reached, the algorithm switches to 10-bit codes and
266: continues to use more bits until the
267: limit specified by the
268: .Fl b
1.9 aaron 269: flag is reached.
1.6 aaron 270: .Ar bits
1.23 jmc 271: must be between 9 and 16
272: .Pq the default is 16 .
1.1 deraadt 273: .Pp
274: After the
275: .Ar bits
276: limit is reached,
1.8 aaron 277: .Nm
1.1 deraadt 278: periodically checks the compression ratio.
279: If it is increasing,
1.8 aaron 280: .Nm
1.1 deraadt 281: continues to use the existing code dictionary.
282: However, if the compression ratio decreases,
1.8 aaron 283: .Nm
1.11 aaron 284: discards the table of substrings and rebuilds it from scratch.
285: This allows the algorithm to adapt to the next
1.8 aaron 286: .Dq block
287: of the file.
1.1 deraadt 288: .Pp
289: The
290: .Fl b
291: flag is omitted for
1.3 deraadt 292: .Nm uncompress
1.1 deraadt 293: since the
294: .Ar bits
295: parameter specified during compression
296: is encoded within the output, along with
297: a magic number to ensure that neither decompression of random data nor
298: recompression of compressed data is attempted.
299: .Pp
300: The amount of compression obtained depends on the size of the
301: input, the number of
302: .Ar bits
303: per code, and the distribution of common substrings.
1.23 jmc 304: Typically, text such as source code or English is reduced by 50 \- 60% using
1.35 jmc 305: .Nm .
1.1 deraadt 306: Compression is generally much better than that achieved by Huffman
307: coding (as used in the historical command pack), or adaptive Huffman
308: coding (as used in the historical command compact), and takes less
309: time to compute.
310: .Pp
311: The
1.35 jmc 312: .Nm compress ,
313: .Nm uncompress ,
1.18 deraadt 314: and
1.35 jmc 315: .Nm zcat
1.34 jmc 316: utilities exit with 0 on success; 1 if an error occurred;
317: or 2 if a warning occurred.
1.1 deraadt 318: .Sh SEE ALSO
1.32 jmc 319: .Xr gzexe 1 ,
1.35 jmc 320: .Xr gzip 1 ,
1.32 jmc 321: .Xr zdiff 1 ,
322: .Xr zforce 1 ,
323: .Xr zmore 1 ,
324: .Xr znew 1 ,
1.29 jmc 325: .Xr compress 3
326: .Pp
1.1 deraadt 327: .Rs
328: .%A Welch, Terry A.
329: .%D June, 1984
330: .%T "A Technique for High Performance Data Compression"
331: .%J "IEEE Computer"
332: .%V 17:6
1.32 jmc 333: .%P pp. 8\-19
1.1 deraadt 334: .Re
1.5 denny 335: .Sh STANDARDS
336: The
1.38 jmc 337: .Nm ,
338: .Nm uncompress ,
339: and
340: .Nm zcat
341: utilities are compliant with the
1.42 jmc 342: .St -xpg4
1.38 jmc 343: specification.
344: .Pp
345: The
1.8 aaron 346: .Nm
1.38 jmc 347: flags
1.40 jmc 348: .Op Fl 123456789dghLlNnOoqrStV ,
1.38 jmc 349: .Nm uncompress
350: flags
1.40 jmc 351: .Op Fl hlNnoqrt ,
1.38 jmc 352: and the
353: .Nm zcat
354: flags
355: .Op Fl fghqr
356: are extensions to that specification.
1.1 deraadt 357: .Sh HISTORY
358: The
359: .Nm
360: command appeared in
361: .Bx 4.3 .
1.35 jmc 362: Deflate compression support was added in
1.4 mickey 363: .Ox 2.1 .