← Index
NYTProf Performance Profile   « block view • line view • sub view »
For ddd2.pl
  Run on Tue May 25 16:52:24 2010
Reported on Tue May 25 16:56:45 2010

File /project/perl/lib/IO/Compress/Gzip.pm
Statements Executed 37
Statement Execution Time 5.56ms
Subroutines — ordered by exclusive time
Calls P F Exclusive
Time		 Inclusive
Time		 Subroutine
0000s0sIO::Compress::Gzip::::BEGINIO::Compress::Gzip::BEGIN
0000s0sIO::Compress::Gzip::::__ANON__[:23]IO::Compress::Gzip::__ANON__[:23]
0000s0sIO::Compress::Gzip::::ckParamsIO::Compress::Gzip::ckParams
0000s0sIO::Compress::Gzip::::getExtraParamsIO::Compress::Gzip::getExtraParams
0000s0sIO::Compress::Gzip::::getFileInfoIO::Compress::Gzip::getFileInfo
0000s0sIO::Compress::Gzip::::getInverseClassIO::Compress::Gzip::getInverseClass
0000s0sIO::Compress::Gzip::::gzipIO::Compress::Gzip::gzip
0000s0sIO::Compress::Gzip::::mkFinalTrailerIO::Compress::Gzip::mkFinalTrailer
0000s0sIO::Compress::Gzip::::mkHeaderIO::Compress::Gzip::mkHeader
0000s0sIO::Compress::Gzip::::mkTrailerIO::Compress::Gzip::mkTrailer
0000s0sIO::Compress::Gzip::::newIO::Compress::Gzip::new
Call graph for these subroutines as a Graphviz dot language file.
Line State
ments		 Time
on line		 Calls Time
in subs		 Code
1
2package IO::Compress::Gzip ;
3
415µsrequire 5.004 ;
5
6395µs127µsuse strict ;
# spent 27µs making 1 call to strict::import
7378µs1117µsuse warnings;
# spent 117µs making 1 call to warnings::import
8397µs114µsuse bytes;
# spent 14µs making 1 call to bytes::import
9
10
113624µs2366µsuse IO::Compress::RawDeflate 2.005 ;
# spent 229µs making 1 call to UNIVERSAL::VERSION # spent 137µs making 1 call to Exporter::import
12
133379µs21.39msuse Compress::Raw::Zlib 2.005 ;
# spent 1.18ms making 1 call to Exporter::import # spent 212µs making 1 call to UNIVERSAL::VERSION
143366µs21.50msuse IO::Compress::Base::Common 2.005 qw(:Status :Parse createSelfTiedObject);
# spent 1.29ms making 1 call to Exporter::import # spent 207µs making 1 call to UNIVERSAL::VERSION
153704µs21.96msuse IO::Compress::Gzip::Constants 2.005 ;
# spent 1.71ms making 1 call to Exporter::import # spent 247µs making 1 call to UNIVERSAL::VERSION
163751µs2377µsuse IO::Compress::Zlib::Extra 2.005 ;
# spent 238µs making 1 call to UNIVERSAL::VERSION # spent 139µs making 1 call to Exporter::import
17
18BEGIN
19{
20111µs if (defined &utf8::downgrade )
21 { *noUTF8 = \&utf8::downgrade }
22 else
23 { *noUTF8 = sub {} }
2412.33ms}
25
2616µsrequire Exporter ;
27
28122µsour ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $GzipError);
29
3015µs$VERSION = '2.005';
3114µs$GzipError = '' ;
32
33110µs@ISA = qw(Exporter IO::Compress::RawDeflate);
3416µs@EXPORT_OK = qw( $GzipError gzip ) ;
35117µs%EXPORT_TAGS = %IO::Compress::RawDeflate::DEFLATE_CONSTANTS ;
3618µspush @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
37120µs1111µsExporter::export_ok_tags('all');
# spent 111µs making 1 call to Exporter::export_ok_tags
38
39sub new
40{
41 my $class = shift ;
42
43 my $obj = createSelfTiedObject($class, \$GzipError);
44
45 $obj->_create(undef, @_);
46}
47
48
49sub 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
62sub 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
85sub 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
162sub mkTrailer
163{
164 my $self = shift ;
165 return pack("V V", *$self->{Compress}->crc32(),
166 *$self->{UnCompSize}->get32bit());
167}
168
169sub getInverseClass
170{
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 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
191sub 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
266sub mkFinalTrailer
267{
268 return '';
269}
270
271125µs1;
272
273__END__
274
275=head1 NAME
276
277
278
279IO::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
330This module provides a Perl interface that allows writing compressed
331data to files or buffer as defined in RFC 1952.
332
333
334
335
336
337All the gzip headers defined in RFC 1952 can be created using
338this module.
339
340
341
342
343
344
345
346For reading RFC 1952 files/buffers, see the companion module
347L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>.
348
349
350=head1 Functional Interface
351
352A top-level function, C<gzip>, is provided to carry out
353"one-shot" compression between buffers and/or files. For finer
354control over the compression process, see the L</"OO Interface">
355section.
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
364The functional interface needs Perl5.005 or better.
365
366
367=head2 gzip $input => $output [, OPTS]
368
369
370C<gzip> expects at least two parameters, C<$input> and C<$output>.
371
372=head3 The C<$input> parameter
373
374The parameter, C<$input>, is used to define the source of
375the uncompressed data.
376
377It can take one of the following forms:
378
379=over 5
380
381=item A filename
382
383If the C<$input> parameter is a simple scalar, it is assumed to be a
384filename. This file will be opened for reading and the input data
385will be read from it.
386
387=item A filehandle
388
389If the C<$input> parameter is a filehandle, the input data will be
390read from it.
391The string '-' can be used as an alias for standard input.
392
393=item A scalar reference
394
395If C<$input> is a scalar reference, the input data will be read
396from C<$$input>.
397
398=item An array reference
399
400If C<$input> is an array reference, each element in the array must be a
401filename.
402
403The input data will be read from each file in turn.
404
405The complete array will be walked to ensure that it only
406contains valid filenames before any data is compressed.
407
408
409
410=item An Input FileGlob string
411
412If C<$input> is a string that is delimited by the characters "<" and ">"
413C<gzip> will assume that it is an I<input fileglob string>. The
414input is the list of files that match the fileglob.
415
416If the fileglob does not match any files ...
417
418See L<File::GlobMapper|File::GlobMapper> for more details.
419
420
421=back
422
423If the C<$input> parameter is any other type, C<undef> will be returned.
424
425
426In addition, if C<$input> is a simple filename, the default values for
427the C<Name> and C<Time> options will be sourced from that file.
428
429If you do not want to use these defaults they can be overridden by
430explicitly setting the C<Name> and C<Time> options or by setting the
431C<Minimal> parameter.
432
433
434
435=head3 The C<$output> parameter
436
437The parameter C<$output> is used to control the destination of the
438compressed data. This parameter can take one of these forms.
439
440=over 5
441
442=item A filename
443
444If the C<$output> parameter is a simple scalar, it is assumed to be a
445filename. This file will be opened for writing and the compressed
446data will be written to it.
447
448=item A filehandle
449
450If the C<$output> parameter is a filehandle, the compressed data
451will be written to it.
452The string '-' can be used as an alias for standard output.
453
454
455=item A scalar reference
456
457If C<$output> is a scalar reference, the compressed data will be
458stored in C<$$output>.
459
460
461
462=item An Array Reference
463
464If C<$output> is an array reference, the compressed data will be
465pushed onto the array.
466
467=item An Output FileGlob
468
469If C<$output> is a string that is delimited by the characters "<" and ">"
470C<gzip> will assume that it is an I<output fileglob string>. The
471output is the list of files that match the fileglob.
472
473When C<$output> is an fileglob string, C<$input> must also be a fileglob
474string. Anything else is an error.
475
476=back
477
478If the C<$output> parameter is any other type, C<undef> will be returned.
479
480
481
482=head2 Notes
483
484
485
486When C<$input> maps to multiple files/buffers and C<$output> is a single
487file/buffer the input files/buffers will be stored
488in C<$output> as a concatenated series of compressed data streams.
489
490
491
492
493
494
495=head2 Optional Parameters
496
497Unless specified below, the optional parameters for C<gzip>,
498C<OPTS>, are the same as those used with the OO interface defined in the
499L</"Constructor Options"> section below.
500
501=over 5
502
503=item C<< AutoClose => 0|1 >>
504
505This option applies to any input or output data streams to
506C<gzip> that are filehandles.
507
508If C<AutoClose> is specified, and the value is true, it will result in all
509input and/or output filehandles being closed once C<gzip> has
510completed.
511
512This parameter defaults to 0.
513
514
515=item C<< BinModeIn => 0|1 >>
516
517When reading from a file or filehandle, set C<binmode> before reading.
518
519Defaults to 0.
520
521
522
523
524
525=item C<< Append => 0|1 >>
526
527TODO
528
529
530
531=back
532
533
534
535=head2 Examples
536
537To read the contents of the file C<file1.txt> and write the compressed
538data 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
549To read from an existing Perl filehandle, C<$input>, and write the
550compressed 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
563To compress all files in the directory "/my/home" that match "*.txt"
564and 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
573and 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
591The 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
596It returns an C<IO::Compress::Gzip> object on success and undef on failure.
597The variable C<$GzipError> will contain an error message on failure.
598
599If you are running Perl 5.005 or better the object, C<$z>, returned from
600IO::Compress::Gzip can be used exactly like an L<IO::File|IO::File> filehandle.
601This means that all normal output file operations can be carried out
602with C<$z>.
603For example, to write to a compressed file/buffer you can use either of
604these forms
605
606 $z->print("hello world\n");
607 print $z "hello world\n";
608
609The mandatory parameter C<$output> is used to control the destination
610of the compressed data. This parameter can take one of these forms.
611
612=over 5
613
614=item A filename
615
616If the C<$output> parameter is a simple scalar, it is assumed to be a
617filename. This file will be opened for writing and the compressed data
618will be written to it.
619
620=item A filehandle
621
622If the C<$output> parameter is a filehandle, the compressed data will be
623written to it.
624The string '-' can be used as an alias for standard output.
625
626
627=item A scalar reference
628
629If C<$output> is a scalar reference, the compressed data will be stored
630in C<$$output>.
631
632=back
633
634If the C<$output> parameter is any other type, C<IO::Compress::Gzip>::new will
635return undef.
636
637=head2 Constructor Options
638
639C<OPTS> is any combination of the following options:
640
641=over 5
642
643=item C<< AutoClose => 0|1 >>
644
645This option is only valid when the C<$output> parameter is a filehandle. If
646specified, and the value is true, it will result in the C<$output> being
647closed once either the C<close> method is called or the C<IO::Compress::Gzip>
648object is destroyed.
649
650This parameter defaults to 0.
651
652=item C<< Append => 0|1 >>
653
654Opens C<$output> in append mode.
655
656The behaviour of this option is dependent on the type of C<$output>.
657
658=over 5
659
660=item * A Buffer
661
662If C<$output> is a buffer and C<Append> is enabled, all compressed data
663will be append to the end if C<$output>. Otherwise C<$output> will be
664cleared before any data is written to it.
665
666=item * A Filename
667
668If C<$output> is a filename and C<Append> is enabled, the file will be
669opened in append mode. Otherwise the contents of the file, if any, will be
670truncated before any compressed data is written to it.
671
672=item * A Filehandle
673
674If C<$output> is a filehandle, the file pointer will be positioned to the
675end of the file via a call to C<seek> before any compressed data is written
676to it. Otherwise the file pointer will not be moved.
677
678=back
679
680This parameter defaults to 0.
681
682
683
684
685
686=item C<< Merge => 0|1 >>
687
688This option is used to compress input data and append it to an existing
689compressed data stream in C<$output>. The end result is a single compressed
690data stream stored in C<$output>.
691
692
693
694It is a fatal error to attempt to use this option when C<$output> is not an
695RFC 1952 data stream.
696
697
698
699There are a number of other limitations with the C<Merge> option:
700
701=over 5
702
703=item 1
704
705This module needs to have been built with zlib 1.2.1 or better to work. A
706fatal error will be thrown if C<Merge> is used with an older version of
707zlib.
708
709=item 2
710
711If C<$output> is a file or a filehandle, it must be seekable.
712
713=back
714
715
716This parameter defaults to 0.
717
718
719
720=item -Level
721
722Defines the compression level used by zlib. The value should either be
723a number between 0 and 9 (0 means no compression and 9 is maximum
724compression), 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
731The default is Z_DEFAULT_COMPRESSION.
732
733Note, 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
741Defines the strategy used to tune the compression. Use one of the symbolic
742constants defined below.
743
744 Z_FILTERED
745 Z_HUFFMAN_ONLY
746 Z_RLE
747 Z_FIXED
748 Z_DEFAULT_STRATEGY
749
750The default is Z_DEFAULT_STRATEGY.
751
752
753
754
755
756
757=item C<< Minimal => 0|1 >>
758
759If specified, this option will force the creation of the smallest possible
760compliant gzip header (which is exactly 10 bytes long) as defined in
761RFC 1952.
762
763See the section titled "Compliance" in RFC 1952 for a definition
764of the values used for the fields in the gzip header.
765
766All other parameters that control the content of the gzip header will
767be ignored if this parameter is set to 1.
768
769This parameter defaults to 0.
770
771=item C<< Comment => $comment >>
772
773Stores the contents of C<$comment> in the COMMENT field in
774the gzip header.
775By default, no comment field is written to the gzip file.
776
777If the C<-Strict> option is enabled, the comment can only consist of ISO
7788859-1 characters plus line feed.
779
780If the C<-Strict> option is disabled, the comment field can contain any
781character except NULL. If any null characters are present, the field
782will be truncated at the first NULL.
783
784=item C<< Name => $string >>
785
786Stores the contents of C<$string> in the gzip NAME header field. If
787C<Name> is not specified, no gzip NAME field will be created.
788
789If the C<-Strict> option is enabled, C<$string> can only consist of ISO
7908859-1 characters.
791
792If C<-Strict> is disabled, then C<$string> can contain any character
793except NULL. If any null characters are present, the field will be
794truncated at the first NULL.
795
796=item C<< Time => $number >>
797
798Sets the MTIME field in the gzip header to $number.
799
800This field defaults to the time the C<IO::Compress::Gzip> object was created
801if this option is not specified.
802
803=item C<< TextFlag => 0|1 >>
804
805This parameter controls the setting of the FLG.FTEXT bit in the gzip
806header. It is used to signal that the data stored in the gzip file/buffer
807is probably text.
808
809The default is 0.
810
811=item C<< HeaderCRC => 0|1 >>
812
813When true this parameter will set the FLG.FHCRC bit to 1 in the gzip header
814and set the CRC16 header field to the CRC of the complete gzip header
815except the CRC16 field itself.
816
817B<Note> that gzip files created with the C<HeaderCRC> flag set to 1 cannot
818be read by most, if not all, of the the standard gunzip utilities, most
819notably gzip version 1.2.4. You should therefore avoid using this option if
820you want to maximize the portability of your gzip files.
821
822This parameter defaults to 0.
823
824=item C<< OS_Code => $value >>
825
826Stores C<$value> in the gzip OS header field. A number between 0 and 255 is
827valid.
828
829If not specified, this parameter defaults to the OS code of the Operating
830System this module was built on. The value 3 is used as a catch-all for all
831Unix variants and unknown Operating Systems.
832
833=item C<< ExtraField => $data >>
834
835This parameter allows additional metadata to be stored in the ExtraField in
836the gzip header. An RFC 1952 compliant ExtraField consists of zero or more
837subfields. Each subfield consists of a two byte header followed by the
838subfield data.
839
840The 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
855Where C<$id1>, C<$id2> are two byte subfield ID's. The second byte of
856the ID cannot be 0, unless the C<Strict> option has been disabled.
857
858If you use the hash syntax, you have no control over the order in which
859the ExtraSubFields are stored, plus you cannot have SubFields with
860duplicate ID.
861
862Alternatively the list of subfields can by supplied as a scalar, thus
863
864 -ExtraField => $rawdata
865
866If you use the raw format, and the C<Strict> option is enabled,
867C<IO::Compress::Gzip> will check that C<$rawdata> consists of zero or more
868conformant sub-fields. When C<Strict> is disabled, C<$rawdata> can
869consist of any arbitrary byte stream.
870
871The maximum size of the Extra Field 65535 bytes.
872
873=item C<< ExtraFlags => $value >>
874
875Sets the XFL byte in the gzip header to C<$value>.
876
877If this option is not present, the value stored in XFL field will be
878determined by the setting of the C<Level> option.
879
880If C<< Level => Z_BEST_SPEED >> has been specified then XFL is set to 2.
881If C<< Level => Z_BEST_COMPRESSION >> has been specified then XFL is set to 4.
882Otherwise XFL is set to 0.
883
884
885
886=item C<< Strict => 0|1 >>
887
888
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
960
961=back
962
963=head2 Examples
964
965TODO
966
967=head1 Methods
968
969=head2 print
970
971Usage is
972
973 $z->print($data)
974 print $z $data
975
976Compresses and outputs the contents of the C<$data> parameter. This
977has the same behaviour as the C<print> built-in.
978
979Returns true if successful.
980
981=head2 printf
982
983Usage is
984
985 $z->printf($format, $data)
986 printf $z $format, $data
987
988Compresses and outputs the contents of the C<$data> parameter.
989
990Returns true if successful.
991
992=head2 syswrite
993
994Usage is
995
996 $z->syswrite $data
997 $z->syswrite $data, $length
998 $z->syswrite $data, $length, $offset
999
1000Compresses and outputs the contents of the C<$data> parameter.
1001
1002Returns the number of uncompressed bytes written, or C<undef> if
1003unsuccessful.
1004
1005=head2 write
1006
1007Usage is
1008
1009 $z->write $data
1010 $z->write $data, $length
1011 $z->write $data, $length, $offset
1012
1013Compresses and outputs the contents of the C<$data> parameter.
1014
1015Returns the number of uncompressed bytes written, or C<undef> if
1016unsuccessful.
1017
1018=head2 flush
1019
1020Usage is
1021
1022
1023 $z->flush;
1024 $z->flush($flush_type);
1025
1026
1027Flushes any pending compressed data to the output file/buffer.
1028
1029
1030This method takes an optional parameter, C<$flush_type>, that controls
1031how the flushing will be carried out. By default the C<$flush_type>
1032used is C<Z_FINISH>. Other valid values for C<$flush_type> are
1033C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
1034strongly recommended that you only set the C<flush_type> parameter if
1035you fully understand the implications of what it does - overuse of C<flush>
1036can seriously degrade the level of compression achieved. See the C<zlib>
1037documentation for details.
1038
1039
1040Returns true on success.
1041
1042
1043=head2 tell
1044
1045Usage is
1046
1047 $z->tell()
1048 tell $z
1049
1050Returns the uncompressed file offset.
1051
1052=head2 eof
1053
1054Usage is
1055
1056 $z->eof();
1057 eof($z);
1058
1059
1060
1061Returns 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
1073Provides a sub-set of the C<seek> functionality, with the restriction
1074that it is only legal to seek forward in the output file/buffer.
1075It is a fatal error to attempt to seek backward.
1076
1077Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
1078
1079
1080
1081The C<$whence> parameter takes one the usual values, namely SEEK_SET,
1082SEEK_CUR or SEEK_END.
1083
1084Returns 1 on success, 0 on failure.
1085
1086=head2 binmode
1087
1088Usage is
1089
1090 $z->binmode
1091 binmode $z ;
1092
1093This is a noop provided for completeness.
1094
1095=head2 opened
1096
1097 $z->opened()
1098
1099Returns 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
1106If the C<$z> object is associated with a file or a filehandle, this method
1107returns the current autoflush setting for the underlying filehandle. If
1108C<EXPR> is present, and is non-zero, it will enable flushing after every
1109write/print operation.
1110
1111If C<$z> is associated with a buffer, this method has no effect and always
1112returns C<undef>.
1113
1114B<Note> that the special variable C<$|> B<cannot> be used to set or
1115retrieve the autoflush setting.
1116
1117=head2 input_line_number
1118
1119 $z->input_line_number()
1120 $z->input_line_number(EXPR)
1121
1122
1123This method always returns C<undef> when compressing.
1124
1125
1126
1127=head2 fileno
1128
1129 $z->fileno()
1130 fileno($z)
1131
1132If the C<$z> object is associated with a file or a filehandle, this method
1133will return the underlying file descriptor.
1134
1135If the C<$z> object is is associated with a buffer, this method will
1136return undef.
1137
1138=head2 close
1139
1140 $z->close() ;
1141 close $z ;
1142
1143
1144
1145Flushes any pending compressed data and then closes the output file/buffer.
1146
1147
1148
1149For most versions of Perl this method will be automatically invoked if
1150the IO::Compress::Gzip object is destroyed (either explicitly or by the
1151variable with the reference to the object going out of scope). The
1152exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1153these cases, the C<close> method will be called automatically, but
1154not until global destruction of all live objects when the program is
1155terminating.
1156
1157Therefore, if you want your scripts to be able to run on all versions
1158of Perl, you should call C<close> explicitly and not rely on automatic
1159closing.
1160
1161Returns true on success, otherwise 0.
1162
1163If the C<AutoClose> option has been enabled when the IO::Compress::Gzip
1164object was created, and the object is associated with a file, the
1165underlying file will also be closed.
1166
1167
1168
1169
1170=head2 newStream([OPTS])
1171
1172Usage is
1173
1174 $z->newStream( [OPTS] )
1175
1176Closes the current compressed data stream and starts a new one.
1177
1178OPTS consists of any of the the options that are available when creating
1179the C<$z> object.
1180
1181See the L</"Constructor Options"> section for more details.
1182
1183
1184=head2 deflateParams
1185
1186Usage is
1187
1188 $z->deflateParams
1189
1190TODO
1191
1192
1193=head1 Importing
1194
1195
1196A number of symbolic constants are required by some methods in
1197C<IO::Compress::Gzip>. None are imported by default.
1198
1199
1200
1201=over 5
1202
1203=item :all
1204
1205
1206Imports C<gzip>, C<$GzipError> and all symbolic
1207constants 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
1213Import all symbolic constants. Same as doing this
1214
1215
1216 use IO::Compress::Gzip qw(:flush :level :strategy) ;
1217
1218
1219=item :flush
1220
1221These 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
1232These 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
1242These 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
1255For
1256
1257=head1 EXAMPLES
1258
1259TODO
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271=head1 SEE ALSO
1272
1273L<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
1275L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1276
1277L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1278L<Archive::Tar|Archive::Tar>,
1279L<IO::Zlib|IO::Zlib>
1280
1281
1282For RFC 1950, 1951 and 1952 see
1283F<http://www.faqs.org/rfcs/rfc1950.html>,
1284F<http://www.faqs.org/rfcs/rfc1951.html> and
1285F<http://www.faqs.org/rfcs/rfc1952.html>
1286
1287The I<zlib> compression library was written by Jean-loup Gailly
1288F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1289
1290The primary site for the I<zlib> compression library is
1291F<http://www.zlib.org>.
1292
1293The primary site for gzip is F<http://www.gzip.org>.
1294
1295
1296
1297
1298=head1 AUTHOR
1299
1300This module was written by Paul Marquess, F<pmqs@cpan.org>.
1301
1302
1303
1304=head1 MODIFICATION HISTORY
1305
1306See the Changes file.
1307
1308=head1 COPYRIGHT AND LICENSE
1309
1310Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
1311
1312This program is free software; you can redistribute it and/or
1313modify it under the same terms as Perl itself.
1314
1315
Report produced by the NYTProf 3.11 Perl profiler, developed by Tim Bunce and Adam Kaplan.