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

File	/opt/wise/lib/perl5/5.10.0/x86_64-linux-thread-multi/IO/Uncompress/RawInflate.pm
Statements Executed	32
Total Time	0.002636 seconds

Subroutines — ordered by exclusive time
Calls	P	F	Exclusive Time	Inclusive Time	Subroutine
0	0	0	0	0	IO::Uncompress::RawInflate::	BEGIN
0	0	0	0	0	IO::Uncompress::RawInflate::	_isRaw
0	0	0	0	0	IO::Uncompress::RawInflate::	_isRawx
0	0	0	0	0	IO::Uncompress::RawInflate::	chkTrailer
0	0	0	0	0	IO::Uncompress::RawInflate::	ckMagic
0	0	0	0	0	IO::Uncompress::RawInflate::	ckParams
0	0	0	0	0	IO::Uncompress::RawInflate::	createDeflate
0	0	0	0	0	IO::Uncompress::RawInflate::	getExtraParams
0	0	0	0	0	IO::Uncompress::RawInflate::	inflateSync
0	0	0	0	0	IO::Uncompress::RawInflate::	mkUncomp
0	0	0	0	0	IO::Uncompress::RawInflate::	new
0	0	0	0	0	IO::Uncompress::RawInflate::	rawinflate
0	0	0	0	0	IO::Uncompress::RawInflate::	readHeader
0	0	0	0	0	IO::Uncompress::RawInflate::	scan
0	0	0	0	0	IO::Uncompress::RawInflate::	zap

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