Profile of /project/perl/lib/IO/Compress/Gzip.pm

File	/project/perl/lib/IO/Compress/Gzip.pm
Statements Executed	37
Statement Execution Time	5.56ms

Subroutines — ordered by exclusive time
Exclusive Time	Inclusive Time	Subroutine
0s	0s	IO::Compress::Gzip::::BEGINIO::Compress::Gzip::BEGIN
0s	0s	IO::Compress::Gzip::::__ANON__[:23]IO::Compress::Gzip::__ANON__[:23]
0s	0s	IO::Compress::Gzip::::ckParamsIO::Compress::Gzip::ckParams
0s	0s	IO::Compress::Gzip::::getExtraParamsIO::Compress::Gzip::getExtraParams
0s	0s	IO::Compress::Gzip::::getFileInfoIO::Compress::Gzip::getFileInfo
0s	0s	IO::Compress::Gzip::::getInverseClassIO::Compress::Gzip::getInverseClass
0s	0s	IO::Compress::Gzip::::gzipIO::Compress::Gzip::gzip
0s	0s	IO::Compress::Gzip::::mkFinalTrailerIO::Compress::Gzip::mkFinalTrailer
0s	0s	IO::Compress::Gzip::::mkHeaderIO::Compress::Gzip::mkHeader
0s	0s	IO::Compress::Gzip::::mkTrailerIO::Compress::Gzip::mkTrailer
0s	0s	IO::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
2					package IO::Compress::Gzip ;
3
4	1	5µs			require 5.004 ;
5
6	3	95µs	1	27µs	use strict ; # spent 27µs making 1 call to strict::import
7	3	78µs	1	117µs	use warnings; # spent 117µs making 1 call to warnings::import
8	3	97µs	1	14µs	use bytes; # spent 14µs making 1 call to bytes::import
9
10
11	3	624µs	2	366µs	use IO::Compress::RawDeflate 2.005 ; # spent 229µs making 1 call to UNIVERSAL::VERSION # spent 137µs making 1 call to Exporter::import
12
13	3	379µs	2	1.39ms	use Compress::Raw::Zlib 2.005 ; # spent 1.18ms making 1 call to Exporter::import # spent 212µs making 1 call to UNIVERSAL::VERSION
14	3	366µs	2	1.50ms	use 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
15	3	704µs	2	1.96ms	use IO::Compress::Gzip::Constants 2.005 ; # spent 1.71ms making 1 call to Exporter::import # spent 247µs making 1 call to UNIVERSAL::VERSION
16	3	751µs	2	377µs	use 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
18					BEGIN
19					{
20	1	11µs			if (defined &utf8::downgrade )
21					{ *noUTF8 = \&utf8::downgrade }
22					else
23					{ *noUTF8 = sub {} }
24	1	2.33ms			}
25
26	1	6µs			require Exporter ;
27
28	1	22µs			our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $GzipError);
29
30	1	5µs			$VERSION = '2.005';
31	1	4µs			$GzipError = '' ;
32
33	1	10µs			@ISA = qw(Exporter IO::Compress::RawDeflate);
34	1	6µs			@EXPORT_OK = qw( $GzipError gzip ) ;
35	1	17µs			%EXPORT_TAGS = %IO::Compress::RawDeflate::DEFLATE_CONSTANTS ;
36	1	8µs			push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
37	1	20µs	1	111µs	Exporter::export_ok_tags('all'); # spent 111µs making 1 call to Exporter::export_ok_tags
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	25µs			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