Annotation of src/usr.bin/compress/gzip.1, Revision 1.13
1.13 ! sobrado 1: .\" $OpenBSD: gzip.1,v 1.12 2014/01/28 14:18:28 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: .\"
1.13 ! sobrado 36: .Dd $Mdocdate: January 28 2014 $
1.1 jmc 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
1.11 millert 46: .Op Fl 123456789cdfhLlNnOqrtVv
1.1 jmc 47: .Op Fl b Ar bits
48: .Op Fl o Ar filename
49: .Op Fl S Ar suffix
50: .Op Ar
51: .Nm gunzip
1.11 millert 52: .Op Fl cfhLlNnqrtVv
1.1 jmc 53: .Op Fl o Ar filename
54: .Op Ar
55: .Nm gzcat
1.11 millert 56: .Op Fl fhqr
1.1 jmc 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
1.3 millert 129: By default, when compressing, the original file name and time stamp
1.4 jmc 130: are stored in the compressed file.
1.3 millert 131: When uncompressing, this information is not used.
132: Instead, the uncompressed file inherits the time stamp of the
133: compressed version and the uncompressed file name is generated from
134: the name of the compressed file as described above.
135: These defaults may be overridden by the
136: .Fl N
137: and
138: .Fl n
139: flags, described below.
140: .Pp
1.1 jmc 141: The options are as follows:
142: .Bl -tag -width Ds
143: .It Fl 1...9
144: Use the deflate scheme, with compression factor of
145: .Fl 1
146: to
147: .Fl 9 .
148: Compression factor
149: .Fl 1
150: is the fastest, but provides a poorer level of compression.
151: Compression factor
152: .Fl 9
153: provides the best level of compression, but is relatively slow.
154: The default is
155: .Fl 6 .
156: .It Fl b Ar bits
157: Specify the
158: .Ar bits
159: code limit
160: .Pq see below .
161: .It Fl c
162: Compressed or uncompressed output is written to the standard output.
163: No files are modified (force
164: .Nm gzcat
165: mode).
166: .It Fl d
167: Decompress the source files instead of compressing them (force
168: .Nm gunzip
169: mode).
170: .It Fl f
171: Force compression of
172: .Ar file ,
173: even if it is not actually reduced in size.
174: Additionally, files are overwritten without prompting for confirmation.
175: If the input data is not in a format recognized by
176: .Nm
177: and if the option
178: .Fl c
179: is also given, copy the input data without change
180: to the standard output: let
181: .Nm gzcat
182: behave as
183: .Xr cat 1 .
184: .It Fl h
185: Print a short help message.
186: .It Fl L
1.12 jmc 187: A no-op which exists for compatibility only.
188: On GNU gzip, it displays the program's license.
1.1 jmc 189: .It Fl l
190: List information for the specified compressed files.
191: The following information is listed:
192: .Bl -tag -width "compression ratio"
193: .It compressed size
194: Size of the compressed file.
195: .It uncompressed size
196: Size of the file when uncompressed.
197: .It compression ratio
198: Ratio of the difference between the compressed and uncompressed
199: sizes to the uncompressed size.
200: .It uncompressed name
201: Name the file will be saved as when uncompressing.
202: .El
203: .Pp
204: If the
205: .Fl v
206: option is specified, the following additional information is printed:
207: .Bl -tag -width "compression method"
208: .It compression method
209: Name of the method used to compress the file.
210: .It crc
211: 32-bit CRC
212: .Pq cyclic redundancy code
213: of the uncompressed file.
214: .It "time stamp"
215: Date and time corresponding to the last data modification time
216: (mtime) of the compressed file (if the
217: .Fl n
218: option is specified, the time stamp stored in the compressed file
219: is printed instead).
220: .El
221: .It Fl N
222: When uncompressing or listing, use the time stamp and file name stored
223: in the compressed file, if any, for the uncompressed version.
224: .It Fl n
1.3 millert 225: When compressing, do not store the original file name and time stamp
226: in the
227: .Nm
228: header.
1.1 jmc 229: .It Fl O
230: Use old compression method
231: (force
232: .Xr compress 1
233: mode).
234: .It Fl o Ar filename
235: Set the output file name.
236: .It Fl q
237: Be quiet: suppress all messages.
238: .It Fl r
239: Recursive mode:
240: .Nm
241: will descend into specified directories.
242: .It Fl S Ar suffix
243: Set the suffix for compressed files.
244: .It Fl t
245: Test the integrity of each file leaving any files intact.
246: .It Fl V
1.12 jmc 247: A no-op which exists for compatibility only.
248: On GNU gzip, it displays version information.
1.1 jmc 249: .It Fl v
250: Print the percentage reduction of each file and other information.
251: .El
252: .Pp
253: .Nm
254: uses a modified Lempel-Ziv algorithm
255: .Pq LZW .
256: Common substrings are replaced by pointers to previous strings,
257: and are found using a hash table.
258: Unique substrings are emitted as a string of literal bytes,
259: and compressed as Huffman trees.
260: When code 512 is reached, the algorithm switches to 10-bit codes and
261: continues to use more bits until the
262: limit specified by the
263: .Fl b
264: flag is reached.
265: .Ar bits
266: must be between 9 and 16
267: .Pq the default is 16 .
268: .Pp
269: After the
270: .Ar bits
271: limit is reached,
272: .Nm
273: periodically checks the compression ratio.
274: If it is increasing,
275: .Nm
276: continues to use the existing code dictionary.
277: However, if the compression ratio decreases,
278: .Nm
279: discards the table of substrings and rebuilds it from scratch.
280: This allows the algorithm to adapt to the next
281: .Dq block
282: of the file.
283: .Pp
284: The
285: .Fl b
286: flag is omitted for
287: .Nm gunzip
288: since the
289: .Ar bits
290: parameter specified during compression
291: is encoded within the output, along with
292: a magic number to ensure that neither decompression of random data nor
293: recompression of compressed data is attempted.
294: .Pp
295: The amount of compression obtained depends on the size of the
296: input, the number of
297: .Ar bits
298: per code, and the distribution of common substrings.
299: Typically, text such as source code or English is reduced by 60 \- 70% using
300: .Nm .
301: Compression is generally much better than that achieved by Huffman
302: coding (as used in the historical command pack), or adaptive Huffman
303: coding (as used in the historical command compact), and takes less
304: time to compute.
1.2 ray 305: .Sh ENVIRONMENT
306: .Bl -tag -width Ds
307: .It Ev GZIP
308: Options which are passed to
309: .Nm ,
310: .Nm gunzip ,
311: and
312: .Nm gzcat
313: automatically.
314: .El
1.10 jmc 315: .Sh EXIT STATUS
316: The
1.13 ! sobrado 317: .Nm gzip
! 318: utility exits with one of the following values:
! 319: .Pp
! 320: .Bl -tag -width Ds -offset indent -compact
! 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
! 334: The
! 335: .Nm gunzip
1.10 jmc 336: and
337: .Nm gzcat
1.13 ! sobrado 338: utilities exit 0 on success,
! 339: and >0 if an error occurs.
1.1 jmc 340: .Sh SEE ALSO
341: .Xr compress 1 ,
342: .Xr gzexe 1 ,
343: .Xr gzsig 1 ,
344: .Xr zdiff 1 ,
345: .Xr zforce 1 ,
346: .Xr zmore 1 ,
347: .Xr znew 1 ,
348: .Xr compress 3
1.9 jmc 349: .Sh STANDARDS
1.8 jmc 350: .Rs
351: .%A P. Deutsch
352: .%A J-L. Gailly
353: .%D May 1996
354: .%R RFC 1950
355: .%T ZLIB Compressed Data Format Specification version 3.3
356: .Re
1.9 jmc 357: .Pp
1.8 jmc 358: .Rs
359: .%A P. Deutsch
360: .%D May 1996
361: .%R RFC 1951
362: .%T DEFLATE Compressed Data Format Specification version 1.3
363: .Re
1.9 jmc 364: .Pp
1.8 jmc 365: .Rs
366: .%A P. Deutsch
367: .%D May 1996
368: .%R RFC 1952
369: .%T GZIP file format specification version 4.3
370: .Re
1.1 jmc 371: .Sh HISTORY
372: .Nm gzip
373: compatibility was added to
374: .Xr compress 1
375: in
376: .Ox 3.4 .
377: The
378: .Sq g
379: in this version of
380: .Nm gzip
381: stands for
382: .Dq gratis .
![[BACK]](/icons/back.gif){kind=icon}
Return to gzip.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / compress