1IO::Compress::Gzip(3pm)Perl Programmers Reference GuideIO::Compress::Gzip(3pm)
2
6 IO::Compress::Gzip - Write RFC 1952 files/buffers
7
9 use IO::Compress::Gzip qw(gzip $GzipError) ;
10 my $status = gzip $input => $output [,OPTS]
12 or die "gzip failed: $GzipError\n";
13 my $z = new IO::Compress::Gzip $output [,OPTS]
15 or die "gzip failed: $GzipError\n";
16 $z->print($string);
18 $z->printf($format, $string);
19 $z->write($string);
20 $z->syswrite($string [, $length, $offset]);
21 $z->flush();
22 $z->tell();
23 $z->eof();
24 $z->seek($position, $whence);
25 $z->binmode();
26 $z->fileno();
27 $z->opened();
28 $z->autoflush();
29 $z->input_line_number();
30 $z->newStream( [OPTS] );
31 $z->deflateParams();
33 $z->close() ;
35 $GzipError ;
37 # IO::File mode
39 print $z $string;
41 printf $z $format, $string;
42 tell $z
43 eof $z
44 seek $z, $position, $whence
45 binmode $z
46 fileno $z
47 close $z ;
48
50 This module provides a Perl interface that allows writing compressed
51 data to files or buffer as defined in RFC 1952.
52 All the gzip headers defined in RFC 1952 can be created using this
54 module.
55 For reading RFC 1952 files/buffers, see the companion module
57 IO::Uncompress::Gunzip.
58
60 A top-level function, "gzip", is provided to carry out "one-shot"
61 compression between buffers and/or files. For finer control over the
62 compression process, see the "OO Interface" section.
63 use IO::Compress::Gzip qw(gzip $GzipError) ;
65 gzip $input => $output [,OPTS]
67 or die "gzip failed: $GzipError\n";
68 The functional interface needs Perl5.005 or better.
70 gzip $input => $output [, OPTS]
72 "gzip" expects at least two parameters, $input and $output.
73 The $input parameter
75 The parameter, $input, is used to define the source of the uncompressed
77 data.
78 It can take one of the following forms:
80 A filename
82 If the $input parameter is a simple scalar, it is assumed to be a
83 filename. This file will be opened for reading and the input data
84 will be read from it.
85 A filehandle
87 If the $input parameter is a filehandle, the input data will be
88 read from it. The string '-' can be used as an alias for standard
89 input.
90 A scalar reference
92 If $input is a scalar reference, the input data will be read from
93 $$input.
94 An array reference
96 If $input is an array reference, each element in the array must be
97 a filename.
98 The input data will be read from each file in turn.
100 The complete array will be walked to ensure that it only contains
102 valid filenames before any data is compressed.
103 An Input FileGlob string
105 If $input is a string that is delimited by the characters "<" and
106 ">" "gzip" will assume that it is an input fileglob string. The
107 input is the list of files that match the fileglob.
108 If the fileglob does not match any files ...
110 See File::GlobMapper for more details.
112 If the $input parameter is any other type, "undef" will be returned.
114 In addition, if $input is a simple filename, the default values for the
116 "Name" and "Time" options will be sourced from that file.
117 If you do not want to use these defaults they can be overridden by
119 explicitly setting the "Name" and "Time" options or by setting the
120 "Minimal" parameter.
121 The $output parameter
123 The parameter $output is used to control the destination of the
125 compressed data. This parameter can take one of these forms.
126 A filename
128 If the $output parameter is a simple scalar, it is assumed to be a
129 filename. This file will be opened for writing and the compressed
130 data will be written to it.
131 A filehandle
133 If the $output parameter is a filehandle, the compressed data will
134 be written to it. The string '-' can be used as an alias for
135 standard output.
136 A scalar reference
138 If $output is a scalar reference, the compressed data will be
139 stored in $$output.
140 An Array Reference
142 If $output is an array reference, the compressed data will be
143 pushed onto the array.
144 An Output FileGlob
146 If $output is a string that is delimited by the characters "<" and
147 ">" "gzip" will assume that it is an output fileglob string. The
148 output is the list of files that match the fileglob.
149 When $output is an fileglob string, $input must also be a fileglob
151 string. Anything else is an error.
152 If the $output parameter is any other type, "undef" will be returned.
154 Notes
156 When $input maps to multiple files/buffers and $output is a single
157 file/buffer the input files/buffers will be stored in $output as a
158 concatenated series of compressed data streams.
159 Optional Parameters
161 Unless specified below, the optional parameters for "gzip", "OPTS", are
162 the same as those used with the OO interface defined in the
163 "Constructor Options" section below.
164 "AutoClose => 0|1"
166 This option applies to any input or output data streams to "gzip"
167 that are filehandles.
168 If "AutoClose" is specified, and the value is true, it will result
170 in all input and/or output filehandles being closed once "gzip"
171 has completed.
172 This parameter defaults to 0.
174 "BinModeIn => 0|1"
176 When reading from a file or filehandle, set "binmode" before
177 reading.
178 Defaults to 0.
180 "Append => 0|1"
182 TODO
183 Examples
185 To read the contents of the file "file1.txt" and write the compressed
186 data to the file "file1.txt.gz".
187 use strict ;
189 use warnings ;
190 use IO::Compress::Gzip qw(gzip $GzipError) ;
191 my $input = "file1.txt";
193 gzip $input => "$input.gz"
194 or die "gzip failed: $GzipError\n";
195 To read from an existing Perl filehandle, $input, and write the
197 compressed data to a buffer, $buffer.
198 use strict ;
200 use warnings ;
201 use IO::Compress::Gzip qw(gzip $GzipError) ;
202 use IO::File ;
203 my $input = new IO::File "<file1.txt"
205 or die "Cannot open 'file1.txt': $!\n" ;
206 my $buffer ;
207 gzip $input => \$buffer
208 or die "gzip failed: $GzipError\n";
209 To compress all files in the directory "/my/home" that match "*.txt"
211 and store the compressed data in the same directory
212 use strict ;
214 use warnings ;
215 use IO::Compress::Gzip qw(gzip $GzipError) ;
216 gzip '</my/home/*.txt>' => '<*.gz>'
218 or die "gzip failed: $GzipError\n";
219 and if you want to compress each file one at a time, this will do the
221 trick
222 use strict ;
224 use warnings ;
225 use IO::Compress::Gzip qw(gzip $GzipError) ;
226 for my $input ( glob "/my/home/*.txt" )
228 {
229 my $output = "$input.gz" ;
230 gzip $input => $output
231 or die "Error compressing '$input': $GzipError\n";
232 }
233
235 Constructor
236 The format of the constructor for "IO::Compress::Gzip" is shown below
237 my $z = new IO::Compress::Gzip $output [,OPTS]
239 or die "IO::Compress::Gzip failed: $GzipError\n";
240 It returns an "IO::Compress::Gzip" object on success and undef on
242 failure. The variable $GzipError will contain an error message on
243 failure.
244 If you are running Perl 5.005 or better the object, $z, returned from
246 IO::Compress::Gzip can be used exactly like an IO::File filehandle.
247 This means that all normal output file operations can be carried out
248 with $z. For example, to write to a compressed file/buffer you can use
249 either of these forms
250 $z->print("hello world\n");
252 print $z "hello world\n";
253 The mandatory parameter $output is used to control the destination of
255 the compressed data. This parameter can take one of these forms.
256 A filename
258 If the $output parameter is a simple scalar, it is assumed to be a
259 filename. This file will be opened for writing and the compressed
260 data will be written to it.
261 A filehandle
263 If the $output parameter is a filehandle, the compressed data will
264 be written to it. The string '-' can be used as an alias for
265 standard output.
266 A scalar reference
268 If $output is a scalar reference, the compressed data will be
269 stored in $$output.
270 If the $output parameter is any other type, "IO::Compress::Gzip"::new
272 will return undef.
273 Constructor Options
275 "OPTS" is any combination of the following options:
276 "AutoClose => 0|1"
278 This option is only valid when the $output parameter is a
279 filehandle. If specified, and the value is true, it will result in
280 the $output being closed once either the "close" method is called
281 or the "IO::Compress::Gzip" object is destroyed.
282 This parameter defaults to 0.
284 "Append => 0|1"
286 Opens $output in append mode.
287 The behaviour of this option is dependent on the type of $output.
289 · A Buffer
291 If $output is a buffer and "Append" is enabled, all
293 compressed data will be append to the end if $output.
294 Otherwise $output will be cleared before any data is written
295 to it.
296 · A Filename
298 If $output is a filename and "Append" is enabled, the file
300 will be opened in append mode. Otherwise the contents of the
301 file, if any, will be truncated before any compressed data is
302 written to it.
303 · A Filehandle
305 If $output is a filehandle, the file pointer will be
307 positioned to the end of the file via a call to "seek" before
308 any compressed data is written to it. Otherwise the file
309 pointer will not be moved.
310 This parameter defaults to 0.
312 "Merge => 0|1"
314 This option is used to compress input data and append it to an
315 existing compressed data stream in $output. The end result is a
316 single compressed data stream stored in $output.
317 It is a fatal error to attempt to use this option when $output is
319 not an RFC 1952 data stream.
320 There are a number of other limitations with the "Merge" option:
322 1. This module needs to have been built with zlib 1.2.1 or
324 better to work. A fatal error will be thrown if "Merge" is
325 used with an older version of zlib.
326 2. If $output is a file or a filehandle, it must be seekable.
328 This parameter defaults to 0.
330 -Level
332 Defines the compression level used by zlib. The value should
333 either be a number between 0 and 9 (0 means no compression and 9
334 is maximum compression), or one of the symbolic constants defined
335 below.
336 Z_NO_COMPRESSION
338 Z_BEST_SPEED
339 Z_BEST_COMPRESSION
340 Z_DEFAULT_COMPRESSION
341 The default is Z_DEFAULT_COMPRESSION.
343 Note, these constants are not imported by "IO::Compress::Gzip" by
345 default.
346 use IO::Compress::Gzip qw(:strategy);
348 use IO::Compress::Gzip qw(:constants);
349 use IO::Compress::Gzip qw(:all);
350 -Strategy
352 Defines the strategy used to tune the compression. Use one of the
353 symbolic constants defined below.
354 Z_FILTERED
356 Z_HUFFMAN_ONLY
357 Z_RLE
358 Z_FIXED
359 Z_DEFAULT_STRATEGY
360 The default is Z_DEFAULT_STRATEGY.
362 "Minimal => 0|1"
364 If specified, this option will force the creation of the smallest
365 possible compliant gzip header (which is exactly 10 bytes long) as
366 defined in RFC 1952.
367 See the section titled "Compliance" in RFC 1952 for a definition
369 of the values used for the fields in the gzip header.
370 All other parameters that control the content of the gzip header
372 will be ignored if this parameter is set to 1.
373 This parameter defaults to 0.
375 "Comment => $comment"
377 Stores the contents of $comment in the COMMENT field in the gzip
378 header. By default, no comment field is written to the gzip file.
379 If the "-Strict" option is enabled, the comment can only consist
381 of ISO 8859-1 characters plus line feed.
382 If the "-Strict" option is disabled, the comment field can contain
384 any character except NULL. If any null characters are present, the
385 field will be truncated at the first NULL.
386 "Name => $string"
388 Stores the contents of $string in the gzip NAME header field. If
389 "Name" is not specified, no gzip NAME field will be created.
390 If the "-Strict" option is enabled, $string can only consist of
392 ISO 8859-1 characters.
393 If "-Strict" is disabled, then $string can contain any character
395 except NULL. If any null characters are present, the field will be
396 truncated at the first NULL.
397 "Time => $number"
399 Sets the MTIME field in the gzip header to $number.
400 This field defaults to the time the "IO::Compress::Gzip" object
402 was created if this option is not specified.
403 "TextFlag => 0|1"
405 This parameter controls the setting of the FLG.FTEXT bit in the
406 gzip header. It is used to signal that the data stored in the gzip
407 file/buffer is probably text.
408 The default is 0.
410 "HeaderCRC => 0|1"
412 When true this parameter will set the FLG.FHCRC bit to 1 in the
413 gzip header and set the CRC16 header field to the CRC of the
414 complete gzip header except the CRC16 field itself.
415 Note that gzip files created with the "HeaderCRC" flag set to 1
417 cannot be read by most, if not all, of the the standard gunzip
418 utilities, most notably gzip version 1.2.4. You should therefore
419 avoid using this option if you want to maximize the portability of
420 your gzip files.
421 This parameter defaults to 0.
423 "OS_Code => $value"
425 Stores $value in the gzip OS header field. A number between 0 and
426 255 is valid.
427 If not specified, this parameter defaults to the OS code of the
429 Operating System this module was built on. The value 3 is used as
430 a catch-all for all Unix variants and unknown Operating Systems.
431 "ExtraField => $data"
433 This parameter allows additional metadata to be stored in the
434 ExtraField in the gzip header. An RFC 1952 compliant ExtraField
435 consists of zero or more subfields. Each subfield consists of a
436 two byte header followed by the subfield data.
437 The list of subfields can be supplied in any of the following
439 formats
440 -ExtraField => [$id1, $data1,
442 $id2, $data2,
443 ...
444 ]
445 -ExtraField => [ [$id1 => $data1],
446 [$id2 => $data2],
447 ...
448 ]
449 -ExtraField => { $id1 => $data1,
450 $id2 => $data2,
451 ...
452 }
453 Where $id1, $id2 are two byte subfield ID's. The second byte of
455 the ID cannot be 0, unless the "Strict" option has been disabled.
456 If you use the hash syntax, you have no control over the order in
458 which the ExtraSubFields are stored, plus you cannot have
459 SubFields with duplicate ID.
460 Alternatively the list of subfields can by supplied as a scalar,
462 thus
463 -ExtraField => $rawdata
465 If you use the raw format, and the "Strict" option is enabled,
467 "IO::Compress::Gzip" will check that $rawdata consists of zero or
468 more conformant sub-fields. When "Strict" is disabled, $rawdata
469 can consist of any arbitrary byte stream.
470 The maximum size of the Extra Field 65535 bytes.
472 "ExtraFlags => $value"
474 Sets the XFL byte in the gzip header to $value.
475 If this option is not present, the value stored in XFL field will
477 be determined by the setting of the "Level" option.
478 If "Level => Z_BEST_SPEED" has been specified then XFL is set to
480 2. If "Level => Z_BEST_COMPRESSION" has been specified then XFL
481 is set to 4. Otherwise XFL is set to 0.
482 "Strict => 0|1"
484 "Strict" will optionally police the values supplied with other
485 options to ensure they are compliant with RFC1952.
486 This option is enabled by default.
488 If "Strict" is enabled the following behaviour will be policed:
490 · The value supplied with the "Name" option can only contain
492 ISO 8859-1 characters.
493 · The value supplied with the "Comment" option can only contain
495 ISO 8859-1 characters plus line-feed.
496 · The values supplied with the "-Name" and "-Comment" options
498 cannot contain multiple embedded nulls.
499 · If an "ExtraField" option is specified and it is a simple
501 scalar, it must conform to the sub-field structure as defined
502 in RFC 1952.
503 · If an "ExtraField" option is specified the second byte of the
505 ID will be checked in each subfield to ensure that it does
506 not contain the reserved value 0x00.
507 When "Strict" is disabled the following behaviour will be policed:
509 · The value supplied with "-Name" option can contain any
511 character except NULL.
512 · The value supplied with "-Comment" option can contain any
514 character except NULL.
515 · The values supplied with the "-Name" and "-Comment" options
517 can contain multiple embedded nulls. The string written to
518 the gzip header will consist of the characters up to, but not
519 including, the first embedded NULL.
520 · If an "ExtraField" option is specified and it is a simple
522 scalar, the structure will not be checked. The only error is
523 if the length is too big.
524 · The ID header in an "ExtraField" sub-field can consist of any
526 two bytes.
527 Examples
529 TODO
530
532 print
533 Usage is
534 $z->print($data)
536 print $z $data
537 Compresses and outputs the contents of the $data parameter. This has
539 the same behaviour as the "print" built-in.
540 Returns true if successful.
542 printf
544 Usage is
545 $z->printf($format, $data)
547 printf $z $format, $data
548 Compresses and outputs the contents of the $data parameter.
550 Returns true if successful.
552 syswrite
554 Usage is
555 $z->syswrite $data
557 $z->syswrite $data, $length
558 $z->syswrite $data, $length, $offset
559 Compresses and outputs the contents of the $data parameter.
561 Returns the number of uncompressed bytes written, or "undef" if
563 unsuccessful.
564 write
566 Usage is
567 $z->write $data
569 $z->write $data, $length
570 $z->write $data, $length, $offset
571 Compresses and outputs the contents of the $data parameter.
573 Returns the number of uncompressed bytes written, or "undef" if
575 unsuccessful.
576 flush
578 Usage is
579 $z->flush;
581 $z->flush($flush_type);
582 Flushes any pending compressed data to the output file/buffer.
584 This method takes an optional parameter, $flush_type, that controls how
586 the flushing will be carried out. By default the $flush_type used is
587 "Z_FINISH". Other valid values for $flush_type are "Z_NO_FLUSH",
588 "Z_SYNC_FLUSH", "Z_FULL_FLUSH" and "Z_BLOCK". It is strongly
589 recommended that you only set the "flush_type" parameter if you fully
590 understand the implications of what it does - overuse of "flush" can
591 seriously degrade the level of compression achieved. See the "zlib"
592 documentation for details.
593 Returns true on success.
595 tell
597 Usage is
598 $z->tell()
600 tell $z
601 Returns the uncompressed file offset.
603 eof
605 Usage is
606 $z->eof();
608 eof($z);
609 Returns true if the "close" method has been called.
611 seek
613 $z->seek($position, $whence);
614 seek($z, $position, $whence);
615 Provides a sub-set of the "seek" functionality, with the restriction
617 that it is only legal to seek forward in the output file/buffer. It is
618 a fatal error to attempt to seek backward.
619 Empty parts of the file/buffer will have NULL (0x00) bytes written to
621 them.
622 The $whence parameter takes one the usual values, namely SEEK_SET,
624 SEEK_CUR or SEEK_END.
625 Returns 1 on success, 0 on failure.
627 binmode
629 Usage is
630 $z->binmode
632 binmode $z ;
633 This is a noop provided for completeness.
635 opened
637 $z->opened()
638 Returns true if the object currently refers to a opened file/buffer.
640 autoflush
642 my $prev = $z->autoflush()
643 my $prev = $z->autoflush(EXPR)
644 If the $z object is associated with a file or a filehandle, this method
646 returns the current autoflush setting for the underlying filehandle. If
647 "EXPR" is present, and is non-zero, it will enable flushing after every
648 write/print operation.
649 If $z is associated with a buffer, this method has no effect and always
651 returns "undef".
652 Note that the special variable $| cannot be used to set or retrieve the
654 autoflush setting.
655 input_line_number
657 $z->input_line_number()
658 $z->input_line_number(EXPR)
659 This method always returns "undef" when compressing.
661 fileno
663 $z->fileno()
664 fileno($z)
665 If the $z object is associated with a file or a filehandle, "fileno"
667 will return the underlying file descriptor. Once the "close" method is
668 called "fileno" will return "undef".
669 If the $z object is is associated with a buffer, this method will
671 return "undef".
672 close
674 $z->close() ;
675 close $z ;
676 Flushes any pending compressed data and then closes the output
678 file/buffer.
679 For most versions of Perl this method will be automatically invoked if
681 the IO::Compress::Gzip object is destroyed (either explicitly or by the
682 variable with the reference to the object going out of scope). The
683 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
684 cases, the "close" method will be called automatically, but not until
685 global destruction of all live objects when the program is terminating.
686 Therefore, if you want your scripts to be able to run on all versions
688 of Perl, you should call "close" explicitly and not rely on automatic
689 closing.
690 Returns true on success, otherwise 0.
692 If the "AutoClose" option has been enabled when the IO::Compress::Gzip
694 object was created, and the object is associated with a file, the
695 underlying file will also be closed.
696 newStream([OPTS])
698 Usage is
699 $z->newStream( [OPTS] )
701 Closes the current compressed data stream and starts a new one.
703 OPTS consists of any of the the options that are available when
705 creating the $z object.
706 See the "Constructor Options" section for more details.
708 deflateParams
710 Usage is
711 $z->deflateParams
713 TODO
715
717 A number of symbolic constants are required by some methods in
718 "IO::Compress::Gzip". None are imported by default.
719 :all Imports "gzip", $GzipError and all symbolic constants that can be
721 used by "IO::Compress::Gzip". Same as doing this
722 use IO::Compress::Gzip qw(gzip $GzipError :constants) ;
724 :constants
726 Import all symbolic constants. Same as doing this
727 use IO::Compress::Gzip qw(:flush :level :strategy) ;
729 :flush
731 These symbolic constants are used by the "flush" method.
732 Z_NO_FLUSH
734 Z_PARTIAL_FLUSH
735 Z_SYNC_FLUSH
736 Z_FULL_FLUSH
737 Z_FINISH
738 Z_BLOCK
739 :level
741 These symbolic constants are used by the "Level" option in the
742 constructor.
743 Z_NO_COMPRESSION
745 Z_BEST_SPEED
746 Z_BEST_COMPRESSION
747 Z_DEFAULT_COMPRESSION
748 :strategy
750 These symbolic constants are used by the "Strategy" option in the
751 constructor.
752 Z_FILTERED
754 Z_HUFFMAN_ONLY
755 Z_RLE
756 Z_FIXED
757 Z_DEFAULT_STRATEGY
758
760 Apache::GZip Revisited
761 See IO::Compress::FAQ
762 Working with Net::FTP
764 See IO::Compress::FAQ
765
767 Compress::Zlib, IO::Uncompress::Gunzip, IO::Compress::Deflate,
768 IO::Uncompress::Inflate, IO::Compress::RawDeflate,
769 IO::Uncompress::RawInflate, IO::Compress::Bzip2,
770 IO::Uncompress::Bunzip2, IO::Compress::Lzop, IO::Uncompress::UnLzop,
771 IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Uncompress::AnyInflate,
772 IO::Uncompress::AnyUncompress
773 Compress::Zlib::FAQ
775 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
777 For RFC 1950, 1951 and 1952 see http://www.faqs.org/rfcs/rfc1950.html,
779 http://www.faqs.org/rfcs/rfc1951.html and
780 http://www.faqs.org/rfcs/rfc1952.html
781 The zlib compression library was written by Jean-loup Gailly
783 gzip@prep.ai.mit.edu and Mark Adler madler@alumni.caltech.edu.
784 The primary site for the zlib compression library is
786 http://www.zlib.org.
787 The primary site for gzip is http://www.gzip.org.
789
791 This module was written by Paul Marquess, pmqs@cpan.org.
792
794 See the Changes file.
795
797 Copyright (c) 2005-2009 Paul Marquess. All rights reserved.
798 This program is free software; you can redistribute it and/or modify it
800 under the same terms as Perl itself.
801perl v5.10.1 2017-03-22 IO::Compress::Gzip(3pm)