← Index
NYTProf Performance Profile   « block view • line view • sub view »
For 05.Domain_and_Item.t
  Run on Tue May 4 17:21:41 2010
Reported on Tue May 4 17:22:39 2010

File /usr/local/lib/perl5/5.10.1/darwin-2level/IO/Uncompress/Gunzip.pm
Statements Executed 38
Statement Execution Time 1.73ms
Subroutines — ordered by exclusive time
Calls P F Exclusive
Time
Inclusive
Time
Subroutine
1111.32ms22.8msIO::Uncompress::Gunzip::::BEGIN@12IO::Uncompress::Gunzip::BEGIN@12
1111.10ms2.54msIO::Uncompress::Gunzip::::BEGIN@16IO::Uncompress::Gunzip::BEGIN@16
111761µs1.10msIO::Uncompress::Gunzip::::BEGIN@17IO::Uncompress::Gunzip::BEGIN@17
11123µs30µsIO::Uncompress::Gunzip::::BEGIN@8IO::Uncompress::Gunzip::BEGIN@8
11123µs27µsIO::Uncompress::Gunzip::::BEGIN@10IO::Uncompress::Gunzip::BEGIN@10
11115µs176µsIO::Uncompress::Gunzip::::BEGIN@50IO::Uncompress::Gunzip::BEGIN@50
11114µs55µsIO::Uncompress::Gunzip::::BEGIN@14IO::Uncompress::Gunzip::BEGIN@14
11114µs153µsIO::Uncompress::Gunzip::::BEGIN@15IO::Uncompress::Gunzip::BEGIN@15
11113µs33µsIO::Uncompress::Gunzip::::BEGIN@9IO::Uncompress::Gunzip::BEGIN@9
0000s0sIO::Uncompress::Gunzip::::_readFullGzipHeaderIO::Uncompress::Gunzip::_readFullGzipHeader
0000s0sIO::Uncompress::Gunzip::::_readGzipHeaderIO::Uncompress::Gunzip::_readGzipHeader
0000s0sIO::Uncompress::Gunzip::::chkTrailerIO::Uncompress::Gunzip::chkTrailer
0000s0sIO::Uncompress::Gunzip::::ckMagicIO::Uncompress::Gunzip::ckMagic
0000s0sIO::Uncompress::Gunzip::::ckParamsIO::Uncompress::Gunzip::ckParams
0000s0sIO::Uncompress::Gunzip::::getExtraParamsIO::Uncompress::Gunzip::getExtraParams
0000s0sIO::Uncompress::Gunzip::::gunzipIO::Uncompress::Gunzip::gunzip
0000s0sIO::Uncompress::Gunzip::::isGzipMagicIO::Uncompress::Gunzip::isGzipMagic
0000s0sIO::Uncompress::Gunzip::::newIO::Uncompress::Gunzip::new
0000s0sIO::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
2package IO::Uncompress::Gunzip ;
3
4115µsrequire 5.004 ;
5
6# for RFC1952
7
8329µs238µs
# spent 30µs (23+7) within IO::Uncompress::Gunzip::BEGIN@8 which was called # once (23µs+7µs) by Net::HTTP::Methods::gunzip_ok at line 8
use strict ;
# spent 30µs making 1 call to IO::Uncompress::Gunzip::BEGIN@8 # spent 7µs making 1 call to strict::import
9342µs254µs
# spent 33µs (13+21) within IO::Uncompress::Gunzip::BEGIN@9 which was called # once (13µs+21µs) by Net::HTTP::Methods::gunzip_ok at line 9
use warnings;
# spent 33µs making 1 call to IO::Uncompress::Gunzip::BEGIN@9 # spent 21µs making 1 call to warnings::import
10349µs232µs
# spent 27µs (23+5) within IO::Uncompress::Gunzip::BEGIN@10 which was called # once (23µs+5µs) by Net::HTTP::Methods::gunzip_ok at line 10
use bytes;
# spent 27µs making 1 call to IO::Uncompress::Gunzip::BEGIN@10 # spent 5µs making 1 call to bytes::import
11
123164µs322.8ms
# spent 22.8ms (1.32+21.5) within IO::Uncompress::Gunzip::BEGIN@12 which was called # once (1.32ms+21.5ms) by Net::HTTP::Methods::gunzip_ok at line 12
use IO::Uncompress::RawInflate 2.020 ;
# spent 22.8ms making 1 call to IO::Uncompress::Gunzip::BEGIN@12 # spent 22µs making 1 call to Exporter::import # spent 14µs making 1 call to UNIVERSAL::VERSION
13
14351µs396µs
# spent 55µs (14+41) within IO::Uncompress::Gunzip::BEGIN@14 which was called # once (14µs+41µs) by Net::HTTP::Methods::gunzip_ok at line 14
use Compress::Raw::Zlib 2.020 qw( crc32 ) ;
# spent 55µs making 1 call to IO::Uncompress::Gunzip::BEGIN@14 # spent 27µs making 1 call to Exporter::import # spent 14µs making 1 call to UNIVERSAL::VERSION
15348µs3293µs
# spent 153µs (14+140) within IO::Uncompress::Gunzip::BEGIN@15 which was called # once (14µs+140µs) by Net::HTTP::Methods::gunzip_ok at line 15
use IO::Compress::Base::Common 2.020 qw(:Status createSelfTiedObject);
# spent 153µs making 1 call to IO::Uncompress::Gunzip::BEGIN@15 # spent 128µs making 1 call to Exporter::import # spent 12µs making 1 call to UNIVERSAL::VERSION
163159µs32.81ms
# spent 2.54ms (1.10+1.43) within IO::Uncompress::Gunzip::BEGIN@16 which was called # once (1.10ms+1.43ms) by Net::HTTP::Methods::gunzip_ok at line 16
use IO::Compress::Gzip::Constants 2.020 ;
# spent 2.54ms making 1 call to IO::Uncompress::Gunzip::BEGIN@16 # spent 262µs making 1 call to Exporter::import # spent 17µs making 1 call to UNIVERSAL::VERSION
173302µs21.11ms
# spent 1.10ms (761µs+342µs) within IO::Uncompress::Gunzip::BEGIN@17 which was called # once (761µs+342µs) by Net::HTTP::Methods::gunzip_ok at line 17
use IO::Compress::Zlib::Extra 2.020 ;
# spent 1.10ms making 1 call to IO::Uncompress::Gunzip::BEGIN@17 # spent 10µs making 1 call to UNIVERSAL::VERSION
18
191500nsrequire Exporter ;
20
211800nsour ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $GunzipError);
22
23123µs@ISA = qw( Exporter IO::Uncompress::RawInflate );
241800ns@EXPORT_OK = qw( $GunzipError gunzip );
2511µs%EXPORT_TAGS = %IO::Uncompress::RawInflate::DEFLATE_CONSTANTS ;
2612µspush @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
2713µs120µsExporter::export_ok_tags('all');
# spent 20µs making 1 call to Exporter::export_ok_tags
28
291400ns$GunzipError = '';
30
311200ns$VERSION = '2.020';
32
33sub new
34{
35 my $class = shift ;
36 $GunzipError = '';
37 my $obj = createSelfTiedObject($class, \$GunzipError);
38
39 $obj->_create(undef, 0, @_);
40}
41
42sub gunzip
43{
44 my $obj = createSelfTiedObject(undef, \$GunzipError);
45 return $obj->_inf(@_) ;
46}
47
48sub getExtraParams
49{
503828µs3336µs
# spent 176µs (15+161) within IO::Uncompress::Gunzip::BEGIN@50 which was called # once (15µs+161µs) by Net::HTTP::Methods::gunzip_ok at line 50
use IO::Compress::Base::Common 2.020 qw(:Parse);
# spent 176µs making 1 call to IO::Uncompress::Gunzip::BEGIN@50 # spent 146µs making 1 call to Exporter::import # spent 15µs making 1 call to UNIVERSAL::VERSION
51 return ( 'ParseExtra' => [1, 1, Parse_boolean, 0] ) ;
52}
53
54sub 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
65sub 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
86sub readHeader
87{
88 my $self = shift;
89 my $magic = shift;
90
91 return $self->_readGzipHeader($magic);
92}
93
94sub 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
117sub 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
125sub _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
147sub _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
274115µs1;
275
276__END__
277
278
279=head1 NAME
280
281IO::Uncompress::Gunzip - Read RFC 1952 files/buffers
282
283=head1 SYNOPSIS
284
285 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
286
287 my $status = gunzip $input => $output [,OPTS]
288 or die "gunzip failed: $GunzipError\n";
289
290 my $z = new IO::Uncompress::Gunzip $input [OPTS]
291 or die "gunzip failed: $GunzipError\n";
292
293 $status = $z->read($buffer)
294 $status = $z->read($buffer, $length)
295 $status = $z->read($buffer, $length, $offset)
296 $line = $z->getline()
297 $char = $z->getc()
298 $char = $z->ungetc()
299 $char = $z->opened()
300
301 $status = $z->inflateSync()
302
303 $data = $z->trailingData()
304 $status = $z->nextStream()
305 $data = $z->getHeaderInfo()
306 $z->tell()
307 $z->seek($position, $whence)
308 $z->binmode()
309 $z->fileno()
310 $z->eof()
311 $z->close()
312
313 $GunzipError ;
314
315 # IO::File mode
316
317 <$z>
318 read($z, $buffer);
319 read($z, $buffer, $length);
320 read($z, $buffer, $length, $offset);
321 tell($z)
322 seek($z, $position, $whence)
323 binmode($z)
324 fileno($z)
325 eof($z)
326 close($z)
327
328=head1 DESCRIPTION
329
330This module provides a Perl interface that allows the reading of
331files/buffers that conform to RFC 1952.
332
333For writing RFC 1952 files/buffers, see the companion module IO::Compress::Gzip.
334
335=head1 Functional Interface
336
337A top-level function, C<gunzip>, is provided to carry out
338"one-shot" uncompression between buffers and/or files. For finer
339control over the uncompression process, see the L</"OO Interface">
340section.
341
342 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
343
344 gunzip $input => $output [,OPTS]
345 or die "gunzip failed: $GunzipError\n";
346
347The functional interface needs Perl5.005 or better.
348
349=head2 gunzip $input => $output [, OPTS]
350
351C<gunzip> expects at least two parameters, C<$input> and C<$output>.
352
353=head3 The C<$input> parameter
354
355The parameter, C<$input>, is used to define the source of
356the compressed data.
357
358It can take one of the following forms:
359
360=over 5
361
362=item A filename
363
364If the C<$input> parameter is a simple scalar, it is assumed to be a
365filename. This file will be opened for reading and the input data
366will be read from it.
367
368=item A filehandle
369
370If the C<$input> parameter is a filehandle, the input data will be
371read from it.
372The string '-' can be used as an alias for standard input.
373
374=item A scalar reference
375
376If C<$input> is a scalar reference, the input data will be read
377from C<$$input>.
378
379=item An array reference
380
381If C<$input> is an array reference, each element in the array must be a
382filename.
383
384The input data will be read from each file in turn.
385
386The complete array will be walked to ensure that it only
387contains valid filenames before any data is uncompressed.
388
389=item An Input FileGlob string
390
391If C<$input> is a string that is delimited by the characters "<" and ">"
392C<gunzip> will assume that it is an I<input fileglob string>. The
393input is the list of files that match the fileglob.
394
395If the fileglob does not match any files ...
396
397See L<File::GlobMapper|File::GlobMapper> for more details.
398
399=back
400
401If the C<$input> parameter is any other type, C<undef> will be returned.
402
403=head3 The C<$output> parameter
404
405The parameter C<$output> is used to control the destination of the
406uncompressed data. This parameter can take one of these forms.
407
408=over 5
409
410=item A filename
411
412If the C<$output> parameter is a simple scalar, it is assumed to be a
413filename. This file will be opened for writing and the uncompressed
414data will be written to it.
415
416=item A filehandle
417
418If the C<$output> parameter is a filehandle, the uncompressed data
419will be written to it.
420The string '-' can be used as an alias for standard output.
421
422=item A scalar reference
423
424If C<$output> is a scalar reference, the uncompressed data will be
425stored in C<$$output>.
426
427=item An Array Reference
428
429If C<$output> is an array reference, the uncompressed data will be
430pushed onto the array.
431
432=item An Output FileGlob
433
434If C<$output> is a string that is delimited by the characters "<" and ">"
435C<gunzip> will assume that it is an I<output fileglob string>. The
436output is the list of files that match the fileglob.
437
438When C<$output> is an fileglob string, C<$input> must also be a fileglob
439string. Anything else is an error.
440
441=back
442
443If the C<$output> parameter is any other type, C<undef> will be returned.
444
445=head2 Notes
446
447When C<$input> maps to multiple compressed files/buffers and C<$output> is
448a single file/buffer, after uncompression C<$output> will contain a
449concatenation of all the uncompressed data from each of the input
450files/buffers.
451
452=head2 Optional Parameters
453
454Unless specified below, the optional parameters for C<gunzip>,
455C<OPTS>, are the same as those used with the OO interface defined in the
456L</"Constructor Options"> section below.
457
458=over 5
459
460=item C<< AutoClose => 0|1 >>
461
462This option applies to any input or output data streams to
463C<gunzip> that are filehandles.
464
465If C<AutoClose> is specified, and the value is true, it will result in all
466input and/or output filehandles being closed once C<gunzip> has
467completed.
468
469This parameter defaults to 0.
470
471=item C<< BinModeOut => 0|1 >>
472
473When writing to a file or filehandle, set C<binmode> before writing to the
474file.
475
476Defaults to 0.
477
478=item C<< Append => 0|1 >>
479
480TODO
481
482=item C<< MultiStream => 0|1 >>
483
484If the input file/buffer contains multiple compressed data streams, this
485option will uncompress the whole lot as a single data stream.
486
487Defaults to 0.
488
489=item C<< TrailingData => $scalar >>
490
491Returns the data, if any, that is present immediately after the compressed
492data stream once uncompression is complete.
493
494This option can be used when there is useful information immediately
495following the compressed data stream, and you don't know the length of the
496compressed data stream.
497
498If the input is a buffer, C<trailingData> will return everything from the
499end of the compressed data stream to the end of the buffer.
500
501If the input is a filehandle, C<trailingData> will return the data that is
502left in the filehandle input buffer once the end of the compressed data
503stream has been reached. You can then use the filehandle to read the rest
504of the input file.
505
506Don't bother using C<trailingData> if the input is a filename.
507
508If you know the length of the compressed data stream before you start
509uncompressing, you can avoid having to use C<trailingData> by setting the
510C<InputLength> option.
511
512=back
513
514=head2 Examples
515
516To read the contents of the file C<file1.txt.gz> and write the
517compressed data to the file C<file1.txt>.
518
519 use strict ;
520 use warnings ;
521 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
522
523 my $input = "file1.txt.gz";
524 my $output = "file1.txt";
525 gunzip $input => $output
526 or die "gunzip failed: $GunzipError\n";
527
528To read from an existing Perl filehandle, C<$input>, and write the
529uncompressed data to a buffer, C<$buffer>.
530
531 use strict ;
532 use warnings ;
533 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
534 use IO::File ;
535
536 my $input = new IO::File "<file1.txt.gz"
537 or die "Cannot open 'file1.txt.gz': $!\n" ;
538 my $buffer ;
539 gunzip $input => \$buffer
540 or die "gunzip failed: $GunzipError\n";
541
542To uncompress all files in the directory "/my/home" that match "*.txt.gz" and store the compressed data in the same directory
543
544 use strict ;
545 use warnings ;
546 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
547
548 gunzip '</my/home/*.txt.gz>' => '</my/home/#1.txt>'
549 or die "gunzip failed: $GunzipError\n";
550
551and if you want to compress each file one at a time, this will do the trick
552
553 use strict ;
554 use warnings ;
555 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
556
557 for my $input ( glob "/my/home/*.txt.gz" )
558 {
559 my $output = $input;
560 $output =~ s/.gz// ;
561 gunzip $input => $output
562 or die "Error compressing '$input': $GunzipError\n";
563 }
564
565=head1 OO Interface
566
567=head2 Constructor
568
569The format of the constructor for IO::Uncompress::Gunzip is shown below
570
571 my $z = new IO::Uncompress::Gunzip $input [OPTS]
572 or die "IO::Uncompress::Gunzip failed: $GunzipError\n";
573
574Returns an C<IO::Uncompress::Gunzip> object on success and undef on failure.
575The variable C<$GunzipError> will contain an error message on failure.
576
577If you are running Perl 5.005 or better the object, C<$z>, returned from
578IO::Uncompress::Gunzip can be used exactly like an L<IO::File|IO::File> filehandle.
579This means that all normal input file operations can be carried out with
580C<$z>. For example, to read a line from a compressed file/buffer you can
581use either of these forms
582
583 $line = $z->getline();
584 $line = <$z>;
585
586The mandatory parameter C<$input> is used to determine the source of the
587compressed data. This parameter can take one of three forms.
588
589=over 5
590
591=item A filename
592
593If the C<$input> parameter is a scalar, it is assumed to be a filename. This
594file will be opened for reading and the compressed data will be read from it.
595
596=item A filehandle
597
598If the C<$input> parameter is a filehandle, the compressed data will be
599read from it.
600The string '-' can be used as an alias for standard input.
601
602=item A scalar reference
603
604If C<$input> is a scalar reference, the compressed data will be read from
605C<$$output>.
606
607=back
608
609=head2 Constructor Options
610
611The option names defined below are case insensitive and can be optionally
612prefixed by a '-'. So all of the following are valid
613
614 -AutoClose
615 -autoclose
616 AUTOCLOSE
617 autoclose
618
619OPTS is a combination of the following options:
620
621=over 5
622
623=item C<< AutoClose => 0|1 >>
624
625This option is only valid when the C<$input> parameter is a filehandle. If
626specified, and the value is true, it will result in the file being closed once
627either the C<close> method is called or the IO::Uncompress::Gunzip object is
628destroyed.
629
630This parameter defaults to 0.
631
632=item C<< MultiStream => 0|1 >>
633
634Allows multiple concatenated compressed streams to be treated as a single
635compressed stream. Decompression will stop once either the end of the
636file/buffer is reached, an error is encountered (premature eof, corrupt
637compressed data) or the end of a stream is not immediately followed by the
638start of another stream.
639
640This parameter defaults to 0.
641
642=item C<< Prime => $string >>
643
644This option will uncompress the contents of C<$string> before processing the
645input file/buffer.
646
647This option can be useful when the compressed data is embedded in another
648file/data structure and it is not possible to work out where the compressed
649data begins without having to read the first few bytes. If this is the
650case, the uncompression can be I<primed> with these bytes using this
651option.
652
653=item C<< Transparent => 0|1 >>
654
655If this option is set and the input file/buffer is not compressed data,
656the module will allow reading of it anyway.
657
658In addition, if the input file/buffer does contain compressed data and
659there is non-compressed data immediately following it, setting this option
660will make this module treat the whole file/bufffer as a single data stream.
661
662This option defaults to 1.
663
664=item C<< BlockSize => $num >>
665
666When reading the compressed input data, IO::Uncompress::Gunzip will read it in
667blocks of C<$num> bytes.
668
669This option defaults to 4096.
670
671=item C<< InputLength => $size >>
672
673When present this option will limit the number of compressed bytes read
674from the input file/buffer to C<$size>. This option can be used in the
675situation where there is useful data directly after the compressed data
676stream and you know beforehand the exact length of the compressed data
677stream.
678
679This option is mostly used when reading from a filehandle, in which case
680the file pointer will be left pointing to the first byte directly after the
681compressed data stream.
682
683This option defaults to off.
684
685=item C<< Append => 0|1 >>
686
687This option controls what the C<read> method does with uncompressed data.
688
689If set to 1, all uncompressed data will be appended to the output parameter
690of the C<read> method.
691
692If set to 0, the contents of the output parameter of the C<read> method
693will be overwritten by the uncompressed data.
694
695Defaults to 0.
696
697=item C<< Strict => 0|1 >>
698
699This option controls whether the extra checks defined below are used when
700carrying out the decompression. When Strict is on, the extra tests are
701carried out, when Strict is off they are not.
702
703The default for this option is off.
704
705=over 5
706
707=item 1
708
709If the FHCRC bit is set in the gzip FLG header byte, the CRC16 bytes in the
710header must match the crc16 value of the gzip header actually read.
711
712=item 2
713
714If the gzip header contains a name field (FNAME) it consists solely of ISO
7158859-1 characters.
716
717=item 3
718
719If the gzip header contains a comment field (FCOMMENT) it consists solely
720of ISO 8859-1 characters plus line-feed.
721
722=item 4
723
724If the gzip FEXTRA header field is present it must conform to the sub-field
725structure as defined in RFC 1952.
726
727=item 5
728
729The CRC32 and ISIZE trailer fields must be present.
730
731=item 6
732
733The value of the CRC32 field read must match the crc32 value of the
734uncompressed data actually contained in the gzip file.
735
736=item 7
737
738The value of the ISIZE fields read must match the length of the
739uncompressed data actually read from the file.
740
741=back
742
743=item C<< ParseExtra => 0|1 >>
744If the gzip FEXTRA header field is present and this option is set, it will
745force the module to check that it conforms to the sub-field structure as
746defined in RFC 1952.
747
748If the C<Strict> is on it will automatically enable this option.
749
750Defaults to 0.
751
752=back
753
754=head2 Examples
755
756TODO
757
758=head1 Methods
759
760=head2 read
761
762Usage is
763
764 $status = $z->read($buffer)
765
766Reads a block of compressed data (the size the the compressed block is
767determined by the C<Buffer> option in the constructor), uncompresses it and
768writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
769set in the constructor, the uncompressed data will be appended to the
770C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
771
772Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
773or a negative number on error.
774
775=head2 read
776
777Usage is
778
779 $status = $z->read($buffer, $length)
780 $status = $z->read($buffer, $length, $offset)
781
782 $status = read($z, $buffer, $length)
783 $status = read($z, $buffer, $length, $offset)
784
785Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
786
787The main difference between this form of the C<read> method and the
788previous one, is that this one will attempt to return I<exactly> C<$length>
789bytes. The only circumstances that this function will not is if end-of-file
790or an IO error is encountered.
791
792Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
793or a negative number on error.
794
795=head2 getline
796
797Usage is
798
799 $line = $z->getline()
800 $line = <$z>
801
802Reads a single line.
803
804This method fully supports the use of of the variable C<$/> (or
805C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
806determine what constitutes an end of line. Paragraph mode, record mode and
807file slurp mode are all supported.
808
809=head2 getc
810
811Usage is
812
813 $char = $z->getc()
814
815Read a single character.
816
817=head2 ungetc
818
819Usage is
820
821 $char = $z->ungetc($string)
822
823=head2 inflateSync
824
825Usage is
826
827 $status = $z->inflateSync()
828
829TODO
830
831=head2 getHeaderInfo
832
833Usage is
834
835 $hdr = $z->getHeaderInfo();
836 @hdrs = $z->getHeaderInfo();
837
838This method returns either a hash reference (in scalar context) or a list
839or hash references (in array context) that contains information about each
840of the header fields in the compressed data stream(s).
841
842=over 5
843
844=item Name
845
846The contents of the Name header field, if present. If no name is
847present, the value will be undef. Note this is different from a zero length
848name, which will return an empty string.
849
850=item Comment
851
852The contents of the Comment header field, if present. If no comment is
853present, the value will be undef. Note this is different from a zero length
854comment, which will return an empty string.
855
856=back
857
858=head2 tell
859
860Usage is
861
862 $z->tell()
863 tell $z
864
865Returns the uncompressed file offset.
866
867=head2 eof
868
869Usage is
870
871 $z->eof();
872 eof($z);
873
874Returns true if the end of the compressed input stream has been reached.
875
876=head2 seek
877
878 $z->seek($position, $whence);
879 seek($z, $position, $whence);
880
881Provides a sub-set of the C<seek> functionality, with the restriction
882that it is only legal to seek forward in the input file/buffer.
883It is a fatal error to attempt to seek backward.
884
885The C<$whence> parameter takes one the usual values, namely SEEK_SET,
886SEEK_CUR or SEEK_END.
887
888Returns 1 on success, 0 on failure.
889
890=head2 binmode
891
892Usage is
893
894 $z->binmode
895 binmode $z ;
896
897This is a noop provided for completeness.
898
899=head2 opened
900
901 $z->opened()
902
903Returns true if the object currently refers to a opened file/buffer.
904
905=head2 autoflush
906
907 my $prev = $z->autoflush()
908 my $prev = $z->autoflush(EXPR)
909
910If the C<$z> object is associated with a file or a filehandle, this method
911returns the current autoflush setting for the underlying filehandle. If
912C<EXPR> is present, and is non-zero, it will enable flushing after every
913write/print operation.
914
915If C<$z> is associated with a buffer, this method has no effect and always
916returns C<undef>.
917
918B<Note> that the special variable C<$|> B<cannot> be used to set or
919retrieve the autoflush setting.
920
921=head2 input_line_number
922
923 $z->input_line_number()
924 $z->input_line_number(EXPR)
925
926Returns the current uncompressed line number. If C<EXPR> is present it has
927the effect of setting the line number. Note that setting the line number
928does not change the current position within the file/buffer being read.
929
930The contents of C<$/> are used to to determine what constitutes a line
931terminator.
932
933=head2 fileno
934
935 $z->fileno()
936 fileno($z)
937
938If the C<$z> object is associated with a file or a filehandle, C<fileno>
939will return the underlying file descriptor. Once the C<close> method is
940called C<fileno> will return C<undef>.
941
942If the C<$z> object is is associated with a buffer, this method will return
943C<undef>.
944
945=head2 close
946
947 $z->close() ;
948 close $z ;
949
950Closes the output file/buffer.
951
952For most versions of Perl this method will be automatically invoked if
953the IO::Uncompress::Gunzip object is destroyed (either explicitly or by the
954variable with the reference to the object going out of scope). The
955exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
956these cases, the C<close> method will be called automatically, but
957not until global destruction of all live objects when the program is
958terminating.
959
960Therefore, if you want your scripts to be able to run on all versions
961of Perl, you should call C<close> explicitly and not rely on automatic
962closing.
963
964Returns true on success, otherwise 0.
965
966If the C<AutoClose> option has been enabled when the IO::Uncompress::Gunzip
967object was created, and the object is associated with a file, the
968underlying file will also be closed.
969
970=head2 nextStream
971
972Usage is
973
974 my $status = $z->nextStream();
975
976Skips to the next compressed data stream in the input file/buffer. If a new
977compressed data stream is found, the eof marker will be cleared and C<$.>
978will be reset to 0.
979
980Returns 1 if a new stream was found, 0 if none was found, and -1 if an
981error was encountered.
982
983=head2 trailingData
984
985Usage is
986
987 my $data = $z->trailingData();
988
989Returns the data, if any, that is present immediately after the compressed
990data stream once uncompression is complete. It only makes sense to call
991this method once the end of the compressed data stream has been
992encountered.
993
994This option can be used when there is useful information immediately
995following the compressed data stream, and you don't know the length of the
996compressed data stream.
997
998If the input is a buffer, C<trailingData> will return everything from the
999end of the compressed data stream to the end of the buffer.
1000
1001If the input is a filehandle, C<trailingData> will return the data that is
1002left in the filehandle input buffer once the end of the compressed data
1003stream has been reached. You can then use the filehandle to read the rest
1004of the input file.
1005
1006Don't bother using C<trailingData> if the input is a filename.
1007
1008If you know the length of the compressed data stream before you start
1009uncompressing, you can avoid having to use C<trailingData> by setting the
1010C<InputLength> option in the constructor.
1011
1012=head1 Importing
1013
1014No symbolic constants are required by this IO::Uncompress::Gunzip at present.
1015
1016=over 5
1017
1018=item :all
1019
1020Imports C<gunzip> and C<$GunzipError>.
1021Same as doing this
1022
1023 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
1024
1025=back
1026
1027=head1 EXAMPLES
1028
1029=head2 Working with Net::FTP
1030
1031See L<IO::Uncompress::Gunzip::FAQ|IO::Uncompress::Gunzip::FAQ/"Compressed files and Net::FTP">
1032
1033=head1 SEE ALSO
1034
1035L<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>
1036
1037L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1038
1039L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1040L<Archive::Tar|Archive::Tar>,
1041L<IO::Zlib|IO::Zlib>
1042
1043For RFC 1950, 1951 and 1952 see
1044F<http://www.faqs.org/rfcs/rfc1950.html>,
1045F<http://www.faqs.org/rfcs/rfc1951.html> and
1046F<http://www.faqs.org/rfcs/rfc1952.html>
1047
1048The I<zlib> compression library was written by Jean-loup Gailly
1049F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1050
1051The primary site for the I<zlib> compression library is
1052F<http://www.zlib.org>.
1053
1054The primary site for gzip is F<http://www.gzip.org>.
1055
1056=head1 AUTHOR
1057
1058This module was written by Paul Marquess, F<pmqs@cpan.org>.
1059
1060=head1 MODIFICATION HISTORY
1061
1062See the Changes file.
1063
1064=head1 COPYRIGHT AND LICENSE
1065
1066Copyright (c) 2005-2009 Paul Marquess. All rights reserved.
1067
1068This program is free software; you can redistribute it and/or
1069modify it under the same terms as Perl itself.
1070