2 package IO::Compress::Gzip ;
11 use IO::Compress::RawDeflate;
13 use Compress::Raw::Zlib ;
14 use IO::Compress::Base::Common qw(:Status :Parse createSelfTiedObject);
15 use IO::Compress::Gzip::Constants;
19 if (defined &utf8::downgrade )
20 { *noUTF8 = \&utf8::downgrade }
27 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $GzipError);
29 $VERSION = '2.000_08';
32 @ISA = qw(Exporter IO::Compress::RawDeflate);
33 @EXPORT_OK = qw( $GzipError gzip ) ;
34 %EXPORT_TAGS = %IO::Compress::RawDeflate::DEFLATE_CONSTANTS ;
35 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
36 Exporter::export_ok_tags('all');
42 my $obj = createSelfTiedObject($class, \$GzipError);
44 $obj->_create(undef, @_);
50 my $obj = createSelfTiedObject(undef, \$GzipError);
51 return $obj->_def(@_);
57 # #return GZIP_MINIMUM_HEADER ;
58 # return $self->mkHeader(*$self->{Got});
67 $self->getZlibParams(),
70 'Minimal' => [0, 1, Parse_boolean, 0],
71 'Comment' => [0, 1, Parse_any, undef],
72 'Name' => [0, 1, Parse_any, undef],
73 'Time' => [0, 1, Parse_any, undef],
74 'TextFlag' => [0, 1, Parse_boolean, 0],
75 'HeaderCRC' => [0, 1, Parse_boolean, 0],
76 'OS_Code' => [0, 1, Parse_unsigned, $Compress::Raw::Zlib::gzip_os_code],
77 'ExtraField'=> [0, 1, Parse_string, undef],
78 'ExtraFlags'=> [0, 1, Parse_any, undef],
89 # gzip always needs crc32
90 $got->value('CRC32' => 1);
93 if $got->value('Merge') ;
95 my $lax = ! $got->value('Strict') ;
99 if (! $got->parsed('Time') ) {
100 # Modification time defaults to now.
101 $got->value('Time' => time) ;
104 # Check that the Name & Comment don't have embedded NULLs
105 # Also check that they only contain ISO 8859-1 chars.
106 if ($got->parsed('Name') && defined $got->value('Name')) {
107 my $name = $got->value('Name');
109 return $self->saveErrorString(undef, "Null Character found in Name",
111 if ! $lax && $name =~ /\x00/ ;
113 return $self->saveErrorString(undef, "Non ISO 8859-1 Character found in Name",
115 if ! $lax && $name =~ /$GZIP_FNAME_INVALID_CHAR_RE/o ;
118 if ($got->parsed('Comment') && defined $got->value('Comment')) {
119 my $comment = $got->value('Comment');
121 return $self->saveErrorString(undef, "Null Character found in Comment",
123 if ! $lax && $comment =~ /\x00/ ;
125 return $self->saveErrorString(undef, "Non ISO 8859-1 Character found in Comment",
127 if ! $lax && $comment =~ /$GZIP_FCOMMENT_INVALID_CHAR_RE/o;
130 if ($got->parsed('OS_Code') ) {
131 my $value = $got->value('OS_Code');
133 return $self->saveErrorString(undef, "OS_Code must be between 0 and 255, got '$value'")
134 if $value < 0 || $value > 255 ;
138 # gzip only supports Deflate at present
139 $got->value('Method' => Z_DEFLATED) ;
141 if ( ! $got->parsed('ExtraFlags')) {
142 $got->value('ExtraFlags' => 2)
143 if $got->value('Level') == Z_BEST_SPEED ;
144 $got->value('ExtraFlags' => 4)
145 if $got->value('Level') == Z_BEST_COMPRESSION ;
148 if ($got->parsed('ExtraField')) {
150 my $bad = $self->parseExtraField($got, $lax) ;
151 return $self->saveErrorString(undef, $bad, Z_DATA_ERROR)
154 my $len = length $got->value('ExtraField') ;
155 return $self->saveErrorString(undef, ExtraFieldError("Too Large"),
157 if $len > GZIP_FEXTRA_MAX_SIZE;
167 return pack("V V", *$self->{Compress}->crc32(),
168 *$self->{UnCompSize_32bit});
173 return ('IO::Uncompress::Gunzip',
174 \$IO::Uncompress::Gunzip::GunzipError);
181 my $filename = shift ;
183 my $defaultTime = (stat($filename))[9] ;
185 $params->value('Name' => $filename)
186 if ! $params->parsed('Name') ;
188 $params->value('Time' => $defaultTime)
189 if ! $params->parsed('Time') ;
198 # stort-circuit if a minimal header is requested.
199 return GZIP_MINIMUM_HEADER if $param->value('Minimal') ;
202 my $method = $param->valueOrDefault('Method', GZIP_CM_DEFLATED) ;
205 my $flags = GZIP_FLG_DEFAULT ;
206 $flags |= GZIP_FLG_FTEXT if $param->value('TextFlag') ;
207 $flags |= GZIP_FLG_FHCRC if $param->value('HeaderCRC') ;
208 $flags |= GZIP_FLG_FEXTRA if $param->wantValue('ExtraField') ;
209 $flags |= GZIP_FLG_FNAME if $param->wantValue('Name') ;
210 $flags |= GZIP_FLG_FCOMMENT if $param->wantValue('Comment') ;
213 my $time = $param->valueOrDefault('Time', GZIP_MTIME_DEFAULT) ;
216 my $extra_flags = $param->valueOrDefault('ExtraFlags', GZIP_XFL_DEFAULT);
219 my $os_code = $param->valueOrDefault('OS_Code', GZIP_OS_DEFAULT) ;
222 my $out = pack("C4 V C C",
225 $method, # Compression Method
227 $time, # Modification Time
228 $extra_flags, # Extra Flags
229 $os_code, # Operating System Code
233 if ($flags & GZIP_FLG_FEXTRA) {
234 my $extra = $param->value('ExtraField') ;
235 $out .= pack("v", length $extra) . $extra ;
239 if ($flags & GZIP_FLG_FNAME) {
240 my $name .= $param->value('Name') ;
241 $name =~ s/\x00.*$//;
243 # Terminate the filename with NULL unless it already is
244 $out .= GZIP_NULL_BYTE
246 substr($name, 1, -1) ne GZIP_NULL_BYTE ;
250 if ($flags & GZIP_FLG_FCOMMENT) {
251 my $comment .= $param->value('Comment') ;
252 $comment =~ s/\x00.*$//;
254 # Terminate the comment with NULL unless it already is
255 $out .= GZIP_NULL_BYTE
256 if ! length $comment or
257 substr($comment, 1, -1) ne GZIP_NULL_BYTE;
261 $out .= pack("v", crc32($out) & 0x00FF ) if $param->value('HeaderCRC') ;
270 return "Error with ExtraField Parameter: $_[0]" ;
273 sub validateExtraFieldPair
278 return ExtraFieldError("Not an array ref")
279 unless ref $pair && ref $pair eq 'ARRAY';
281 return ExtraFieldError("SubField must have two parts")
284 return ExtraFieldError("SubField ID is a reference")
287 return ExtraFieldError("SubField Data is a reference")
290 # ID is exactly two chars
291 return ExtraFieldError("SubField ID not two chars long")
292 unless length $pair->[0] == GZIP_FEXTRA_SUBFIELD_ID_SIZE ;
294 # Check that the 2nd byte of the ID isn't 0
295 return ExtraFieldError("SubField ID 2nd byte is 0x00")
296 if ! $lax && substr($pair->[0], 1, 1) eq "\x00" ;
298 return ExtraFieldError("SubField Data too long")
299 if length $pair->[1] > GZIP_FEXTRA_SUBFIELD_MAX_SIZE ;
313 my $XLEN = length $data ;
315 return ExtraFieldError("Too Large")
316 if $XLEN > GZIP_FEXTRA_MAX_SIZE;
319 while ($offset < $XLEN) {
321 return ExtraFieldError("FEXTRA Body")
322 if $offset + GZIP_FEXTRA_SUBFIELD_HEADER_SIZE > $XLEN ;
324 my $id = substr($data, $offset, GZIP_FEXTRA_SUBFIELD_ID_SIZE);
325 $offset += GZIP_FEXTRA_SUBFIELD_ID_SIZE;
327 my $subLen = unpack("v", substr($data, $offset,
328 GZIP_FEXTRA_SUBFIELD_LEN_SIZE));
329 $offset += GZIP_FEXTRA_SUBFIELD_LEN_SIZE ;
331 return ExtraFieldError("FEXTRA Body")
332 if $offset + $subLen > $XLEN ;
334 my $bad = validateExtraFieldPair( [$id,
335 substr($data, $offset, $subLen)], $lax );
336 return $bad if $bad ;
350 # ExtraField can be any of
352 # -ExtraField => $data
353 # -ExtraField => [$id1, $data1,
357 # -ExtraField => [ [$id1 => $data1],
361 # -ExtraField => { $id1 => $data1,
368 unless $got->parsed('ExtraField') ;
370 return parseExtra($got->value('ExtraField'), $lax)
371 unless ref $got->value('ExtraField') ;
373 my $data = $got->value('ExtraField');
376 if (ref $data eq 'ARRAY') {
377 if (ref $data->[0]) {
379 foreach my $pair (@$data) {
380 return ExtraFieldError("Not list of lists")
381 unless ref $pair eq 'ARRAY' ;
383 my $bad = validateExtraFieldPair($pair, $lax) ;
384 return $bad if $bad ;
386 $out .= $pair->[0] . pack("v", length $pair->[1]) .
391 return ExtraFieldError("Not even number of elements")
392 unless @$data % 2 == 0;
394 for (my $ix = 0; $ix <= length(@$data) -1 ; $ix += 2) {
395 my $bad = validateExtraFieldPair([$data->[$ix], $data->[$ix+1]], $lax) ;
396 return $bad if $bad ;
398 $out .= $data->[$ix] . pack("v", length $data->[$ix+1]) .
403 elsif (ref $data eq 'HASH') {
404 while (my ($id, $info) = each %$data) {
405 my $bad = validateExtraFieldPair([$id, $info], $lax);
406 return $bad if $bad ;
408 $out .= $id . pack("v", length $info) . $info ;
412 return ExtraFieldError("Not a scalar, array ref or hash ref") ;
415 $got->value('ExtraField' => $out);
432 IO::Compress::Gzip - Perl interface to write RFC 1952 files/buffers
437 use IO::Compress::Gzip qw(gzip $GzipError) ;
440 my $status = gzip $input => $output [,OPTS]
441 or die "gzip failed: $GzipError\n";
443 my $z = new IO::Compress::Gzip $output [,OPTS]
444 or die "gzip failed: $GzipError\n";
447 $z->printf($format, $string);
449 $z->syswrite($string [, $length, $offset]);
453 $z->seek($position, $whence);
458 $z->input_line_number();
459 $z->newStream( [OPTS] );
470 printf $z $format, $string;
473 seek $z, $position, $whence
483 B<WARNING -- This is a Beta release>.
487 =item * DO NOT use in production code.
489 =item * The documentation is incomplete in places.
491 =item * Parts of the interface defined here are tentative.
493 =item * Please report any problems you find.
500 This module provides a Perl interface that allows writing compressed
501 data to files or buffer as defined in RFC 1952.
505 All the gzip headers defined in RFC 1952 can be created using
514 For reading RFC 1952 files/buffers, see the companion module
515 L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>.
518 =head1 Functional Interface
520 A top-level function, C<gzip>, is provided to carry out
521 "one-shot" compression between buffers and/or files. For finer
522 control over the compression process, see the L</"OO Interface">
525 use IO::Compress::Gzip qw(gzip $GzipError) ;
527 gzip $input => $output [,OPTS]
528 or die "gzip failed: $GzipError\n";
532 The functional interface needs Perl5.005 or better.
535 =head2 gzip $input => $output [, OPTS]
538 C<gzip> expects at least two parameters, C<$input> and C<$output>.
540 =head3 The C<$input> parameter
542 The parameter, C<$input>, is used to define the source of
543 the uncompressed data.
545 It can take one of the following forms:
551 If the C<$input> parameter is a simple scalar, it is assumed to be a
552 filename. This file will be opened for reading and the input data
553 will be read from it.
557 If the C<$input> parameter is a filehandle, the input data will be
559 The string '-' can be used as an alias for standard input.
561 =item A scalar reference
563 If C<$input> is a scalar reference, the input data will be read
566 =item An array reference
568 If C<$input> is an array reference, each element in the array must be a
571 The input data will be read from each file in turn.
573 The complete array will be walked to ensure that it only
574 contains valid filenames before any data is compressed.
578 =item An Input FileGlob string
580 If C<$input> is a string that is delimited by the characters "<" and ">"
581 C<gzip> will assume that it is an I<input fileglob string>. The
582 input is the list of files that match the fileglob.
584 If the fileglob does not match any files ...
586 See L<File::GlobMapper|File::GlobMapper> for more details.
591 If the C<$input> parameter is any other type, C<undef> will be returned.
595 In addition, if C<$input> is a simple filename, the default values for
596 a number of the gzip header fields created by this function will
597 be sourced from that file --
599 the NAME gzip header field will be populated with
600 the filename itself, and the MTIME header field will be set to the
601 modification time of the file.
602 The intention here is to mirror part of the behaviour of the gzip
605 If you do not want to use these defaults they can be overridden by
606 explicitly setting the C<Name> and C<Time> options or by setting the
607 C<Minimal> parameter.
611 =head3 The C<$output> parameter
613 The parameter C<$output> is used to control the destination of the
614 compressed data. This parameter can take one of these forms.
620 If the C<$output> parameter is a simple scalar, it is assumed to be a
621 filename. This file will be opened for writing and the compressed
622 data will be written to it.
626 If the C<$output> parameter is a filehandle, the compressed data
627 will be written to it.
628 The string '-' can be used as an alias for standard output.
631 =item A scalar reference
633 If C<$output> is a scalar reference, the compressed data will be
634 stored in C<$$output>.
638 =item An Array Reference
640 If C<$output> is an array reference, the compressed data will be
641 pushed onto the array.
643 =item An Output FileGlob
645 If C<$output> is a string that is delimited by the characters "<" and ">"
646 C<gzip> will assume that it is an I<output fileglob string>. The
647 output is the list of files that match the fileglob.
649 When C<$output> is an fileglob string, C<$input> must also be a fileglob
650 string. Anything else is an error.
654 If the C<$output> parameter is any other type, C<undef> will be returned.
660 When C<$input> maps to multiple files/buffers and C<$output> is a single
661 file/buffer the compressed input files/buffers will all be stored
662 in C<$output> as a single compressed stream.
666 =head2 Optional Parameters
668 Unless specified below, the optional parameters for C<gzip>,
669 C<OPTS>, are the same as those used with the OO interface defined in the
670 L</"Constructor Options"> section below.
674 =item AutoClose =E<gt> 0|1
676 This option applies to any input or output data streams to
677 C<gzip> that are filehandles.
679 If C<AutoClose> is specified, and the value is true, it will result in all
680 input and/or output filehandles being closed once C<gzip> has
683 This parameter defaults to 0.
687 =item BinModeIn =E<gt> 0|1
689 When reading from a file or filehandle, set C<binmode> before reading.
697 =item -Append =E<gt> 0|1
708 To read the contents of the file C<file1.txt> and write the compressed
709 data to the file C<file1.txt.gz>.
713 use IO::Compress::Gzip qw(gzip $GzipError) ;
715 my $input = "file1.txt";
716 gzip $input => "$input.gz"
717 or die "gzip failed: $GzipError\n";
720 To read from an existing Perl filehandle, C<$input>, and write the
721 compressed data to a buffer, C<$buffer>.
725 use IO::Compress::Gzip qw(gzip $GzipError) ;
728 my $input = new IO::File "<file1.txt"
729 or die "Cannot open 'file1.txt': $!\n" ;
731 gzip $input => \$buffer
732 or die "gzip failed: $GzipError\n";
734 To compress all files in the directory "/my/home" that match "*.txt"
735 and store the compressed data in the same directory
739 use IO::Compress::Gzip qw(gzip $GzipError) ;
741 gzip '</my/home/*.txt>' => '<*.gz>'
742 or die "gzip failed: $GzipError\n";
744 and if you want to compress each file one at a time, this will do the trick
748 use IO::Compress::Gzip qw(gzip $GzipError) ;
750 for my $input ( glob "/my/home/*.txt" )
752 my $output = "$input.gz" ;
753 gzip $input => $output
754 or die "Error compressing '$input': $GzipError\n";
762 The format of the constructor for C<IO::Compress::Gzip> is shown below
764 my $z = new IO::Compress::Gzip $output [,OPTS]
765 or die "IO::Compress::Gzip failed: $GzipError\n";
767 It returns an C<IO::Compress::Gzip> object on success and undef on failure.
768 The variable C<$GzipError> will contain an error message on failure.
770 If you are running Perl 5.005 or better the object, C<$z>, returned from
771 IO::Compress::Gzip can be used exactly like an L<IO::File|IO::File> filehandle.
772 This means that all normal output file operations can be carried out
774 For example, to write to a compressed file/buffer you can use either of
777 $z->print("hello world\n");
778 print $z "hello world\n";
780 The mandatory parameter C<$output> is used to control the destination
781 of the compressed data. This parameter can take one of these forms.
787 If the C<$output> parameter is a simple scalar, it is assumed to be a
788 filename. This file will be opened for writing and the compressed data
789 will be written to it.
793 If the C<$output> parameter is a filehandle, the compressed data will be
795 The string '-' can be used as an alias for standard output.
798 =item A scalar reference
800 If C<$output> is a scalar reference, the compressed data will be stored
805 If the C<$output> parameter is any other type, C<IO::Compress::Gzip>::new will
808 =head2 Constructor Options
810 C<OPTS> is any combination of the following options:
814 =item AutoClose =E<gt> 0|1
816 This option is only valid when the C<$output> parameter is a filehandle. If
817 specified, and the value is true, it will result in the C<$output> being
818 closed once either the C<close> method is called or the C<IO::Compress::Gzip>
821 This parameter defaults to 0.
823 =item Append =E<gt> 0|1
825 Opens C<$output> in append mode.
827 The behaviour of this option is dependent on the type of C<$output>.
833 If C<$output> is a buffer and C<Append> is enabled, all compressed data
834 will be append to the end if C<$output>. Otherwise C<$output> will be
835 cleared before any data is written to it.
839 If C<$output> is a filename and C<Append> is enabled, the file will be
840 opened in append mode. Otherwise the contents of the file, if any, will be
841 truncated before any compressed data is written to it.
845 If C<$output> is a filehandle, the file pointer will be positioned to the
846 end of the file via a call to C<seek> before any compressed data is written
847 to it. Otherwise the file pointer will not be moved.
851 This parameter defaults to 0.
857 =item -Merge =E<gt> 0|1
859 This option is used to compress input data and append it to an existing
860 compressed data stream in C<$output>. The end result is a single compressed
861 data stream stored in C<$output>.
865 It is a fatal error to attempt to use this option when C<$output> is not an
866 RFC 1952 data stream.
870 There are a number of other limitations with the C<Merge> option:
876 This module needs to have been built with zlib 1.2.1 or better to work. A
877 fatal error will be thrown if C<Merge> is used with an older version of
882 If C<$output> is a file or a filehandle, it must be seekable.
887 This parameter defaults to 0.
893 Defines the compression level used by zlib. The value should either be
894 a number between 0 and 9 (0 means no compression and 9 is maximum
895 compression), or one of the symbolic constants defined below.
900 Z_DEFAULT_COMPRESSION
902 The default is Z_DEFAULT_COMPRESSION.
904 Note, these constants are not imported by C<IO::Compress::Gzip> by default.
906 use IO::Compress::Gzip qw(:strategy);
907 use IO::Compress::Gzip qw(:constants);
908 use IO::Compress::Gzip qw(:all);
912 Defines the strategy used to tune the compression. Use one of the symbolic
913 constants defined below.
921 The default is Z_DEFAULT_STRATEGY.
928 =item -Minimal =E<gt> 0|1
930 If specified, this option will force the creation of the smallest possible
931 compliant gzip header (which is exactly 10 bytes long) as defined in
934 See the section titled "Compliance" in RFC 1952 for a definition
935 of the values used for the fields in the gzip header.
937 All other parameters that control the content of the gzip header will
938 be ignored if this parameter is set to 1.
940 This parameter defaults to 0.
942 =item -Comment =E<gt> $comment
944 Stores the contents of C<$comment> in the COMMENT field in
946 By default, no comment field is written to the gzip file.
948 If the C<-Strict> option is enabled, the comment can only consist of ISO
949 8859-1 characters plus line feed.
951 If the C<-Strict> option is disabled, the comment field can contain any
952 character except NULL. If any null characters are present, the field
953 will be truncated at the first NULL.
955 =item -Name =E<gt> $string
957 Stores the contents of C<$string> in the gzip NAME header field. If
958 C<Name> is not specified, no gzip NAME field will be created.
960 If the C<-Strict> option is enabled, C<$string> can only consist of ISO
963 If C<-Strict> is disabled, then C<$string> can contain any character
964 except NULL. If any null characters are present, the field will be
965 truncated at the first NULL.
967 =item -Time =E<gt> $number
969 Sets the MTIME field in the gzip header to $number.
971 This field defaults to the time the C<IO::Compress::Gzip> object was created
972 if this option is not specified.
974 =item -TextFlag =E<gt> 0|1
976 This parameter controls the setting of the FLG.FTEXT bit in the gzip
977 header. It is used to signal that the data stored in the gzip file/buffer
982 =item -HeaderCRC =E<gt> 0|1
984 When true this parameter will set the FLG.FHCRC bit to 1 in the gzip header
985 and set the CRC16 header field to the CRC of the complete gzip header
986 except the CRC16 field itself.
988 B<Note> that gzip files created with the C<HeaderCRC> flag set to 1 cannot
989 be read by most, if not all, of the the standard gunzip utilities, most
990 notably gzip version 1.2.4. You should therefore avoid using this option if
991 you want to maximize the portability of your gzip files.
993 This parameter defaults to 0.
995 =item -OS_Code =E<gt> $value
997 Stores C<$value> in the gzip OS header field. A number between 0 and 255 is
1000 If not specified, this parameter defaults to the OS code of the Operating
1001 System this module was built on. The value 3 is used as a catch-all for all
1002 Unix variants and unknown Operating Systems.
1004 =item -ExtraField =E<gt> $data
1006 This parameter allows additional metadata to be stored in the ExtraField in
1007 the gzip header. An RFC 1952 compliant ExtraField consists of zero or more
1008 subfields. Each subfield consists of a two byte header followed by the
1011 The list of subfields can be supplied in any of the following formats
1013 -ExtraField => [$id1, $data1,
1017 -ExtraField => [ [$id1 => $data1],
1021 -ExtraField => { $id1 => $data1,
1026 Where C<$id1>, C<$id2> are two byte subfield ID's. The second byte of
1027 the ID cannot be 0, unless the C<Strict> option has been disabled.
1029 If you use the hash syntax, you have no control over the order in which
1030 the ExtraSubFields are stored, plus you cannot have SubFields with
1033 Alternatively the list of subfields can by supplied as a scalar, thus
1035 -ExtraField => $rawdata
1037 If you use the raw format, and the C<Strict> option is enabled,
1038 C<IO::Compress::Gzip> will check that C<$rawdata> consists of zero or more
1039 conformant sub-fields. When C<Strict> is disabled, C<$rawdata> can
1040 consist of any arbitrary byte stream.
1042 The maximum size of the Extra Field 65535 bytes.
1044 =item -ExtraFlags =E<gt> $value
1046 Sets the XFL byte in the gzip header to C<$value>.
1048 If this option is not present, the value stored in XFL field will be
1049 determined by the setting of the C<Level> option.
1051 If C<Level =E<gt> Z_BEST_SPEED> has been specified then XFL is set to 2.
1052 If C<Level =E<gt> Z_BEST_COMPRESSION> has been specified then XFL is set to 4.
1053 Otherwise XFL is set to 0.
1057 =item -Strict =E<gt> 0|1
1061 C<Strict> will optionally police the values supplied with other options
1062 to ensure they are compliant with RFC1952.
1064 This option is enabled by default.
1066 If C<Strict> is enabled the following behaviour will be policed:
1072 The value supplied with the C<Name> option can only contain ISO 8859-1
1077 The value supplied with the C<Comment> option can only contain ISO 8859-1
1078 characters plus line-feed.
1082 The values supplied with the C<-Name> and C<-Comment> options cannot
1083 contain multiple embedded nulls.
1087 If an C<ExtraField> option is specified and it is a simple scalar,
1088 it must conform to the sub-field structure as defined in RFC 1952.
1092 If an C<ExtraField> option is specified the second byte of the ID will be
1093 checked in each subfield to ensure that it does not contain the reserved
1098 When C<Strict> is disabled the following behaviour will be policed:
1104 The value supplied with C<-Name> option can contain
1105 any character except NULL.
1109 The value supplied with C<-Comment> option can contain any character
1114 The values supplied with the C<-Name> and C<-Comment> options can contain
1115 multiple embedded nulls. The string written to the gzip header will
1116 consist of the characters up to, but not including, the first embedded
1121 If an C<ExtraField> option is specified and it is a simple scalar, the
1122 structure will not be checked. The only error is if the length is too big.
1126 The ID header in an C<ExtraField> sub-field can consist of any two bytes.
1147 Compresses and outputs the contents of the C<$data> parameter. This
1148 has the same behaviour as the C<print> built-in.
1150 Returns true if successful.
1156 $z->printf($format, $data)
1157 printf $z $format, $data
1159 Compresses and outputs the contents of the C<$data> parameter.
1161 Returns true if successful.
1168 $z->syswrite $data, $length
1169 $z->syswrite $data, $length, $offset
1171 Compresses and outputs the contents of the C<$data> parameter.
1173 Returns the number of uncompressed bytes written, or C<undef> if
1181 $z->write $data, $length
1182 $z->write $data, $length, $offset
1184 Compresses and outputs the contents of the C<$data> parameter.
1186 Returns the number of uncompressed bytes written, or C<undef> if
1195 $z->flush($flush_type);
1198 Flushes any pending compressed data to the output file/buffer.
1201 This method takes an optional parameter, C<$flush_type>, that controls
1202 how the flushing will be carried out. By default the C<$flush_type>
1203 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
1204 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
1205 strongly recommended that you only set the C<flush_type> parameter if
1206 you fully understand the implications of what it does - overuse of C<flush>
1207 can seriously degrade the level of compression achieved. See the C<zlib>
1208 documentation for details.
1211 Returns true on success.
1221 Returns the uncompressed file offset.
1232 Returns true if the C<close> method has been called.
1238 $z->seek($position, $whence);
1239 seek($z, $position, $whence);
1244 Provides a sub-set of the C<seek> functionality, with the restriction
1245 that it is only legal to seek forward in the output file/buffer.
1246 It is a fatal error to attempt to seek backward.
1248 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
1252 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
1253 SEEK_CUR or SEEK_END.
1255 Returns 1 on success, 0 on failure.
1264 This is a noop provided for completeness.
1270 Returns true if the object currently refers to a opened file/buffer.
1274 my $prev = $z->autoflush()
1275 my $prev = $z->autoflush(EXPR)
1277 If the C<$z> object is associated with a file or a filehandle, this method
1278 returns the current autoflush setting for the underlying filehandle. If
1279 C<EXPR> is present, and is non-zero, it will enable flushing after every
1280 write/print operation.
1282 If C<$z> is associated with a buffer, this method has no effect and always
1285 B<Note> that the special variable C<$|> B<cannot> be used to set or
1286 retrieve the autoflush setting.
1288 =head2 input_line_number
1290 $z->input_line_number()
1291 $z->input_line_number(EXPR)
1294 This method always returns C<undef> when compressing.
1303 If the C<$z> object is associated with a file or a filehandle, this method
1304 will return the underlying file descriptor.
1306 If the C<$z> object is is associated with a buffer, this method will
1316 Flushes any pending compressed data and then closes the output file/buffer.
1320 For most versions of Perl this method will be automatically invoked if
1321 the IO::Compress::Gzip object is destroyed (either explicitly or by the
1322 variable with the reference to the object going out of scope). The
1323 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1324 these cases, the C<close> method will be called automatically, but
1325 not until global destruction of all live objects when the program is
1328 Therefore, if you want your scripts to be able to run on all versions
1329 of Perl, you should call C<close> explicitly and not rely on automatic
1332 Returns true on success, otherwise 0.
1334 If the C<AutoClose> option has been enabled when the IO::Compress::Gzip
1335 object was created, and the object is associated with a file, the
1336 underlying file will also be closed.
1341 =head2 newStream([OPTS])
1345 $z->newStream( [OPTS] )
1347 Closes the current compressed data stream and starts a new one.
1349 OPTS consists of the following sub-set of the the options that are
1350 available when creating the C<$z> object,
1363 =head2 deflateParams
1375 A number of symbolic constants are required by some methods in
1376 C<IO::Compress::Gzip>. None are imported by default.
1385 Imports C<gzip>, C<$GzipError> and all symbolic
1386 constants that can be used by C<IO::Compress::Gzip>. Same as doing this
1388 use IO::Compress::Gzip qw(gzip $GzipError :constants) ;
1392 Import all symbolic constants. Same as doing this
1394 use IO::Compress::Gzip qw(:flush :level :strategy) ;
1398 These symbolic constants are used by the C<flush> method.
1409 These symbolic constants are used by the C<Level> option in the constructor.
1414 Z_DEFAULT_COMPRESSION
1419 These symbolic constants are used by the C<Strategy> option in the constructor.
1443 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::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1445 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1447 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1448 L<Archive::Tar|Archive::Tar>,
1449 L<IO::Zlib|IO::Zlib>
1452 For RFC 1950, 1951 and 1952 see
1453 F<http://www.faqs.org/rfcs/rfc1950.html>,
1454 F<http://www.faqs.org/rfcs/rfc1951.html> and
1455 F<http://www.faqs.org/rfcs/rfc1952.html>
1457 The I<zlib> compression library was written by Jean-loup Gailly
1458 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1460 The primary site for the I<zlib> compression library is
1461 F<http://www.zlib.org>.
1463 The primary site for gzip is F<http://www.gzip.org>.
1473 The I<IO::Compress::Gzip> module was written by Paul Marquess,
1478 =head1 MODIFICATION HISTORY
1480 See the Changes file.
1482 =head1 COPYRIGHT AND LICENSE
1485 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1487 This program is free software; you can redistribute it and/or
1488 modify it under the same terms as Perl itself.