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_10';
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);
433 IO::Compress::Gzip - Write RFC 1952 files/buffers
439 use IO::Compress::Gzip qw(gzip $GzipError) ;
442 my $status = gzip $input => $output [,OPTS]
443 or die "gzip failed: $GzipError\n";
445 my $z = new IO::Compress::Gzip $output [,OPTS]
446 or die "gzip failed: $GzipError\n";
449 $z->printf($format, $string);
451 $z->syswrite($string [, $length, $offset]);
455 $z->seek($position, $whence);
460 $z->input_line_number();
461 $z->newStream( [OPTS] );
472 printf $z $format, $string;
475 seek $z, $position, $whence
485 B<WARNING -- This is a Beta release>.
489 =item * DO NOT use in production code.
491 =item * The documentation is incomplete in places.
493 =item * Parts of the interface defined here are tentative.
495 =item * Please report any problems you find.
502 This module provides a Perl interface that allows writing compressed
503 data to files or buffer as defined in RFC 1952.
507 All the gzip headers defined in RFC 1952 can be created using
516 For reading RFC 1952 files/buffers, see the companion module
517 L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>.
520 =head1 Functional Interface
522 A top-level function, C<gzip>, is provided to carry out
523 "one-shot" compression between buffers and/or files. For finer
524 control over the compression process, see the L</"OO Interface">
527 use IO::Compress::Gzip qw(gzip $GzipError) ;
529 gzip $input => $output [,OPTS]
530 or die "gzip failed: $GzipError\n";
534 The functional interface needs Perl5.005 or better.
537 =head2 gzip $input => $output [, OPTS]
540 C<gzip> expects at least two parameters, C<$input> and C<$output>.
542 =head3 The C<$input> parameter
544 The parameter, C<$input>, is used to define the source of
545 the uncompressed data.
547 It can take one of the following forms:
553 If the C<$input> parameter is a simple scalar, it is assumed to be a
554 filename. This file will be opened for reading and the input data
555 will be read from it.
559 If the C<$input> parameter is a filehandle, the input data will be
561 The string '-' can be used as an alias for standard input.
563 =item A scalar reference
565 If C<$input> is a scalar reference, the input data will be read
568 =item An array reference
570 If C<$input> is an array reference, each element in the array must be a
573 The input data will be read from each file in turn.
575 The complete array will be walked to ensure that it only
576 contains valid filenames before any data is compressed.
580 =item An Input FileGlob string
582 If C<$input> is a string that is delimited by the characters "<" and ">"
583 C<gzip> will assume that it is an I<input fileglob string>. The
584 input is the list of files that match the fileglob.
586 If the fileglob does not match any files ...
588 See L<File::GlobMapper|File::GlobMapper> for more details.
593 If the C<$input> parameter is any other type, C<undef> will be returned.
596 In addition, if C<$input> is a simple filename, the default values for
597 the C<Name> and C<Time> options will be sourced from that file.
599 If you do not want to use these defaults they can be overridden by
600 explicitly setting the C<Name> and C<Time> options or by setting the
601 C<Minimal> parameter.
605 =head3 The C<$output> parameter
607 The parameter C<$output> is used to control the destination of the
608 compressed data. This parameter can take one of these forms.
614 If the C<$output> parameter is a simple scalar, it is assumed to be a
615 filename. This file will be opened for writing and the compressed
616 data will be written to it.
620 If the C<$output> parameter is a filehandle, the compressed data
621 will be written to it.
622 The string '-' can be used as an alias for standard output.
625 =item A scalar reference
627 If C<$output> is a scalar reference, the compressed data will be
628 stored in C<$$output>.
632 =item An Array Reference
634 If C<$output> is an array reference, the compressed data will be
635 pushed onto the array.
637 =item An Output FileGlob
639 If C<$output> is a string that is delimited by the characters "<" and ">"
640 C<gzip> will assume that it is an I<output fileglob string>. The
641 output is the list of files that match the fileglob.
643 When C<$output> is an fileglob string, C<$input> must also be a fileglob
644 string. Anything else is an error.
648 If the C<$output> parameter is any other type, C<undef> will be returned.
654 When C<$input> maps to multiple files/buffers and C<$output> is a single
655 file/buffer the compressed input files/buffers will all be stored
656 in C<$output> as a single compressed stream.
660 =head2 Optional Parameters
662 Unless specified below, the optional parameters for C<gzip>,
663 C<OPTS>, are the same as those used with the OO interface defined in the
664 L</"Constructor Options"> section below.
668 =item AutoClose =E<gt> 0|1
670 This option applies to any input or output data streams to
671 C<gzip> that are filehandles.
673 If C<AutoClose> is specified, and the value is true, it will result in all
674 input and/or output filehandles being closed once C<gzip> has
677 This parameter defaults to 0.
681 =item BinModeIn =E<gt> 0|1
683 When reading from a file or filehandle, set C<binmode> before reading.
691 =item -Append =E<gt> 0|1
702 To read the contents of the file C<file1.txt> and write the compressed
703 data to the file C<file1.txt.gz>.
707 use IO::Compress::Gzip qw(gzip $GzipError) ;
709 my $input = "file1.txt";
710 gzip $input => "$input.gz"
711 or die "gzip failed: $GzipError\n";
714 To read from an existing Perl filehandle, C<$input>, and write the
715 compressed data to a buffer, C<$buffer>.
719 use IO::Compress::Gzip qw(gzip $GzipError) ;
722 my $input = new IO::File "<file1.txt"
723 or die "Cannot open 'file1.txt': $!\n" ;
725 gzip $input => \$buffer
726 or die "gzip failed: $GzipError\n";
728 To compress all files in the directory "/my/home" that match "*.txt"
729 and store the compressed data in the same directory
733 use IO::Compress::Gzip qw(gzip $GzipError) ;
735 gzip '</my/home/*.txt>' => '<*.gz>'
736 or die "gzip failed: $GzipError\n";
738 and if you want to compress each file one at a time, this will do the trick
742 use IO::Compress::Gzip qw(gzip $GzipError) ;
744 for my $input ( glob "/my/home/*.txt" )
746 my $output = "$input.gz" ;
747 gzip $input => $output
748 or die "Error compressing '$input': $GzipError\n";
756 The format of the constructor for C<IO::Compress::Gzip> is shown below
758 my $z = new IO::Compress::Gzip $output [,OPTS]
759 or die "IO::Compress::Gzip failed: $GzipError\n";
761 It returns an C<IO::Compress::Gzip> object on success and undef on failure.
762 The variable C<$GzipError> will contain an error message on failure.
764 If you are running Perl 5.005 or better the object, C<$z>, returned from
765 IO::Compress::Gzip can be used exactly like an L<IO::File|IO::File> filehandle.
766 This means that all normal output file operations can be carried out
768 For example, to write to a compressed file/buffer you can use either of
771 $z->print("hello world\n");
772 print $z "hello world\n";
774 The mandatory parameter C<$output> is used to control the destination
775 of the compressed data. This parameter can take one of these forms.
781 If the C<$output> parameter is a simple scalar, it is assumed to be a
782 filename. This file will be opened for writing and the compressed data
783 will be written to it.
787 If the C<$output> parameter is a filehandle, the compressed data will be
789 The string '-' can be used as an alias for standard output.
792 =item A scalar reference
794 If C<$output> is a scalar reference, the compressed data will be stored
799 If the C<$output> parameter is any other type, C<IO::Compress::Gzip>::new will
802 =head2 Constructor Options
804 C<OPTS> is any combination of the following options:
808 =item AutoClose =E<gt> 0|1
810 This option is only valid when the C<$output> parameter is a filehandle. If
811 specified, and the value is true, it will result in the C<$output> being
812 closed once either the C<close> method is called or the C<IO::Compress::Gzip>
815 This parameter defaults to 0.
817 =item Append =E<gt> 0|1
819 Opens C<$output> in append mode.
821 The behaviour of this option is dependent on the type of C<$output>.
827 If C<$output> is a buffer and C<Append> is enabled, all compressed data
828 will be append to the end if C<$output>. Otherwise C<$output> will be
829 cleared before any data is written to it.
833 If C<$output> is a filename and C<Append> is enabled, the file will be
834 opened in append mode. Otherwise the contents of the file, if any, will be
835 truncated before any compressed data is written to it.
839 If C<$output> is a filehandle, the file pointer will be positioned to the
840 end of the file via a call to C<seek> before any compressed data is written
841 to it. Otherwise the file pointer will not be moved.
845 This parameter defaults to 0.
851 =item Merge =E<gt> 0|1
853 This option is used to compress input data and append it to an existing
854 compressed data stream in C<$output>. The end result is a single compressed
855 data stream stored in C<$output>.
859 It is a fatal error to attempt to use this option when C<$output> is not an
860 RFC 1952 data stream.
864 There are a number of other limitations with the C<Merge> option:
870 This module needs to have been built with zlib 1.2.1 or better to work. A
871 fatal error will be thrown if C<Merge> is used with an older version of
876 If C<$output> is a file or a filehandle, it must be seekable.
881 This parameter defaults to 0.
887 Defines the compression level used by zlib. The value should either be
888 a number between 0 and 9 (0 means no compression and 9 is maximum
889 compression), or one of the symbolic constants defined below.
894 Z_DEFAULT_COMPRESSION
896 The default is Z_DEFAULT_COMPRESSION.
898 Note, these constants are not imported by C<IO::Compress::Gzip> by default.
900 use IO::Compress::Gzip qw(:strategy);
901 use IO::Compress::Gzip qw(:constants);
902 use IO::Compress::Gzip qw(:all);
906 Defines the strategy used to tune the compression. Use one of the symbolic
907 constants defined below.
915 The default is Z_DEFAULT_STRATEGY.
922 =item -Minimal =E<gt> 0|1
924 If specified, this option will force the creation of the smallest possible
925 compliant gzip header (which is exactly 10 bytes long) as defined in
928 See the section titled "Compliance" in RFC 1952 for a definition
929 of the values used for the fields in the gzip header.
931 All other parameters that control the content of the gzip header will
932 be ignored if this parameter is set to 1.
934 This parameter defaults to 0.
936 =item -Comment =E<gt> $comment
938 Stores the contents of C<$comment> in the COMMENT field in
940 By default, no comment field is written to the gzip file.
942 If the C<-Strict> option is enabled, the comment can only consist of ISO
943 8859-1 characters plus line feed.
945 If the C<-Strict> option is disabled, the comment field can contain any
946 character except NULL. If any null characters are present, the field
947 will be truncated at the first NULL.
949 =item -Name =E<gt> $string
951 Stores the contents of C<$string> in the gzip NAME header field. If
952 C<Name> is not specified, no gzip NAME field will be created.
954 If the C<-Strict> option is enabled, C<$string> can only consist of ISO
957 If C<-Strict> is disabled, then C<$string> can contain any character
958 except NULL. If any null characters are present, the field will be
959 truncated at the first NULL.
961 =item -Time =E<gt> $number
963 Sets the MTIME field in the gzip header to $number.
965 This field defaults to the time the C<IO::Compress::Gzip> object was created
966 if this option is not specified.
968 =item -TextFlag =E<gt> 0|1
970 This parameter controls the setting of the FLG.FTEXT bit in the gzip
971 header. It is used to signal that the data stored in the gzip file/buffer
976 =item -HeaderCRC =E<gt> 0|1
978 When true this parameter will set the FLG.FHCRC bit to 1 in the gzip header
979 and set the CRC16 header field to the CRC of the complete gzip header
980 except the CRC16 field itself.
982 B<Note> that gzip files created with the C<HeaderCRC> flag set to 1 cannot
983 be read by most, if not all, of the the standard gunzip utilities, most
984 notably gzip version 1.2.4. You should therefore avoid using this option if
985 you want to maximize the portability of your gzip files.
987 This parameter defaults to 0.
989 =item -OS_Code =E<gt> $value
991 Stores C<$value> in the gzip OS header field. A number between 0 and 255 is
994 If not specified, this parameter defaults to the OS code of the Operating
995 System this module was built on. The value 3 is used as a catch-all for all
996 Unix variants and unknown Operating Systems.
998 =item -ExtraField =E<gt> $data
1000 This parameter allows additional metadata to be stored in the ExtraField in
1001 the gzip header. An RFC 1952 compliant ExtraField consists of zero or more
1002 subfields. Each subfield consists of a two byte header followed by the
1005 The list of subfields can be supplied in any of the following formats
1007 -ExtraField => [$id1, $data1,
1011 -ExtraField => [ [$id1 => $data1],
1015 -ExtraField => { $id1 => $data1,
1020 Where C<$id1>, C<$id2> are two byte subfield ID's. The second byte of
1021 the ID cannot be 0, unless the C<Strict> option has been disabled.
1023 If you use the hash syntax, you have no control over the order in which
1024 the ExtraSubFields are stored, plus you cannot have SubFields with
1027 Alternatively the list of subfields can by supplied as a scalar, thus
1029 -ExtraField => $rawdata
1031 If you use the raw format, and the C<Strict> option is enabled,
1032 C<IO::Compress::Gzip> will check that C<$rawdata> consists of zero or more
1033 conformant sub-fields. When C<Strict> is disabled, C<$rawdata> can
1034 consist of any arbitrary byte stream.
1036 The maximum size of the Extra Field 65535 bytes.
1038 =item -ExtraFlags =E<gt> $value
1040 Sets the XFL byte in the gzip header to C<$value>.
1042 If this option is not present, the value stored in XFL field will be
1043 determined by the setting of the C<Level> option.
1045 If C<Level =E<gt> Z_BEST_SPEED> has been specified then XFL is set to 2.
1046 If C<Level =E<gt> Z_BEST_COMPRESSION> has been specified then XFL is set to 4.
1047 Otherwise XFL is set to 0.
1051 =item -Strict =E<gt> 0|1
1055 C<Strict> will optionally police the values supplied with other options
1056 to ensure they are compliant with RFC1952.
1058 This option is enabled by default.
1060 If C<Strict> is enabled the following behaviour will be policed:
1066 The value supplied with the C<Name> option can only contain ISO 8859-1
1071 The value supplied with the C<Comment> option can only contain ISO 8859-1
1072 characters plus line-feed.
1076 The values supplied with the C<-Name> and C<-Comment> options cannot
1077 contain multiple embedded nulls.
1081 If an C<ExtraField> option is specified and it is a simple scalar,
1082 it must conform to the sub-field structure as defined in RFC 1952.
1086 If an C<ExtraField> option is specified the second byte of the ID will be
1087 checked in each subfield to ensure that it does not contain the reserved
1092 When C<Strict> is disabled the following behaviour will be policed:
1098 The value supplied with C<-Name> option can contain
1099 any character except NULL.
1103 The value supplied with C<-Comment> option can contain any character
1108 The values supplied with the C<-Name> and C<-Comment> options can contain
1109 multiple embedded nulls. The string written to the gzip header will
1110 consist of the characters up to, but not including, the first embedded
1115 If an C<ExtraField> option is specified and it is a simple scalar, the
1116 structure will not be checked. The only error is if the length is too big.
1120 The ID header in an C<ExtraField> sub-field can consist of any two bytes.
1141 Compresses and outputs the contents of the C<$data> parameter. This
1142 has the same behaviour as the C<print> built-in.
1144 Returns true if successful.
1150 $z->printf($format, $data)
1151 printf $z $format, $data
1153 Compresses and outputs the contents of the C<$data> parameter.
1155 Returns true if successful.
1162 $z->syswrite $data, $length
1163 $z->syswrite $data, $length, $offset
1165 Compresses and outputs the contents of the C<$data> parameter.
1167 Returns the number of uncompressed bytes written, or C<undef> if
1175 $z->write $data, $length
1176 $z->write $data, $length, $offset
1178 Compresses and outputs the contents of the C<$data> parameter.
1180 Returns the number of uncompressed bytes written, or C<undef> if
1189 $z->flush($flush_type);
1192 Flushes any pending compressed data to the output file/buffer.
1195 This method takes an optional parameter, C<$flush_type>, that controls
1196 how the flushing will be carried out. By default the C<$flush_type>
1197 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
1198 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
1199 strongly recommended that you only set the C<flush_type> parameter if
1200 you fully understand the implications of what it does - overuse of C<flush>
1201 can seriously degrade the level of compression achieved. See the C<zlib>
1202 documentation for details.
1205 Returns true on success.
1215 Returns the uncompressed file offset.
1226 Returns true if the C<close> method has been called.
1232 $z->seek($position, $whence);
1233 seek($z, $position, $whence);
1238 Provides a sub-set of the C<seek> functionality, with the restriction
1239 that it is only legal to seek forward in the output file/buffer.
1240 It is a fatal error to attempt to seek backward.
1242 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
1246 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
1247 SEEK_CUR or SEEK_END.
1249 Returns 1 on success, 0 on failure.
1258 This is a noop provided for completeness.
1264 Returns true if the object currently refers to a opened file/buffer.
1268 my $prev = $z->autoflush()
1269 my $prev = $z->autoflush(EXPR)
1271 If the C<$z> object is associated with a file or a filehandle, this method
1272 returns the current autoflush setting for the underlying filehandle. If
1273 C<EXPR> is present, and is non-zero, it will enable flushing after every
1274 write/print operation.
1276 If C<$z> is associated with a buffer, this method has no effect and always
1279 B<Note> that the special variable C<$|> B<cannot> be used to set or
1280 retrieve the autoflush setting.
1282 =head2 input_line_number
1284 $z->input_line_number()
1285 $z->input_line_number(EXPR)
1288 This method always returns C<undef> when compressing.
1297 If the C<$z> object is associated with a file or a filehandle, this method
1298 will return the underlying file descriptor.
1300 If the C<$z> object is is associated with a buffer, this method will
1310 Flushes any pending compressed data and then closes the output file/buffer.
1314 For most versions of Perl this method will be automatically invoked if
1315 the IO::Compress::Gzip object is destroyed (either explicitly or by the
1316 variable with the reference to the object going out of scope). The
1317 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1318 these cases, the C<close> method will be called automatically, but
1319 not until global destruction of all live objects when the program is
1322 Therefore, if you want your scripts to be able to run on all versions
1323 of Perl, you should call C<close> explicitly and not rely on automatic
1326 Returns true on success, otherwise 0.
1328 If the C<AutoClose> option has been enabled when the IO::Compress::Gzip
1329 object was created, and the object is associated with a file, the
1330 underlying file will also be closed.
1335 =head2 newStream([OPTS])
1339 $z->newStream( [OPTS] )
1341 Closes the current compressed data stream and starts a new one.
1343 OPTS consists of the following sub-set of the the options that are
1344 available when creating the C<$z> object,
1357 =head2 deflateParams
1369 A number of symbolic constants are required by some methods in
1370 C<IO::Compress::Gzip>. None are imported by default.
1379 Imports C<gzip>, C<$GzipError> and all symbolic
1380 constants that can be used by C<IO::Compress::Gzip>. Same as doing this
1382 use IO::Compress::Gzip qw(gzip $GzipError :constants) ;
1386 Import all symbolic constants. Same as doing this
1388 use IO::Compress::Gzip qw(:flush :level :strategy) ;
1392 These symbolic constants are used by the C<flush> method.
1403 These symbolic constants are used by the C<Level> option in the constructor.
1408 Z_DEFAULT_COMPRESSION
1413 These symbolic constants are used by the C<Strategy> option in the constructor.
1437 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>
1439 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1441 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1442 L<Archive::Tar|Archive::Tar>,
1443 L<IO::Zlib|IO::Zlib>
1446 For RFC 1950, 1951 and 1952 see
1447 F<http://www.faqs.org/rfcs/rfc1950.html>,
1448 F<http://www.faqs.org/rfcs/rfc1951.html> and
1449 F<http://www.faqs.org/rfcs/rfc1952.html>
1451 The I<zlib> compression library was written by Jean-loup Gailly
1452 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1454 The primary site for the I<zlib> compression library is
1455 F<http://www.zlib.org>.
1457 The primary site for gzip is F<http://www.gzip.org>.
1464 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1468 =head1 MODIFICATION HISTORY
1470 See the Changes file.
1472 =head1 COPYRIGHT AND LICENSE
1474 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1476 This program is free software; you can redistribute it and/or
1477 modify it under the same terms as Perl itself.