1package IO::Compress::Gzip ; 2 3require 5.006 ; 4 5use strict ; 6use warnings; 7use bytes; 8 9require Exporter ; 10 11use IO::Compress::RawDeflate 2.204 () ; 12use IO::Compress::Adapter::Deflate 2.204 ; 13 14use IO::Compress::Base::Common 2.204 qw(:Status ); 15use IO::Compress::Gzip::Constants 2.204 ; 16use IO::Compress::Zlib::Extra 2.204 ; 17 18BEGIN 19{ 20 if (defined &utf8::downgrade ) 21 { *noUTF8 = \&utf8::downgrade } 22 else 23 { *noUTF8 = sub {} } 24} 25 26our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, %DEFLATE_CONSTANTS, $GzipError); 27 28$VERSION = '2.204'; 29$GzipError = '' ; 30 31@ISA = qw(IO::Compress::RawDeflate Exporter); 32@EXPORT_OK = qw( $GzipError gzip ) ; 33%EXPORT_TAGS = %IO::Compress::RawDeflate::DEFLATE_CONSTANTS ; 34 35push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ; 36Exporter::export_ok_tags('all'); 37 38sub new 39{ 40 my $class = shift ; 41 42 my $obj = IO::Compress::Base::Common::createSelfTiedObject($class, \$GzipError); 43 44 $obj->_create(undef, @_); 45} 46 47 48sub gzip 49{ 50 my $obj = IO::Compress::Base::Common::createSelfTiedObject(undef, \$GzipError); 51 return $obj->_def(@_); 52} 53 54#sub newHeader 55#{ 56# my $self = shift ; 57# #return GZIP_MINIMUM_HEADER ; 58# return $self->mkHeader(*$self->{Got}); 59#} 60 61sub getExtraParams 62{ 63 my $self = shift ; 64 65 return ( 66 # zlib behaviour 67 $self->getZlibParams(), 68 69 # Gzip header fields 70 'minimal' => [IO::Compress::Base::Common::Parse_boolean, 0], 71 'comment' => [IO::Compress::Base::Common::Parse_any, undef], 72 'name' => [IO::Compress::Base::Common::Parse_any, undef], 73 'time' => [IO::Compress::Base::Common::Parse_any, undef], 74 'textflag' => [IO::Compress::Base::Common::Parse_boolean, 0], 75 'headercrc' => [IO::Compress::Base::Common::Parse_boolean, 0], 76 'os_code' => [IO::Compress::Base::Common::Parse_unsigned, $Compress::Raw::Zlib::gzip_os_code], 77 'extrafield'=> [IO::Compress::Base::Common::Parse_any, undef], 78 'extraflags'=> [IO::Compress::Base::Common::Parse_any, undef], 79 80 ); 81} 82 83 84sub ckParams 85{ 86 my $self = shift ; 87 my $got = shift ; 88 89 # gzip always needs crc32 90 $got->setValue('crc32' => 1); 91 92 return 1 93 if $got->getValue('merge') ; 94 95 my $strict = $got->getValue('strict') ; 96 97 98 { 99 if (! $got->parsed('time') ) { 100 # Modification time defaults to now. 101 $got->setValue(time => time) ; 102 } 103 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->getValue('name')) { 107 my $name = $got->getValue('name'); 108 109 return $self->saveErrorString(undef, "Null Character found in Name", 110 Z_DATA_ERROR) 111 if $strict && $name =~ /\x00/ ; 112 113 return $self->saveErrorString(undef, "Non ISO 8859-1 Character found in Name", 114 Z_DATA_ERROR) 115 if $strict && $name =~ /$GZIP_FNAME_INVALID_CHAR_RE/o ; 116 } 117 118 if ($got->parsed('comment') && defined $got->getValue('comment')) { 119 my $comment = $got->getValue('comment'); 120 121 return $self->saveErrorString(undef, "Null Character found in Comment", 122 Z_DATA_ERROR) 123 if $strict && $comment =~ /\x00/ ; 124 125 return $self->saveErrorString(undef, "Non ISO 8859-1 Character found in Comment", 126 Z_DATA_ERROR) 127 if $strict && $comment =~ /$GZIP_FCOMMENT_INVALID_CHAR_RE/o; 128 } 129 130 if ($got->parsed('os_code') ) { 131 my $value = $got->getValue('os_code'); 132 133 return $self->saveErrorString(undef, "OS_Code must be between 0 and 255, got '$value'") 134 if $value < 0 || $value > 255 ; 135 136 } 137 138 # gzip only supports Deflate at present 139 $got->setValue('method' => Z_DEFLATED) ; 140 141 if ( ! $got->parsed('extraflags')) { 142 $got->setValue('extraflags' => 2) 143 if $got->getValue('level') == Z_BEST_COMPRESSION ; 144 $got->setValue('extraflags' => 4) 145 if $got->getValue('level') == Z_BEST_SPEED ; 146 } 147 148 my $data = $got->getValue('extrafield') ; 149 if (defined $data) { 150 my $bad = IO::Compress::Zlib::Extra::parseExtraField($data, $strict, 1) ; 151 return $self->saveErrorString(undef, "Error with ExtraField Parameter: $bad", Z_DATA_ERROR) 152 if $bad ; 153 154 $got->setValue('extrafield' => $data) ; 155 } 156 } 157 158 return 1; 159} 160 161sub mkTrailer 162{ 163 my $self = shift ; 164 return pack("V V", *$self->{Compress}->crc32(), 165 *$self->{UnCompSize}->get32bit()); 166} 167 168sub getInverseClass 169{ 170 no warnings 'once'; 171 return ('IO::Uncompress::Gunzip', 172 \$IO::Uncompress::Gunzip::GunzipError); 173} 174 175sub getFileInfo 176{ 177 my $self = shift ; 178 my $params = shift; 179 my $filename = shift ; 180 181 return if IO::Compress::Base::Common::isaScalar($filename); 182 183 my $defaultTime = (stat($filename))[9] ; 184 185 $params->setValue('name' => $filename) 186 if ! $params->parsed('name') ; 187 188 $params->setValue('time' => $defaultTime) 189 if ! $params->parsed('time') ; 190} 191 192 193sub mkHeader 194{ 195 my $self = shift ; 196 my $param = shift ; 197 198 # short-circuit if a minimal header is requested. 199 return GZIP_MINIMUM_HEADER if $param->getValue('minimal') ; 200 201 # METHOD 202 my $method = $param->valueOrDefault('method', GZIP_CM_DEFLATED) ; 203 204 # FLAGS 205 my $flags = GZIP_FLG_DEFAULT ; 206 $flags |= GZIP_FLG_FTEXT if $param->getValue('textflag') ; 207 $flags |= GZIP_FLG_FHCRC if $param->getValue('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') ; 211 212 # MTIME 213 my $time = $param->valueOrDefault('time', GZIP_MTIME_DEFAULT) ; 214 215 # EXTRA FLAGS 216 my $extra_flags = $param->valueOrDefault('extraflags', GZIP_XFL_DEFAULT); 217 218 # OS CODE 219 my $os_code = $param->valueOrDefault('os_code', GZIP_OS_DEFAULT) ; 220 221 222 my $out = pack("C4 V C C", 223 GZIP_ID1, # ID1 224 GZIP_ID2, # ID2 225 $method, # Compression Method 226 $flags, # Flags 227 $time, # Modification Time 228 $extra_flags, # Extra Flags 229 $os_code, # Operating System Code 230 ) ; 231 232 # EXTRA 233 if ($flags & GZIP_FLG_FEXTRA) { 234 my $extra = $param->getValue('extrafield') ; 235 $out .= pack("v", length $extra) . $extra ; 236 } 237 238 # NAME 239 if ($flags & GZIP_FLG_FNAME) { 240 my $name .= $param->getValue('name') ; 241 $name =~ s/\x00.*$//; 242 $out .= $name ; 243 # Terminate the filename with NULL unless it already is 244 $out .= GZIP_NULL_BYTE 245 if !length $name or 246 substr($name, 1, -1) ne GZIP_NULL_BYTE ; 247 } 248 249 # COMMENT 250 if ($flags & GZIP_FLG_FCOMMENT) { 251 my $comment .= $param->getValue('comment') ; 252 $comment =~ s/\x00.*$//; 253 $out .= $comment ; 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; 258 } 259 260 # HEADER CRC 261 $out .= pack("v", Compress::Raw::Zlib::crc32($out) & 0x00FF ) 262 if $param->getValue('headercrc') ; 263 264 noUTF8($out); 265 266 return $out ; 267} 268 269sub mkFinalTrailer 270{ 271 return ''; 272} 273 2741; 275 276__END__ 277 278=head1 NAME 279 280IO::Compress::Gzip - Write RFC 1952 files/buffers 281 282=head1 SYNOPSIS 283 284 use IO::Compress::Gzip qw(gzip $GzipError) ; 285 286 my $status = gzip $input => $output [,OPTS] 287 or die "gzip failed: $GzipError\n"; 288 289 my $z = IO::Compress::Gzip->new( $output [,OPTS] ) 290 or die "gzip failed: $GzipError\n"; 291 292 $z->print($string); 293 $z->printf($format, $string); 294 $z->write($string); 295 $z->syswrite($string [, $length, $offset]); 296 $z->flush(); 297 $z->tell(); 298 $z->eof(); 299 $z->seek($position, $whence); 300 $z->binmode(); 301 $z->fileno(); 302 $z->opened(); 303 $z->autoflush(); 304 $z->input_line_number(); 305 $z->newStream( [OPTS] ); 306 307 $z->deflateParams(); 308 309 $z->close() ; 310 311 $GzipError ; 312 313 # IO::File mode 314 315 print $z $string; 316 printf $z $format, $string; 317 tell $z 318 eof $z 319 seek $z, $position, $whence 320 binmode $z 321 fileno $z 322 close $z ; 323 324=head1 DESCRIPTION 325 326This module provides a Perl interface that allows writing compressed 327data to files or buffer as defined in RFC 1952. 328 329All the gzip headers defined in RFC 1952 can be created using 330this module. 331 332For reading RFC 1952 files/buffers, see the companion module 333L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>. 334 335=head1 Functional Interface 336 337A top-level function, C<gzip>, is provided to carry out 338"one-shot" compression between buffers and/or files. For finer 339control over the compression process, see the L</"OO Interface"> 340section. 341 342 use IO::Compress::Gzip qw(gzip $GzipError) ; 343 344 gzip $input_filename_or_reference => $output_filename_or_reference [,OPTS] 345 or die "gzip failed: $GzipError\n"; 346 347The functional interface needs Perl5.005 or better. 348 349=head2 gzip $input_filename_or_reference => $output_filename_or_reference [, OPTS] 350 351C<gzip> expects at least two parameters, 352C<$input_filename_or_reference> and C<$output_filename_or_reference> 353and zero or more optional parameters (see L</Optional Parameters>) 354 355=head3 The C<$input_filename_or_reference> parameter 356 357The parameter, C<$input_filename_or_reference>, is used to define the 358source of the uncompressed data. 359 360It can take one of the following forms: 361 362=over 5 363 364=item A filename 365 366If the C<$input_filename_or_reference> parameter is a simple scalar, it is 367assumed to be a filename. This file will be opened for reading and the 368input data will be read from it. 369 370=item A filehandle 371 372If the C<$input_filename_or_reference> parameter is a filehandle, the input 373data will be read from it. The string '-' can be used as an alias for 374standard input. 375 376=item A scalar reference 377 378If C<$input_filename_or_reference> is a scalar reference, the input data 379will be read from C<$$input_filename_or_reference>. 380 381=item An array reference 382 383If C<$input_filename_or_reference> is an array reference, each element in 384the array must be a filename. 385 386The input data will be read from each file in turn. 387 388The complete array will be walked to ensure that it only 389contains valid filenames before any data is compressed. 390 391=item An Input FileGlob string 392 393If C<$input_filename_or_reference> is a string that is delimited by the 394characters "<" and ">" C<gzip> will assume that it is an 395I<input fileglob string>. The input is the list of files that match the 396fileglob. 397 398See L<File::GlobMapper|File::GlobMapper> for more details. 399 400=back 401 402If the C<$input_filename_or_reference> parameter is any other type, 403C<undef> will be returned. 404 405In addition, if C<$input_filename_or_reference> is a simple filename, 406the default values for 407the C<Name> and C<Time> options will be sourced from that file. 408 409If you do not want to use these defaults they can be overridden by 410explicitly setting the C<Name> and C<Time> options or by setting the 411C<Minimal> parameter. 412 413=head3 The C<$output_filename_or_reference> parameter 414 415The parameter C<$output_filename_or_reference> is used to control the 416destination of the compressed data. This parameter can take one of 417these forms. 418 419=over 5 420 421=item A filename 422 423If the C<$output_filename_or_reference> parameter is a simple scalar, it is 424assumed to be a filename. This file will be opened for writing and the 425compressed data will be written to it. 426 427=item A filehandle 428 429If the C<$output_filename_or_reference> parameter is a filehandle, the 430compressed data will be written to it. The string '-' can be used as 431an alias for standard output. 432 433=item A scalar reference 434 435If C<$output_filename_or_reference> is a scalar reference, the 436compressed data will be stored in C<$$output_filename_or_reference>. 437 438=item An Array Reference 439 440If C<$output_filename_or_reference> is an array reference, 441the compressed data will be pushed onto the array. 442 443=item An Output FileGlob 444 445If C<$output_filename_or_reference> is a string that is delimited by the 446characters "<" and ">" C<gzip> will assume that it is an 447I<output fileglob string>. The output is the list of files that match the 448fileglob. 449 450When C<$output_filename_or_reference> is an fileglob string, 451C<$input_filename_or_reference> must also be a fileglob string. Anything 452else is an error. 453 454See L<File::GlobMapper|File::GlobMapper> for more details. 455 456=back 457 458If the C<$output_filename_or_reference> parameter is any other type, 459C<undef> will be returned. 460 461=head2 Notes 462 463When C<$input_filename_or_reference> maps to multiple files/buffers and 464C<$output_filename_or_reference> is a single 465file/buffer the input files/buffers will be stored 466in C<$output_filename_or_reference> as a concatenated series of compressed data streams. 467 468=head2 Optional Parameters 469 470The optional parameters for the one-shot function C<gzip> 471are (for the most part) identical to those used with the OO interface defined in the 472L</"Constructor Options"> section. The exceptions are listed below 473 474=over 5 475 476=item C<< AutoClose => 0|1 >> 477 478This option applies to any input or output data streams to 479C<gzip> that are filehandles. 480 481If C<AutoClose> is specified, and the value is true, it will result in all 482input and/or output filehandles being closed once C<gzip> has 483completed. 484 485This parameter defaults to 0. 486 487=item C<< BinModeIn => 0|1 >> 488 489This option is now a no-op. All files will be read in binmode. 490 491=item C<< Append => 0|1 >> 492 493The behaviour of this option is dependent on the type of output data 494stream. 495 496=over 5 497 498=item * A Buffer 499 500If C<Append> is enabled, all compressed data will be append to the end of 501the output buffer. Otherwise the output buffer will be cleared before any 502compressed data is written to it. 503 504=item * A Filename 505 506If C<Append> is enabled, the file will be opened in append mode. Otherwise 507the contents of the file, if any, will be truncated before any compressed 508data is written to it. 509 510=item * A Filehandle 511 512If C<Append> is enabled, the filehandle will be positioned to the end of 513the file via a call to C<seek> before any compressed data is 514written to it. Otherwise the file pointer will not be moved. 515 516=back 517 518When C<Append> is specified, and set to true, it will I<append> all compressed 519data to the output data stream. 520 521So when the output is a filehandle it will carry out a seek to the eof 522before writing any compressed data. If the output is a filename, it will be opened for 523appending. If the output is a buffer, all compressed data will be 524appended to the existing buffer. 525 526Conversely when C<Append> is not specified, or it is present and is set to 527false, it will operate as follows. 528 529When the output is a filename, it will truncate the contents of the file 530before writing any compressed data. If the output is a filehandle 531its position will not be changed. If the output is a buffer, it will be 532wiped before any compressed data is output. 533 534Defaults to 0. 535 536=back 537 538=head2 Examples 539 540Here are a few example that show the capabilities of the module. 541 542=head3 Streaming 543 544This very simple command line example demonstrates the streaming capabilities of the module. 545The code reads data from STDIN, compresses it, and writes the compressed data to STDOUT. 546 547 $ echo hello world | perl -MIO::Compress::Gzip=gzip -e 'gzip \*STDIN => \*STDOUT' >output.gz 548 549The special filename "-" can be used as a standin for both C<\*STDIN> and C<\*STDOUT>, 550so the above can be rewritten as 551 552 $ echo hello world | perl -MIO::Compress::Gzip=gzip -e 'gzip "-" => "-"' >output.gz 553 554=head3 Compressing a file from the filesystem 555 556To read the contents of the file C<file1.txt> and write the compressed 557data to the file C<file1.txt.gz>. 558 559 use strict ; 560 use warnings ; 561 use IO::Compress::Gzip qw(gzip $GzipError) ; 562 563 my $input = "file1.txt"; 564 gzip $input => "$input.gz" 565 or die "gzip failed: $GzipError\n"; 566 567=head3 Reading from a Filehandle and writing to an in-memory buffer 568 569To read from an existing Perl filehandle, C<$input>, and write the 570compressed data to a buffer, C<$buffer>. 571 572 use strict ; 573 use warnings ; 574 use IO::Compress::Gzip qw(gzip $GzipError) ; 575 use IO::File ; 576 577 my $input = IO::File->new( "<file1.txt" ) 578 or die "Cannot open 'file1.txt': $!\n" ; 579 my $buffer ; 580 gzip $input => \$buffer 581 or die "gzip failed: $GzipError\n"; 582 583=head3 Compressing multiple files 584 585To compress all files in the directory "/my/home" that match "*.txt" 586and store the compressed data in the same directory 587 588 use strict ; 589 use warnings ; 590 use IO::Compress::Gzip qw(gzip $GzipError) ; 591 592 gzip '</my/home/*.txt>' => '<*.gz>' 593 or die "gzip failed: $GzipError\n"; 594 595and if you want to compress each file one at a time, this will do the trick 596 597 use strict ; 598 use warnings ; 599 use IO::Compress::Gzip qw(gzip $GzipError) ; 600 601 for my $input ( glob "/my/home/*.txt" ) 602 { 603 my $output = "$input.gz" ; 604 gzip $input => $output 605 or die "Error compressing '$input': $GzipError\n"; 606 } 607 608=head1 OO Interface 609 610=head2 Constructor 611 612The format of the constructor for C<IO::Compress::Gzip> is shown below 613 614 my $z = IO::Compress::Gzip->new( $output [,OPTS] ) 615 or die "IO::Compress::Gzip failed: $GzipError\n"; 616 617It returns an C<IO::Compress::Gzip> object on success and undef on failure. 618The variable C<$GzipError> will contain an error message on failure. 619 620If you are running Perl 5.005 or better the object, C<$z>, returned from 621IO::Compress::Gzip can be used exactly like an L<IO::File|IO::File> filehandle. 622This means that all normal output file operations can be carried out 623with C<$z>. 624For example, to write to a compressed file/buffer you can use either of 625these forms 626 627 $z->print("hello world\n"); 628 print $z "hello world\n"; 629 630The mandatory parameter C<$output> is used to control the destination 631of the compressed data. This parameter can take one of these forms. 632 633=over 5 634 635=item A filename 636 637If the C<$output> parameter is a simple scalar, it is assumed to be a 638filename. This file will be opened for writing and the compressed data 639will be written to it. 640 641=item A filehandle 642 643If the C<$output> parameter is a filehandle, the compressed data will be 644written to it. 645The string '-' can be used as an alias for standard output. 646 647=item A scalar reference 648 649If C<$output> is a scalar reference, the compressed data will be stored 650in C<$$output>. 651 652=back 653 654If the C<$output> parameter is any other type, C<IO::Compress::Gzip>::new will 655return undef. 656 657=head2 Constructor Options 658 659C<OPTS> is any combination of zero or more the following options: 660 661=over 5 662 663=item C<< AutoClose => 0|1 >> 664 665This option is only valid when the C<$output> parameter is a filehandle. If 666specified, and the value is true, it will result in the C<$output> being 667closed once either the C<close> method is called or the C<IO::Compress::Gzip> 668object is destroyed. 669 670This parameter defaults to 0. 671 672=item C<< Append => 0|1 >> 673 674Opens C<$output> in append mode. 675 676The behaviour of this option is dependent on the type of C<$output>. 677 678=over 5 679 680=item * A Buffer 681 682If C<$output> is a buffer and C<Append> is enabled, all compressed data 683will be append to the end of C<$output>. Otherwise C<$output> will be 684cleared before any data is written to it. 685 686=item * A Filename 687 688If C<$output> is a filename and C<Append> is enabled, the file will be 689opened in append mode. Otherwise the contents of the file, if any, will be 690truncated before any compressed data is written to it. 691 692=item * A Filehandle 693 694If C<$output> is a filehandle, the file pointer will be positioned to the 695end of the file via a call to C<seek> before any compressed data is written 696to it. Otherwise the file pointer will not be moved. 697 698=back 699 700This parameter defaults to 0. 701 702=item C<< Merge => 0|1 >> 703 704This option is used to compress input data and append it to an existing 705compressed data stream in C<$output>. The end result is a single compressed 706data stream stored in C<$output>. 707 708It is a fatal error to attempt to use this option when C<$output> is not an 709RFC 1952 data stream. 710 711There are a number of other limitations with the C<Merge> option: 712 713=over 5 714 715=item 1 716 717This module needs to have been built with zlib 1.2.1 or better to work. A 718fatal error will be thrown if C<Merge> is used with an older version of 719zlib. 720 721=item 2 722 723If C<$output> is a file or a filehandle, it must be seekable. 724 725=back 726 727This parameter defaults to 0. 728 729=item -Level 730 731Defines the compression level used by zlib. The value should either be 732a number between 0 and 9 (0 means no compression and 9 is maximum 733compression), or one of the symbolic constants defined below. 734 735 Z_NO_COMPRESSION 736 Z_BEST_SPEED 737 Z_BEST_COMPRESSION 738 Z_DEFAULT_COMPRESSION 739 740The default is Z_DEFAULT_COMPRESSION. 741 742Note, these constants are not imported by C<IO::Compress::Gzip> by default. 743 744 use IO::Compress::Gzip qw(:strategy); 745 use IO::Compress::Gzip qw(:constants); 746 use IO::Compress::Gzip qw(:all); 747 748=item -Strategy 749 750Defines the strategy used to tune the compression. Use one of the symbolic 751constants defined below. 752 753 Z_FILTERED 754 Z_HUFFMAN_ONLY 755 Z_RLE 756 Z_FIXED 757 Z_DEFAULT_STRATEGY 758 759The default is Z_DEFAULT_STRATEGY. 760 761=item C<< Minimal => 0|1 >> 762 763If specified, this option will force the creation of the smallest possible 764compliant gzip header (which is exactly 10 bytes long) as defined in 765RFC 1952. 766 767See the section titled "Compliance" in RFC 1952 for a definition 768of the values used for the fields in the gzip header. 769 770All other parameters that control the content of the gzip header will 771be ignored if this parameter is set to 1. 772 773This parameter defaults to 0. 774 775=item C<< Comment => $comment >> 776 777Stores the contents of C<$comment> in the COMMENT field in 778the gzip header. 779By default, no comment field is written to the gzip file. 780 781If the C<-Strict> option is enabled, the comment can only consist of ISO 7828859-1 characters plus line feed. 783 784If the C<-Strict> option is disabled, the comment field can contain any 785character except NULL. If any null characters are present, the field 786will be truncated at the first NULL. 787 788=item C<< Name => $string >> 789 790Stores the contents of C<$string> in the gzip NAME header field. If 791C<Name> is not specified, no gzip NAME field will be created. 792 793If the C<-Strict> option is enabled, C<$string> can only consist of ISO 7948859-1 characters. 795 796If C<-Strict> is disabled, then C<$string> can contain any character 797except NULL. If any null characters are present, the field will be 798truncated at the first NULL. 799 800=item C<< Time => $number >> 801 802Sets the MTIME field in the gzip header to $number. 803 804This field defaults to the time the C<IO::Compress::Gzip> object was created 805if this option is not specified. 806 807=item C<< TextFlag => 0|1 >> 808 809This parameter controls the setting of the FLG.FTEXT bit in the gzip 810header. It is used to signal that the data stored in the gzip file/buffer 811is probably text. 812 813The default is 0. 814 815=item C<< HeaderCRC => 0|1 >> 816 817When true this parameter will set the FLG.FHCRC bit to 1 in the gzip header 818and set the CRC16 header field to the CRC of the complete gzip header 819except the CRC16 field itself. 820 821B<Note> that gzip files created with the C<HeaderCRC> flag set to 1 cannot 822be read by most, if not all, of the standard gunzip utilities, most 823notably gzip version 1.2.4. You should therefore avoid using this option if 824you want to maximize the portability of your gzip files. 825 826This parameter defaults to 0. 827 828=item C<< OS_Code => $value >> 829 830Stores C<$value> in the gzip OS header field. A number between 0 and 255 is 831valid. 832 833If not specified, this parameter defaults to the OS code of the Operating 834System this module was built on. The value 3 is used as a catch-all for all 835Unix variants and unknown Operating Systems. 836 837=item C<< ExtraField => $data >> 838 839This parameter allows additional metadata to be stored in the ExtraField in 840the gzip header. An RFC 1952 compliant ExtraField consists of zero or more 841subfields. Each subfield consists of a two byte header followed by the 842subfield data. 843 844The list of subfields can be supplied in any of the following formats 845 846 -ExtraField => [$id1, $data1, 847 $id2, $data2, 848 ... 849 ] 850 -ExtraField => [ [$id1 => $data1], 851 [$id2 => $data2], 852 ... 853 ] 854 -ExtraField => { $id1 => $data1, 855 $id2 => $data2, 856 ... 857 } 858 859Where C<$id1>, C<$id2> are two byte subfield ID's. The second byte of 860the ID cannot be 0, unless the C<Strict> option has been disabled. 861 862If you use the hash syntax, you have no control over the order in which 863the ExtraSubFields are stored, plus you cannot have SubFields with 864duplicate ID. 865 866Alternatively the list of subfields can by supplied as a scalar, thus 867 868 -ExtraField => $rawdata 869 870If you use the raw format, and the C<Strict> option is enabled, 871C<IO::Compress::Gzip> will check that C<$rawdata> consists of zero or more 872conformant sub-fields. When C<Strict> is disabled, C<$rawdata> can 873consist of any arbitrary byte stream. 874 875The maximum size of the Extra Field 65535 bytes. 876 877=item C<< ExtraFlags => $value >> 878 879Sets the XFL byte in the gzip header to C<$value>. 880 881If this option is not present, the value stored in XFL field will be 882determined by the setting of the C<Level> option. 883 884If C<< Level => Z_BEST_SPEED >> has been specified then XFL is set to 2. 885If C<< Level => Z_BEST_COMPRESSION >> has been specified then XFL is set to 4. 886Otherwise XFL is set to 0. 887 888=item C<< Strict => 0|1 >> 889 890C<Strict> will optionally police the values supplied with other options 891to ensure they are compliant with RFC1952. 892 893This option is enabled by default. 894 895If C<Strict> is enabled the following behaviour will be policed: 896 897=over 5 898 899=item * 900 901The value supplied with the C<Name> option can only contain ISO 8859-1 902characters. 903 904=item * 905 906The value supplied with the C<Comment> option can only contain ISO 8859-1 907characters plus line-feed. 908 909=item * 910 911The values supplied with the C<-Name> and C<-Comment> options cannot 912contain multiple embedded nulls. 913 914=item * 915 916If an C<ExtraField> option is specified and it is a simple scalar, 917it must conform to the sub-field structure as defined in RFC 1952. 918 919=item * 920 921If an C<ExtraField> option is specified the second byte of the ID will be 922checked in each subfield to ensure that it does not contain the reserved 923value 0x00. 924 925=back 926 927When C<Strict> is disabled the following behaviour will be policed: 928 929=over 5 930 931=item * 932 933The value supplied with C<-Name> option can contain 934any character except NULL. 935 936=item * 937 938The value supplied with C<-Comment> option can contain any character 939except NULL. 940 941=item * 942 943The values supplied with the C<-Name> and C<-Comment> options can contain 944multiple embedded nulls. The string written to the gzip header will 945consist of the characters up to, but not including, the first embedded 946NULL. 947 948=item * 949 950If an C<ExtraField> option is specified and it is a simple scalar, the 951structure will not be checked. The only error is if the length is too big. 952 953=item * 954 955The ID header in an C<ExtraField> sub-field can consist of any two bytes. 956 957=back 958 959=back 960 961=head2 Examples 962 963TODO 964 965=head1 Methods 966 967=head2 print 968 969Usage is 970 971 $z->print($data) 972 print $z $data 973 974Compresses and outputs the contents of the C<$data> parameter. This 975has the same behaviour as the C<print> built-in. 976 977Returns true if successful. 978 979=head2 printf 980 981Usage is 982 983 $z->printf($format, $data) 984 printf $z $format, $data 985 986Compresses and outputs the contents of the C<$data> parameter. 987 988Returns true if successful. 989 990=head2 syswrite 991 992Usage is 993 994 $z->syswrite $data 995 $z->syswrite $data, $length 996 $z->syswrite $data, $length, $offset 997 998Compresses and outputs the contents of the C<$data> parameter. 999 1000Returns the number of uncompressed bytes written, or C<undef> if 1001unsuccessful. 1002 1003=head2 write 1004 1005Usage is 1006 1007 $z->write $data 1008 $z->write $data, $length 1009 $z->write $data, $length, $offset 1010 1011Compresses and outputs the contents of the C<$data> parameter. 1012 1013Returns the number of uncompressed bytes written, or C<undef> if 1014unsuccessful. 1015 1016=head2 flush 1017 1018Usage is 1019 1020 $z->flush; 1021 $z->flush($flush_type); 1022 1023Flushes any pending compressed data to the output file/buffer. 1024 1025This method takes an optional parameter, C<$flush_type>, that controls 1026how the flushing will be carried out. By default the C<$flush_type> 1027used is C<Z_FINISH>. Other valid values for C<$flush_type> are 1028C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is 1029strongly recommended that you only set the C<flush_type> parameter if 1030you fully understand the implications of what it does - overuse of C<flush> 1031can seriously degrade the level of compression achieved. See the C<zlib> 1032documentation for details. 1033 1034Returns true on success. 1035 1036=head2 tell 1037 1038Usage is 1039 1040 $z->tell() 1041 tell $z 1042 1043Returns the uncompressed file offset. 1044 1045=head2 eof 1046 1047Usage is 1048 1049 $z->eof(); 1050 eof($z); 1051 1052Returns true if the C<close> method has been called. 1053 1054=head2 seek 1055 1056 $z->seek($position, $whence); 1057 seek($z, $position, $whence); 1058 1059Provides a sub-set of the C<seek> functionality, with the restriction 1060that it is only legal to seek forward in the output file/buffer. 1061It is a fatal error to attempt to seek backward. 1062 1063Empty parts of the file/buffer will have NULL (0x00) bytes written to them. 1064 1065The C<$whence> parameter takes one the usual values, namely SEEK_SET, 1066SEEK_CUR or SEEK_END. 1067 1068Returns 1 on success, 0 on failure. 1069 1070=head2 binmode 1071 1072Usage is 1073 1074 $z->binmode 1075 binmode $z ; 1076 1077This is a noop provided for completeness. 1078 1079=head2 opened 1080 1081 $z->opened() 1082 1083Returns true if the object currently refers to a opened file/buffer. 1084 1085=head2 autoflush 1086 1087 my $prev = $z->autoflush() 1088 my $prev = $z->autoflush(EXPR) 1089 1090If the C<$z> object is associated with a file or a filehandle, this method 1091returns the current autoflush setting for the underlying filehandle. If 1092C<EXPR> is present, and is non-zero, it will enable flushing after every 1093write/print operation. 1094 1095If C<$z> is associated with a buffer, this method has no effect and always 1096returns C<undef>. 1097 1098B<Note> that the special variable C<$|> B<cannot> be used to set or 1099retrieve the autoflush setting. 1100 1101=head2 input_line_number 1102 1103 $z->input_line_number() 1104 $z->input_line_number(EXPR) 1105 1106This method always returns C<undef> when compressing. 1107 1108=head2 fileno 1109 1110 $z->fileno() 1111 fileno($z) 1112 1113If the C<$z> object is associated with a file or a filehandle, C<fileno> 1114will return the underlying file descriptor. Once the C<close> method is 1115called C<fileno> will return C<undef>. 1116 1117If the C<$z> object is associated with a buffer, this method will return 1118C<undef>. 1119 1120=head2 close 1121 1122 $z->close() ; 1123 close $z ; 1124 1125Flushes any pending compressed data and then closes the output file/buffer. 1126 1127For most versions of Perl this method will be automatically invoked if 1128the IO::Compress::Gzip object is destroyed (either explicitly or by the 1129variable with the reference to the object going out of scope). The 1130exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In 1131these cases, the C<close> method will be called automatically, but 1132not until global destruction of all live objects when the program is 1133terminating. 1134 1135Therefore, if you want your scripts to be able to run on all versions 1136of Perl, you should call C<close> explicitly and not rely on automatic 1137closing. 1138 1139Returns true on success, otherwise 0. 1140 1141If the C<AutoClose> option has been enabled when the IO::Compress::Gzip 1142object was created, and the object is associated with a file, the 1143underlying file will also be closed. 1144 1145=head2 newStream([OPTS]) 1146 1147Usage is 1148 1149 $z->newStream( [OPTS] ) 1150 1151Closes the current compressed data stream and starts a new one. 1152 1153OPTS consists of any of the options that are available when creating 1154the C<$z> object. 1155 1156See the L</"Constructor Options"> section for more details. 1157 1158=head2 deflateParams 1159 1160Usage is 1161 1162 $z->deflateParams 1163 1164TODO 1165 1166=head1 Importing 1167 1168A number of symbolic constants are required by some methods in 1169C<IO::Compress::Gzip>. None are imported by default. 1170 1171=over 5 1172 1173=item :all 1174 1175Imports C<gzip>, C<$GzipError> and all symbolic 1176constants that can be used by C<IO::Compress::Gzip>. Same as doing this 1177 1178 use IO::Compress::Gzip qw(gzip $GzipError :constants) ; 1179 1180=item :constants 1181 1182Import all symbolic constants. Same as doing this 1183 1184 use IO::Compress::Gzip qw(:flush :level :strategy) ; 1185 1186=item :flush 1187 1188These symbolic constants are used by the C<flush> method. 1189 1190 Z_NO_FLUSH 1191 Z_PARTIAL_FLUSH 1192 Z_SYNC_FLUSH 1193 Z_FULL_FLUSH 1194 Z_FINISH 1195 Z_BLOCK 1196 1197=item :level 1198 1199These symbolic constants are used by the C<Level> option in the constructor. 1200 1201 Z_NO_COMPRESSION 1202 Z_BEST_SPEED 1203 Z_BEST_COMPRESSION 1204 Z_DEFAULT_COMPRESSION 1205 1206=item :strategy 1207 1208These symbolic constants are used by the C<Strategy> option in the constructor. 1209 1210 Z_FILTERED 1211 Z_HUFFMAN_ONLY 1212 Z_RLE 1213 Z_FIXED 1214 Z_DEFAULT_STRATEGY 1215 1216=back 1217 1218=head1 EXAMPLES 1219 1220=head2 Apache::GZip Revisited 1221 1222See L<IO::Compress::FAQ|IO::Compress::FAQ/"Apache::GZip Revisited"> 1223 1224=head2 Working with Net::FTP 1225 1226See L<IO::Compress::FAQ|IO::Compress::FAQ/"Compressed files and Net::FTP"> 1227 1228=head1 SUPPORT 1229 1230General feedback/questions/bug reports should be sent to 1231L<https://github.com/pmqs/IO-Copress/issues> (preferred) or 1232L<https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Copress>. 1233 1234=head1 SEE ALSO 1235 1236L<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::Lzma>, L<IO::Uncompress::UnLzma>, L<IO::Compress::Xz>, L<IO::Uncompress::UnXz>, L<IO::Compress::Lzip>, L<IO::Uncompress::UnLzip>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Compress::Zstd>, L<IO::Uncompress::UnZstd>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress> 1237 1238L<IO::Compress::FAQ|IO::Compress::FAQ> 1239 1240L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>, 1241L<Archive::Tar|Archive::Tar>, 1242L<IO::Zlib|IO::Zlib> 1243 1244For RFC 1950, 1951 and 1952 see 1245L<https://datatracker.ietf.org/doc/html/rfc1950>, 1246L<https://datatracker.ietf.org/doc/html/rfc1951> and 1247L<https://datatracker.ietf.org/doc/html/rfc1952> 1248 1249The I<zlib> compression library was written by Jean-loup Gailly 1250C<gzip@prep.ai.mit.edu> and Mark Adler C<madler@alumni.caltech.edu>. 1251 1252The primary site for the I<zlib> compression library is 1253L<http://www.zlib.org>. 1254 1255The primary site for the I<zlib-ng> compression library is 1256L<https://github.com/zlib-ng/zlib-ng>. 1257 1258The primary site for gzip is L<http://www.gzip.org>. 1259 1260=head1 AUTHOR 1261 1262This module was written by Paul Marquess, C<pmqs@cpan.org>. 1263 1264=head1 MODIFICATION HISTORY 1265 1266See the Changes file. 1267 1268=head1 COPYRIGHT AND LICENSE 1269 1270Copyright (c) 2005-2023 Paul Marquess. All rights reserved. 1271 1272This program is free software; you can redistribute it and/or 1273modify it under the same terms as Perl itself. 1274