"Fossies" - the Fresh Open Source Software Archive

Member "IO-Compress-2.093/lib/IO/Uncompress/Bunzip2.pm" (7 Dec 2019, 25579 Bytes) of package /linux/privat/IO-Compress-2.093.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "Bunzip2.pm" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 2.092_vs_2.093.

    1 package IO::Uncompress::Bunzip2 ;
    2 
    3 use strict ;
    4 use warnings;
    5 use bytes;
    6 
    7 use IO::Compress::Base::Common 2.093 qw(:Status );
    8 
    9 use IO::Uncompress::Base 2.093 ;
   10 use IO::Uncompress::Adapter::Bunzip2 2.093 ;
   11 
   12 require Exporter ;
   13 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $Bunzip2Error);
   14 
   15 $VERSION = '2.093';
   16 $Bunzip2Error = '';
   17 
   18 @ISA    = qw(IO::Uncompress::Base Exporter);
   19 @EXPORT_OK = qw( $Bunzip2Error bunzip2 ) ;
   20 #%EXPORT_TAGS = %IO::Uncompress::Base::EXPORT_TAGS ;
   21 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
   22 #Exporter::export_ok_tags('all');
   23 
   24 
   25 sub new
   26 {
   27     my $class = shift ;
   28     my $obj = IO::Compress::Base::Common::createSelfTiedObject($class, \$Bunzip2Error);
   29 
   30     $obj->_create(undef, 0, @_);
   31 }
   32 
   33 sub bunzip2
   34 {
   35     my $obj = IO::Compress::Base::Common::createSelfTiedObject(undef, \$Bunzip2Error);
   36     return $obj->_inf(@_);
   37 }
   38 
   39 sub getExtraParams
   40 {
   41     return (
   42             'verbosity'     => [IO::Compress::Base::Common::Parse_boolean,   0],
   43             'small'         => [IO::Compress::Base::Common::Parse_boolean,   0],
   44         );
   45 }
   46 
   47 
   48 sub ckParams
   49 {
   50     my $self = shift ;
   51     my $got = shift ;
   52 
   53     return 1;
   54 }
   55 
   56 sub mkUncomp
   57 {
   58     my $self = shift ;
   59     my $got = shift ;
   60 
   61      my $magic = $self->ckMagic()
   62         or return 0;
   63 
   64     *$self->{Info} = $self->readHeader($magic)
   65         or return undef ;
   66 
   67     my $Small     = $got->getValue('small');
   68     my $Verbosity = $got->getValue('verbosity');
   69 
   70     my ($obj, $errstr, $errno) =  IO::Uncompress::Adapter::Bunzip2::mkUncompObject(
   71                                                     $Small, $Verbosity);
   72 
   73     return $self->saveErrorString(undef, $errstr, $errno)
   74         if ! defined $obj;
   75     
   76     *$self->{Uncomp} = $obj;
   77 
   78     return 1;
   79 
   80 }
   81 
   82 
   83 sub ckMagic
   84 {
   85     my $self = shift;
   86 
   87     my $magic ;
   88     $self->smartReadExact(\$magic, 4);
   89 
   90     *$self->{HeaderPending} = $magic ;
   91     
   92     return $self->HeaderError("Header size is " . 
   93                                         4 . " bytes") 
   94         if length $magic != 4;
   95 
   96     return $self->HeaderError("Bad Magic.")
   97         if ! isBzip2Magic($magic) ;
   98                       
   99         
  100     *$self->{Type} = 'bzip2';
  101     return $magic;
  102 }
  103 
  104 sub readHeader
  105 {
  106     my $self = shift;
  107     my $magic = shift ;
  108 
  109     $self->pushBack($magic);
  110     *$self->{HeaderPending} = '';
  111 
  112 
  113     return {
  114         'Type'              => 'bzip2',
  115         'FingerprintLength' => 4,
  116         'HeaderLength'      => 4,
  117         'TrailerLength'     => 0,
  118         'Header'            => '$magic'
  119         };
  120     
  121 }
  122 
  123 sub chkTrailer
  124 {
  125     return STATUS_OK;
  126 }
  127 
  128 
  129 
  130 sub isBzip2Magic
  131 {
  132     my $buffer = shift ;
  133     return $buffer =~ /^BZh\d$/;
  134 }
  135 
  136 1 ;
  137 
  138 __END__
  139 
  140 
  141 =head1 NAME
  142 
  143 IO::Uncompress::Bunzip2 - Read bzip2 files/buffers
  144 
  145 =head1 SYNOPSIS
  146 
  147     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
  148 
  149     my $status = bunzip2 $input => $output [,OPTS]
  150         or die "bunzip2 failed: $Bunzip2Error\n";
  151 
  152     my $z = new IO::Uncompress::Bunzip2 $input [OPTS]
  153         or die "bunzip2 failed: $Bunzip2Error\n";
  154 
  155     $status = $z->read($buffer)
  156     $status = $z->read($buffer, $length)
  157     $status = $z->read($buffer, $length, $offset)
  158     $line = $z->getline()
  159     $char = $z->getc()
  160     $char = $z->ungetc()
  161     $char = $z->opened()
  162 
  163     $data = $z->trailingData()
  164     $status = $z->nextStream()
  165     $data = $z->getHeaderInfo()
  166     $z->tell()
  167     $z->seek($position, $whence)
  168     $z->binmode()
  169     $z->fileno()
  170     $z->eof()
  171     $z->close()
  172 
  173     $Bunzip2Error ;
  174 
  175     # IO::File mode
  176 
  177     <$z>
  178     read($z, $buffer);
  179     read($z, $buffer, $length);
  180     read($z, $buffer, $length, $offset);
  181     tell($z)
  182     seek($z, $position, $whence)
  183     binmode($z)
  184     fileno($z)
  185     eof($z)
  186     close($z)
  187 
  188 =head1 DESCRIPTION
  189 
  190 This module provides a Perl interface that allows the reading of
  191 bzip2 files/buffers.
  192 
  193 For writing bzip2 files/buffers, see the companion module IO::Compress::Bzip2.
  194 
  195 =head1 Functional Interface
  196 
  197 A top-level function, C<bunzip2>, is provided to carry out
  198 "one-shot" uncompression between buffers and/or files. For finer
  199 control over the uncompression process, see the L</"OO Interface">
  200 section.
  201 
  202     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
  203 
  204     bunzip2 $input_filename_or_reference => $output_filename_or_reference [,OPTS]
  205         or die "bunzip2 failed: $Bunzip2Error\n";
  206 
  207 The functional interface needs Perl5.005 or better.
  208 
  209 =head2 bunzip2 $input_filename_or_reference => $output_filename_or_reference [, OPTS]
  210 
  211 C<bunzip2> expects at least two parameters,
  212 C<$input_filename_or_reference> and C<$output_filename_or_reference>
  213 and zero or more optional parameters (see L</Optional Parameters>)
  214 
  215 =head3 The C<$input_filename_or_reference> parameter
  216 
  217 The parameter, C<$input_filename_or_reference>, is used to define the
  218 source of the compressed data.
  219 
  220 It can take one of the following forms:
  221 
  222 =over 5
  223 
  224 =item A filename
  225 
  226 If the C<$input_filename_or_reference> parameter is a simple scalar, it is
  227 assumed to be a filename. This file will be opened for reading and the
  228 input data will be read from it.
  229 
  230 =item A filehandle
  231 
  232 If the C<$input_filename_or_reference> parameter is a filehandle, the input
  233 data will be read from it.  The string '-' can be used as an alias for
  234 standard input.
  235 
  236 =item A scalar reference
  237 
  238 If C<$input_filename_or_reference> is a scalar reference, the input data
  239 will be read from C<$$input_filename_or_reference>.
  240 
  241 =item An array reference
  242 
  243 If C<$input_filename_or_reference> is an array reference, each element in
  244 the array must be a filename.
  245 
  246 The input data will be read from each file in turn.
  247 
  248 The complete array will be walked to ensure that it only
  249 contains valid filenames before any data is uncompressed.
  250 
  251 =item An Input FileGlob string
  252 
  253 If C<$input_filename_or_reference> is a string that is delimited by the
  254 characters "<" and ">" C<bunzip2> will assume that it is an
  255 I<input fileglob string>. The input is the list of files that match the
  256 fileglob.
  257 
  258 See L<File::GlobMapper|File::GlobMapper> for more details.
  259 
  260 =back
  261 
  262 If the C<$input_filename_or_reference> parameter is any other type,
  263 C<undef> will be returned.
  264 
  265 =head3 The C<$output_filename_or_reference> parameter
  266 
  267 The parameter C<$output_filename_or_reference> is used to control the
  268 destination of the uncompressed data. This parameter can take one of
  269 these forms.
  270 
  271 =over 5
  272 
  273 =item A filename
  274 
  275 If the C<$output_filename_or_reference> parameter is a simple scalar, it is
  276 assumed to be a filename.  This file will be opened for writing and the
  277 uncompressed data will be written to it.
  278 
  279 =item A filehandle
  280 
  281 If the C<$output_filename_or_reference> parameter is a filehandle, the
  282 uncompressed data will be written to it.  The string '-' can be used as
  283 an alias for standard output.
  284 
  285 =item A scalar reference
  286 
  287 If C<$output_filename_or_reference> is a scalar reference, the
  288 uncompressed data will be stored in C<$$output_filename_or_reference>.
  289 
  290 =item An Array Reference
  291 
  292 If C<$output_filename_or_reference> is an array reference,
  293 the uncompressed data will be pushed onto the array.
  294 
  295 =item An Output FileGlob
  296 
  297 If C<$output_filename_or_reference> is a string that is delimited by the
  298 characters "<" and ">" C<bunzip2> will assume that it is an
  299 I<output fileglob string>. The output is the list of files that match the
  300 fileglob.
  301 
  302 When C<$output_filename_or_reference> is an fileglob string,
  303 C<$input_filename_or_reference> must also be a fileglob string. Anything
  304 else is an error.
  305 
  306 See L<File::GlobMapper|File::GlobMapper> for more details.
  307 
  308 =back
  309 
  310 If the C<$output_filename_or_reference> parameter is any other type,
  311 C<undef> will be returned.
  312 
  313 =head2 Notes
  314 
  315 When C<$input_filename_or_reference> maps to multiple compressed
  316 files/buffers and C<$output_filename_or_reference> is
  317 a single file/buffer, after uncompression C<$output_filename_or_reference> will contain a
  318 concatenation of all the uncompressed data from each of the input
  319 files/buffers.
  320 
  321 =head2 Optional Parameters
  322 
  323 The optional parameters for the one-shot function C<bunzip2>
  324 are (for the most part) identical to those used with the OO interface defined in the
  325 L</"Constructor Options"> section. The exceptions are listed below
  326 
  327 =over 5
  328 
  329 =item C<< AutoClose => 0|1 >>
  330 
  331 This option applies to any input or output data streams to
  332 C<bunzip2> that are filehandles.
  333 
  334 If C<AutoClose> is specified, and the value is true, it will result in all
  335 input and/or output filehandles being closed once C<bunzip2> has
  336 completed.
  337 
  338 This parameter defaults to 0.
  339 
  340 =item C<< BinModeOut => 0|1 >>
  341 
  342 This option is now a no-op. All files will be written  in binmode.
  343 
  344 =item C<< Append => 0|1 >>
  345 
  346 The behaviour of this option is dependent on the type of output data
  347 stream.
  348 
  349 =over 5
  350 
  351 =item * A Buffer
  352 
  353 If C<Append> is enabled, all uncompressed data will be append to the end of
  354 the output buffer. Otherwise the output buffer will be cleared before any
  355 uncompressed data is written to it.
  356 
  357 =item * A Filename
  358 
  359 If C<Append> is enabled, the file will be opened in append mode. Otherwise
  360 the contents of the file, if any, will be truncated before any uncompressed
  361 data is written to it.
  362 
  363 =item * A Filehandle
  364 
  365 If C<Append> is enabled, the filehandle will be positioned to the end of
  366 the file via a call to C<seek> before any uncompressed data is
  367 written to it.  Otherwise the file pointer will not be moved.
  368 
  369 =back
  370 
  371 When C<Append> is specified, and set to true, it will I<append> all uncompressed
  372 data to the output data stream.
  373 
  374 So when the output is a filehandle it will carry out a seek to the eof
  375 before writing any uncompressed data. If the output is a filename, it will be opened for
  376 appending. If the output is a buffer, all uncompressed data will be
  377 appended to the existing buffer.
  378 
  379 Conversely when C<Append> is not specified, or it is present and is set to
  380 false, it will operate as follows.
  381 
  382 When the output is a filename, it will truncate the contents of the file
  383 before writing any uncompressed data. If the output is a filehandle
  384 its position will not be changed. If the output is a buffer, it will be
  385 wiped before any uncompressed data is output.
  386 
  387 Defaults to 0.
  388 
  389 =item C<< MultiStream => 0|1 >>
  390 
  391 If the input file/buffer contains multiple compressed data streams, this
  392 option will uncompress the whole lot as a single data stream.
  393 
  394 Defaults to 0.
  395 
  396 =item C<< TrailingData => $scalar >>
  397 
  398 Returns the data, if any, that is present immediately after the compressed
  399 data stream once uncompression is complete.
  400 
  401 This option can be used when there is useful information immediately
  402 following the compressed data stream, and you don't know the length of the
  403 compressed data stream.
  404 
  405 If the input is a buffer, C<trailingData> will return everything from the
  406 end of the compressed data stream to the end of the buffer.
  407 
  408 If the input is a filehandle, C<trailingData> will return the data that is
  409 left in the filehandle input buffer once the end of the compressed data
  410 stream has been reached. You can then use the filehandle to read the rest
  411 of the input file.
  412 
  413 Don't bother using C<trailingData> if the input is a filename.
  414 
  415 If you know the length of the compressed data stream before you start
  416 uncompressing, you can avoid having to use C<trailingData> by setting the
  417 C<InputLength> option.
  418 
  419 =back
  420 
  421 =head2 Examples
  422 
  423 To read the contents of the file C<file1.txt.bz2> and write the
  424 uncompressed data to the file C<file1.txt>.
  425 
  426     use strict ;
  427     use warnings ;
  428     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
  429 
  430     my $input = "file1.txt.bz2";
  431     my $output = "file1.txt";
  432     bunzip2 $input => $output
  433         or die "bunzip2 failed: $Bunzip2Error\n";
  434 
  435 To read from an existing Perl filehandle, C<$input>, and write the
  436 uncompressed data to a buffer, C<$buffer>.
  437 
  438     use strict ;
  439     use warnings ;
  440     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
  441     use IO::File ;
  442 
  443     my $input = new IO::File "<file1.txt.bz2"
  444         or die "Cannot open 'file1.txt.bz2': $!\n" ;
  445     my $buffer ;
  446     bunzip2 $input => \$buffer
  447         or die "bunzip2 failed: $Bunzip2Error\n";
  448 
  449 To uncompress all files in the directory "/my/home" that match "*.txt.bz2" and store the compressed data in the same directory
  450 
  451     use strict ;
  452     use warnings ;
  453     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
  454 
  455     bunzip2 '</my/home/*.txt.bz2>' => '</my/home/#1.txt>'
  456         or die "bunzip2 failed: $Bunzip2Error\n";
  457 
  458 and if you want to compress each file one at a time, this will do the trick
  459 
  460     use strict ;
  461     use warnings ;
  462     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
  463 
  464     for my $input ( glob "/my/home/*.txt.bz2" )
  465     {
  466         my $output = $input;
  467         $output =~ s/.bz2// ;
  468         bunzip2 $input => $output
  469             or die "Error compressing '$input': $Bunzip2Error\n";
  470     }
  471 
  472 =head1 OO Interface
  473 
  474 =head2 Constructor
  475 
  476 The format of the constructor for IO::Uncompress::Bunzip2 is shown below
  477 
  478     my $z = new IO::Uncompress::Bunzip2 $input [OPTS]
  479         or die "IO::Uncompress::Bunzip2 failed: $Bunzip2Error\n";
  480 
  481 Returns an C<IO::Uncompress::Bunzip2> object on success and undef on failure.
  482 The variable C<$Bunzip2Error> will contain an error message on failure.
  483 
  484 If you are running Perl 5.005 or better the object, C<$z>, returned from
  485 IO::Uncompress::Bunzip2 can be used exactly like an L<IO::File|IO::File> filehandle.
  486 This means that all normal input file operations can be carried out with
  487 C<$z>.  For example, to read a line from a compressed file/buffer you can
  488 use either of these forms
  489 
  490     $line = $z->getline();
  491     $line = <$z>;
  492 
  493 The mandatory parameter C<$input> is used to determine the source of the
  494 compressed data. This parameter can take one of three forms.
  495 
  496 =over 5
  497 
  498 =item A filename
  499 
  500 If the C<$input> parameter is a scalar, it is assumed to be a filename. This
  501 file will be opened for reading and the compressed data will be read from it.
  502 
  503 =item A filehandle
  504 
  505 If the C<$input> parameter is a filehandle, the compressed data will be
  506 read from it.
  507 The string '-' can be used as an alias for standard input.
  508 
  509 =item A scalar reference
  510 
  511 If C<$input> is a scalar reference, the compressed data will be read from
  512 C<$$input>.
  513 
  514 =back
  515 
  516 =head2 Constructor Options
  517 
  518 The option names defined below are case insensitive and can be optionally
  519 prefixed by a '-'.  So all of the following are valid
  520 
  521     -AutoClose
  522     -autoclose
  523     AUTOCLOSE
  524     autoclose
  525 
  526 OPTS is a combination of the following options:
  527 
  528 =over 5
  529 
  530 =item C<< AutoClose => 0|1 >>
  531 
  532 This option is only valid when the C<$input> parameter is a filehandle. If
  533 specified, and the value is true, it will result in the file being closed once
  534 either the C<close> method is called or the IO::Uncompress::Bunzip2 object is
  535 destroyed.
  536 
  537 This parameter defaults to 0.
  538 
  539 =item C<< MultiStream => 0|1 >>
  540 
  541 Allows multiple concatenated compressed streams to be treated as a single
  542 compressed stream. Decompression will stop once either the end of the
  543 file/buffer is reached, an error is encountered (premature eof, corrupt
  544 compressed data) or the end of a stream is not immediately followed by the
  545 start of another stream.
  546 
  547 This parameter defaults to 0.
  548 
  549 =item C<< Prime => $string >>
  550 
  551 This option will uncompress the contents of C<$string> before processing the
  552 input file/buffer.
  553 
  554 This option can be useful when the compressed data is embedded in another
  555 file/data structure and it is not possible to work out where the compressed
  556 data begins without having to read the first few bytes. If this is the
  557 case, the uncompression can be I<primed> with these bytes using this
  558 option.
  559 
  560 =item C<< Transparent => 0|1 >>
  561 
  562 If this option is set and the input file/buffer is not compressed data,
  563 the module will allow reading of it anyway.
  564 
  565 In addition, if the input file/buffer does contain compressed data and
  566 there is non-compressed data immediately following it, setting this option
  567 will make this module treat the whole file/buffer as a single data stream.
  568 
  569 This option defaults to 1.
  570 
  571 =item C<< BlockSize => $num >>
  572 
  573 When reading the compressed input data, IO::Uncompress::Bunzip2 will read it in
  574 blocks of C<$num> bytes.
  575 
  576 This option defaults to 4096.
  577 
  578 =item C<< InputLength => $size >>
  579 
  580 When present this option will limit the number of compressed bytes read
  581 from the input file/buffer to C<$size>. This option can be used in the
  582 situation where there is useful data directly after the compressed data
  583 stream and you know beforehand the exact length of the compressed data
  584 stream.
  585 
  586 This option is mostly used when reading from a filehandle, in which case
  587 the file pointer will be left pointing to the first byte directly after the
  588 compressed data stream.
  589 
  590 This option defaults to off.
  591 
  592 =item C<< Append => 0|1 >>
  593 
  594 This option controls what the C<read> method does with uncompressed data.
  595 
  596 If set to 1, all uncompressed data will be appended to the output parameter
  597 of the C<read> method.
  598 
  599 If set to 0, the contents of the output parameter of the C<read> method
  600 will be overwritten by the uncompressed data.
  601 
  602 Defaults to 0.
  603 
  604 =item C<< Strict => 0|1 >>
  605 
  606 This option is a no-op.
  607 
  608 =item C<< Small => 0|1 >>
  609 
  610 When non-zero this options will make bzip2 use a decompression algorithm
  611 that uses less memory at the expense of increasing the amount of time
  612 taken for decompression.
  613 
  614 Default is 0.
  615 
  616 =back
  617 
  618 =head2 Examples
  619 
  620 TODO
  621 
  622 =head1 Methods
  623 
  624 =head2 read
  625 
  626 Usage is
  627 
  628     $status = $z->read($buffer)
  629 
  630 Reads a block of compressed data (the size of the compressed block is
  631 determined by the C<Buffer> option in the constructor), uncompresses it and
  632 writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
  633 set in the constructor, the uncompressed data will be appended to the
  634 C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
  635 
  636 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
  637 or a negative number on error.
  638 
  639 =head2 read
  640 
  641 Usage is
  642 
  643     $status = $z->read($buffer, $length)
  644     $status = $z->read($buffer, $length, $offset)
  645 
  646     $status = read($z, $buffer, $length)
  647     $status = read($z, $buffer, $length, $offset)
  648 
  649 Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
  650 
  651 The main difference between this form of the C<read> method and the
  652 previous one, is that this one will attempt to return I<exactly> C<$length>
  653 bytes. The only circumstances that this function will not is if end-of-file
  654 or an IO error is encountered.
  655 
  656 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
  657 or a negative number on error.
  658 
  659 =head2 getline
  660 
  661 Usage is
  662 
  663     $line = $z->getline()
  664     $line = <$z>
  665 
  666 Reads a single line.
  667 
  668 This method fully supports the use of the variable C<$/> (or
  669 C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
  670 determine what constitutes an end of line. Paragraph mode, record mode and
  671 file slurp mode are all supported.
  672 
  673 =head2 getc
  674 
  675 Usage is
  676 
  677     $char = $z->getc()
  678 
  679 Read a single character.
  680 
  681 =head2 ungetc
  682 
  683 Usage is
  684 
  685     $char = $z->ungetc($string)
  686 
  687 =head2 getHeaderInfo
  688 
  689 Usage is
  690 
  691     $hdr  = $z->getHeaderInfo();
  692     @hdrs = $z->getHeaderInfo();
  693 
  694 This method returns either a hash reference (in scalar context) or a list
  695 or hash references (in array context) that contains information about each
  696 of the header fields in the compressed data stream(s).
  697 
  698 =head2 tell
  699 
  700 Usage is
  701 
  702     $z->tell()
  703     tell $z
  704 
  705 Returns the uncompressed file offset.
  706 
  707 =head2 eof
  708 
  709 Usage is
  710 
  711     $z->eof();
  712     eof($z);
  713 
  714 Returns true if the end of the compressed input stream has been reached.
  715 
  716 =head2 seek
  717 
  718     $z->seek($position, $whence);
  719     seek($z, $position, $whence);
  720 
  721 Provides a sub-set of the C<seek> functionality, with the restriction
  722 that it is only legal to seek forward in the input file/buffer.
  723 It is a fatal error to attempt to seek backward.
  724 
  725 Note that the implementation of C<seek> in this module does not provide
  726 true random access to a compressed file/buffer. It  works by uncompressing
  727 data from the current offset in the file/buffer until it reaches the
  728 uncompressed offset specified in the parameters to C<seek>. For very small
  729 files this may be acceptable behaviour. For large files it may cause an
  730 unacceptable delay.
  731 
  732 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
  733 SEEK_CUR or SEEK_END.
  734 
  735 Returns 1 on success, 0 on failure.
  736 
  737 =head2 binmode
  738 
  739 Usage is
  740 
  741     $z->binmode
  742     binmode $z ;
  743 
  744 This is a noop provided for completeness.
  745 
  746 =head2 opened
  747 
  748     $z->opened()
  749 
  750 Returns true if the object currently refers to a opened file/buffer.
  751 
  752 =head2 autoflush
  753 
  754     my $prev = $z->autoflush()
  755     my $prev = $z->autoflush(EXPR)
  756 
  757 If the C<$z> object is associated with a file or a filehandle, this method
  758 returns the current autoflush setting for the underlying filehandle. If
  759 C<EXPR> is present, and is non-zero, it will enable flushing after every
  760 write/print operation.
  761 
  762 If C<$z> is associated with a buffer, this method has no effect and always
  763 returns C<undef>.
  764 
  765 B<Note> that the special variable C<$|> B<cannot> be used to set or
  766 retrieve the autoflush setting.
  767 
  768 =head2 input_line_number
  769 
  770     $z->input_line_number()
  771     $z->input_line_number(EXPR)
  772 
  773 Returns the current uncompressed line number. If C<EXPR> is present it has
  774 the effect of setting the line number. Note that setting the line number
  775 does not change the current position within the file/buffer being read.
  776 
  777 The contents of C<$/> are used to determine what constitutes a line
  778 terminator.
  779 
  780 =head2 fileno
  781 
  782     $z->fileno()
  783     fileno($z)
  784 
  785 If the C<$z> object is associated with a file or a filehandle, C<fileno>
  786 will return the underlying file descriptor. Once the C<close> method is
  787 called C<fileno> will return C<undef>.
  788 
  789 If the C<$z> object is associated with a buffer, this method will return
  790 C<undef>.
  791 
  792 =head2 close
  793 
  794     $z->close() ;
  795     close $z ;
  796 
  797 Closes the output file/buffer.
  798 
  799 For most versions of Perl this method will be automatically invoked if
  800 the IO::Uncompress::Bunzip2 object is destroyed (either explicitly or by the
  801 variable with the reference to the object going out of scope). The
  802 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
  803 these cases, the C<close> method will be called automatically, but
  804 not until global destruction of all live objects when the program is
  805 terminating.
  806 
  807 Therefore, if you want your scripts to be able to run on all versions
  808 of Perl, you should call C<close> explicitly and not rely on automatic
  809 closing.
  810 
  811 Returns true on success, otherwise 0.
  812 
  813 If the C<AutoClose> option has been enabled when the IO::Uncompress::Bunzip2
  814 object was created, and the object is associated with a file, the
  815 underlying file will also be closed.
  816 
  817 =head2 nextStream
  818 
  819 Usage is
  820 
  821     my $status = $z->nextStream();
  822 
  823 Skips to the next compressed data stream in the input file/buffer. If a new
  824 compressed data stream is found, the eof marker will be cleared and C<$.>
  825 will be reset to 0.
  826 
  827 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
  828 error was encountered.
  829 
  830 =head2 trailingData
  831 
  832 Usage is
  833 
  834     my $data = $z->trailingData();
  835 
  836 Returns the data, if any, that is present immediately after the compressed
  837 data stream once uncompression is complete. It only makes sense to call
  838 this method once the end of the compressed data stream has been
  839 encountered.
  840 
  841 This option can be used when there is useful information immediately
  842 following the compressed data stream, and you don't know the length of the
  843 compressed data stream.
  844 
  845 If the input is a buffer, C<trailingData> will return everything from the
  846 end of the compressed data stream to the end of the buffer.
  847 
  848 If the input is a filehandle, C<trailingData> will return the data that is
  849 left in the filehandle input buffer once the end of the compressed data
  850 stream has been reached. You can then use the filehandle to read the rest
  851 of the input file.
  852 
  853 Don't bother using C<trailingData> if the input is a filename.
  854 
  855 If you know the length of the compressed data stream before you start
  856 uncompressing, you can avoid having to use C<trailingData> by setting the
  857 C<InputLength> option in the constructor.
  858 
  859 =head1 Importing
  860 
  861 No symbolic constants are required by this IO::Uncompress::Bunzip2 at present.
  862 
  863 =over 5
  864 
  865 =item :all
  866 
  867 Imports C<bunzip2> and C<$Bunzip2Error>.
  868 Same as doing this
  869 
  870     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
  871 
  872 =back
  873 
  874 =head1 EXAMPLES
  875 
  876 =head2 Working with Net::FTP
  877 
  878 See L<IO::Compress::FAQ|IO::Compress::FAQ/"Compressed files and Net::FTP">
  879 
  880 =head1 SUPPORT
  881 
  882 General feedback/questions/bug reports should be sent to 
  883 L<https://github.com/pmqs/IO-Compress/issues> (preferred) or
  884 L<https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress>.
  885 
  886 =head1 SEE ALSO
  887 
  888 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::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Compress::Lzma>, L<IO::Uncompress::UnLzma>, L<IO::Compress::Xz>, L<IO::Uncompress::UnXz>, L<IO::Compress::Lzip>, L<IO::Uncompress::UnLzip>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Compress::Zstd>, L<IO::Uncompress::UnZstd>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
  889 
  890 L<IO::Compress::FAQ|IO::Compress::FAQ>
  891 
  892 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
  893 L<Archive::Tar|Archive::Tar>,
  894 L<IO::Zlib|IO::Zlib>
  895 
  896 The primary site for the bzip2 program is L<https://sourceware.org/bzip2/>.
  897 
  898 See the module L<Compress::Bzip2|Compress::Bzip2>
  899 
  900 =head1 AUTHOR
  901 
  902 This module was written by Paul Marquess, C<pmqs@cpan.org>.
  903 
  904 =head1 MODIFICATION HISTORY
  905 
  906 See the Changes file.
  907 
  908 =head1 COPYRIGHT AND LICENSE
  909 
  910 Copyright (c) 2005-2019 Paul Marquess. All rights reserved.
  911 
  912 This program is free software; you can redistribute it and/or
  913 modify it under the same terms as Perl itself.
  914