Annotation of src/usr.bin/compress/gzip.1, Revision 1.2
1.2 ! ray 1: .\" $OpenBSD: gzip.1,v 1.1 2007/01/24 10:53:43 jmc Exp $
1.1 jmc 2: .\"
3: .\" Copyright (c) 1986, 1990, 1993
4: .\" The Regents of the University of California. All rights reserved.
5: .\"
6: .\" This code is derived from software contributed to Berkeley by
7: .\" James A. Woods, derived from original work by Spencer Thomas
8: .\" and Joseph Orost.
9: .\"
10: .\" Redistribution and use in source and binary forms, with or without
11: .\" modification, are permitted provided that the following conditions
12: .\" are met:
13: .\" 1. Redistributions of source code must retain the above copyright
14: .\" notice, this list of conditions and the following disclaimer.
15: .\" 2. Redistributions in binary form must reproduce the above copyright
16: .\" notice, this list of conditions and the following disclaimer in the
17: .\" documentation and/or other materials provided with the distribution.
18: .\" 3. Neither the name of the University nor the names of its contributors
19: .\" may be used to endorse or promote products derived from this software
20: .\" without specific prior written permission.
21: .\"
22: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32: .\" SUCH DAMAGE.
33: .\"
34: .\" @(#)compress.1 8.2 (Berkeley) 4/18/94
35: .\"
36: .Dd April 18, 1994
37: .Dt GZIP 1
38: .Os
39: .Sh NAME
40: .Nm gzip ,
41: .Nm gunzip ,
42: .Nm gzcat
43: .Nd compress and expand data (deflate mode)
44: .Sh SYNOPSIS
45: .Nm gzip
46: .Op Fl 123456789cdfghLlNnOqrtVv
47: .Op Fl b Ar bits
48: .Op Fl o Ar filename
49: .Op Fl S Ar suffix
50: .Op Ar
51: .Nm gunzip
52: .Op Fl cfhlNnqrtv
53: .Op Fl o Ar filename
54: .Op Ar
55: .Nm gzcat
56: .Op Fl fghqr
57: .Op Ar
58: .Sh DESCRIPTION
59: The
60: .Nm
61: utility
62: reduces the size of the named files using adaptive Lempel-Ziv coding,
63: in deflate mode.
64: If invoked as
65: .Nm gzip -O ,
66: the compress mode of compression is chosen;
67: see
68: .Xr compress 1
69: for more information.
70: Each file is renamed to the same name plus the extension
71: .Dq .gz .
72: As many of the modification time, access time, file flags, file mode,
73: user ID, and group ID as allowed by permissions are retained in the
74: new file.
75: If compression would not reduce the size of a file,
76: the file is ignored (unless
77: .Fl f
78: is used).
79: .Pp
80: The
81: .Nm gunzip
82: utility restores compressed files to their original form, renaming the
83: files by removing the extension (or by using the stored name if the
84: .Fl N
85: flag is specified).
86: It has the ability to restore files compressed by both
87: .Nm
88: and
89: .Xr compress 1 ,
90: recognising the following extensions:
91: .Dq .Z ,
92: .Dq -Z ,
93: .Dq _Z ,
94: .Dq .gz ,
95: .Dq -gz ,
96: .Dq _gz ,
97: .Dq .tgz ,
98: .Dq -tgz ,
99: .Dq _tgz ,
100: .Dq .taz ,
101: .Dq -taz ,
102: and
103: .Dq _taz .
104: Extensions ending in
105: .Dq tgz
106: and
107: .Dq taz
108: are not removed when decompressing, instead they are converted to
109: .Dq tar .
110: .Pp
111: The
112: .Nm gzcat
113: command is equivalent in functionality to
114: .Nm gunzip
115: .Fl c .
116: .Pp
117: If renaming the files would cause files to be overwritten and the standard
118: input device is a terminal, the user is prompted (on the standard error
119: output) for confirmation.
120: If prompting is not possible or confirmation is not received, the files
121: are not overwritten.
122: .Pp
123: If no files are specified, the standard input is compressed or uncompressed
124: to the standard output.
125: If either the input or output files are not regular files, the checks for
126: reduction in size and file overwriting are not performed, the input file is
127: not removed, and the attributes of the input file are not retained.
128: .Pp
129: The options are as follows:
130: .Bl -tag -width Ds
131: .It Fl 1...9
132: Use the deflate scheme, with compression factor of
133: .Fl 1
134: to
135: .Fl 9 .
136: Compression factor
137: .Fl 1
138: is the fastest, but provides a poorer level of compression.
139: Compression factor
140: .Fl 9
141: provides the best level of compression, but is relatively slow.
142: The default is
143: .Fl 6 .
144: This option implies
145: .Fl g .
146: .It Fl b Ar bits
147: Specify the
148: .Ar bits
149: code limit
150: .Pq see below .
151: .It Fl c
152: Compressed or uncompressed output is written to the standard output.
153: No files are modified (force
154: .Nm gzcat
155: mode).
156: .It Fl d
157: Decompress the source files instead of compressing them (force
158: .Nm gunzip
159: mode).
160: .It Fl f
161: Force compression of
162: .Ar file ,
163: even if it is not actually reduced in size.
164: Additionally, files are overwritten without prompting for confirmation.
165: If the input data is not in a format recognized by
166: .Nm
167: and if the option
168: .Fl c
169: is also given, copy the input data without change
170: to the standard output: let
171: .Nm gzcat
172: behave as
173: .Xr cat 1 .
174: .It Fl g
175: Use the deflate scheme, which reportedly provides better compression rates
176: (the default).
177: .It Fl h
178: Print a short help message.
179: .It Fl L
180: Print the license.
181: .It Fl l
182: List information for the specified compressed files.
183: The following information is listed:
184: .Bl -tag -width "compression ratio"
185: .It compressed size
186: Size of the compressed file.
187: .It uncompressed size
188: Size of the file when uncompressed.
189: .It compression ratio
190: Ratio of the difference between the compressed and uncompressed
191: sizes to the uncompressed size.
192: .It uncompressed name
193: Name the file will be saved as when uncompressing.
194: .El
195: .Pp
196: If the
197: .Fl v
198: option is specified, the following additional information is printed:
199: .Bl -tag -width "compression method"
200: .It compression method
201: Name of the method used to compress the file.
202: .It crc
203: 32-bit CRC
204: .Pq cyclic redundancy code
205: of the uncompressed file.
206: .It "time stamp"
207: Date and time corresponding to the last data modification time
208: (mtime) of the compressed file (if the
209: .Fl n
210: option is specified, the time stamp stored in the compressed file
211: is printed instead).
212: .El
213: .It Fl N
214: When compressing, save the original file name and time stamp in the
215: compressed file.
216: This information is saved by default.
217: When uncompressing or listing, use the time stamp and file name stored
218: in the compressed file, if any, for the uncompressed version.
219: .It Fl n
220: When compressing, do not save the original file name and time stamp.
221: This information is saved by default.
222: When uncompressing, do not restore the original file name and time stamp.
223: By default, the uncompressed file inherits the time stamp of the
224: compressed version and the uncompressed file name is generated from
225: the name of the compressed file name as described above.
226: .It Fl O
227: Use old compression method
228: (force
229: .Xr compress 1
230: mode).
231: .It Fl o Ar filename
232: Set the output file name.
233: .It Fl q
234: Be quiet: suppress all messages.
235: .It Fl r
236: Recursive mode:
237: .Nm
238: will descend into specified directories.
239: .It Fl S Ar suffix
240: Set the suffix for compressed files.
241: .It Fl t
242: Test the integrity of each file leaving any files intact.
243: .It Fl V
244: Display the program version
245: .Pq RCS IDs of the source files
246: and exit.
247: .It Fl v
248: Print the percentage reduction of each file and other information.
249: .El
250: .Pp
251: .Nm
252: uses a modified Lempel-Ziv algorithm
253: .Pq LZW .
254: Common substrings are replaced by pointers to previous strings,
255: and are found using a hash table.
256: Unique substrings are emitted as a string of literal bytes,
257: and compressed as Huffman trees.
258: When code 512 is reached, the algorithm switches to 10-bit codes and
259: continues to use more bits until the
260: limit specified by the
261: .Fl b
262: flag is reached.
263: .Ar bits
264: must be between 9 and 16
265: .Pq the default is 16 .
266: .Pp
267: After the
268: .Ar bits
269: limit is reached,
270: .Nm
271: periodically checks the compression ratio.
272: If it is increasing,
273: .Nm
274: continues to use the existing code dictionary.
275: However, if the compression ratio decreases,
276: .Nm
277: discards the table of substrings and rebuilds it from scratch.
278: This allows the algorithm to adapt to the next
279: .Dq block
280: of the file.
281: .Pp
282: The
283: .Fl b
284: flag is omitted for
285: .Nm gunzip
286: since the
287: .Ar bits
288: parameter specified during compression
289: is encoded within the output, along with
290: a magic number to ensure that neither decompression of random data nor
291: recompression of compressed data is attempted.
292: .Pp
293: The amount of compression obtained depends on the size of the
294: input, the number of
295: .Ar bits
296: per code, and the distribution of common substrings.
297: Typically, text such as source code or English is reduced by 60 \- 70% using
298: .Nm .
299: Compression is generally much better than that achieved by Huffman
300: coding (as used in the historical command pack), or adaptive Huffman
301: coding (as used in the historical command compact), and takes less
302: time to compute.
303: .Pp
304: The
305: .Nm gzip ,
306: .Nm gunzip ,
307: and
308: .Nm gzcat
309: utilities exit with 0 on success; 1 if an error occurred;
310: or 2 if a warning occurred.
1.2 ! ray 311: .Sh ENVIRONMENT
! 312: .Bl -tag -width Ds
! 313: .It Ev GZIP
! 314: Options which are passed to
! 315: .Nm ,
! 316: .Nm gunzip ,
! 317: and
! 318: .Nm gzcat
! 319: automatically.
! 320: .El
1.1 jmc 321: .Sh SEE ALSO
322: .Xr compress 1 ,
323: .Xr gzexe 1 ,
324: .Xr gzsig 1 ,
325: .Xr zdiff 1 ,
326: .Xr zforce 1 ,
327: .Xr zmore 1 ,
328: .Xr znew 1 ,
329: .Xr compress 3
330: .Pp
331: .Bl -tag -width 12n -compact
332: .It RFC 1950
333: ZLIB Compressed Data Format Specification.
334: .It RFC 1951
335: DEFLATE Compressed Data Format Specification.
336: .It RFC 1952
337: GZIP File Format Specification.
338: .El
339: .Sh HISTORY
340: .Nm gzip
341: compatibility was added to
342: .Xr compress 1
343: in
344: .Ox 3.4 .
345: The
346: .Sq g
347: in this version of
348: .Nm gzip
349: stands for
350: .Dq gratis .