local-lib5/man/man3/IO::Uncompress::Bunzip2.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "IO::Uncompress::Bunzip2 3"
 132 .TH IO::Uncompress::Bunzip2 3 "2009-11-09" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 IO::Uncompress::Bunzip2 \- Read bzip2 files/buffers
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
 139 .Ve
 140 .PP
 141 .Vb 2
 142 \&    my $status = bunzip2 $input => $output [,OPTS]
 143 \&        or die "bunzip2 failed: $Bunzip2Error\en";
 144 .Ve
 145 .PP
 146 .Vb 2
 147 \&    my $z = new IO::Uncompress::Bunzip2 $input [OPTS]
 148 \&        or die "bunzip2 failed: $Bunzip2Error\en";
 149 .Ve
 150 .PP
 151 .Vb 7
 152 \&    $status = $z\->read($buffer)
 153 \&    $status = $z\->read($buffer, $length)
 154 \&    $status = $z\->read($buffer, $length, $offset)
 155 \&    $line = $z\->getline()
 156 \&    $char = $z\->getc()
 157 \&    $char = $z\->ungetc()
 158 \&    $char = $z\->opened()
 159 .Ve
 160 .PP
 161 .Vb 9
 162 \&    $data = $z\->trailingData()
 163 \&    $status = $z\->nextStream()
 164 \&    $data = $z\->getHeaderInfo()
 165 \&    $z\->tell()
 166 \&    $z\->seek($position, $whence)
 167 \&    $z\->binmode()
 168 \&    $z\->fileno()
 169 \&    $z\->eof()
 170 \&    $z\->close()
 171 .Ve
 172 .PP
 173 .Vb 1
 174 \&    $Bunzip2Error ;
 175 .Ve
 176 .PP
 177 .Vb 1
 178 \&    # IO::File mode
 179 .Ve
 180 .PP
 181 .Vb 10
 182 \&    <$z>
 183 \&    read($z, $buffer);
 184 \&    read($z, $buffer, $length);
 185 \&    read($z, $buffer, $length, $offset);
 186 \&    tell($z)
 187 \&    seek($z, $position, $whence)
 188 \&    binmode($z)
 189 \&    fileno($z)
 190 \&    eof($z)
 191 \&    close($z)
 192 .Ve
 193 .SH "DESCRIPTION"
 194 .IX Header "DESCRIPTION"
 195 This module provides a Perl interface that allows the reading of
 196 bzip2 files/buffers.
 197 .PP
 198 For writing bzip2 files/buffers, see the companion module IO::Compress::Bzip2.
 199 .SH "Functional Interface"
 200 .IX Header "Functional Interface"
 201 A top-level function, \f(CW\*(C`bunzip2\*(C'\fR, is provided to carry out
 202 \&\*(L"one\-shot\*(R" uncompression between buffers and/or files. For finer
 203 control over the uncompression process, see the \*(L"\s-1OO\s0 Interface\*(R"
 204 section.
 205 .PP
 206 .Vb 1
 207 \&    use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
 208 .Ve
 209 .PP
 210 .Vb 2
 211 \&    bunzip2 $input => $output [,OPTS]
 212 \&        or die "bunzip2 failed: $Bunzip2Error\en";
 213 .Ve
 214 .PP
 215 The functional interface needs Perl5.005 or better.
 216 .ie n .Sh "bunzip2 $input\fP => \f(CW$output [, \s-1OPTS\s0]"
 217 .el .Sh "bunzip2 \f(CW$input\fP => \f(CW$output\fP [, \s-1OPTS\s0]"
 218 .IX Subsection "bunzip2 $input => $output [, OPTS]"
 219 \&\f(CW\*(C`bunzip2\*(C'\fR expects at least two parameters, \f(CW$input\fR and \f(CW$output\fR.
 220 .PP
 221 \fIThe \f(CI$input\fI parameter\fR
 222 .IX Subsection "The $input parameter"
 223 .PP
 224 The parameter, \f(CW$input\fR, is used to define the source of
 225 the compressed data.
 226 .PP
 227 It can take one of the following forms:
 228 .IP "A filename" 5
 229 .IX Item "A filename"
 230 If the \f(CW$input\fR parameter is a simple scalar, it is assumed to be a
 231 filename. This file will be opened for reading and the input data
 232 will be read from it.
 233 .IP "A filehandle" 5
 234 .IX Item "A filehandle"
 235 If the \f(CW$input\fR parameter is a filehandle, the input data will be
 236 read from it.
 237 The string '\-' can be used as an alias for standard input.
 238 .IP "A scalar reference" 5
 239 .IX Item "A scalar reference"
 240 If \f(CW$input\fR is a scalar reference, the input data will be read
 241 from \f(CW$$input\fR.
 242 .IP "An array reference" 5
 243 .IX Item "An array reference"
 244 If \f(CW$input\fR is an array reference, each element in the array must be a
 245 filename.
 246 .Sp
 247 The input data will be read from each file in turn.
 248 .Sp
 249 The complete array will be walked to ensure that it only
 250 contains valid filenames before any data is uncompressed.
 251 .IP "An Input FileGlob string" 5
 252 .IX Item "An Input FileGlob string"
 253 If \f(CW$input\fR is a string that is delimited by the characters \*(L"<\*(R" and \*(L">\*(R"
 254 \&\f(CW\*(C`bunzip2\*(C'\fR will assume that it is an \fIinput fileglob string\fR. The
 255 input is the list of files that match the fileglob.
 256 .Sp
 257 If the fileglob does not match any files ...
 258 .Sp
 259 See File::GlobMapper for more details.
 260 .PP
 261 If the \f(CW$input\fR parameter is any other type, \f(CW\*(C`undef\*(C'\fR will be returned.
 262 .PP
 263 \fIThe \f(CI$output\fI parameter\fR
 264 .IX Subsection "The $output parameter"
 265 .PP
 266 The parameter \f(CW$output\fR is used to control the destination of the
 267 uncompressed data. This parameter can take one of these forms.
 268 .IP "A filename" 5
 269 .IX Item "A filename"
 270 If the \f(CW$output\fR parameter is a simple scalar, it is assumed to be a
 271 filename.  This file will be opened for writing and the uncompressed
 272 data will be written to it.
 273 .IP "A filehandle" 5
 274 .IX Item "A filehandle"
 275 If the \f(CW$output\fR parameter is a filehandle, the uncompressed data
 276 will be written to it.
 277 The string '\-' can be used as an alias for standard output.
 278 .IP "A scalar reference" 5
 279 .IX Item "A scalar reference"
 280 If \f(CW$output\fR is a scalar reference, the uncompressed data will be
 281 stored in \f(CW$$output\fR.
 282 .IP "An Array Reference" 5
 283 .IX Item "An Array Reference"
 284 If \f(CW$output\fR is an array reference, the uncompressed data will be
 285 pushed onto the array.
 286 .IP "An Output FileGlob" 5
 287 .IX Item "An Output FileGlob"
 288 If \f(CW$output\fR is a string that is delimited by the characters \*(L"<\*(R" and \*(L">\*(R"
 289 \&\f(CW\*(C`bunzip2\*(C'\fR will assume that it is an \fIoutput fileglob string\fR. The
 290 output is the list of files that match the fileglob.
 291 .Sp
 292 When \f(CW$output\fR is an fileglob string, \f(CW$input\fR must also be a fileglob
 293 string. Anything else is an error.
 294 .PP
 295 If the \f(CW$output\fR parameter is any other type, \f(CW\*(C`undef\*(C'\fR will be returned.
 296 .Sh "Notes"
 297 .IX Subsection "Notes"
 298 When \f(CW$input\fR maps to multiple compressed files/buffers and \f(CW$output\fR is
 299 a single file/buffer, after uncompression \f(CW$output\fR will contain a
 300 concatenation of all the uncompressed data from each of the input
 301 files/buffers.
 302 .Sh "Optional Parameters"
 303 .IX Subsection "Optional Parameters"
 304 Unless specified below, the optional parameters for \f(CW\*(C`bunzip2\*(C'\fR,
 305 \&\f(CW\*(C`OPTS\*(C'\fR, are the same as those used with the \s-1OO\s0 interface defined in the
 306 \&\*(L"Constructor Options\*(R" section below.
 307 .ie n .IP """AutoClose => 0|1""" 5
 308 .el .IP "\f(CWAutoClose => 0|1\fR" 5
 309 .IX Item "AutoClose => 0|1"
 310 This option applies to any input or output data streams to
 311 \&\f(CW\*(C`bunzip2\*(C'\fR that are filehandles.
 312 .Sp
 313 If \f(CW\*(C`AutoClose\*(C'\fR is specified, and the value is true, it will result in all
 314 input and/or output filehandles being closed once \f(CW\*(C`bunzip2\*(C'\fR has
 315 completed.
 316 .Sp
 317 This parameter defaults to 0.
 318 .ie n .IP """BinModeOut => 0|1""" 5
 319 .el .IP "\f(CWBinModeOut => 0|1\fR" 5
 320 .IX Item "BinModeOut => 0|1"
 321 When writing to a file or filehandle, set \f(CW\*(C`binmode\*(C'\fR before writing to the
 322 file.
 323 .Sp
 324 Defaults to 0.
 325 .ie n .IP """Append => 0|1""" 5
 326 .el .IP "\f(CWAppend => 0|1\fR" 5
 327 .IX Item "Append => 0|1"
 328 \&\s-1TODO\s0
 329 .ie n .IP """MultiStream => 0|1""" 5
 330 .el .IP "\f(CWMultiStream => 0|1\fR" 5
 331 .IX Item "MultiStream => 0|1"
 332 If the input file/buffer contains multiple compressed data streams, this
 333 option will uncompress the whole lot as a single data stream.
 334 .Sp
 335 Defaults to 0.
 336 .ie n .IP """TrailingData => $scalar""" 5
 337 .el .IP "\f(CWTrailingData => $scalar\fR" 5
 338 .IX Item "TrailingData => $scalar"
 339 Returns the data, if any, that is present immediately after the compressed
 340 data stream once uncompression is complete.
 341 .Sp
 342 This option can be used when there is useful information immediately
 343 following the compressed data stream, and you don't know the length of the
 344 compressed data stream.
 345 .Sp
 346 If the input is a buffer, \f(CW\*(C`trailingData\*(C'\fR will return everything from the
 347 end of the compressed data stream to the end of the buffer.
 348 .Sp
 349 If the input is a filehandle, \f(CW\*(C`trailingData\*(C'\fR will return the data that is
 350 left in the filehandle input buffer once the end of the compressed data
 351 stream has been reached. You can then use the filehandle to read the rest
 352 of the input file.
 353 .Sp
 354 Don't bother using \f(CW\*(C`trailingData\*(C'\fR if the input is a filename.
 355 .Sp
 356 If you know the length of the compressed data stream before you start
 357 uncompressing, you can avoid having to use \f(CW\*(C`trailingData\*(C'\fR by setting the
 358 \&\f(CW\*(C`InputLength\*(C'\fR option.
 359 .Sh "Examples"
 360 .IX Subsection "Examples"
 361 To read the contents of the file \f(CW\*(C`file1.txt.bz2\*(C'\fR and write the
 362 compressed data to the file \f(CW\*(C`file1.txt\*(C'\fR.
 363 .PP
 364 .Vb 3
 365 \&    use strict ;
 366 \&    use warnings ;
 367 \&    use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
 368 .Ve
 369 .PP
 370 .Vb 4
 371 \&    my $input = "file1.txt.bz2";
 372 \&    my $output = "file1.txt";
 373 \&    bunzip2 $input => $output
 374 \&        or die "bunzip2 failed: $Bunzip2Error\en";
 375 .Ve
 376 .PP
 377 To read from an existing Perl filehandle, \f(CW$input\fR, and write the
 378 uncompressed data to a buffer, \f(CW$buffer\fR.
 379 .PP
 380 .Vb 4
 381 \&    use strict ;
 382 \&    use warnings ;
 383 \&    use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
 384 \&    use IO::File ;
 385 .Ve
 386 .PP
 387 .Vb 5
 388 \&    my $input = new IO::File "<file1.txt.bz2"
 389 \&        or die "Cannot open 'file1.txt.bz2': $!\en" ;
 390 \&    my $buffer ;
 391 \&    bunzip2 $input => \e$buffer
 392 \&        or die "bunzip2 failed: $Bunzip2Error\en";
 393 .Ve
 394 .PP
 395 To uncompress all files in the directory \*(L"/my/home\*(R" that match \*(L"*.txt.bz2\*(R" and store the compressed data in the same directory
 396 .PP
 397 .Vb 3
 398 \&    use strict ;
 399 \&    use warnings ;
 400 \&    use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
 401 .Ve
 402 .PP
 403 .Vb 2
 404 \&    bunzip2 '</my/home/*.txt.bz2>' => '</my/home/#1.txt>'
 405 \&        or die "bunzip2 failed: $Bunzip2Error\en";
 406 .Ve
 407 .PP
 408 and if you want to compress each file one at a time, this will do the trick
 409 .PP
 410 .Vb 3
 411 \&    use strict ;
 412 \&    use warnings ;
 413 \&    use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
 414 .Ve
 415 .PP
 416 .Vb 7
 417 \&    for my $input ( glob "/my/home/*.txt.bz2" )
 418 \&    {
 419 \&        my $output = $input;
 420 \&        $output =~ s/.bz2// ;
 421 \&        bunzip2 $input => $output
 422 \&            or die "Error compressing '$input': $Bunzip2Error\en";
 423 \&    }
 424 .Ve
 425 .SH "OO Interface"
 426 .IX Header "OO Interface"
 427 .Sh "Constructor"
 428 .IX Subsection "Constructor"
 429 The format of the constructor for IO::Uncompress::Bunzip2 is shown below
 430 .PP
 431 .Vb 2
 432 \&    my $z = new IO::Uncompress::Bunzip2 $input [OPTS]
 433 \&        or die "IO::Uncompress::Bunzip2 failed: $Bunzip2Error\en";
 434 .Ve
 435 .PP
 436 Returns an \f(CW\*(C`IO::Uncompress::Bunzip2\*(C'\fR object on success and undef on failure.
 437 The variable \f(CW$Bunzip2Error\fR will contain an error message on failure.
 438 .PP
 439 If you are running Perl 5.005 or better the object, \f(CW$z\fR, returned from
 440 IO::Uncompress::Bunzip2 can be used exactly like an IO::File filehandle.
 441 This means that all normal input file operations can be carried out with
 442 \&\f(CW$z\fR.  For example, to read a line from a compressed file/buffer you can
 443 use either of these forms
 444 .PP
 445 .Vb 2
 446 \&    $line = $z\->getline();
 447 \&    $line = <$z>;
 448 .Ve
 449 .PP
 450 The mandatory parameter \f(CW$input\fR is used to determine the source of the
 451 compressed data. This parameter can take one of three forms.
 452 .IP "A filename" 5
 453 .IX Item "A filename"
 454 If the \f(CW$input\fR parameter is a scalar, it is assumed to be a filename. This
 455 file will be opened for reading and the compressed data will be read from it.
 456 .IP "A filehandle" 5
 457 .IX Item "A filehandle"
 458 If the \f(CW$input\fR parameter is a filehandle, the compressed data will be
 459 read from it.
 460 The string '\-' can be used as an alias for standard input.
 461 .IP "A scalar reference" 5
 462 .IX Item "A scalar reference"
 463 If \f(CW$input\fR is a scalar reference, the compressed data will be read from
 464 \&\f(CW$$output\fR.
 465 .Sh "Constructor Options"
 466 .IX Subsection "Constructor Options"
 467 The option names defined below are case insensitive and can be optionally
 468 prefixed by a '\-'.  So all of the following are valid
 469 .PP
 470 .Vb 4
 471 \&    \-AutoClose
 472 \&    \-autoclose
 473 \&    AUTOCLOSE
 474 \&    autoclose
 475 .Ve
 476 .PP
 477 \&\s-1OPTS\s0 is a combination of the following options:
 478 .ie n .IP """AutoClose => 0|1""" 5
 479 .el .IP "\f(CWAutoClose => 0|1\fR" 5
 480 .IX Item "AutoClose => 0|1"
 481 This option is only valid when the \f(CW$input\fR parameter is a filehandle. If
 482 specified, and the value is true, it will result in the file being closed once
 483 either the \f(CW\*(C`close\*(C'\fR method is called or the IO::Uncompress::Bunzip2 object is
 484 destroyed.
 485 .Sp
 486 This parameter defaults to 0.
 487 .ie n .IP """MultiStream => 0|1""" 5
 488 .el .IP "\f(CWMultiStream => 0|1\fR" 5
 489 .IX Item "MultiStream => 0|1"
 490 Allows multiple concatenated compressed streams to be treated as a single
 491 compressed stream. Decompression will stop once either the end of the
 492 file/buffer is reached, an error is encountered (premature eof, corrupt
 493 compressed data) or the end of a stream is not immediately followed by the
 494 start of another stream.
 495 .Sp
 496 This parameter defaults to 0.
 497 .ie n .IP """Prime => $string""" 5
 498 .el .IP "\f(CWPrime => $string\fR" 5
 499 .IX Item "Prime => $string"
 500 This option will uncompress the contents of \f(CW$string\fR before processing the
 501 input file/buffer.
 502 .Sp
 503 This option can be useful when the compressed data is embedded in another
 504 file/data structure and it is not possible to work out where the compressed
 505 data begins without having to read the first few bytes. If this is the
 506 case, the uncompression can be \fIprimed\fR with these bytes using this
 507 option.
 508 .ie n .IP """Transparent => 0|1""" 5
 509 .el .IP "\f(CWTransparent => 0|1\fR" 5
 510 .IX Item "Transparent => 0|1"
 511 If this option is set and the input file/buffer is not compressed data,
 512 the module will allow reading of it anyway.
 513 .Sp
 514 In addition, if the input file/buffer does contain compressed data and
 515 there is non-compressed data immediately following it, setting this option
 516 will make this module treat the whole file/bufffer as a single data stream.
 517 .Sp
 518 This option defaults to 1.
 519 .ie n .IP """BlockSize => $num""" 5
 520 .el .IP "\f(CWBlockSize => $num\fR" 5
 521 .IX Item "BlockSize => $num"
 522 When reading the compressed input data, IO::Uncompress::Bunzip2 will read it in
 523 blocks of \f(CW$num\fR bytes.
 524 .Sp
 525 This option defaults to 4096.
 526 .ie n .IP """InputLength => $size""" 5
 527 .el .IP "\f(CWInputLength => $size\fR" 5
 528 .IX Item "InputLength => $size"
 529 When present this option will limit the number of compressed bytes read
 530 from the input file/buffer to \f(CW$size\fR. This option can be used in the
 531 situation where there is useful data directly after the compressed data
 532 stream and you know beforehand the exact length of the compressed data
 533 stream.
 534 .Sp
 535 This option is mostly used when reading from a filehandle, in which case
 536 the file pointer will be left pointing to the first byte directly after the
 537 compressed data stream.
 538 .Sp
 539 This option defaults to off.
 540 .ie n .IP """Append => 0|1""" 5
 541 .el .IP "\f(CWAppend => 0|1\fR" 5
 542 .IX Item "Append => 0|1"
 543 This option controls what the \f(CW\*(C`read\*(C'\fR method does with uncompressed data.
 544 .Sp
 545 If set to 1, all uncompressed data will be appended to the output parameter
 546 of the \f(CW\*(C`read\*(C'\fR method.
 547 .Sp
 548 If set to 0, the contents of the output parameter of the \f(CW\*(C`read\*(C'\fR method
 549 will be overwritten by the uncompressed data.
 550 .Sp
 551 Defaults to 0.
 552 .ie n .IP """Strict => 0|1""" 5
 553 .el .IP "\f(CWStrict => 0|1\fR" 5
 554 .IX Item "Strict => 0|1"
 555 This option is a no\-op.
 556 .ie n .IP """Small => 0|1""" 5
 557 .el .IP "\f(CWSmall => 0|1\fR" 5
 558 .IX Item "Small => 0|1"
 559 When non-zero this options will make bzip2 use a decompression algorithm
 560 that uses less memory at the expense of increasing the amount of time
 561 taken for decompression.
 562 .Sp
 563 Default is 0.
 564 .Sh "Examples"
 565 .IX Subsection "Examples"
 566 \&\s-1TODO\s0
 567 .SH "Methods"
 568 .IX Header "Methods"
 569 .Sh "read"
 570 .IX Subsection "read"
 571 Usage is
 572 .PP
 573 .Vb 1
 574 \&    $status = $z\->read($buffer)
 575 .Ve
 576 .PP
 577 Reads a block of compressed data (the size the the compressed block is
 578 determined by the \f(CW\*(C`Buffer\*(C'\fR option in the constructor), uncompresses it and
 579 writes any uncompressed data into \f(CW$buffer\fR. If the \f(CW\*(C`Append\*(C'\fR parameter is
 580 set in the constructor, the uncompressed data will be appended to the
 581 \&\f(CW$buffer\fR parameter. Otherwise \f(CW$buffer\fR will be overwritten.
 582 .PP
 583 Returns the number of uncompressed bytes written to \f(CW$buffer\fR, zero if eof
 584 or a negative number on error.
 585 .Sh "read"
 586 .IX Subsection "read"
 587 Usage is
 588 .PP
 589 .Vb 2
 590 \&    $status = $z\->read($buffer, $length)
 591 \&    $status = $z\->read($buffer, $length, $offset)
 592 .Ve
 593 .PP
 594 .Vb 2
 595 \&    $status = read($z, $buffer, $length)
 596 \&    $status = read($z, $buffer, $length, $offset)
 597 .Ve
 598 .PP
 599 Attempt to read \f(CW$length\fR bytes of uncompressed data into \f(CW$buffer\fR.
 600 .PP
 601 The main difference between this form of the \f(CW\*(C`read\*(C'\fR method and the
 602 previous one, is that this one will attempt to return \fIexactly\fR \f(CW$length\fR
 603 bytes. The only circumstances that this function will not is if end-of-file
 604 or an \s-1IO\s0 error is encountered.
 605 .PP
 606 Returns the number of uncompressed bytes written to \f(CW$buffer\fR, zero if eof
 607 or a negative number on error.
 608 .Sh "getline"
 609 .IX Subsection "getline"
 610 Usage is
 611 .PP
 612 .Vb 2
 613 \&    $line = $z\->getline()
 614 \&    $line = <$z>
 615 .Ve
 616 .PP
 617 Reads a single line.
 618 .PP
 619 This method fully supports the use of of the variable \f(CW$/\fR (or
 620 \&\f(CW$INPUT_RECORD_SEPARATOR\fR or \f(CW$RS\fR when \f(CW\*(C`English\*(C'\fR is in use) to
 621 determine what constitutes an end of line. Paragraph mode, record mode and
 622 file slurp mode are all supported.
 623 .Sh "getc"
 624 .IX Subsection "getc"
 625 Usage is
 626 .PP
 627 .Vb 1
 628 \&    $char = $z\->getc()
 629 .Ve
 630 .PP
 631 Read a single character.
 632 .Sh "ungetc"
 633 .IX Subsection "ungetc"
 634 Usage is
 635 .PP
 636 .Vb 1
 637 \&    $char = $z\->ungetc($string)
 638 .Ve
 639 .Sh "getHeaderInfo"
 640 .IX Subsection "getHeaderInfo"
 641 Usage is
 642 .PP
 643 .Vb 2
 644 \&    $hdr  = $z\->getHeaderInfo();
 645 \&    @hdrs = $z\->getHeaderInfo();
 646 .Ve
 647 .PP
 648 This method returns either a hash reference (in scalar context) or a list
 649 or hash references (in array context) that contains information about each
 650 of the header fields in the compressed data stream(s).
 651 .Sh "tell"
 652 .IX Subsection "tell"
 653 Usage is
 654 .PP
 655 .Vb 2
 656 \&    $z\->tell()
 657 \&    tell $z
 658 .Ve
 659 .PP
 660 Returns the uncompressed file offset.
 661 .Sh "eof"
 662 .IX Subsection "eof"
 663 Usage is
 664 .PP
 665 .Vb 2
 666 \&    $z\->eof();
 667 \&    eof($z);
 668 .Ve
 669 .PP
 670 Returns true if the end of the compressed input stream has been reached.
 671 .Sh "seek"
 672 .IX Subsection "seek"
 673 .Vb 2
 674 \&    $z\->seek($position, $whence);
 675 \&    seek($z, $position, $whence);
 676 .Ve
 677 .PP
 678 Provides a sub-set of the \f(CW\*(C`seek\*(C'\fR functionality, with the restriction
 679 that it is only legal to seek forward in the input file/buffer.
 680 It is a fatal error to attempt to seek backward.
 681 .PP
 682 The \f(CW$whence\fR parameter takes one the usual values, namely \s-1SEEK_SET\s0,
 683 \&\s-1SEEK_CUR\s0 or \s-1SEEK_END\s0.
 684 .PP
 685 Returns 1 on success, 0 on failure.
 686 .Sh "binmode"
 687 .IX Subsection "binmode"
 688 Usage is
 689 .PP
 690 .Vb 2
 691 \&    $z\->binmode
 692 \&    binmode $z ;
 693 .Ve
 694 .PP
 695 This is a noop provided for completeness.
 696 .Sh "opened"
 697 .IX Subsection "opened"
 698 .Vb 1
 699 \&    $z\->opened()
 700 .Ve
 701 .PP
 702 Returns true if the object currently refers to a opened file/buffer.
 703 .Sh "autoflush"
 704 .IX Subsection "autoflush"
 705 .Vb 2
 706 \&    my $prev = $z\->autoflush()
 707 \&    my $prev = $z\->autoflush(EXPR)
 708 .Ve
 709 .PP
 710 If the \f(CW$z\fR object is associated with a file or a filehandle, this method
 711 returns the current autoflush setting for the underlying filehandle. If
 712 \&\f(CW\*(C`EXPR\*(C'\fR is present, and is non\-zero, it will enable flushing after every
 713 write/print operation.
 714 .PP
 715 If \f(CW$z\fR is associated with a buffer, this method has no effect and always
 716 returns \f(CW\*(C`undef\*(C'\fR.
 717 .PP
 718 \&\fBNote\fR that the special variable \f(CW$|\fR \fBcannot\fR be used to set or
 719 retrieve the autoflush setting.
 720 .Sh "input_line_number"
 721 .IX Subsection "input_line_number"
 722 .Vb 2
 723 \&    $z\->input_line_number()
 724 \&    $z\->input_line_number(EXPR)
 725 .Ve
 726 .PP
 727 Returns the current uncompressed line number. If \f(CW\*(C`EXPR\*(C'\fR is present it has
 728 the effect of setting the line number. Note that setting the line number
 729 does not change the current position within the file/buffer being read.
 730 .PP
 731 The contents of \f(CW$/\fR are used to to determine what constitutes a line
 732 terminator.
 733 .Sh "fileno"
 734 .IX Subsection "fileno"
 735 .Vb 2
 736 \&    $z\->fileno()
 737 \&    fileno($z)
 738 .Ve
 739 .PP
 740 If the \f(CW$z\fR object is associated with a file or a filehandle, \f(CW\*(C`fileno\*(C'\fR
 741 will return the underlying file descriptor. Once the \f(CW\*(C`close\*(C'\fR method is
 742 called \f(CW\*(C`fileno\*(C'\fR will return \f(CW\*(C`undef\*(C'\fR.
 743 .PP
 744 If the \f(CW$z\fR object is is associated with a buffer, this method will return
 745 \&\f(CW\*(C`undef\*(C'\fR.
 746 .Sh "close"
 747 .IX Subsection "close"
 748 .Vb 2
 749 \&    $z\->close() ;
 750 \&    close $z ;
 751 .Ve
 752 .PP
 753 Closes the output file/buffer.
 754 .PP
 755 For most versions of Perl this method will be automatically invoked if
 756 the IO::Uncompress::Bunzip2 object is destroyed (either explicitly or by the
 757 variable with the reference to the object going out of scope). The
 758 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
 759 these cases, the \f(CW\*(C`close\*(C'\fR method will be called automatically, but
 760 not until global destruction of all live objects when the program is
 761 terminating.
 762 .PP
 763 Therefore, if you want your scripts to be able to run on all versions
 764 of Perl, you should call \f(CW\*(C`close\*(C'\fR explicitly and not rely on automatic
 765 closing.
 766 .PP
 767 Returns true on success, otherwise 0.
 768 .PP
 769 If the \f(CW\*(C`AutoClose\*(C'\fR option has been enabled when the IO::Uncompress::Bunzip2
 770 object was created, and the object is associated with a file, the
 771 underlying file will also be closed.
 772 .Sh "nextStream"
 773 .IX Subsection "nextStream"
 774 Usage is
 775 .PP
 776 .Vb 1
 777 \&    my $status = $z\->nextStream();
 778 .Ve
 779 .PP
 780 Skips to the next compressed data stream in the input file/buffer. If a new
 781 compressed data stream is found, the eof marker will be cleared and \f(CW$.\fR
 782 will be reset to 0.
 783 .PP
 784 Returns 1 if a new stream was found, 0 if none was found, and \-1 if an
 785 error was encountered.
 786 .Sh "trailingData"
 787 .IX Subsection "trailingData"
 788 Usage is
 789 .PP
 790 .Vb 1
 791 \&    my $data = $z\->trailingData();
 792 .Ve
 793 .PP
 794 Returns the data, if any, that is present immediately after the compressed
 795 data stream once uncompression is complete. It only makes sense to call
 796 this method once the end of the compressed data stream has been
 797 encountered.
 798 .PP
 799 This option can be used when there is useful information immediately
 800 following the compressed data stream, and you don't know the length of the
 801 compressed data stream.
 802 .PP
 803 If the input is a buffer, \f(CW\*(C`trailingData\*(C'\fR will return everything from the
 804 end of the compressed data stream to the end of the buffer.
 805 .PP
 806 If the input is a filehandle, \f(CW\*(C`trailingData\*(C'\fR will return the data that is
 807 left in the filehandle input buffer once the end of the compressed data
 808 stream has been reached. You can then use the filehandle to read the rest
 809 of the input file.
 810 .PP
 811 Don't bother using \f(CW\*(C`trailingData\*(C'\fR if the input is a filename.
 812 .PP
 813 If you know the length of the compressed data stream before you start
 814 uncompressing, you can avoid having to use \f(CW\*(C`trailingData\*(C'\fR by setting the
 815 \&\f(CW\*(C`InputLength\*(C'\fR option in the constructor.
 816 .SH "Importing"
 817 .IX Header "Importing"
 818 No symbolic constants are required by this IO::Uncompress::Bunzip2 at present.
 819 .IP ":all" 5
 820 .IX Item ":all"
 821 Imports \f(CW\*(C`bunzip2\*(C'\fR and \f(CW$Bunzip2Error\fR.
 822 Same as doing this
 823 .Sp
 824 .Vb 1
 825 \&    use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
 826 .Ve
 827 .SH "EXAMPLES"
 828 .IX Header "EXAMPLES"
 829 .Sh "Working with Net::FTP"
 830 .IX Subsection "Working with Net::FTP"
 831 See IO::Uncompress::Bunzip2::FAQ
 832 .SH "SEE ALSO"
 833 .IX Header "SEE ALSO"
 834 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip, IO::Compress::Deflate, IO::Uncompress::Inflate, IO::Compress::RawDeflate, IO::Uncompress::RawInflate, IO::Compress::Bzip2, IO::Compress::Lzop, IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress
 835 .PP
 836 Compress::Zlib::FAQ
 837 .PP
 838 File::GlobMapper, Archive::Zip,
 839 Archive::Tar,
 840 IO::Zlib
 841 .PP
 842 The primary site for the bzip2 program is \fIhttp://www.bzip.org\fR.
 843 .PP
 844 See the module Compress::Bzip2
 845 .SH "AUTHOR"
 846 .IX Header "AUTHOR"
 847 This module was written by Paul Marquess, \fIpmqs@cpan.org\fR.
 848 .SH "MODIFICATION HISTORY"
 849 .IX Header "MODIFICATION HISTORY"
 850 See the Changes file.
 851 .SH "COPYRIGHT AND LICENSE"
 852 .IX Header "COPYRIGHT AND LICENSE"
 853 Copyright (c) 2005\-2008 Paul Marquess. All rights reserved.
 854 .PP
 855 This program is free software; you can redistribute it and/or
 856 modify it under the same terms as Perl itself.