Profile of /usr/local/lib/perl5/5.10.1/darwin-2level/IO/Uncompress/Gunzip.pm

← 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
--- | --- | --- | --- | --- | ---
1 | 1 | 1 | 1.32ms | 22.8ms | IO::Uncompress::Gunzip::::BEGIN@12IO::Uncompress::Gunzip::BEGIN@12
1 | 1 | 1 | 1.10ms | 2.54ms | IO::Uncompress::Gunzip::::BEGIN@16IO::Uncompress::Gunzip::BEGIN@16
1 | 1 | 1 | 761µs | 1.10ms | IO::Uncompress::Gunzip::::BEGIN@17IO::Uncompress::Gunzip::BEGIN@17
1 | 1 | 1 | 23µs | 30µs | IO::Uncompress::Gunzip::::BEGIN@8IO::Uncompress::Gunzip::BEGIN@8
1 | 1 | 1 | 23µs | 27µs | IO::Uncompress::Gunzip::::BEGIN@10IO::Uncompress::Gunzip::BEGIN@10
1 | 1 | 1 | 15µs | 176µs | IO::Uncompress::Gunzip::::BEGIN@50IO::Uncompress::Gunzip::BEGIN@50
1 | 1 | 1 | 14µs | 55µs | IO::Uncompress::Gunzip::::BEGIN@14IO::Uncompress::Gunzip::BEGIN@14
1 | 1 | 1 | 14µs | 153µs | IO::Uncompress::Gunzip::::BEGIN@15IO::Uncompress::Gunzip::BEGIN@15
1 | 1 | 1 | 13µs | 33µs | IO::Uncompress::Gunzip::::BEGIN@9IO::Uncompress::Gunzip::BEGIN@9
0 | 0 | 0 | 0s | 0s | IO::Uncompress::Gunzip::::_readFullGzipHeaderIO::Uncompress::Gunzip::_readFullGzipHeader
0 | 0 | 0 | 0s | 0s | IO::Uncompress::Gunzip::::_readGzipHeaderIO::Uncompress::Gunzip::_readGzipHeader
0 | 0 | 0 | 0s | 0s | IO::Uncompress::Gunzip::::chkTrailerIO::Uncompress::Gunzip::chkTrailer
0 | 0 | 0 | 0s | 0s | IO::Uncompress::Gunzip::::ckMagicIO::Uncompress::Gunzip::ckMagic
0 | 0 | 0 | 0s | 0s | IO::Uncompress::Gunzip::::ckParamsIO::Uncompress::Gunzip::ckParams
0 | 0 | 0 | 0s | 0s | IO::Uncompress::Gunzip::::getExtraParamsIO::Uncompress::Gunzip::getExtraParams
0 | 0 | 0 | 0s | 0s | IO::Uncompress::Gunzip::::gunzipIO::Uncompress::Gunzip::gunzip
0 | 0 | 0 | 0s | 0s | IO::Uncompress::Gunzip::::isGzipMagicIO::Uncompress::Gunzip::isGzipMagic
0 | 0 | 0 | 0s | 0s | IO::Uncompress::Gunzip::::newIO::Uncompress::Gunzip::new
0 | 0 | 0 | 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 | 15µs |  |  | require 5.004 ;
5 |  |  |  |  |
6 |  |  |  |  | # for RFC1952
7 |  |  |  |  |
8 | 3 | 29µs | 2 | 38µ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
9 | 3 | 42µs | 2 | 54µ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
10 | 3 | 49µs | 2 | 32µ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 |  |  |  |  |
12 | 3 | 164µs | 3 | 22.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 |  |  |  |  |
14 | 3 | 51µs | 3 | 96µ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
15 | 3 | 48µs | 3 | 293µ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
16 | 3 | 159µs | 3 | 2.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
17 | 3 | 302µs | 2 | 1.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 |  |  |  |  |
19 | 1 | 500ns |  |  | require Exporter ;
20 |  |  |  |  |
21 | 1 | 800ns |  |  | our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $GunzipError);
22 |  |  |  |  |
23 | 1 | 23µs |  |  | @ISA = qw( Exporter IO::Uncompress::RawInflate );
24 | 1 | 800ns |  |  | @EXPORT_OK = qw( $GunzipError gunzip );
25 | 1 | 1µs |  |  | %EXPORT_TAGS = %IO::Uncompress::RawInflate::DEFLATE_CONSTANTS ;
26 | 1 | 2µs |  |  | push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
27 | 1 | 3µs | 1 | 20µs | Exporter::export_ok_tags('all'); # spent 20µs making 1 call to Exporter::export_ok_tags
28 |  |  |  |  |
29 | 1 | 400ns |  |  | $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 | 828µs | 3 | 336µ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 |  |  |  |  |
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 | 15µ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 |  |  |  |  |