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