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