Annotation of src/usr.bin/compress/compress.1, Revision 1.49
1.49 ! millert 1: .\" $OpenBSD: compress.1,v 1.48 2014/03/17 14:23:50 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.49 ! millert 37: .Dd $Mdocdate: March 17 2014 $
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.47 sobrado 47: .Op Fl 123456789cdfghlNnOqrtv
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.47 sobrado 53: .Op Fl cfhlNnqrtv
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.49 ! millert 87: It has the ability to restore files compressed by
! 88: .Nm ,
! 89: .Xr gzip 1 ,
1.35 jmc 90: and
1.49 ! millert 91: .Xr zip 1 ,
1.35 jmc 92: recognising the following extensions:
1.24 millert 93: .Dq .Z ,
94: .Dq -Z ,
95: .Dq _Z ,
96: .Dq .gz ,
97: .Dq -gz ,
98: .Dq _gz ,
99: .Dq .tgz ,
100: .Dq -tgz ,
101: .Dq _tgz ,
102: .Dq .taz ,
103: .Dq -taz ,
104: and
105: .Dq _taz .
1.49 ! millert 106: The
! 107: .Fl S
! 108: option can be used to support other file extensions.
1.25 jmc 109: Extensions ending in
1.24 millert 110: .Dq tgz
111: and
112: .Dq taz
113: are not removed when decompressing, instead they are converted to
114: .Dq tar .
1.49 ! millert 115: Files in zip format are only supported if they contain a single member
! 116: either compressed with the deflate scheme or stored uncompressed.
1.12 mickey 117: .Pp
118: The
119: .Nm zcat
1.13 mickey 120: command is equivalent in functionality to
1.12 mickey 121: .Nm uncompress
1.13 mickey 122: .Fl c .
1.1 deraadt 123: .Pp
124: If renaming the files would cause files to be overwritten and the standard
125: input device is a terminal, the user is prompted (on the standard error
126: output) for confirmation.
127: If prompting is not possible or confirmation is not received, the files
128: are not overwritten.
129: .Pp
130: If no files are specified, the standard input is compressed or uncompressed
131: to the standard output.
1.9 aaron 132: If either the input or output files are not regular files, the checks for
1.1 deraadt 133: reduction in size and file overwriting are not performed, the input file is
134: not removed, and the attributes of the input file are not retained.
135: .Pp
1.36 millert 136: By default, when compressing using the deflate scheme
137: .Pf ( Fl g ) ,
1.37 jmc 138: the original file name and time stamp are stored in the compressed file.
1.36 millert 139: When uncompressing, this information is not used.
140: Instead, the uncompressed file inherits the time stamp of the
141: compressed version and the uncompressed file name is generated from
142: the name of the compressed file as described above.
143: These defaults may be overridden by the
144: .Fl N
145: and
146: .Fl n
147: flags, described below.
148: .Pp
1.1 deraadt 149: The options are as follows:
150: .Bl -tag -width Ds
1.30 jmc 151: .It Fl 1...9
1.35 jmc 152: Use the deflate scheme, with compression factor of
1.30 jmc 153: .Fl 1
154: to
155: .Fl 9 .
156: Compression factor
157: .Fl 1
158: is the fastest, but provides a poorer level of compression.
159: Compression factor
160: .Fl 9
161: provides the best level of compression, but is relatively slow.
162: The default is
163: .Fl 6 .
164: This option implies
165: .Fl g .
1.6 aaron 166: .It Fl b Ar bits
1.1 deraadt 167: Specify the
168: .Ar bits
1.23 jmc 169: code limit
170: .Pq see below .
1.1 deraadt 171: .It Fl c
172: Compressed or uncompressed output is written to the standard output.
1.17 jmc 173: No files are modified (force
1.14 mickey 174: .Nm zcat
175: mode).
1.4 mickey 176: .It Fl d
1.14 mickey 177: Decompress the source files instead of compressing them (force
178: .Nm uncompress
179: mode).
1.1 deraadt 180: .It Fl f
181: Force compression of
182: .Ar file ,
183: even if it is not actually reduced in size.
184: Additionally, files are overwritten without prompting for confirmation.
1.27 tedu 185: If the input data is not in a format recognized by
186: .Nm
187: and if the option
188: .Fl c
189: is also given, copy the input data without change
1.29 jmc 190: to the standard output: let
1.27 tedu 191: .Nm zcat
192: behave as
1.28 jmc 193: .Xr cat 1 .
1.4 mickey 194: .It Fl g
1.35 jmc 195: Use the deflate scheme, which reportedly provides better compression rates
196: (force
197: .Xr gzip 1
1.14 mickey 198: mode).
1.20 millert 199: .It Fl h
200: Print a short help message.
1.21 millert 201: .It Fl l
202: List information for the specified compressed files.
203: The following information is listed:
1.23 jmc 204: .Bl -tag -width "compression ratio"
1.21 millert 205: .It compressed size
1.23 jmc 206: Size of the compressed file.
1.21 millert 207: .It uncompressed size
1.23 jmc 208: Size of the file when uncompressed.
1.21 millert 209: .It compression ratio
1.23 jmc 210: Ratio of the difference between the compressed and uncompressed
1.21 millert 211: sizes to the uncompressed size.
212: .It uncompressed name
1.23 jmc 213: Name the file will be saved as when uncompressing.
1.21 millert 214: .El
215: .Pp
216: If the
217: .Fl v
218: option is specified, the following additional information is printed:
1.23 jmc 219: .Bl -tag -width "compression method"
1.21 millert 220: .It compression method
1.23 jmc 221: Name of the method used to compress the file.
1.21 millert 222: .It crc
1.23 jmc 223: 32-bit CRC
224: .Pq cyclic redundancy code
225: of the uncompressed file.
1.21 millert 226: .It "time stamp"
1.23 jmc 227: Date and time corresponding to the last data modification time
1.21 millert 228: (mtime) of the compressed file (if the
229: .Fl n
230: option is specified, the time stamp stored in the compressed file
231: is printed instead).
232: .El
1.30 jmc 233: .It Fl N
234: When uncompressing or listing, use the time stamp and file name stored
235: in the compressed file, if any, for the uncompressed version.
1.36 millert 236: This information is only available when the deflate scheme
1.35 jmc 237: .Pf ( Fl g )
238: is used.
1.36 millert 239: .It Fl n
240: When compressing, do not store the original file name and time stamp
241: in the header of the compressed file.
1.4 mickey 242: .It Fl O
1.35 jmc 243: Use compress mode
244: (the default).
1.6 aaron 245: .It Fl o Ar filename
1.4 mickey 246: Set the output file name.
1.30 jmc 247: .It Fl q
1.35 jmc 248: Be quiet: suppress all messages.
1.30 jmc 249: .It Fl r
1.35 jmc 250: Recursive mode:
1.30 jmc 251: .Nm
252: will descend into specified directories.
1.14 mickey 253: .It Fl S Ar suffix
1.49 ! millert 254: When compressing, use the specified
! 255: .Ar suffix
! 256: as the extension when creating output files.
! 257: When uncompressing, recognize file names with the specified
! 258: .Ar suffix
! 259: as compressed files.
1.4 mickey 260: .It Fl t
1.6 aaron 261: Test the integrity of each file leaving any files intact.
1.1 deraadt 262: .It Fl v
1.14 mickey 263: Print the percentage reduction of each file and other information.
1.1 deraadt 264: .El
265: .Pp
1.8 aaron 266: .Nm
1.19 jmc 267: uses a modified Lempel-Ziv algorithm
268: .Pq LZW .
1.1 deraadt 269: Common substrings in the file are first replaced by 9-bit codes 257 and up.
270: When code 512 is reached, the algorithm switches to 10-bit codes and
271: continues to use more bits until the
272: limit specified by the
273: .Fl b
1.9 aaron 274: flag is reached.
1.6 aaron 275: .Ar bits
1.23 jmc 276: must be between 9 and 16
277: .Pq the default is 16 .
1.1 deraadt 278: .Pp
279: After the
280: .Ar bits
281: limit is reached,
1.8 aaron 282: .Nm
1.1 deraadt 283: periodically checks the compression ratio.
284: If it is increasing,
1.8 aaron 285: .Nm
1.1 deraadt 286: continues to use the existing code dictionary.
287: However, if the compression ratio decreases,
1.8 aaron 288: .Nm
1.11 aaron 289: discards the table of substrings and rebuilds it from scratch.
290: This allows the algorithm to adapt to the next
1.8 aaron 291: .Dq block
292: of the file.
1.1 deraadt 293: .Pp
294: The
295: .Fl b
296: flag is omitted for
1.3 deraadt 297: .Nm uncompress
1.1 deraadt 298: since the
299: .Ar bits
300: parameter specified during compression
301: is encoded within the output, along with
302: a magic number to ensure that neither decompression of random data nor
303: recompression of compressed data is attempted.
304: .Pp
305: The amount of compression obtained depends on the size of the
306: input, the number of
307: .Ar bits
308: per code, and the distribution of common substrings.
1.23 jmc 309: Typically, text such as source code or English is reduced by 50 \- 60% using
1.35 jmc 310: .Nm .
1.1 deraadt 311: Compression is generally much better than that achieved by Huffman
312: coding (as used in the historical command pack), or adaptive Huffman
313: coding (as used in the historical command compact), and takes less
314: time to compute.
1.45 jmc 315: .Sh EXIT STATUS
1.1 deraadt 316: The
1.44 jmc 317: .Nm compress
318: utility exits with one of the following values:
319: .Pp
1.45 jmc 320: .Bl -tag -width Ds -offset indent -compact
1.44 jmc 321: .It 0
322: Success.
323: .It 1
324: An error occurred.
325: .It 2
326: At least one of the specified files was not compressed since
327: .Fl f
328: was not specified and compression would have resulted in a size
329: increase.
330: .It \*(Gt2
331: An error occurred.
332: .El
333: .Pp
1.48 jmc 334: .Ex -std uncompress zcat
1.1 deraadt 335: .Sh SEE ALSO
1.32 jmc 336: .Xr gzexe 1 ,
1.35 jmc 337: .Xr gzip 1 ,
1.32 jmc 338: .Xr zdiff 1 ,
339: .Xr zforce 1 ,
340: .Xr zmore 1 ,
341: .Xr znew 1 ,
1.29 jmc 342: .Xr compress 3
1.1 deraadt 343: .Rs
344: .%A Welch, Terry A.
345: .%D June, 1984
346: .%T "A Technique for High Performance Data Compression"
347: .%J "IEEE Computer"
348: .%V 17:6
1.32 jmc 349: .%P pp. 8\-19
1.1 deraadt 350: .Re
1.5 denny 351: .Sh STANDARDS
352: The
1.38 jmc 353: .Nm ,
354: .Nm uncompress ,
355: and
356: .Nm zcat
357: utilities are compliant with the
1.46 jmc 358: X/Open System Interfaces option of the
359: .St -p1003.1-2008
1.38 jmc 360: specification.
361: .Pp
362: The
1.8 aaron 363: .Nm
1.38 jmc 364: flags
1.47 sobrado 365: .Op Fl 123456789dghlNnOoqrSt ,
1.38 jmc 366: .Nm uncompress
367: flags
1.47 sobrado 368: .Op Fl hlNnoqrt ,
1.38 jmc 369: and the
370: .Nm zcat
371: flags
372: .Op Fl fghqr
373: are extensions to that specification.
1.46 jmc 374: .Pp
375: .St -p1003.1-2008
376: specifies a maximum bits limit
377: .Pq Fl b
378: of 14 to
379: .Qq achieve portability to all systems .
1.1 deraadt 380: .Sh HISTORY
381: The
382: .Nm
383: command appeared in
384: .Bx 4.3 .
1.35 jmc 385: Deflate compression support was added in
1.4 mickey 386: .Ox 2.1 .
![[BACK]](/icons/back.gif){kind=icon}
Return to compress.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / compress