« back to all changes in this revision
Viewing changes to doc/gzip.texi
- browse files at revision 4
- compare with another revision
- download diff
- download tarball
- view history from revision 4
- Committer: Bazaar Package Importer
- Author(s): Bdale Garbee
- Date: 2008-04-15 14:03:26 UTC
- mfrom: (2.1.8 hardy)
- Revision ID: james.westby@ubuntu.com-20080415140326-tt0bpzc652x56msg
Tags: 1.3.12-6
* strip the win32 gzip.exe binary during install, closes: #464455
* patch from Reuben Thomas for the zless.1 man page with pointers to
lessfile and lesspipe, which are a better solution than zless in most
cases... closes: #46787, #51162
* fix FTBFS when using gcc-4.3, closes: #476031
* remove the preinst since the --assert-support-predepends check should
no longer be necessary
* patch from Reuben Thomas for the zless.1 man page with pointers to
lessfile and lesspipe, which are a better solution than zless in most
cases... closes: #46787, #51162
* fix FTBFS when using gcc-4.3, closes: #476031
* remove the preinst since the --assert-support-predepends check should
no longer be necessary
added
removed
doc/gzip.texi
1
\input texinfo @c -*-texinfo-*-
2
@c %**start of header
3
@setfilename gzip.info
4
@include version.texi
5
@settitle Gzip User's Manual
6
@finalout
7
@setchapternewpage odd
8
@c %**end of header
9
@copying
10
This manual is for Gzip
11
(version @value{VERSION}, @value{UPDATED}),
12
and documents commands for compressing and decompressing data.
13
14
Copyright @copyright{} 1998, 1999, 2001, 2002, 2006, 2007 Free
15
Software Foundation, Inc.
16
17
Copyright @copyright{} 1992, 1993 Jean-loup Gailly
18
19
@quotation
20
Permission is granted to copy, distribute and/or modify this document
21
under the terms of the GNU Free Documentation License, Version 1.2 or
22
any later version published by the Free Software Foundation; with no
23
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
24
Texts. A copy of the license is included in the section entitled ``GNU
25
Free Documentation License''.
26
@end quotation
27
@end copying
28
29
@c Debian install-info (up through at least version 1.9.20) uses only the
30
@c first dircategory. But install-info 1.10.28 rejects any attempt to
31
@c put the more-useful individual utility first. So put the less-useful
32
@c general category first.
33
@dircategory Utilities
34
@direntry
35
* Gzip: (gzip). The gzip command for compressing files.
36
@end direntry
37
38
@dircategory Individual utilities
39
@direntry
40
* gzip: (gzip)Invoking gzip. Compress files.
41
@end direntry
42
43
@titlepage
44
@title gzip
45
@subtitle The data compression program
46
@subtitle for Gzip Version @value{VERSION}
47
@subtitle @value{UPDATED}
48
@author by Jean-loup Gailly
49
50
@page
51
@vskip 0pt plus 1filll
52
@insertcopying
53
@end titlepage
54
55
@contents
56
57
@ifnottex
58
@node Top
59
@top Compressing Files
60
61
@insertcopying
62
@end ifnottex
63
64
@menu
65
* Overview:: Preliminary information.
66
* Sample:: Sample output from @command{gzip}.
67
* Invoking gzip:: How to run @command{gzip}.
68
* Advanced usage:: Concatenated files.
69
* Environment:: The @env{GZIP} environment variable
70
* Tapes:: Using @command{gzip} on tapes.
71
* Problems:: Reporting bugs.
72
* Copying This Manual:: How to make copies of this manual.
73
* Concept Index:: Index of concepts.
74
@end menu
75
76
@node Overview
77
@chapter Overview
78
@cindex overview
79
80
@command{gzip} reduces the size of the named files using Lempel-Ziv coding
81
(LZ77). Whenever possible, each file is replaced by one with the
82
extension @samp{.gz}, while keeping the same ownership modes, access and
83
modification times. (The default extension is @option{-gz} for @abbr{VMS},
84
@samp{z} for @abbr{MSDOS}, @abbr{OS/2} @abbr{FAT} and Atari.)
85
If no files are specified or
86
if a file name is "-", the standard input is compressed to the standard
87
output. @command{gzip} will only attempt to compress regular files. In
88
particular, it will ignore symbolic links.
89
90
If the new file name is too long for its file system, @command{gzip}
91
truncates it. @command{gzip} attempts to truncate only the parts of the
92
file name longer than 3 characters. (A part is delimited by dots.) If
93
the name consists of small parts only, the longest parts are truncated.
94
For example, if file names are limited to 14 characters, gzip.msdos.exe
95
is compressed to gzi.msd.exe.gz. Names are not truncated on systems
96
which do not have a limit on file name length.
97
98
By default, @command{gzip} keeps the original file name and time stamp in
99
the compressed file. These are used when decompressing the file with the
100
@option{-N} option. This is useful when the compressed file name was
101
truncated or when the time stamp was not preserved after a file
102
transfer. However, due to limitations in the current @command{gzip} file
103
format, fractional seconds are discarded. Also, time stamps must fall
104
within the range 1970-01-01 00:00:00 through 2106-02-07 06:28:15
105
@abbr{UTC}, and hosts whose operating systems use 32-bit time
106
stamps are further restricted to time stamps no later than 2038-01-19
107
03:14:07 @abbr{UTC}. The upper bounds assume the typical case
108
where leap seconds are ignored.
109
110
Compressed files can be restored to their original form using @samp{gzip -d}
111
or @command{gunzip} or @command{zcat}. If the original name saved in the
112
compressed file is not suitable for its file system, a new name is
113
constructed from the original one to make it legal.
114
115
@command{gunzip} takes a list of files on its command line and replaces
116
each file whose name ends with @samp{.gz}, @samp{.z}, @samp{.Z},
117
@option{-gz}, @option{-z} or @samp{_z} and which begins with the correct
118
magic number with an uncompressed file without the original extension.
119
@command{gunzip} also recognizes the special extensions @samp{.tgz} and
120
@samp{.taz} as shorthands for @samp{.tar.gz} and @samp{.tar.Z}
121
respectively. When compressing, @command{gzip} uses the @samp{.tgz}
122
extension if necessary instead of truncating a file with a @samp{.tar}
123
extension.
124
125
@command{gunzip} can currently decompress files created by @command{gzip},
126
@command{zip}, @command{compress} or @command{pack}. The detection of the input
127
format is automatic. When using the first two formats, @command{gunzip}
128
checks a 32 bit @abbr{CRC} (cyclic redundancy check). For @command{pack},
129
@command{gunzip} checks the uncompressed length. The @command{compress} format
130
was not designed to allow consistency checks. However @command{gunzip} is
131
sometimes able to detect a bad @samp{.Z} file. If you get an error when
132
uncompressing a @samp{.Z} file, do not assume that the @samp{.Z} file is
133
correct simply because the standard @command{uncompress} does not complain.
134
This generally means that the standard @command{uncompress} does not check
135
its input, and happily generates garbage output. The @abbr{SCO} @samp{compress
136
-H} format (@abbr{LZH} compression method) does not include a @abbr{CRC} but
137
also allows some consistency checks.
138
139
Files created by @command{zip} can be uncompressed by @command{gzip} only if
140
they have a single member compressed with the 'deflation' method. This
141
feature is only intended to help conversion of @file{tar.zip} files to
142
the @file{tar.gz} format. To extract a @command{zip} file with a single
143
member, use a command like @samp{gunzip <foo.zip} or @samp{gunzip -S
144
.zip foo.zip}. To extract @command{zip} files with several
145
members, use @command{unzip} instead of @command{gunzip}.
146
147
@command{zcat} is identical to @samp{gunzip -c}. @command{zcat}
148
uncompresses either a list of files on the command line or its standard
149
input and writes the uncompressed data on standard output. @command{zcat}
150
will uncompress files that have the correct magic number whether they
151
have a @samp{.gz} suffix or not.
152
153
@command{gzip} uses the Lempel-Ziv algorithm used in @command{zip} and
154
@abbr{PKZIP}@.
155
The amount of compression obtained depends on the size of the input and
156
the distribution of common substrings. Typically, text such as source
157
code or English is reduced by 60-70%. Compression is generally much
158
better than that achieved by @abbr{LZW} (as used in @command{compress}), Huffman
159
coding (as used in @command{pack}), or adaptive Huffman coding
160
(@command{compact}).
161
162
Compression is always performed, even if the compressed file is slightly
163
larger than the original. The worst case expansion is a few bytes for
164
the @command{gzip} file header, plus 5 bytes every 32K block, or an expansion
165
ratio of 0.015% for large files. Note that the actual number of used
166
disk blocks almost never increases. @command{gzip} normally preserves the mode,
167
ownership and time stamps of files when compressing or decompressing.
168
169
The @command{gzip} file format is specified in P. Deutsch, @sc{gzip} file
170
format specification version 4.3,
171
@uref{ftp://ftp.isi.edu/in-notes/rfc1952.txt, Internet @abbr{RFC} 1952} (May
172
1996). The @command{zip} deflation format is specified in P. Deutsch,
173
@sc{deflate} Compressed Data Format Specification version 1.3,
174
@uref{ftp://ftp.isi.edu/in-notes/rfc1951.txt, Internet @abbr{RFC} 1951} (May
175
1996).
176
177
@node Sample
178
@chapter Sample Output
179
@cindex sample
180
181
Here are some realistic examples of running @command{gzip}.
182
183
This is the output of the command @samp{gzip -h}:
184
185
@example
186
Usage: gzip [OPTION]... [FILE]...
187
Compress or uncompress FILEs (by default, compress FILES in-place).
188
189
Mandatory arguments to long options are mandatory for short options too.
190
191
-c, --stdout write on standard output, keep original files unchanged
192
-d, --decompress decompress
193
-f, --force force overwrite of output file and compress links
194
-h, --help give this help
195
-l, --list list compressed file contents
196
-L, --license display software license
197
-n, --no-name do not save or restore the original name and time stamp
198
-N, --name save or restore the original name and time stamp
199
-q, --quiet suppress all warnings
200
-r, --recursive operate recursively on directories
201
-S, --suffix=SUF use suffix SUF on compressed files
202
-t, --test test compressed file integrity
203
-v, --verbose verbose mode
204
-V, --version display version number
205
-1, --fast compress faster
206
-9, --best compress better
207
208
With no FILE, or when FILE is -, read standard input.
209
210
Report bugs to <bug-gzip@@gnu.org>.
211
@end example
212
213
This is the output of the command @samp{gzip -v texinfo.tex}:
214
215
@example
216
texinfo.tex: 69.3% -- replaced with texinfo.tex.gz
217
@end example
218
219
The following command will find all regular @samp{.gz} files in the
220
current directory and subdirectories (skipping file names that contain
221
newlines), and extract them in place without destroying the original,
222
stopping on the first failure:
223
224
@example
225
find . -name '*
226
*' -prune -o -name '*.gz' -type f -print |
227
sed "
228
s/'/'\\''/g
229
s/^\\(.*\\)\\.gz$/gunzip <'\\1.gz' >'\\1'/
230
" |
231
sh -e
232
@end example
233
234
@node Invoking gzip
235
@chapter Invoking @command{gzip}
236
@cindex invoking
237
@cindex options
238
239
The format for running the @command{gzip} program is:
240
241
@example
242
gzip @var{option} @dots{}
243
@end example
244
245
@command{gzip} supports the following options:
246
247
@table @option
248
@item --stdout
249
@itemx --to-stdout
250
@itemx -c
251
Write output on standard output; keep original files unchanged.
252
If there are several input files, the output consists of a sequence of
253
independently compressed members. To obtain better compression,
254
concatenate all input files before compressing them.
255
256
@item --decompress
257
@itemx --uncompress
258
@itemx -d
259
Decompress.
260
261
@item --force
262
@itemx -f
263
Force compression or decompression even if the file has multiple links
264
or the corresponding file already exists, or if the compressed data
265
is read from or written to a terminal. If the input data is not in
266
a format recognized by @command{gzip}, and if the option @option{--stdout} is also
267
given, copy the input data without change to the standard output: let
268
@command{zcat} behave as @command{cat}. If @option{-f} is not given, and
269
when not running in the background, @command{gzip} prompts to verify
270
whether an existing file should be overwritten.
271
272
@item --help
273
@itemx -h
274
Print an informative help message describing the options then quit.
275
276
@item --list
277
@itemx -l
278
For each compressed file, list the following fields:
279
280
@example
281
compressed size: size of the compressed file
282
uncompressed size: size of the uncompressed file
283
ratio: compression ratio (0.0% if unknown)
284
uncompressed_name: name of the uncompressed file
285
@end example
286
287
The uncompressed size is given as @minus{}1 for files not in @command{gzip}
288
format, such as compressed @samp{.Z} files. To get the uncompressed size for
289
such a file, you can use:
290
291
@example
292
zcat file.Z | wc -c
293
@end example
294
295
In combination with the @option{--verbose} option, the following fields are also
296
displayed:
297
298
@example
299
method: compression method (deflate,compress,lzh,pack)
300
crc: the 32-bit CRC of the uncompressed data
301
date & time: time stamp for the uncompressed file
302
@end example
303
304
The @abbr{CRC} is given as ffffffff for a file not in gzip format.
305
306
With @option{--verbose}, the size totals and compression ratio for all files
307
is also displayed, unless some sizes are unknown. With @option{--quiet},
308
the title and totals lines are not displayed.
309
310
The @command{gzip} format represents the input size modulo
311
@math{2^32}, so the uncompressed size and compression ratio are listed
312
incorrectly for uncompressed files 4 GiB and larger. To work around
313
this problem, you can use the following command to discover a large
314
uncompressed file's true size:
315
316
@example
317
zcat file.gz | wc -c
318
@end example
319
320
@item --license
321
@itemx -L
322
Display the @command{gzip} license then quit.
323
324
@item --no-name
325
@itemx -n
326
When compressing, do not save the original file name and time stamp by
327
default. (The original name is always saved if the name had to be
328
truncated.) When decompressing, do not restore the original file name
329
if present (remove only the @command{gzip}
330
suffix from the compressed file name) and do not restore the original
331
time stamp if present (copy it from the compressed file). This option
332
is the default when decompressing.
333
334
@item --name
335
@itemx -N
336
When compressing, always save the original file name and time stamp; this
337
is the default. When decompressing, restore the original file name and
338
time stamp if present. This option is useful on systems which have
339
a limit on file name length or when the time stamp has been lost after
340
a file transfer.
341
342
@item --quiet
343
@itemx -q
344
Suppress all warning messages.
345
346
@item --recursive
347
@itemx -r
348
Travel the directory structure recursively. If any of the file names
349
specified on the command line are directories, @command{gzip} will descend
350
into the directory and compress all the files it finds there (or
351
decompress them in the case of @command{gunzip}).
352
353
@item --suffix @var{suf}
354
@itemx -S @var{suf}
355
Use suffix @var{suf} instead of @samp{.gz}. Any suffix can be
356
given, but suffixes other than @samp{.z} and @samp{.gz} should be
357
avoided to avoid confusion when files are transferred to other systems.
358
A null suffix forces gunzip to try decompression on all given files
359
regardless of suffix, as in:
360
361
@example
362
gunzip -S "" * (*.* for MSDOS)
363
@end example
364
365
Previous versions of gzip used the @samp{.z} suffix. This was changed to
366
avoid a conflict with @command{pack}.
367
368
@item --test
369
@itemx -t
370
Test. Check the compressed file integrity.
371
372
@item --verbose
373
@itemx -v
374
Verbose. Display the name and percentage reduction for each file compressed.
375
376
@item --version
377
@itemx -V
378
Version. Display the version number and compilation options, then quit.
379
380
@item --fast
381
@itemx --best
382
@itemx -@var{n}
383
Regulate the speed of compression using the specified digit @var{n},
384
where @option{-1} or @option{--fast} indicates the fastest compression
385
method (less compression) and @option{--best} or @option{-9} indicates the
386
slowest compression method (optimal compression). The default
387
compression level is @option{-6} (that is, biased towards high compression at
388
expense of speed).
389
@end table
390
391
@node Advanced usage
392
@chapter Advanced usage
393
@cindex concatenated files
394
395
Multiple compressed files can be concatenated. In this case,
396
@command{gunzip} will extract all members at once. If one member is
397
damaged, other members might still be recovered after removal of the
398
damaged member. Better compression can be usually obtained if all
399
members are decompressed and then recompressed in a single step.
400
401
This is an example of concatenating @command{gzip} files:
402
403
@example
404
gzip -c file1 > foo.gz
405
gzip -c file2 >> foo.gz
406
@end example
407
408
@noindent
409
Then
410
411
@example
412
gunzip -c foo
413
@end example
414
415
@noindent
416
is equivalent to
417
418
@example
419
cat file1 file2
420
@end example
421
422
In case of damage to one member of a @samp{.gz} file, other members can
423
still be recovered (if the damaged member is removed). However,
424
you can get better compression by compressing all members at once:
425
426
@example
427
cat file1 file2 | gzip > foo.gz
428
@end example
429
430
@noindent
431
compresses better than
432
433
@example
434
gzip -c file1 file2 > foo.gz
435
@end example
436
437
If you want to recompress concatenated files to get better compression, do:
438
439
@example
440
zcat old.gz | gzip > new.gz
441
@end example
442
443
If a compressed file consists of several members, the uncompressed
444
size and @abbr{CRC} reported by the @option{--list} option applies to
445
the last member
446
only. If you need the uncompressed size for all members, you can use:
447
448
@example
449
zcat file.gz | wc -c
450
@end example
451
452
If you wish to create a single archive file with multiple members so
453
that members can later be extracted independently, use an archiver such
454
as @command{tar} or @command{zip}. @acronym{GNU} @command{tar}
455
supports the @option{-z}
456
option to invoke @command{gzip} transparently. @command{gzip} is designed as a
457
complement to @command{tar}, not as a replacement.
458
459
@node Environment
460
@chapter Environment
461
@cindex Environment
462
463
The environment variable @env{GZIP} can hold a set of default options for
464
@command{gzip}. These options are interpreted first and can be overwritten by
465
explicit command line parameters. For example:
466
467
@example
468
for sh: GZIP="-8v --name"; export GZIP
469
for csh: setenv GZIP "-8v --name"
470
for MSDOS: set GZIP=-8v --name
471
@end example
472
473
On @abbr{VMS}, the name of the environment variable is @env{GZIP_OPT}, to
474
avoid a conflict with the symbol set for invocation of the program.
475
476
@node Tapes
477
@chapter Using @command{gzip} on tapes
478
@cindex tapes
479
480
When writing compressed data to a tape, it is generally necessary to pad
481
the output with zeroes up to a block boundary. When the data is read and
482
the whole block is passed to @command{gunzip} for decompression,
483
@command{gunzip} detects that there is extra trailing garbage after the
484
compressed data and emits a warning by default if the garbage contains
485
nonzero bytes. You have to use the
486
@option{--quiet} option to suppress the warning. This option can be set in the
487
@env{GZIP} environment variable, as in:
488
489
@example
490
for sh: GZIP="-q" tar -xfz --block-compress /dev/rst0
491
for csh: (setenv GZIP "-q"; tar -xfz --block-compress /dev/rst0)
492
@end example
493
494
In the above example, @command{gzip} is invoked implicitly by the @option{-z}
495
option of @acronym{GNU} @command{tar}. Make sure that the same block
496
size (@option{-b}
497
option of @command{tar}) is used for reading and writing compressed data on
498
tapes. (This example assumes you are using the @acronym{GNU} version of
499
@command{tar}.)
500
501
@node Problems
502
@chapter Reporting Bugs
503
@cindex bugs
504
505
If you find a bug in @command{gzip}, please send electronic mail to
506
@email{bug-gzip@@gnu.org}. Include the version number,
507
which you can find by running @w{@samp{gzip -V}}. Also include in your
508
message the hardware and operating system, the compiler used to compile
509
@command{gzip},
510
a description of the bug behavior, and the input to @command{gzip}
511
that triggered
512
the bug.@refill
513
514
@node Copying This Manual
515
@appendix Copying This Manual
516
517
@menu
518
* GNU Free Documentation License:: License for copying this manual.
519
@end menu
520
521
@include fdl.texi
522
523
@node Concept Index
524
@appendix Concept Index
525
526
@printindex cp
527
528
@bye
Loggerhead is a web-based interface for Breezy
Version: 2.0.1