Profile: /opt/wise/lib/perl5/5.10.0/x86_64-linux-thread-multi/IO/Compress/Gzip.pm

File	/opt/wise/lib/perl5/5.10.0/x86_64-linux-thread-multi/IO/Compress/Gzip.pm
Statements Executed	37
Total Time	0.002213 seconds

Subroutines — ordered by exclusive time
Calls	P	F	Exclusive Time	Inclusive Time	Subroutine
0	0	0	0	0	IO::Compress::Gzip::	BEGIN
0	0	0	0	0	IO::Compress::Gzip::	__ANON__[:23]
0	0	0	0	0	IO::Compress::Gzip::	ckParams
0	0	0	0	0	IO::Compress::Gzip::	getExtraParams
0	0	0	0	0	IO::Compress::Gzip::	getFileInfo
0	0	0	0	0	IO::Compress::Gzip::	getInverseClass
0	0	0	0	0	IO::Compress::Gzip::	gzip
0	0	0	0	0	IO::Compress::Gzip::	mkFinalTrailer
0	0	0	0	0	IO::Compress::Gzip::	mkHeader
0	0	0	0	0	IO::Compress::Gzip::	mkTrailer
0	0	0	0	0	IO::Compress::Gzip::	new

Line	Stmts.	Exclusive Time	Avg.	Code
1
2				package IO::Compress::Gzip ;
3
4	1	1.6e-5	1.6e-5	require 5.004 ;
5
6	3	2.9e-5	9.7e-6	use strict ; # spent 10µs making 1 call to strict::import
7	3	3.5e-5	1.2e-5	use warnings; # spent 40µs making 1 call to warnings::import
8	3	2.9e-5	9.7e-6	use bytes; # spent 8µs making 1 call to bytes::import
9
10
11	3	0.00025	8.2e-5	use IO::Compress::RawDeflate 2.008 ; # spent 31µs making 1 call to Exporter::import # spent 18µs making 1 call to UNIVERSAL::VERSION
12
13	3	5.9e-5	2.0e-5	use Compress::Raw::Zlib 2.008 ; # spent 220µs making 1 call to Exporter::import # spent 20µs making 1 call to UNIVERSAL::VERSION
14	3	5.3e-5	1.8e-5	use IO::Compress::Base::Common 2.008 qw(:Status :Parse createSelfTiedObject); # spent 226µs making 1 call to Exporter::import # spent 19µs making 1 call to UNIVERSAL::VERSION
15	3	0.00026	8.5e-5	use IO::Compress::Gzip::Constants 2.008 ; # spent 263µs making 1 call to Exporter::import # spent 19µs making 1 call to UNIVERSAL::VERSION
16	3	0.00026	8.6e-5	use IO::Compress::Zlib::Extra 2.008 ; # spent 17µs making 1 call to UNIVERSAL::VERSION # spent 3µs making 1 call to import
17
18				BEGIN
19				{
20	1	3.0e-6	3.0e-6	if (defined &utf8::downgrade )
21				{ *noUTF8 = \&utf8::downgrade }
22				else
23				{ *noUTF8 = sub {} }
24	1	0.00117	0.00117	}
25
26	1	1.0e-6	1.0e-6	require Exporter ;
27
28	1	1.0e-6	1.0e-6	our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $GzipError);
29
30	1	1.0e-6	1.0e-6	$VERSION = '2.008';
31	1	0	0	$GzipError = '' ;
32
33	1	1.3e-5	1.3e-5	@ISA = qw(Exporter IO::Compress::RawDeflate);
34	1	1.0e-6	1.0e-6	@EXPORT_OK = qw( $GzipError gzip ) ;
35	1	4.0e-6	4.0e-6	%EXPORT_TAGS = %IO::Compress::RawDeflate::DEFLATE_CONSTANTS ;
36	1	2.0e-6	2.0e-6	push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
37	1	2.2e-5	2.2e-5	Exporter::export_ok_tags('all'); # spent 49µ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	1.1e-5	1.1e-5	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