Profile of /project/perl/lib/IO/Uncompress/Gunzip.pm

File	/project/perl/lib/IO/Uncompress/Gunzip.pm
Statements Executed	38
Statement Execution Time	5.45ms

Subroutines — ordered by exclusive time
Exclusive Time	Inclusive Time	Subroutine
0s	0s	IO::Uncompress::Gunzip::::BEGINIO::Uncompress::Gunzip::BEGIN
0s	0s	IO::Uncompress::Gunzip::_readFullGzipHeader
0s	0s	IO::Uncompress::Gunzip::_readGzipHeader
0s	0s	IO::Uncompress::Gunzip::::chkTrailerIO::Uncompress::Gunzip::chkTrailer
0s	0s	IO::Uncompress::Gunzip::::ckMagicIO::Uncompress::Gunzip::ckMagic
0s	0s	IO::Uncompress::Gunzip::::ckParamsIO::Uncompress::Gunzip::ckParams
0s	0s	IO::Uncompress::Gunzip::getExtraParams
0s	0s	IO::Uncompress::Gunzip::::gunzipIO::Uncompress::Gunzip::gunzip
0s	0s	IO::Uncompress::Gunzip::::isGzipMagicIO::Uncompress::Gunzip::isGzipMagic
0s	0s	IO::Uncompress::Gunzip::::newIO::Uncompress::Gunzip::new
0s	0s	IO::Uncompress::Gunzip::::readHeaderIO::Uncompress::Gunzip::readHeader

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::Uncompress::Gunzip ;
3
4	1	5µs			require 5.004 ;
5
6					# for RFC1952
7
8	3	90µs	1	24µs	use strict ; # spent 24µs making 1 call to strict::import
9	3	86µs	1	108µs	use warnings; # spent 108µs making 1 call to warnings::import
10	3	86µs	1	14µs	use bytes; # spent 14µs making 1 call to bytes::import
11
12	3	667µs	2	354µs	use IO::Uncompress::RawInflate 2.005 ; # spent 213µs making 1 call to UNIVERSAL::VERSION # spent 141µs making 1 call to Exporter::import
13
14	3	389µs	2	416µs	use Compress::Raw::Zlib 2.005 qw( crc32 ) ; # spent 225µs making 1 call to UNIVERSAL::VERSION # spent 191µs making 1 call to Exporter::import
15	3	375µs	2	1.07ms	use IO::Compress::Base::Common 2.005 qw(:Status createSelfTiedObject); # spent 866µs making 1 call to Exporter::import # spent 205µs making 1 call to UNIVERSAL::VERSION
16	3	376µs	2	1.91ms	use IO::Compress::Gzip::Constants 2.005 ; # spent 1.70ms making 1 call to Exporter::import # spent 216µs making 1 call to UNIVERSAL::VERSION
17	3	836µs	2	341µs	use IO::Compress::Zlib::Extra 2.005 ; # spent 210µs making 1 call to UNIVERSAL::VERSION # spent 131µs making 1 call to Exporter::import
18
19	1	6µs			require Exporter ;
20
21	1	6µs			our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $GunzipError);
22
23	1	13µs			@ISA = qw( Exporter IO::Uncompress::RawInflate );
24	1	7µs			@EXPORT_OK = qw( $GunzipError gunzip );
25	1	7µs			%EXPORT_TAGS = %IO::Uncompress::RawInflate::DEFLATE_CONSTANTS ;
26	1	9µs			push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
27	1	21µs	1	110µs	Exporter::export_ok_tags('all'); # spent 110µs making 1 call to Exporter::export_ok_tags
28
29	1	5µs			$GunzipError = '';
30
31	1	5µs			$VERSION = '2.005';
32
33					sub new
34					{
35					my $class = shift ;
36					$GunzipError = '';
37					my $obj = createSelfTiedObject($class, \$GunzipError);
38
39					$obj->_create(undef, 0, @_);
40					}
41
42					sub gunzip
43					{
44					my $obj = createSelfTiedObject(undef, \$GunzipError);
45					return $obj->_inf(@_) ;
46					}
47
48					sub getExtraParams
49					{
50	3	2.43ms	2	1.13ms	use IO::Compress::Base::Common 2.005 qw(:Parse); # spent 909µs making 1 call to Exporter::import # spent 217µs making 1 call to UNIVERSAL::VERSION
51					return ( 'ParseExtra' => [1, 1, Parse_boolean, 0] ) ;
52					}
53
54					sub ckParams
55					{
56					my $self = shift ;
57					my $got = shift ;
58
59					# gunzip always needs crc32
60					$got->value('CRC32' => 1);
61
62					return 1;
63					}
64
65					sub ckMagic
66					{
67					my $self = shift;
68
69					my $magic ;
70					$self->smartReadExact(\$magic, GZIP_ID_SIZE);
71
72					*$self->{HeaderPending} = $magic ;
73
74					return $self->HeaderError("Minimum header size is " .
75					GZIP_MIN_HEADER_SIZE . " bytes")
76					if length $magic != GZIP_ID_SIZE ;
77
78					return $self->HeaderError("Bad Magic")
79					if ! isGzipMagic($magic) ;
80
81					*$self->{Type} = 'rfc1952';
82
83					return $magic ;
84					}
85
86					sub readHeader
87					{
88					my $self = shift;
89					my $magic = shift;
90
91					return $self->_readGzipHeader($magic);
92					}
93
94					sub chkTrailer
95					{
96					my $self = shift;
97					my $trailer = shift;
98
99					# Check CRC & ISIZE
100					my ($CRC32, $ISIZE) = unpack("V V", $trailer) ;
101					*$self->{Info}{CRC32} = $CRC32;
102					*$self->{Info}{ISIZE} = $ISIZE;
103
104					if (*$self->{Strict}) {
105					return $self->TrailerError("CRC mismatch")
106					if $CRC32 != *$self->{Uncomp}->crc32() ;
107
108					my $exp_isize = *$self->{UnCompSize}->get32bit();
109					return $self->TrailerError("ISIZE mismatch. Got $ISIZE"
110					. ", expected $exp_isize")
111					if $ISIZE != $exp_isize ;
112					}
113
114					return STATUS_OK;
115					}
116
117					sub isGzipMagic
118					{
119					my $buffer = shift ;
120					return 0 if length $buffer < GZIP_ID_SIZE ;
121					my ($id1, $id2) = unpack("C C", $buffer) ;
122					return $id1 == GZIP_ID1 && $id2 == GZIP_ID2 ;
123					}
124
125					sub _readFullGzipHeader($)
126					{
127					my ($self) = @_ ;
128					my $magic = '' ;
129
130					$self->smartReadExact(\$magic, GZIP_ID_SIZE);
131
132					*$self->{HeaderPending} = $magic ;
133
134					return $self->HeaderError("Minimum header size is " .
135					GZIP_MIN_HEADER_SIZE . " bytes")
136					if length $magic != GZIP_ID_SIZE ;
137
138
139					return $self->HeaderError("Bad Magic")
140					if ! isGzipMagic($magic) ;
141
142					my $status = $self->_readGzipHeader($magic);
143					delete *$self->{Transparent} if ! defined $status ;
144					return $status ;
145					}
146
147					sub _readGzipHeader($)
148					{
149					my ($self, $magic) = @_ ;
150					my ($HeaderCRC) ;
151					my ($buffer) = '' ;
152
153					$self->smartReadExact(\$buffer, GZIP_MIN_HEADER_SIZE - GZIP_ID_SIZE)
154					or return $self->HeaderError("Minimum header size is " .
155					GZIP_MIN_HEADER_SIZE . " bytes") ;
156
157					my $keep = $magic . $buffer ;
158					*$self->{HeaderPending} = $keep ;
159
160					# now split out the various parts
161					my ($cm, $flag, $mtime, $xfl, $os) = unpack("C C V C C", $buffer) ;
162
163					$cm == GZIP_CM_DEFLATED
164					or return $self->HeaderError("Not Deflate (CM is $cm)") ;
165
166					# check for use of reserved bits
167					return $self->HeaderError("Use of Reserved Bits in FLG field.")
168					if $flag & GZIP_FLG_RESERVED ;
169
170					my $EXTRA ;
171					my @EXTRA = () ;
172					if ($flag & GZIP_FLG_FEXTRA) {
173					$EXTRA = "" ;
174					$self->smartReadExact(\$buffer, GZIP_FEXTRA_HEADER_SIZE)
175					or return $self->TruncatedHeader("FEXTRA Length") ;
176
177					my ($XLEN) = unpack("v", $buffer) ;
178					$self->smartReadExact(\$EXTRA, $XLEN)
179					or return $self->TruncatedHeader("FEXTRA Body");
180					$keep .= $buffer . $EXTRA ;
181
182					if ($XLEN && *$self->{'ParseExtra'}) {
183					my $bad = IO::Compress::Zlib::Extra::parseRawExtra($EXTRA,
184					\@EXTRA, 1, 1);
185					return $self->HeaderError($bad)
186					if defined $bad;
187					}
188					}
189
190					my $origname ;
191					if ($flag & GZIP_FLG_FNAME) {
192					$origname = "" ;
193					while (1) {
194					$self->smartReadExact(\$buffer, 1)
195					or return $self->TruncatedHeader("FNAME");
196					last if $buffer eq GZIP_NULL_BYTE ;
197					$origname .= $buffer
198					}
199					$keep .= $origname . GZIP_NULL_BYTE ;
200
201					return $self->HeaderError("Non ISO 8859-1 Character found in Name")
202					if *$self->{Strict} && $origname =~ /$GZIP_FNAME_INVALID_CHAR_RE/o ;
203					}
204
205					my $comment ;
206					if ($flag & GZIP_FLG_FCOMMENT) {
207					$comment = "";
208					while (1) {
209					$self->smartReadExact(\$buffer, 1)
210					or return $self->TruncatedHeader("FCOMMENT");
211					last if $buffer eq GZIP_NULL_BYTE ;
212					$comment .= $buffer
213					}
214					$keep .= $comment . GZIP_NULL_BYTE ;
215
216					return $self->HeaderError("Non ISO 8859-1 Character found in Comment")
217					if *$self->{Strict} && $comment =~ /$GZIP_FCOMMENT_INVALID_CHAR_RE/o ;
218					}
219
220					if ($flag & GZIP_FLG_FHCRC) {
221					$self->smartReadExact(\$buffer, GZIP_FHCRC_SIZE)
222					or return $self->TruncatedHeader("FHCRC");
223
224					$HeaderCRC = unpack("v", $buffer) ;
225					my $crc16 = crc32($keep) & 0xFF ;
226
227					return $self->HeaderError("CRC16 mismatch.")
228					if *$self->{Strict} && $crc16 != $HeaderCRC;
229
230					$keep .= $buffer ;
231					}
232
233					# Assume compression method is deflated for xfl tests
234					#if ($xfl) {
235					#}
236
237					*$self->{Type} = 'rfc1952';
238
239					return {
240					'Type' => 'rfc1952',
241					'FingerprintLength' => 2,
242					'HeaderLength' => length $keep,
243					'TrailerLength' => GZIP_TRAILER_SIZE,
244					'Header' => $keep,
245					'isMinimalHeader' => $keep eq GZIP_MINIMUM_HEADER ? 1 : 0,
246
247					'MethodID' => $cm,
248					'MethodName' => $cm == GZIP_CM_DEFLATED ? "Deflated" : "Unknown" ,
249					'TextFlag' => $flag & GZIP_FLG_FTEXT ? 1 : 0,
250					'HeaderCRCFlag' => $flag & GZIP_FLG_FHCRC ? 1 : 0,
251					'NameFlag' => $flag & GZIP_FLG_FNAME ? 1 : 0,
252					'CommentFlag' => $flag & GZIP_FLG_FCOMMENT ? 1 : 0,
253					'ExtraFlag' => $flag & GZIP_FLG_FEXTRA ? 1 : 0,
254					'Name' => $origname,
255					'Comment' => $comment,
256					'Time' => $mtime,
257					'OsID' => $os,
258					'OsName' => defined $GZIP_OS_Names{$os}
259					? $GZIP_OS_Names{$os} : "Unknown",
260					'HeaderCRC' => $HeaderCRC,
261					'Flags' => $flag,
262					'ExtraFlags' => $xfl,
263					'ExtraFieldRaw' => $EXTRA,
264					'ExtraField' => [ @EXTRA ],
265
266
267					#'CompSize'=> $compsize,
268					#'CRC32'=> $CRC32,
269					#'OrigSize'=> $ISIZE,
270					}
271					}
272
273
274	1	27µs			1;
275
276					__END__
277
278
279					=head1 NAME
280
281
282
283					IO::Uncompress::Gunzip - Read RFC 1952 files/buffers
284
285
286
287					=head1 SYNOPSIS
288
289					use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
290
291					my $status = gunzip $input => $output [,OPTS]
292					or die "gunzip failed: $GunzipError\n";
293
294					my $z = new IO::Uncompress::Gunzip $input [OPTS]
295					or die "gunzip failed: $GunzipError\n";
296
297					$status = $z->read($buffer)
298					$status = $z->read($buffer, $length)
299					$status = $z->read($buffer, $length, $offset)
300					$line = $z->getline()
301					$char = $z->getc()
302					$char = $z->ungetc()
303					$char = $z->opened()
304
305					$status = $z->inflateSync()
306
307					$data = $z->trailingData()
308					$status = $z->nextStream()
309					$data = $z->getHeaderInfo()
310					$z->tell()
311					$z->seek($position, $whence)
312					$z->binmode()
313					$z->fileno()
314					$z->eof()
315					$z->close()
316
317					$GunzipError ;
318
319					# IO::File mode
320
321					<$z>
322					read($z, $buffer);
323					read($z, $buffer, $length);
324					read($z, $buffer, $length, $offset);
325					tell($z)
326					seek($z, $position, $whence)
327					binmode($z)
328					fileno($z)
329					eof($z)
330					close($z)
331
332
333					=head1 DESCRIPTION
334
335
336
337					This module provides a Perl interface that allows the reading of
338					files/buffers that conform to RFC 1952.
339
340					For writing RFC 1952 files/buffers, see the companion module IO::Compress::Gzip.
341
342
343
344
345
346					=head1 Functional Interface
347
348					A top-level function, C<gunzip>, is provided to carry out
349					"one-shot" uncompression between buffers and/or files. For finer
350					control over the uncompression process, see the L</"OO Interface">
351					section.
352
353					use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
354
355					gunzip $input => $output [,OPTS]
356					or die "gunzip failed: $GunzipError\n";
357
358
359
360					The functional interface needs Perl5.005 or better.
361
362
363					=head2 gunzip $input => $output [, OPTS]
364
365
366					C<gunzip> expects at least two parameters, C<$input> and C<$output>.
367
368					=head3 The C<$input> parameter
369
370					The parameter, C<$input>, is used to define the source of
371					the compressed data.
372
373					It can take one of the following forms:
374
375					=over 5
376
377					=item A filename
378
379					If the C<$input> parameter is a simple scalar, it is assumed to be a
380					filename. This file will be opened for reading and the input data
381					will be read from it.
382
383					=item A filehandle
384
385					If the C<$input> parameter is a filehandle, the input data will be
386					read from it.
387					The string '-' can be used as an alias for standard input.
388
389					=item A scalar reference
390
391					If C<$input> is a scalar reference, the input data will be read
392					from C<$$input>.
393
394					=item An array reference
395
396					If C<$input> is an array reference, each element in the array must be a
397					filename.
398
399					The input data will be read from each file in turn.
400
401					The complete array will be walked to ensure that it only
402					contains valid filenames before any data is uncompressed.
403
404
405
406					=item An Input FileGlob string
407
408					If C<$input> is a string that is delimited by the characters "<" and ">"
409					C<gunzip> will assume that it is an I<input fileglob string>. The
410					input is the list of files that match the fileglob.
411
412					If the fileglob does not match any files ...
413
414					See L<File::GlobMapper\|File::GlobMapper> for more details.
415
416
417					=back
418
419					If the C<$input> parameter is any other type, C<undef> will be returned.
420
421
422
423					=head3 The C<$output> parameter
424
425					The parameter C<$output> is used to control the destination of the
426					uncompressed data. This parameter can take one of these forms.
427
428					=over 5
429
430					=item A filename
431
432					If the C<$output> parameter is a simple scalar, it is assumed to be a
433					filename. This file will be opened for writing and the uncompressed
434					data will be written to it.
435
436					=item A filehandle
437
438					If the C<$output> parameter is a filehandle, the uncompressed data
439					will be written to it.
440					The string '-' can be used as an alias for standard output.
441
442
443					=item A scalar reference
444
445					If C<$output> is a scalar reference, the uncompressed data will be
446					stored in C<$$output>.
447
448
449
450					=item An Array Reference
451
452					If C<$output> is an array reference, the uncompressed data will be
453					pushed onto the array.
454
455					=item An Output FileGlob
456
457					If C<$output> is a string that is delimited by the characters "<" and ">"
458					C<gunzip> will assume that it is an I<output fileglob string>. The
459					output is the list of files that match the fileglob.
460
461					When C<$output> is an fileglob string, C<$input> must also be a fileglob
462					string. Anything else is an error.
463
464					=back
465
466					If the C<$output> parameter is any other type, C<undef> will be returned.
467
468
469
470					=head2 Notes
471
472
473					When C<$input> maps to multiple compressed files/buffers and C<$output> is
474					a single file/buffer, after uncompression C<$output> will contain a
475					concatenation of all the uncompressed data from each of the input
476					files/buffers.
477
478
479
480
481
482					=head2 Optional Parameters
483
484					Unless specified below, the optional parameters for C<gunzip>,
485					C<OPTS>, are the same as those used with the OO interface defined in the
486					L</"Constructor Options"> section below.
487
488					=over 5
489
490					=item C<< AutoClose => 0\|1 >>
491
492					This option applies to any input or output data streams to
493					C<gunzip> that are filehandles.
494
495					If C<AutoClose> is specified, and the value is true, it will result in all
496					input and/or output filehandles being closed once C<gunzip> has
497					completed.
498
499					This parameter defaults to 0.
500
501
502					=item C<< BinModeOut => 0\|1 >>
503
504					When writing to a file or filehandle, set C<binmode> before writing to the
505					file.
506
507					Defaults to 0.
508
509
510
511
512
513					=item C<< Append => 0\|1 >>
514
515					TODO
516
517					=item C<< MultiStream => 0\|1 >>
518
519
520					If the input file/buffer contains multiple compressed data streams, this
521					option will uncompress the whole lot as a single data stream.
522
523					Defaults to 0.
524
525
526
527
528
529					=item C<< TrailingData => $scalar >>
530
531					Returns the data, if any, that is present immediately after the compressed
532					data stream once uncompression is complete.
533
534					This option can be used when there is useful information immediately
535					following the compressed data stream, and you don't know the length of the
536					compressed data stream.
537
538					If the input is a buffer, C<trailingData> will return everything from the
539					end of the compressed data stream to the end of the buffer.
540
541					If the input is a filehandle, C<trailingData> will return the data that is
542					left in the filehandle input buffer once the end of the compressed data
543					stream has been reached. You can then use the filehandle to read the rest
544					of the input file.
545
546					Don't bother using C<trailingData> if the input is a filename.
547
548
549
550					If you know the length of the compressed data stream before you start
551					uncompressing, you can avoid having to use C<trailingData> by setting the
552					C<InputLength> option.
553
554
555
556					=back
557
558
559
560
561					=head2 Examples
562
563					To read the contents of the file C<file1.txt.gz> and write the
564					compressed data to the file C<file1.txt>.
565
566					use strict ;
567					use warnings ;
568					use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
569
570					my $input = "file1.txt.gz";
571					my $output = "file1.txt";
572					gunzip $input => $output
573					or die "gunzip failed: $GunzipError\n";
574
575
576					To read from an existing Perl filehandle, C<$input>, and write the
577					uncompressed data to a buffer, C<$buffer>.
578
579					use strict ;
580					use warnings ;
581					use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
582					use IO::File ;
583
584					my $input = new IO::File "<file1.txt.gz"
585					or die "Cannot open 'file1.txt.gz': $!\n" ;
586					my $buffer ;
587					gunzip $input => \$buffer
588					or die "gunzip failed: $GunzipError\n";
589
590					To uncompress all files in the directory "/my/home" that match "*.txt.gz" and store the compressed data in the same directory
591
592					use strict ;
593					use warnings ;
594					use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
595
596					gunzip '</my/home/*.txt.gz>' => '</my/home/#1.txt>'
597					or die "gunzip failed: $GunzipError\n";
598
599					and if you want to compress each file one at a time, this will do the trick
600
601					use strict ;
602					use warnings ;
603					use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
604
605					for my $input ( glob "/my/home/*.txt.gz" )
606					{
607					my $output = $input;
608					$output =~ s/.gz// ;
609					gunzip $input => $output
610					or die "Error compressing '$input': $GunzipError\n";
611					}
612
613					=head1 OO Interface
614
615					=head2 Constructor
616
617					The format of the constructor for IO::Uncompress::Gunzip is shown below
618
619
620					my $z = new IO::Uncompress::Gunzip $input [OPTS]
621					or die "IO::Uncompress::Gunzip failed: $GunzipError\n";
622
623					Returns an C<IO::Uncompress::Gunzip> object on success and undef on failure.
624					The variable C<$GunzipError> will contain an error message on failure.
625
626					If you are running Perl 5.005 or better the object, C<$z>, returned from
627					IO::Uncompress::Gunzip can be used exactly like an L<IO::File\|IO::File> filehandle.
628					This means that all normal input file operations can be carried out with
629					C<$z>. For example, to read a line from a compressed file/buffer you can
630					use either of these forms
631
632					$line = $z->getline();
633					$line = <$z>;
634
635					The mandatory parameter C<$input> is used to determine the source of the
636					compressed data. This parameter can take one of three forms.
637
638					=over 5
639
640					=item A filename
641
642					If the C<$input> parameter is a scalar, it is assumed to be a filename. This
643					file will be opened for reading and the compressed data will be read from it.
644
645					=item A filehandle
646
647					If the C<$input> parameter is a filehandle, the compressed data will be
648					read from it.
649					The string '-' can be used as an alias for standard input.
650
651
652					=item A scalar reference
653
654					If C<$input> is a scalar reference, the compressed data will be read from
655					C<$$output>.
656
657					=back
658
659					=head2 Constructor Options
660
661
662					The option names defined below are case insensitive and can be optionally
663					prefixed by a '-'. So all of the following are valid
664
665					-AutoClose
666					-autoclose
667					AUTOCLOSE
668					autoclose
669
670					OPTS is a combination of the following options:
671
672					=over 5
673
674					=item C<< AutoClose => 0\|1 >>
675
676					This option is only valid when the C<$input> parameter is a filehandle. If
677					specified, and the value is true, it will result in the file being closed once
678					either the C<close> method is called or the IO::Uncompress::Gunzip object is
679					destroyed.
680
681					This parameter defaults to 0.
682
683					=item C<< MultiStream => 0\|1 >>
684
685
686
687					Allows multiple concatenated compressed streams to be treated as a single
688					compressed stream. Decompression will stop once either the end of the
689					file/buffer is reached, an error is encountered (premature eof, corrupt
690					compressed data) or the end of a stream is not immediately followed by the
691					start of another stream.
692
693					This parameter defaults to 0.
694
695
696					=item C<< Prime => $string >>
697
698					This option will uncompress the contents of C<$string> before processing the
699					input file/buffer.
700
701					This option can be useful when the compressed data is embedded in another
702					file/data structure and it is not possible to work out where the compressed
703					data begins without having to read the first few bytes. If this is the
704					case, the uncompression can be I<primed> with these bytes using this
705					option.
706
707					=item C<< Transparent => 0\|1 >>
708
709					If this option is set and the input file/buffer is not compressed data,
710					the module will allow reading of it anyway.
711
712					In addition, if the input file/buffer does contain compressed data and
713					there is non-compressed data immediately following it, setting this option
714					will make this module treat the whole file/bufffer as a single data stream.
715
716					This option defaults to 1.
717
718					=item C<< BlockSize => $num >>
719
720					When reading the compressed input data, IO::Uncompress::Gunzip will read it in
721					blocks of C<$num> bytes.
722
723					This option defaults to 4096.
724
725					=item C<< InputLength => $size >>
726
727					When present this option will limit the number of compressed bytes read
728					from the input file/buffer to C<$size>. This option can be used in the
729					situation where there is useful data directly after the compressed data
730					stream and you know beforehand the exact length of the compressed data
731					stream.
732
733					This option is mostly used when reading from a filehandle, in which case
734					the file pointer will be left pointing to the first byte directly after the
735					compressed data stream.
736
737
738
739					This option defaults to off.
740
741					=item C<< Append => 0\|1 >>
742
743					This option controls what the C<read> method does with uncompressed data.
744
745					If set to 1, all uncompressed data will be appended to the output parameter
746					of the C<read> method.
747
748					If set to 0, the contents of the output parameter of the C<read> method
749					will be overwritten by the uncompressed data.
750
751					Defaults to 0.
752
753					=item C<< Strict => 0\|1 >>
754
755
756
757					This option controls whether the extra checks defined below are used when
758					carrying out the decompression. When Strict is on, the extra tests are
759					carried out, when Strict is off they are not.
760
761					The default for this option is off.
762
763
764
765
766
767
768
769
770
771					=over 5
772
773					=item 1
774
775					If the FHCRC bit is set in the gzip FLG header byte, the CRC16 bytes in the
776					header must match the crc16 value of the gzip header actually read.
777
778					=item 2
779
780					If the gzip header contains a name field (FNAME) it consists solely of ISO
781					8859-1 characters.
782
783					=item 3
784
785					If the gzip header contains a comment field (FCOMMENT) it consists solely
786					of ISO 8859-1 characters plus line-feed.
787
788					=item 4
789
790					If the gzip FEXTRA header field is present it must conform to the sub-field
791					structure as defined in RFC 1952.
792
793					=item 5
794
795					The CRC32 and ISIZE trailer fields must be present.
796
797					=item 6
798
799					The value of the CRC32 field read must match the crc32 value of the
800					uncompressed data actually contained in the gzip file.
801
802					=item 7
803
804					The value of the ISIZE fields read must match the length of the
805					uncompressed data actually read from the file.
806
807					=back
808
809
810
811
812
813
814
815					=item C<< ParseExtra => 0\|1 >>
816					If the gzip FEXTRA header field is present and this option is set, it will
817					force the module to check that it conforms to the sub-field structure as
818					defined in RFC 1952.
819
820					If the C<Strict> is on it will automatically enable this option.
821
822					Defaults to 0.
823
824
825
826
827					=back
828
829					=head2 Examples
830
831					TODO
832
833					=head1 Methods
834
835					=head2 read
836
837					Usage is
838
839					$status = $z->read($buffer)
840
841					Reads a block of compressed data (the size the the compressed block is
842					determined by the C<Buffer> option in the constructor), uncompresses it and
843					writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
844					set in the constructor, the uncompressed data will be appended to the
845					C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
846
847					Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
848					or a negative number on error.
849
850					=head2 read
851
852					Usage is
853
854					$status = $z->read($buffer, $length)
855					$status = $z->read($buffer, $length, $offset)
856
857					$status = read($z, $buffer, $length)
858					$status = read($z, $buffer, $length, $offset)
859
860					Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
861
862					The main difference between this form of the C<read> method and the
863					previous one, is that this one will attempt to return I<exactly> C<$length>
864					bytes. The only circumstances that this function will not is if end-of-file
865					or an IO error is encountered.
866
867					Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
868					or a negative number on error.
869
870
871					=head2 getline
872
873					Usage is
874
875					$line = $z->getline()
876					$line = <$z>
877
878					Reads a single line.
879
880					This method fully supports the use of of the variable C<$/> (or
881					C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
882					determine what constitutes an end of line. Paragraph mode, record mode and
883					file slurp mode are all supported.
884
885
886					=head2 getc
887
888					Usage is
889
890					$char = $z->getc()
891
892					Read a single character.
893
894					=head2 ungetc
895
896					Usage is
897
898					$char = $z->ungetc($string)
899
900
901
902					=head2 inflateSync
903
904					Usage is
905
906					$status = $z->inflateSync()
907
908					TODO
909
910
911					=head2 getHeaderInfo
912
913					Usage is
914
915					$hdr = $z->getHeaderInfo();
916					@hdrs = $z->getHeaderInfo();
917
918					This method returns either a hash reference (in scalar context) or a list
919					or hash references (in array context) that contains information about each
920					of the header fields in the compressed data stream(s).
921
922
923
924					=over 5
925
926					=item Name
927
928					The contents of the Name header field, if present. If no name is
929					present, the value will be undef. Note this is different from a zero length
930					name, which will return an empty string.
931
932					=item Comment
933
934					The contents of the Comment header field, if present. If no comment is
935					present, the value will be undef. Note this is different from a zero length
936					comment, which will return an empty string.
937
938					=back
939
940
941
942
943					=head2 tell
944
945					Usage is
946
947					$z->tell()
948					tell $z
949
950					Returns the uncompressed file offset.
951
952					=head2 eof
953
954					Usage is
955
956					$z->eof();
957					eof($z);
958
959
960
961					Returns true if the end of the compressed input stream has been reached.
962
963
964
965					=head2 seek
966
967					$z->seek($position, $whence);
968					seek($z, $position, $whence);
969
970
971
972
973					Provides a sub-set of the C<seek> functionality, with the restriction
974					that it is only legal to seek forward in the input file/buffer.
975					It is a fatal error to attempt to seek backward.
976
977
978
979					The C<$whence> parameter takes one the usual values, namely SEEK_SET,
980					SEEK_CUR or SEEK_END.
981
982					Returns 1 on success, 0 on failure.
983
984					=head2 binmode
985
986					Usage is
987
988					$z->binmode
989					binmode $z ;
990
991					This is a noop provided for completeness.
992
993					=head2 opened
994
995					$z->opened()
996
997					Returns true if the object currently refers to a opened file/buffer.
998
999					=head2 autoflush
1000
1001					my $prev = $z->autoflush()
1002					my $prev = $z->autoflush(EXPR)
1003
1004					If the C<$z> object is associated with a file or a filehandle, this method
1005					returns the current autoflush setting for the underlying filehandle. If
1006					C<EXPR> is present, and is non-zero, it will enable flushing after every
1007					write/print operation.
1008
1009					If C<$z> is associated with a buffer, this method has no effect and always
1010					returns C<undef>.
1011
1012					B<Note> that the special variable C<$\|> B<cannot> be used to set or
1013					retrieve the autoflush setting.
1014
1015					=head2 input_line_number
1016
1017					$z->input_line_number()
1018					$z->input_line_number(EXPR)
1019
1020
1021
1022					Returns the current uncompressed line number. If C<EXPR> is present it has
1023					the effect of setting the line number. Note that setting the line number
1024					does not change the current position within the file/buffer being read.
1025
1026					The contents of C<$/> are used to to determine what constitutes a line
1027					terminator.
1028
1029
1030
1031					=head2 fileno
1032
1033					$z->fileno()
1034					fileno($z)
1035
1036					If the C<$z> object is associated with a file or a filehandle, this method
1037					will return the underlying file descriptor.
1038
1039					If the C<$z> object is is associated with a buffer, this method will
1040					return undef.
1041
1042					=head2 close
1043
1044					$z->close() ;
1045					close $z ;
1046
1047
1048
1049					Closes the output file/buffer.
1050
1051
1052
1053					For most versions of Perl this method will be automatically invoked if
1054					the IO::Uncompress::Gunzip object is destroyed (either explicitly or by the
1055					variable with the reference to the object going out of scope). The
1056					exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1057					these cases, the C<close> method will be called automatically, but
1058					not until global destruction of all live objects when the program is
1059					terminating.
1060
1061					Therefore, if you want your scripts to be able to run on all versions
1062					of Perl, you should call C<close> explicitly and not rely on automatic
1063					closing.
1064
1065					Returns true on success, otherwise 0.
1066
1067					If the C<AutoClose> option has been enabled when the IO::Uncompress::Gunzip
1068					object was created, and the object is associated with a file, the
1069					underlying file will also be closed.
1070
1071
1072
1073
1074					=head2 nextStream
1075
1076					Usage is
1077
1078					my $status = $z->nextStream();
1079
1080					Skips to the next compressed data stream in the input file/buffer. If a new
1081					compressed data stream is found, the eof marker will be cleared and C<$.>
1082					will be reset to 0.
1083
1084					Returns 1 if a new stream was found, 0 if none was found, and -1 if an
1085					error was encountered.
1086
1087					=head2 trailingData
1088
1089					Usage is
1090
1091					my $data = $z->trailingData();
1092
1093					Returns the data, if any, that is present immediately after the compressed
1094					data stream once uncompression is complete. It only makes sense to call
1095					this method once the end of the compressed data stream has been
1096					encountered.
1097
1098					This option can be used when there is useful information immediately
1099					following the compressed data stream, and you don't know the length of the
1100					compressed data stream.
1101
1102					If the input is a buffer, C<trailingData> will return everything from the
1103					end of the compressed data stream to the end of the buffer.
1104
1105					If the input is a filehandle, C<trailingData> will return the data that is
1106					left in the filehandle input buffer once the end of the compressed data
1107					stream has been reached. You can then use the filehandle to read the rest
1108					of the input file.
1109
1110					Don't bother using C<trailingData> if the input is a filename.
1111
1112
1113
1114					If you know the length of the compressed data stream before you start
1115					uncompressing, you can avoid having to use C<trailingData> by setting the
1116					C<InputLength> option in the constructor.
1117
1118					=head1 Importing
1119
1120					No symbolic constants are required by this IO::Uncompress::Gunzip at present.
1121
1122					=over 5
1123
1124					=item :all
1125
1126					Imports C<gunzip> and C<$GunzipError>.
1127					Same as doing this
1128
1129					use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
1130
1131					=back
1132
1133					=head1 EXAMPLES
1134
1135
1136
1137
1138					=head1 SEE ALSO
1139
1140					L<Compress::Zlib>, L<IO::Compress::Gzip>, 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>
1141
1142					L<Compress::Zlib::FAQ\|Compress::Zlib::FAQ>
1143
1144					L<File::GlobMapper\|File::GlobMapper>, L<Archive::Zip\|Archive::Zip>,
1145					L<Archive::Tar\|Archive::Tar>,
1146					L<IO::Zlib\|IO::Zlib>
1147
1148
1149					For RFC 1950, 1951 and 1952 see
1150					F<http://www.faqs.org/rfcs/rfc1950.html>,
1151					F<http://www.faqs.org/rfcs/rfc1951.html> and
1152					F<http://www.faqs.org/rfcs/rfc1952.html>
1153
1154					The I<zlib> compression library was written by Jean-loup Gailly
1155					F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1156
1157					The primary site for the I<zlib> compression library is
1158					F<http://www.zlib.org>.
1159
1160					The primary site for gzip is F<http://www.gzip.org>.
1161
1162
1163
1164
1165					=head1 AUTHOR
1166
1167					This module was written by Paul Marquess, F<pmqs@cpan.org>.
1168
1169
1170
1171					=head1 MODIFICATION HISTORY
1172
1173					See the Changes file.
1174
1175					=head1 COPYRIGHT AND LICENSE
1176
1177					Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
1178
1179					This program is free software; you can redistribute it and/or
1180					modify it under the same terms as Perl itself.
1181