2 package IO::Compress::Gzip ;
10 use IO::Compress::RawDeflate;
12 use Compress::Zlib 2 ;
13 use Compress::Zlib::Common qw(:Status createSelfTiedObject);
14 use Compress::Gzip::Constants;
18 if (defined &utf8::downgrade )
19 { *noUTF8 = \&utf8::downgrade }
26 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $GzipError);
28 $VERSION = '2.000_07';
31 @ISA = qw(Exporter IO::Compress::RawDeflate);
32 @EXPORT_OK = qw( $GzipError gzip ) ;
33 %EXPORT_TAGS = %IO::Compress::RawDeflate::DEFLATE_CONSTANTS ;
34 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
35 Exporter::export_ok_tags('all');
41 my $obj = createSelfTiedObject($class, \$GzipError);
43 $obj->_create(undef, @_);
49 my $obj = createSelfTiedObject(undef, \$GzipError);
50 return $obj->_def(@_);
56 # #return GZIP_MINIMUM_HEADER ;
57 # return $self->mkHeader(*$self->{Got});
64 use Compress::Zlib::ParseParameters;
68 $self->getZlibParams(),
71 'Minimal' => [0, 1, Parse_boolean, 0],
72 'Comment' => [0, 1, Parse_any, undef],
73 'Name' => [0, 1, Parse_any, undef],
74 'Time' => [0, 1, Parse_any, undef],
75 'TextFlag' => [0, 1, Parse_boolean, 0],
76 'HeaderCRC' => [0, 1, Parse_boolean, 0],
77 'OS_Code' => [0, 1, Parse_unsigned, $Compress::Zlib::gzip_os_code],
78 'ExtraField'=> [0, 1, Parse_string, undef],
79 'ExtraFlags'=> [0, 1, Parse_any, undef],
90 # gzip always needs crc32
91 $got->value('CRC32' => 1);
94 if $got->value('Merge') ;
96 my $lax = ! $got->value('Strict') ;
100 if (! $got->parsed('Time') ) {
101 # Modification time defaults to now.
102 $got->value('Time' => time) ;
105 # Check that the Name & Comment don't have embedded NULLs
106 # Also check that they only contain ISO 8859-1 chars.
107 if ($got->parsed('Name') && defined $got->value('Name')) {
108 my $name = $got->value('Name');
110 return $self->saveErrorString(undef, "Null Character found in Name",
112 if ! $lax && $name =~ /\x00/ ;
114 return $self->saveErrorString(undef, "Non ISO 8859-1 Character found in Name",
116 if ! $lax && $name =~ /$GZIP_FNAME_INVALID_CHAR_RE/o ;
119 if ($got->parsed('Comment') && defined $got->value('Comment')) {
120 my $comment = $got->value('Comment');
122 return $self->saveErrorString(undef, "Null Character found in Comment",
124 if ! $lax && $comment =~ /\x00/ ;
126 return $self->saveErrorString(undef, "Non ISO 8859-1 Character found in Comment",
128 if ! $lax && $comment =~ /$GZIP_FCOMMENT_INVALID_CHAR_RE/o;
131 if ($got->parsed('OS_Code') ) {
132 my $value = $got->value('OS_Code');
134 return $self->saveErrorString(undef, "OS_Code must be between 0 and 255, got '$value'")
135 if $value < 0 || $value > 255 ;
139 # gzip only supports Deflate at present
140 $got->value('Method' => Z_DEFLATED) ;
142 if ( ! $got->parsed('ExtraFlags')) {
143 $got->value('ExtraFlags' => 2)
144 if $got->value('Level') == Z_BEST_SPEED ;
145 $got->value('ExtraFlags' => 4)
146 if $got->value('Level') == Z_BEST_COMPRESSION ;
149 if ($got->parsed('ExtraField')) {
151 my $bad = $self->parseExtraField($got, $lax) ;
152 return $self->saveErrorString(undef, $bad, Z_DATA_ERROR)
155 my $len = length $got->value('ExtraField') ;
156 return $self->saveErrorString(undef, ExtraFieldError("Too Large"),
158 if $len > GZIP_FEXTRA_MAX_SIZE;
168 return pack("V V", *$self->{Compress}->crc32(),
169 *$self->{UnCompSize_32bit});
174 return ('IO::Uncompress::Gunzip',
175 \$IO::Uncompress::Gunzip::GunzipError);
182 my $filename = shift ;
184 my $defaultTime = (stat($filename))[9] ;
186 $params->value('Name' => $filename)
187 if ! $params->parsed('Name') ;
189 $params->value('Time' => $defaultTime)
190 if ! $params->parsed('Time') ;
199 # stort-circuit if a minimal header is requested.
200 return GZIP_MINIMUM_HEADER if $param->value('Minimal') ;
203 my $method = $param->valueOrDefault('Method', GZIP_CM_DEFLATED) ;
206 my $flags = GZIP_FLG_DEFAULT ;
207 $flags |= GZIP_FLG_FTEXT if $param->value('TextFlag') ;
208 $flags |= GZIP_FLG_FHCRC if $param->value('HeaderCRC') ;
209 $flags |= GZIP_FLG_FEXTRA if $param->wantValue('ExtraField') ;
210 $flags |= GZIP_FLG_FNAME if $param->wantValue('Name') ;
211 $flags |= GZIP_FLG_FCOMMENT if $param->wantValue('Comment') ;
214 my $time = $param->valueOrDefault('Time', GZIP_MTIME_DEFAULT) ;
217 my $extra_flags = $param->valueOrDefault('ExtraFlags', GZIP_XFL_DEFAULT);
220 my $os_code = $param->valueOrDefault('OS_Code', GZIP_OS_DEFAULT) ;
223 my $out = pack("C4 V C C",
226 $method, # Compression Method
228 $time, # Modification Time
229 $extra_flags, # Extra Flags
230 $os_code, # Operating System Code
234 if ($flags & GZIP_FLG_FEXTRA) {
235 my $extra = $param->value('ExtraField') ;
236 $out .= pack("v", length $extra) . $extra ;
240 if ($flags & GZIP_FLG_FNAME) {
241 my $name .= $param->value('Name') ;
242 $name =~ s/\x00.*$//;
244 # Terminate the filename with NULL unless it already is
245 $out .= GZIP_NULL_BYTE
247 substr($name, 1, -1) ne GZIP_NULL_BYTE ;
251 if ($flags & GZIP_FLG_FCOMMENT) {
252 my $comment .= $param->value('Comment') ;
253 $comment =~ s/\x00.*$//;
255 # Terminate the comment with NULL unless it already is
256 $out .= GZIP_NULL_BYTE
257 if ! length $comment or
258 substr($comment, 1, -1) ne GZIP_NULL_BYTE;
262 $out .= pack("v", crc32($out) & 0x00FF ) if $param->value('HeaderCRC') ;
271 return "Error with ExtraField Parameter: $_[0]" ;
274 sub validateExtraFieldPair
279 return ExtraFieldError("Not an array ref")
280 unless ref $pair && ref $pair eq 'ARRAY';
282 return ExtraFieldError("SubField must have two parts")
285 return ExtraFieldError("SubField ID is a reference")
288 return ExtraFieldError("SubField Data is a reference")
291 # ID is exactly two chars
292 return ExtraFieldError("SubField ID not two chars long")
293 unless length $pair->[0] == GZIP_FEXTRA_SUBFIELD_ID_SIZE ;
295 # Check that the 2nd byte of the ID isn't 0
296 return ExtraFieldError("SubField ID 2nd byte is 0x00")
297 if ! $lax && substr($pair->[0], 1, 1) eq "\x00" ;
299 return ExtraFieldError("SubField Data too long")
300 if length $pair->[1] > GZIP_FEXTRA_SUBFIELD_MAX_SIZE ;
314 my $XLEN = length $data ;
316 return ExtraFieldError("Too Large")
317 if $XLEN > GZIP_FEXTRA_MAX_SIZE;
320 while ($offset < $XLEN) {
322 return ExtraFieldError("FEXTRA Body")
323 if $offset + GZIP_FEXTRA_SUBFIELD_HEADER_SIZE > $XLEN ;
325 my $id = substr($data, $offset, GZIP_FEXTRA_SUBFIELD_ID_SIZE);
326 $offset += GZIP_FEXTRA_SUBFIELD_ID_SIZE;
328 my $subLen = unpack("v", substr($data, $offset,
329 GZIP_FEXTRA_SUBFIELD_LEN_SIZE));
330 $offset += GZIP_FEXTRA_SUBFIELD_LEN_SIZE ;
332 return ExtraFieldError("FEXTRA Body")
333 if $offset + $subLen > $XLEN ;
335 my $bad = validateExtraFieldPair( [$id,
336 substr($data, $offset, $subLen)], $lax );
337 return $bad if $bad ;
351 # ExtraField can be any of
353 # -ExtraField => $data
354 # -ExtraField => [$id1, $data1,
358 # -ExtraField => [ [$id1 => $data1],
362 # -ExtraField => { $id1 => $data1,
369 unless $got->parsed('ExtraField') ;
371 return parseExtra($got->value('ExtraField'), $lax)
372 unless ref $got->value('ExtraField') ;
374 my $data = $got->value('ExtraField');
377 if (ref $data eq 'ARRAY') {
378 if (ref $data->[0]) {
380 foreach my $pair (@$data) {
381 return ExtraFieldError("Not list of lists")
382 unless ref $pair eq 'ARRAY' ;
384 my $bad = validateExtraFieldPair($pair, $lax) ;
385 return $bad if $bad ;
387 $out .= $pair->[0] . pack("v", length $pair->[1]) .
392 return ExtraFieldError("Not even number of elements")
393 unless @$data % 2 == 0;
395 for (my $ix = 0; $ix <= length(@$data) -1 ; $ix += 2) {
396 my $bad = validateExtraFieldPair([$data->[$ix], $data->[$ix+1]], $lax) ;
397 return $bad if $bad ;
399 $out .= $data->[$ix] . pack("v", length $data->[$ix+1]) .
404 elsif (ref $data eq 'HASH') {
405 while (my ($id, $info) = each %$data) {
406 my $bad = validateExtraFieldPair([$id, $info], $lax);
407 return $bad if $bad ;
409 $out .= $id . pack("v", length $info) . $info ;
413 return ExtraFieldError("Not a scalar, array ref or hash ref") ;
416 $got->value('ExtraField' => $out);
432 IO::Compress::Gzip - Perl interface to write RFC 1952 files/buffers
436 use IO::Compress::Gzip qw(gzip $GzipError) ;
439 my $status = gzip $input => $output [,OPTS]
440 or die "gzip failed: $GzipError\n";
442 my $z = new IO::Compress::Gzip $output [,OPTS]
443 or die "gzip failed: $GzipError\n";
446 $z->printf($format, $string);
448 $z->syswrite($string [, $length, $offset]);
452 $z->seek($position, $whence);
455 $z->newStream( [OPTS] );
464 printf $z $format, $string;
465 syswrite $z, $string [, $length, $offset];
469 seek $z, $position, $whence
479 B<WARNING -- This is a Beta release>.
483 =item * DO NOT use in production code.
485 =item * The documentation is incomplete in places.
487 =item * Parts of the interface defined here are tentative.
489 =item * Please report any problems you find.
495 This module provides a Perl interface that allows writing compressed
496 data to files or buffer as defined in RFC 1952.
499 All the gzip headers defined in RFC 1952 can be created using
505 For reading RFC 1952 files/buffers, see the companion module
506 L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>.
509 =head1 Functional Interface
511 A top-level function, C<gzip>, is provided to carry out
512 "one-shot" compression between buffers and/or files. For finer
513 control over the compression process, see the L</"OO Interface">
516 use IO::Compress::Gzip qw(gzip $GzipError) ;
518 gzip $input => $output [,OPTS]
519 or die "gzip failed: $GzipError\n";
523 The functional interface needs Perl5.005 or better.
526 =head2 gzip $input => $output [, OPTS]
529 C<gzip> expects at least two parameters, C<$input> and C<$output>.
531 =head3 The C<$input> parameter
533 The parameter, C<$input>, is used to define the source of
534 the uncompressed data.
536 It can take one of the following forms:
542 If the C<$input> parameter is a simple scalar, it is assumed to be a
543 filename. This file will be opened for reading and the input data
544 will be read from it.
548 If the C<$input> parameter is a filehandle, the input data will be
550 The string '-' can be used as an alias for standard input.
552 =item A scalar reference
554 If C<$input> is a scalar reference, the input data will be read
557 =item An array reference
559 If C<$input> is an array reference, each element in the array must be a
562 The input data will be read from each file in turn.
564 The complete array will be walked to ensure that it only
565 contains valid filenames before any data is compressed.
569 =item An Input FileGlob string
571 If C<$input> is a string that is delimited by the characters "<" and ">"
572 C<gzip> will assume that it is an I<input fileglob string>. The
573 input is the list of files that match the fileglob.
575 If the fileglob does not match any files ...
577 See L<File::GlobMapper|File::GlobMapper> for more details.
582 If the C<$input> parameter is any other type, C<undef> will be returned.
586 In addition, if C<$input> is a simple filename, the default values for
587 two of the gzip header fields created by this function will be sourced
588 from that file -- the NAME gzip header field will be populated with
589 the filename itself, and the MTIME header field will be set to the
590 modification time of the file.
591 The intention here is to mirror part of the behaviour of the gzip
593 If you do not want to use these defaults they can be overridden by
594 explicitly setting the C<Name> and C<Time> options or by setting the
595 C<Minimal> parameter.
599 =head3 The C<$output> parameter
601 The parameter C<$output> is used to control the destination of the
602 compressed data. This parameter can take one of these forms.
608 If the C<$output> parameter is a simple scalar, it is assumed to be a
609 filename. This file will be opened for writing and the compressed
610 data will be written to it.
614 If the C<$output> parameter is a filehandle, the compressed data
615 will be written to it.
616 The string '-' can be used as an alias for standard output.
619 =item A scalar reference
621 If C<$output> is a scalar reference, the compressed data will be
622 stored in C<$$output>.
626 =item An Array Reference
628 If C<$output> is an array reference, the compressed data will be
629 pushed onto the array.
631 =item An Output FileGlob
633 If C<$output> is a string that is delimited by the characters "<" and ">"
634 C<gzip> will assume that it is an I<output fileglob string>. The
635 output is the list of files that match the fileglob.
637 When C<$output> is an fileglob string, C<$input> must also be a fileglob
638 string. Anything else is an error.
642 If the C<$output> parameter is any other type, C<undef> will be returned.
648 When C<$input> maps to multiple files/buffers and C<$output> is a single
649 file/buffer the compressed input files/buffers will all be stored
650 in C<$output> as a single compressed stream.
654 =head2 Optional Parameters
656 Unless specified below, the optional parameters for C<gzip>,
657 C<OPTS>, are the same as those used with the OO interface defined in the
658 L</"Constructor Options"> section below.
662 =item AutoClose =E<gt> 0|1
664 This option applies to any input or output data streams to
665 C<gzip> that are filehandles.
667 If C<AutoClose> is specified, and the value is true, it will result in all
668 input and/or output filehandles being closed once C<gzip> has
671 This parameter defaults to 0.
675 =item BinModeIn =E<gt> 0|1
677 When reading from a file or filehandle, set C<binmode> before reading.
685 =item -Append =E<gt> 0|1
696 To read the contents of the file C<file1.txt> and write the compressed
697 data to the file C<file1.txt.gz>.
701 use IO::Compress::Gzip qw(gzip $GzipError) ;
703 my $input = "file1.txt";
704 gzip $input => "$input.gz"
705 or die "gzip failed: $GzipError\n";
708 To read from an existing Perl filehandle, C<$input>, and write the
709 compressed data to a buffer, C<$buffer>.
713 use IO::Compress::Gzip qw(gzip $GzipError) ;
716 my $input = new IO::File "<file1.txt"
717 or die "Cannot open 'file1.txt': $!\n" ;
719 gzip $input => \$buffer
720 or die "gzip failed: $GzipError\n";
722 To compress all files in the directory "/my/home" that match "*.txt"
723 and store the compressed data in the same directory
727 use IO::Compress::Gzip qw(gzip $GzipError) ;
729 gzip '</my/home/*.txt>' => '<*.gz>'
730 or die "gzip failed: $GzipError\n";
732 and if you want to compress each file one at a time, this will do the trick
736 use IO::Compress::Gzip qw(gzip $GzipError) ;
738 for my $input ( glob "/my/home/*.txt" )
740 my $output = "$input.gz" ;
741 gzip $input => $output
742 or die "Error compressing '$input': $GzipError\n";
750 The format of the constructor for C<IO::Compress::Gzip> is shown below
752 my $z = new IO::Compress::Gzip $output [,OPTS]
753 or die "IO::Compress::Gzip failed: $GzipError\n";
755 It returns an C<IO::Compress::Gzip> object on success and undef on failure.
756 The variable C<$GzipError> will contain an error message on failure.
758 If you are running Perl 5.005 or better the object, C<$z>, returned from
759 IO::Compress::Gzip can be used exactly like an L<IO::File|IO::File> filehandle.
760 This means that all normal output file operations can be carried out
762 For example, to write to a compressed file/buffer you can use either of
765 $z->print("hello world\n");
766 print $z "hello world\n";
768 The mandatory parameter C<$output> is used to control the destination
769 of the compressed data. This parameter can take one of these forms.
775 If the C<$output> parameter is a simple scalar, it is assumed to be a
776 filename. This file will be opened for writing and the compressed data
777 will be written to it.
781 If the C<$output> parameter is a filehandle, the compressed data will be
783 The string '-' can be used as an alias for standard output.
786 =item A scalar reference
788 If C<$output> is a scalar reference, the compressed data will be stored
793 If the C<$output> parameter is any other type, C<IO::Compress::Gzip>::new will
796 =head2 Constructor Options
798 C<OPTS> is any combination of the following options:
802 =item -AutoClose =E<gt> 0|1
804 This option is only valid when the C<$output> parameter is a filehandle. If
805 specified, and the value is true, it will result in the C<$output> being
806 closed once either the C<close> method is called or the C<IO::Compress::Gzip>
809 This parameter defaults to 0.
811 =item -Append =E<gt> 0|1
813 Opens C<$output> in append mode.
815 The behaviour of this option is dependent on the type of C<$output>.
821 If C<$output> is a buffer and C<Append> is enabled, all compressed data
822 will be append to the end if C<$output>. Otherwise C<$output> will be
823 cleared before any data is written to it.
827 If C<$output> is a filename and C<Append> is enabled, the file will be
828 opened in append mode. Otherwise the contents of the file, if any, will be
829 truncated before any compressed data is written to it.
833 If C<$output> is a filehandle, the file pointer will be positioned to the
834 end of the file via a call to C<seek> before any compressed data is written
835 to it. Otherwise the file pointer will not be moved.
839 This parameter defaults to 0.
841 =item -Merge =E<gt> 0|1
843 This option is used to compress input data and append it to an existing
844 compressed data stream in C<$output>. The end result is a single compressed
845 data stream stored in C<$output>.
849 It is a fatal error to attempt to use this option when C<$output> is not an
850 RFC 1952 data stream.
854 There are a number of other limitations with the C<Merge> option:
860 This module needs to have been built with zlib 1.2.1 or better to work. A
861 fatal error will be thrown if C<Merge> is used with an older version of
866 If C<$output> is a file or a filehandle, it must be seekable.
871 This parameter defaults to 0.
875 Defines the compression level used by zlib. The value should either be
876 a number between 0 and 9 (0 means no compression and 9 is maximum
877 compression), or one of the symbolic constants defined below.
882 Z_DEFAULT_COMPRESSION
884 The default is Z_DEFAULT_COMPRESSION.
886 Note, these constants are not imported by C<IO::Compress::Gzip> by default.
888 use IO::Compress::Gzip qw(:strategy);
889 use IO::Compress::Gzip qw(:constants);
890 use IO::Compress::Gzip qw(:all);
894 Defines the strategy used to tune the compression. Use one of the symbolic
895 constants defined below.
903 The default is Z_DEFAULT_STRATEGY.
909 =item -Minimal =E<gt> 0|1
911 If specified, this option will force the creation of the smallest possible
912 compliant gzip header (which is exactly 10 bytes long) as defined in
915 See the section titled "Compliance" in RFC 1952 for a definition
916 of the values used for the fields in the gzip header.
918 All other parameters that control the content of the gzip header will
919 be ignored if this parameter is set to 1.
921 This parameter defaults to 0.
923 =item -Comment =E<gt> $comment
925 Stores the contents of C<$comment> in the COMMENT field in
927 By default, no comment field is written to the gzip file.
929 If the C<-Strict> option is enabled, the comment can only consist of ISO
930 8859-1 characters plus line feed.
932 If the C<-Strict> option is disabled, the comment field can contain any
933 character except NULL. If any null characters are present, the field
934 will be truncated at the first NULL.
936 =item -Name =E<gt> $string
938 Stores the contents of C<$string> in the gzip NAME header field. If
939 C<Name> is not specified, no gzip NAME field will be created.
941 If the C<-Strict> option is enabled, C<$string> can only consist of ISO
944 If C<-Strict> is disabled, then C<$string> can contain any character
945 except NULL. If any null characters are present, the field will be
946 truncated at the first NULL.
948 =item -Time =E<gt> $number
950 Sets the MTIME field in the gzip header to $number.
952 This field defaults to the time the C<IO::Compress::Gzip> object was created
953 if this option is not specified.
955 =item -TextFlag =E<gt> 0|1
957 This parameter controls the setting of the FLG.FTEXT bit in the gzip
958 header. It is used to signal that the data stored in the gzip file/buffer
963 =item -HeaderCRC =E<gt> 0|1
965 When true this parameter will set the FLG.FHCRC bit to 1 in the gzip header
966 and set the CRC16 header field to the CRC of the complete gzip header
967 except the CRC16 field itself.
969 B<Note> that gzip files created with the C<HeaderCRC> flag set to 1 cannot
970 be read by most, if not all, of the the standard gunzip utilities, most
971 notably gzip version 1.2.4. You should therefore avoid using this option if
972 you want to maximize the portability of your gzip files.
974 This parameter defaults to 0.
976 =item -OS_Code =E<gt> $value
978 Stores C<$value> in the gzip OS header field. A number between 0 and 255 is
981 If not specified, this parameter defaults to the OS code of the Operating
982 System this module was built on. The value 3 is used as a catch-all for all
983 Unix variants and unknown Operating Systems.
985 =item -ExtraField =E<gt> $data
987 This parameter allows additional metadata to be stored in the ExtraField in
988 the gzip header. An RFC1952 compliant ExtraField consists of zero or more
989 subfields. Each subfield consists of a two byte header followed by the
992 The list of subfields can be supplied in any of the following formats
994 -ExtraField => [$id1, $data1,
998 -ExtraField => [ [$id1 => $data1],
1002 -ExtraField => { $id1 => $data1,
1007 Where C<$id1>, C<$id2> are two byte subfield ID's. The second byte of
1008 the ID cannot be 0, unless the C<Strict> option has been disabled.
1010 If you use the hash syntax, you have no control over the order in which
1011 the ExtraSubFields are stored, plus you cannot have SubFields with
1014 Alternatively the list of subfields can by supplied as a scalar, thus
1016 -ExtraField => $rawdata
1018 If you use the raw format, and the C<Strict> option is enabled,
1019 C<IO::Compress::Gzip> will check that C<$rawdata> consists of zero or more
1020 conformant sub-fields. When C<Strict> is disabled, C<$rawdata> can
1021 consist of any arbitrary byte stream.
1023 The maximum size of the Extra Field 65535 bytes.
1025 =item -ExtraFlags =E<gt> $value
1027 Sets the XFL byte in the gzip header to C<$value>.
1029 If this option is not present, the value stored in XFL field will be
1030 determined by the setting of the C<Level> option.
1032 If C<Level =E<gt> Z_BEST_SPEED> has been specified then XFL is set to 2.
1033 If C<Level =E<gt> Z_BEST_COMPRESSION> has been specified then XFL is set to 4.
1034 Otherwise XFL is set to 0.
1038 =item -Strict =E<gt> 0|1
1042 C<Strict> will optionally police the values supplied with other options
1043 to ensure they are compliant with RFC1952.
1045 This option is enabled by default.
1047 If C<Strict> is enabled the following behaviour will be policed:
1053 The value supplied with the C<Name> option can only contain ISO 8859-1
1058 The value supplied with the C<Comment> option can only contain ISO 8859-1
1059 characters plus line-feed.
1063 The values supplied with the C<-Name> and C<-Comment> options cannot
1064 contain multiple embedded nulls.
1068 If an C<ExtraField> option is specified and it is a simple scalar,
1069 it must conform to the sub-field structure as defined in RFC1952.
1073 If an C<ExtraField> option is specified the second byte of the ID will be
1074 checked in each subfield to ensure that it does not contain the reserved
1079 When C<Strict> is disabled the following behaviour will be policed:
1085 The value supplied with C<-Name> option can contain
1086 any character except NULL.
1090 The value supplied with C<-Comment> option can contain any character
1095 The values supplied with the C<-Name> and C<-Comment> options can contain
1096 multiple embedded nulls. The string written to the gzip header will
1097 consist of the characters up to, but not including, the first embedded
1102 If an C<ExtraField> option is specified and it is a simple scalar, the
1103 structure will not be checked. The only error is if the length is too big.
1107 The ID header in an C<ExtraField> sub-field can consist of any two bytes.
1128 Compresses and outputs the contents of the C<$data> parameter. This
1129 has the same behaviour as the C<print> built-in.
1131 Returns true if successful.
1137 $z->printf($format, $data)
1138 printf $z $format, $data
1140 Compresses and outputs the contents of the C<$data> parameter.
1142 Returns true if successful.
1149 $z->syswrite $data, $length
1150 $z->syswrite $data, $length, $offset
1153 syswrite $z, $data, $length
1154 syswrite $z, $data, $length, $offset
1156 Compresses and outputs the contents of the C<$data> parameter.
1158 Returns the number of uncompressed bytes written, or C<undef> if
1166 $z->write $data, $length
1167 $z->write $data, $length, $offset
1169 Compresses and outputs the contents of the C<$data> parameter.
1171 Returns the number of uncompressed bytes written, or C<undef> if
1179 $z->flush($flush_type);
1181 flush $z $flush_type;
1183 Flushes any pending compressed data to the output file/buffer.
1185 This method takes an optional parameter, C<$flush_type>, that controls
1186 how the flushing will be carried out. By default the C<$flush_type>
1187 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
1188 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
1189 strongly recommended that you only set the C<flush_type> parameter if
1190 you fully understand the implications of what it does - overuse of C<flush>
1191 can seriously degrade the level of compression achieved. See the C<zlib>
1192 documentation for details.
1194 Returns true on success.
1204 Returns the uncompressed file offset.
1215 Returns true if the C<close> method has been called.
1221 $z->seek($position, $whence);
1222 seek($z, $position, $whence);
1227 Provides a sub-set of the C<seek> functionality, with the restriction
1228 that it is only legal to seek forward in the output file/buffer.
1229 It is a fatal error to attempt to seek backward.
1231 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
1235 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
1236 SEEK_CUR or SEEK_END.
1238 Returns 1 on success, 0 on failure.
1247 This is a noop provided for completeness.
1254 If the C<$z> object is associated with a file, this method will return
1255 the underlying filehandle.
1257 If the C<$z> object is is associated with a buffer, this method will
1267 Flushes any pending compressed data and then closes the output file/buffer.
1271 For most versions of Perl this method will be automatically invoked if
1272 the IO::Compress::Gzip object is destroyed (either explicitly or by the
1273 variable with the reference to the object going out of scope). The
1274 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1275 these cases, the C<close> method will be called automatically, but
1276 not until global destruction of all live objects when the program is
1279 Therefore, if you want your scripts to be able to run on all versions
1280 of Perl, you should call C<close> explicitly and not rely on automatic
1283 Returns true on success, otherwise 0.
1285 If the C<AutoClose> option has been enabled when the IO::Compress::Gzip
1286 object was created, and the object is associated with a file, the
1287 underlying file will also be closed.
1292 =head2 newStream([OPTS])
1296 $z->newStream( [OPTS] )
1298 Closes the current compressed data stream and starts a new one.
1300 OPTS consists of the following sub-set of the the options that are
1301 available when creating the C<$z> object,
1311 =head2 deflateParams
1321 A number of symbolic constants are required by some methods in
1322 C<IO::Compress::Gzip>. None are imported by default.
1328 Imports C<gzip>, C<$GzipError> and all symbolic
1329 constants that can be used by C<IO::Compress::Gzip>. Same as doing this
1331 use IO::Compress::Gzip qw(gzip $GzipError :constants) ;
1335 Import all symbolic constants. Same as doing this
1337 use IO::Compress::Gzip qw(:flush :level :strategy) ;
1341 These symbolic constants are used by the C<flush> method.
1353 These symbolic constants are used by the C<Level> option in the constructor.
1358 Z_DEFAULT_COMPRESSION
1363 These symbolic constants are used by the C<Strategy> option in the constructor.
1386 L<Compress::Zlib>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Uncompress::AnyInflate>
1388 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1390 L<File::GlobMapper|File::GlobMapper>, L<Archive::Tar|Archive::Zip>,
1391 L<IO::Zlib|IO::Zlib>
1393 For RFC 1950, 1951 and 1952 see
1394 F<http://www.faqs.org/rfcs/rfc1950.html>,
1395 F<http://www.faqs.org/rfcs/rfc1951.html> and
1396 F<http://www.faqs.org/rfcs/rfc1952.html>
1398 The primary site for the gzip program is F<http://www.gzip.org>.
1402 The I<IO::Compress::Gzip> module was written by Paul Marquess,
1403 F<pmqs@cpan.org>. The latest copy of the module can be
1404 found on CPAN in F<modules/by-module/Compress/Compress-Zlib-x.x.tar.gz>.
1406 The I<zlib> compression library was written by Jean-loup Gailly
1407 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1409 The primary site for the I<zlib> compression library is
1410 F<http://www.zlib.org>.
1412 =head1 MODIFICATION HISTORY
1414 See the Changes file.
1416 =head1 COPYRIGHT AND LICENSE
1419 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1420 This program is free software; you can redistribute it and/or
1421 modify it under the same terms as Perl itself.