maint: update existing copyright year lists to include 2009
[debian/gzip] / 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, 2009 Free Software
15 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 * GNU Free Documentation License:: Copying and sharing 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 @samp{-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}
117 @samp{-gz}, @samp{-z}, or @samp{_z} (ignoring case)
118 and which begins with the correct
119 magic number with an uncompressed file without the original extension.
120 @command{gunzip} also recognizes the special extensions @samp{.tgz} and
121 @samp{.taz} as shorthands for @samp{.tar.gz} and @samp{.tar.Z}
122 respectively.  When compressing, @command{gzip} uses the @samp{.tgz}
123 extension if necessary instead of truncating a file with a @samp{.tar}
124 extension.
125
126 @command{gunzip} can currently decompress files created by @command{gzip},
127 @command{zip}, @command{compress} or @command{pack}.  The detection of the input
128 format is automatic.  When using the first two formats, @command{gunzip}
129 checks a 32 bit @abbr{CRC} (cyclic redundancy check).  For @command{pack},
130 @command{gunzip} checks the uncompressed length.  The @command{compress} format
131 was not designed to allow consistency checks.  However @command{gunzip} is
132 sometimes able to detect a bad @samp{.Z} file.  If you get an error when
133 uncompressing a @samp{.Z} file, do not assume that the @samp{.Z} file is
134 correct simply because the standard @command{uncompress} does not complain.
135 This generally means that the standard @command{uncompress} does not check
136 its input, and happily generates garbage output.  The @abbr{SCO} @samp{compress
137 -H} format (@abbr{LZH} compression method) does not include a @abbr{CRC} but
138 also allows some consistency checks.
139
140 Files created by @command{zip} can be uncompressed by @command{gzip} only if
141 they have a single member compressed with the 'deflation' method.  This
142 feature is only intended to help conversion of @file{tar.zip} files to
143 the @file{tar.gz} format.  To extract a @command{zip} file with a single
144 member, use a command like @samp{gunzip <foo.zip} or @samp{gunzip -S
145 .zip foo.zip}.  To extract @command{zip} files with several
146 members, use @command{unzip} instead of @command{gunzip}.
147
148 @command{zcat} is identical to @samp{gunzip -c}.  @command{zcat}
149 uncompresses either a list of files on the command line or its standard
150 input and writes the uncompressed data on standard output.  @command{zcat}
151 will uncompress files that have the correct magic number whether they
152 have a @samp{.gz} suffix or not.
153
154 @command{gzip} uses the Lempel-Ziv algorithm used in @command{zip} and
155 @abbr{PKZIP}@.
156 The amount of compression obtained depends on the size of the input and
157 the distribution of common substrings.  Typically, text such as source
158 code or English is reduced by 60-70%.  Compression is generally much
159 better than that achieved by @abbr{LZW} (as used in @command{compress}), Huffman
160 coding (as used in @command{pack}), or adaptive Huffman coding
161 (@command{compact}).
162
163 Compression is always performed, even if the compressed file is slightly
164 larger than the original.  The worst case expansion is a few bytes for
165 the @command{gzip} file header, plus 5 bytes every 32K block, or an expansion
166 ratio of 0.015% for large files.  Note that the actual number of used
167 disk blocks almost never increases.  @command{gzip} normally preserves the mode,
168 ownership and time stamps of files when compressing or decompressing.
169
170 The @command{gzip} file format is specified in P. Deutsch, @sc{gzip} file
171 format specification version 4.3,
172 @uref{ftp://ftp.isi.edu/in-notes/rfc1952.txt, Internet @abbr{RFC} 1952} (May
173 1996).  The @command{zip} deflation format is specified in P. Deutsch,
174 @sc{deflate} Compressed Data Format Specification version 1.3,
175 @uref{ftp://ftp.isi.edu/in-notes/rfc1951.txt, Internet @abbr{RFC} 1951} (May
176 1996).
177
178 @node Sample
179 @chapter Sample Output
180 @cindex sample
181
182 Here are some realistic examples of running @command{gzip}.
183
184 This is the output of the command @samp{gzip -h}:
185
186 @example
187 Usage: gzip [OPTION]... [FILE]...
188 Compress or uncompress FILEs (by default, compress FILES in-place).
189
190 Mandatory arguments to long options are mandatory for short options too.
191
192   -c, --stdout      write on standard output, keep original files unchanged
193   -d, --decompress  decompress
194   -f, --force       force overwrite of output file and compress links
195   -h, --help        give this help
196   -l, --list        list compressed file contents
197   -L, --license     display software license
198   -n, --no-name     do not save or restore the original name and time stamp
199   -N, --name        save or restore the original name and time stamp
200   -q, --quiet       suppress all warnings
201   -r, --recursive   operate recursively on directories
202   -S, --suffix=SUF  use suffix SUF on compressed files
203   -t, --test        test compressed file integrity
204   -v, --verbose     verbose mode
205   -V, --version     display version number
206   -1, --fast        compress faster
207   -9, --best        compress better
208
209 With no FILE, or when FILE is -, read standard input.
210
211 Report bugs to <bug-gzip@@gnu.org>.
212 @end example
213
214 This is the output of the command @samp{gzip -v texinfo.tex}:
215
216 @example
217 texinfo.tex:     69.3% -- replaced with texinfo.tex.gz
218 @end example
219
220 The following command will find all regular @samp{.gz} files in the
221 current directory and subdirectories (skipping file names that contain
222 newlines), and extract them in place without destroying the original,
223 stopping on the first failure:
224
225 @example
226 find . -name '*
227 *' -prune -o -name '*.gz' -type f -print |
228   sed "
229     s/'/'\\''/g
230     s/^\\(.*\\)\\.gz$/gunzip <'\\1.gz' >'\\1'/
231   " |
232   sh -e
233 @end example
234
235 @node Invoking gzip
236 @chapter Invoking @command{gzip}
237 @cindex invoking
238 @cindex options
239
240 The format for running the @command{gzip} program is:
241
242 @example
243 gzip @var{option} @dots{}
244 @end example
245
246 @command{gzip} supports the following options:
247
248 @table @option
249 @item --stdout
250 @itemx --to-stdout
251 @itemx -c
252 Write output on standard output; keep original files unchanged.
253 If there are several input files, the output consists of a sequence of
254 independently compressed members.  To obtain better compression,
255 concatenate all input files before compressing them.
256
257 @item --decompress
258 @itemx --uncompress
259 @itemx -d
260 Decompress.
261
262 @item --force
263 @itemx -f
264 Force compression or decompression even if the file has multiple links
265 or the corresponding file already exists, or if the compressed data
266 is read from or written to a terminal.  If the input data is not in
267 a format recognized by @command{gzip}, and if the option @option{--stdout} is also
268 given, copy the input data without change to the standard output: let
269 @command{zcat} behave as @command{cat}.  If @option{-f} is not given, and
270 when not running in the background, @command{gzip} prompts to verify
271 whether an existing file should be overwritten.
272
273 @item --help
274 @itemx -h
275 Print an informative help message describing the options then quit.
276
277 @item --list
278 @itemx -l
279 For each compressed file, list the following fields:
280
281 @example
282 compressed size: size of the compressed file
283 uncompressed size: size of the uncompressed file
284 ratio: compression ratio (0.0% if unknown)
285 uncompressed_name: name of the uncompressed file
286 @end example
287
288 The uncompressed size is given as @minus{}1 for files not in @command{gzip}
289 format, such as compressed @samp{.Z} files.  To get the uncompressed size for
290 such a file, you can use:
291
292 @example
293 zcat file.Z | wc -c
294 @end example
295
296 In combination with the @option{--verbose} option, the following fields are also
297 displayed:
298
299 @example
300 method: compression method (deflate,compress,lzh,pack)
301 crc: the 32-bit CRC of the uncompressed data
302 date & time: time stamp for the uncompressed file
303 @end example
304
305 The @abbr{CRC} is given as ffffffff for a file not in gzip format.
306
307 With @option{--verbose}, the size totals and compression ratio for all files
308 is also displayed, unless some sizes are unknown.  With @option{--quiet},
309 the title and totals lines are not displayed.
310
311 The @command{gzip} format represents the input size modulo
312 @math{2^32}, so the uncompressed size and compression ratio are listed
313 incorrectly for uncompressed files 4 GiB and larger.  To work around
314 this problem, you can use the following command to discover a large
315 uncompressed file's true size:
316
317 @example
318 zcat file.gz | wc -c
319 @end example
320
321 @item --license
322 @itemx -L
323 Display the @command{gzip} license then quit.
324
325 @item --no-name
326 @itemx -n
327 When compressing, do not save the original file name and time stamp by
328 default.  (The original name is always saved if the name had to be
329 truncated.)  When decompressing, do not restore the original file name
330 if present (remove only the @command{gzip}
331 suffix from the compressed file name) and do not restore the original
332 time stamp if present (copy it from the compressed file).  This option
333 is the default when decompressing.
334
335 @item --name
336 @itemx -N
337 When compressing, always save the original file name and time stamp; this
338 is the default.  When decompressing, restore the original file name and
339 time stamp if present.  This option is useful on systems which have
340 a limit on file name length or when the time stamp has been lost after
341 a file transfer.
342
343 @item --quiet
344 @itemx -q
345 Suppress all warning messages.
346
347 @item --recursive
348 @itemx -r
349 Travel the directory structure recursively.  If any of the file names
350 specified on the command line are directories, @command{gzip} will descend
351 into the directory and compress all the files it finds there (or
352 decompress them in the case of @command{gunzip}).
353
354 @item --suffix @var{suf}
355 @itemx -S @var{suf}
356 Use suffix @var{suf} instead of @samp{.gz}.  Any suffix can be
357 given, but suffixes other than @samp{.z} and @samp{.gz} should be
358 avoided to avoid confusion when files are transferred to other systems.
359 A null suffix forces gunzip to try decompression on all given files
360 regardless of suffix, as in:
361
362 @example
363 gunzip -S "" *        (*.* for MSDOS)
364 @end example
365
366 Previous versions of gzip used the @samp{.z} suffix.  This was changed to
367 avoid a conflict with @command{pack}.
368
369 @item --test
370 @itemx -t
371 Test.  Check the compressed file integrity.
372
373 @item --verbose
374 @itemx -v
375 Verbose.  Display the name and percentage reduction for each file compressed.
376
377 @item --version
378 @itemx -V
379 Version.  Display the version number and compilation options, then quit.
380
381 @item --fast
382 @itemx --best
383 @itemx -@var{n}
384 Regulate the speed of compression using the specified digit @var{n},
385 where @option{-1} or @option{--fast} indicates the fastest compression
386 method (less compression) and @option{--best} or @option{-9} indicates the
387 slowest compression method (optimal compression).  The default
388 compression level is @option{-6} (that is, biased towards high compression at
389 expense of speed).
390 @end table
391
392 @node Advanced usage
393 @chapter Advanced usage
394 @cindex concatenated files
395
396 Multiple compressed files can be concatenated.  In this case,
397 @command{gunzip} will extract all members at once.  If one member is
398 damaged, other members might still be recovered after removal of the
399 damaged member.  Better compression can be usually obtained if all
400 members are decompressed and then recompressed in a single step.
401
402 This is an example of concatenating @command{gzip} files:
403
404 @example
405 gzip -c file1  > foo.gz
406 gzip -c file2 >> foo.gz
407 @end example
408
409 @noindent
410 Then
411
412 @example
413 gunzip -c foo
414 @end example
415
416 @noindent
417 is equivalent to
418
419 @example
420 cat file1 file2
421 @end example
422
423 In case of damage to one member of a @samp{.gz} file, other members can
424 still be recovered (if the damaged member is removed).  However,
425 you can get better compression by compressing all members at once:
426
427 @example
428 cat file1 file2 | gzip > foo.gz
429 @end example
430
431 @noindent
432 compresses better than
433
434 @example
435 gzip -c file1 file2 > foo.gz
436 @end example
437
438 If you want to recompress concatenated files to get better compression, do:
439
440 @example
441 zcat old.gz | gzip > new.gz
442 @end example
443
444 If a compressed file consists of several members, the uncompressed
445 size and @abbr{CRC} reported by the @option{--list} option applies to
446 the last member
447 only.  If you need the uncompressed size for all members, you can use:
448
449 @example
450 zcat file.gz | wc -c
451 @end example
452
453 If you wish to create a single archive file with multiple members so
454 that members can later be extracted independently, use an archiver such
455 as @command{tar} or @command{zip}.  @acronym{GNU} @command{tar}
456 supports the @option{-z}
457 option to invoke @command{gzip} transparently.  @command{gzip} is designed as a
458 complement to @command{tar}, not as a replacement.
459
460 @node Environment
461 @chapter Environment
462 @cindex Environment
463
464 The environment variable @env{GZIP} can hold a set of default options for
465 @command{gzip}.  These options are interpreted first and can be overwritten by
466 explicit command line parameters.  For example:
467
468 @example
469 for sh:    GZIP="-8v --name"; export GZIP
470 for csh:   setenv GZIP "-8v --name"
471 for MSDOS: set GZIP=-8v --name
472 @end example
473
474 On @abbr{VMS}, the name of the environment variable is @env{GZIP_OPT}, to
475 avoid a conflict with the symbol set for invocation of the program.
476
477 @node Tapes
478 @chapter Using @command{gzip} on tapes
479 @cindex tapes
480
481 When writing compressed data to a tape, it is generally necessary to pad
482 the output with zeroes up to a block boundary.  When the data is read and
483 the whole block is passed to @command{gunzip} for decompression,
484 @command{gunzip} detects that there is extra trailing garbage after the
485 compressed data and emits a warning by default if the garbage contains
486 nonzero bytes.  You have to use the
487 @option{--quiet} option to suppress the warning.  This option can be set in the
488 @env{GZIP} environment variable, as in:
489
490 @example
491 for sh:    GZIP="-q"  tar -xfz --block-compress /dev/rst0
492 for csh:   (setenv GZIP "-q"; tar -xfz --block-compress /dev/rst0)
493 @end example
494
495 In the above example, @command{gzip} is invoked implicitly by the @option{-z}
496 option of @acronym{GNU} @command{tar}.  Make sure that the same block
497 size (@option{-b}
498 option of @command{tar}) is used for reading and writing compressed data on
499 tapes.  (This example assumes you are using the @acronym{GNU} version of
500 @command{tar}.)
501
502 @node Problems
503 @chapter Reporting Bugs
504 @cindex bugs
505
506 If you find a bug in @command{gzip}, please send electronic mail to
507 @email{bug-gzip@@gnu.org}.  Include the version number,
508 which you can find by running @w{@samp{gzip -V}}.  Also include in your
509 message the hardware and operating system, the compiler used to compile
510 @command{gzip},
511 a description of the bug behavior, and the input to @command{gzip}
512 that triggered
513 the bug.@refill
514
515 @node GNU Free Documentation License
516 @appendix GNU Free Documentation License
517
518 @include fdl.texi
519
520 @node Concept Index
521 @appendix Concept Index
522
523 @printindex cp
524
525 @bye