local-lib5/man/man3/IO::Compress::Bzip2.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::Compress::Bzip2 3"
 132 .TH IO::Compress::Bzip2 3 "2009-11-09" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 IO::Compress::Bzip2 \- Write bzip2 files/buffers
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
 139 .Ve
 140 .PP
 141 .Vb 2
 142 \&    my $status = bzip2 $input => $output [,OPTS]
 143 \&        or die "bzip2 failed: $Bzip2Error\en";
 144 .Ve
 145 .PP
 146 .Vb 2
 147 \&    my $z = new IO::Compress::Bzip2 $output [,OPTS]
 148 \&        or die "bzip2 failed: $Bzip2Error\en";
 149 .Ve
 150 .PP
 151 .Vb 14
 152 \&    $z\->print($string);
 153 \&    $z\->printf($format, $string);
 154 \&    $z\->write($string);
 155 \&    $z\->syswrite($string [, $length, $offset]);
 156 \&    $z\->flush();
 157 \&    $z\->tell();
 158 \&    $z\->eof();
 159 \&    $z\->seek($position, $whence);
 160 \&    $z\->binmode();
 161 \&    $z\->fileno();
 162 \&    $z\->opened();
 163 \&    $z\->autoflush();
 164 \&    $z\->input_line_number();
 165 \&    $z\->newStream( [OPTS] );
 166 .Ve
 167 .PP
 168 .Vb 1
 169 \&    $z\->close() ;
 170 .Ve
 171 .PP
 172 .Vb 1
 173 \&    $Bzip2Error ;
 174 .Ve
 175 .PP
 176 .Vb 1
 177 \&    # IO::File mode
 178 .Ve
 179 .PP
 180 .Vb 8
 181 \&    print $z $string;
 182 \&    printf $z $format, $string;
 183 \&    tell $z
 184 \&    eof $z
 185 \&    seek $z, $position, $whence
 186 \&    binmode $z
 187 \&    fileno $z
 188 \&    close $z ;
 189 .Ve
 190 .SH "DESCRIPTION"
 191 .IX Header "DESCRIPTION"
 192 This module provides a Perl interface that allows writing bzip2
 193 compressed data to files or buffer.
 194 .PP
 195 For reading bzip2 files/buffers, see the companion module
 196 IO::Uncompress::Bunzip2.
 197 .SH "Functional Interface"
 198 .IX Header "Functional Interface"
 199 A top-level function, \f(CW\*(C`bzip2\*(C'\fR, is provided to carry out
 200 \&\*(L"one\-shot\*(R" compression between buffers and/or files. For finer
 201 control over the compression process, see the \*(L"\s-1OO\s0 Interface\*(R"
 202 section.
 203 .PP
 204 .Vb 1
 205 \&    use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
 206 .Ve
 207 .PP
 208 .Vb 2
 209 \&    bzip2 $input => $output [,OPTS]
 210 \&        or die "bzip2 failed: $Bzip2Error\en";
 211 .Ve
 212 .PP
 213 The functional interface needs Perl5.005 or better.
 214 .ie n .Sh "bzip2 $input\fP => \f(CW$output [, \s-1OPTS\s0]"
 215 .el .Sh "bzip2 \f(CW$input\fP => \f(CW$output\fP [, \s-1OPTS\s0]"
 216 .IX Subsection "bzip2 $input => $output [, OPTS]"
 217 \&\f(CW\*(C`bzip2\*(C'\fR expects at least two parameters, \f(CW$input\fR and \f(CW$output\fR.
 218 .PP
 219 \fIThe \f(CI$input\fI parameter\fR
 220 .IX Subsection "The $input parameter"
 221 .PP
 222 The parameter, \f(CW$input\fR, is used to define the source of
 223 the uncompressed data.
 224 .PP
 225 It can take one of the following forms:
 226 .IP "A filename" 5
 227 .IX Item "A filename"
 228 If the \f(CW$input\fR parameter is a simple scalar, it is assumed to be a
 229 filename. This file will be opened for reading and the input data
 230 will be read from it.
 231 .IP "A filehandle" 5
 232 .IX Item "A filehandle"
 233 If the \f(CW$input\fR parameter is a filehandle, the input data will be
 234 read from it.
 235 The string '\-' can be used as an alias for standard input.
 236 .IP "A scalar reference" 5
 237 .IX Item "A scalar reference"
 238 If \f(CW$input\fR is a scalar reference, the input data will be read
 239 from \f(CW$$input\fR.
 240 .IP "An array reference" 5
 241 .IX Item "An array reference"
 242 If \f(CW$input\fR is an array reference, each element in the array must be a
 243 filename.
 244 .Sp
 245 The input data will be read from each file in turn.
 246 .Sp
 247 The complete array will be walked to ensure that it only
 248 contains valid filenames before any data is compressed.
 249 .IP "An Input FileGlob string" 5
 250 .IX Item "An Input FileGlob string"
 251 If \f(CW$input\fR is a string that is delimited by the characters \*(L"<\*(R" and \*(L">\*(R"
 252 \&\f(CW\*(C`bzip2\*(C'\fR will assume that it is an \fIinput fileglob string\fR. The
 253 input is the list of files that match the fileglob.
 254 .Sp
 255 If the fileglob does not match any files ...
 256 .Sp
 257 See File::GlobMapper for more details.
 258 .PP
 259 If the \f(CW$input\fR parameter is any other type, \f(CW\*(C`undef\*(C'\fR will be returned.
 260 .PP
 261 \fIThe \f(CI$output\fI parameter\fR
 262 .IX Subsection "The $output parameter"
 263 .PP
 264 The parameter \f(CW$output\fR is used to control the destination of the
 265 compressed data. This parameter can take one of these forms.
 266 .IP "A filename" 5
 267 .IX Item "A filename"
 268 If the \f(CW$output\fR parameter is a simple scalar, it is assumed to be a
 269 filename.  This file will be opened for writing and the compressed
 270 data will be written to it.
 271 .IP "A filehandle" 5
 272 .IX Item "A filehandle"
 273 If the \f(CW$output\fR parameter is a filehandle, the compressed data
 274 will be written to it.
 275 The string '\-' can be used as an alias for standard output.
 276 .IP "A scalar reference" 5
 277 .IX Item "A scalar reference"
 278 If \f(CW$output\fR is a scalar reference, the compressed data will be
 279 stored in \f(CW$$output\fR.
 280 .IP "An Array Reference" 5
 281 .IX Item "An Array Reference"
 282 If \f(CW$output\fR is an array reference, the compressed data will be
 283 pushed onto the array.
 284 .IP "An Output FileGlob" 5
 285 .IX Item "An Output FileGlob"
 286 If \f(CW$output\fR is a string that is delimited by the characters \*(L"<\*(R" and \*(L">\*(R"
 287 \&\f(CW\*(C`bzip2\*(C'\fR will assume that it is an \fIoutput fileglob string\fR. The
 288 output is the list of files that match the fileglob.
 289 .Sp
 290 When \f(CW$output\fR is an fileglob string, \f(CW$input\fR must also be a fileglob
 291 string. Anything else is an error.
 292 .PP
 293 If the \f(CW$output\fR parameter is any other type, \f(CW\*(C`undef\*(C'\fR will be returned.
 294 .Sh "Notes"
 295 .IX Subsection "Notes"
 296 When \f(CW$input\fR maps to multiple files/buffers and \f(CW$output\fR is a single
 297 file/buffer the input files/buffers will be stored
 298 in \f(CW$output\fR as a concatenated series of compressed data streams.
 299 .Sh "Optional Parameters"
 300 .IX Subsection "Optional Parameters"
 301 Unless specified below, the optional parameters for \f(CW\*(C`bzip2\*(C'\fR,
 302 \&\f(CW\*(C`OPTS\*(C'\fR, are the same as those used with the \s-1OO\s0 interface defined in the
 303 \&\*(L"Constructor Options\*(R" section below.
 304 .ie n .IP """AutoClose => 0|1""" 5
 305 .el .IP "\f(CWAutoClose => 0|1\fR" 5
 306 .IX Item "AutoClose => 0|1"
 307 This option applies to any input or output data streams to
 308 \&\f(CW\*(C`bzip2\*(C'\fR that are filehandles.
 309 .Sp
 310 If \f(CW\*(C`AutoClose\*(C'\fR is specified, and the value is true, it will result in all
 311 input and/or output filehandles being closed once \f(CW\*(C`bzip2\*(C'\fR has
 312 completed.
 313 .Sp
 314 This parameter defaults to 0.
 315 .ie n .IP """BinModeIn => 0|1""" 5
 316 .el .IP "\f(CWBinModeIn => 0|1\fR" 5
 317 .IX Item "BinModeIn => 0|1"
 318 When reading from a file or filehandle, set \f(CW\*(C`binmode\*(C'\fR before reading.
 319 .Sp
 320 Defaults to 0.
 321 .ie n .IP """Append => 0|1""" 5
 322 .el .IP "\f(CWAppend => 0|1\fR" 5
 323 .IX Item "Append => 0|1"
 324 \&\s-1TODO\s0
 325 .Sh "Examples"
 326 .IX Subsection "Examples"
 327 To read the contents of the file \f(CW\*(C`file1.txt\*(C'\fR and write the compressed
 328 data to the file \f(CW\*(C`file1.txt.bz2\*(C'\fR.
 329 .PP
 330 .Vb 3
 331 \&    use strict ;
 332 \&    use warnings ;
 333 \&    use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
 334 .Ve
 335 .PP
 336 .Vb 3
 337 \&    my $input = "file1.txt";
 338 \&    bzip2 $input => "$input.bz2"
 339 \&        or die "bzip2 failed: $Bzip2Error\en";
 340 .Ve
 341 .PP
 342 To read from an existing Perl filehandle, \f(CW$input\fR, and write the
 343 compressed data to a buffer, \f(CW$buffer\fR.
 344 .PP
 345 .Vb 4
 346 \&    use strict ;
 347 \&    use warnings ;
 348 \&    use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
 349 \&    use IO::File ;
 350 .Ve
 351 .PP
 352 .Vb 5
 353 \&    my $input = new IO::File "<file1.txt"
 354 \&        or die "Cannot open 'file1.txt': $!\en" ;
 355 \&    my $buffer ;
 356 \&    bzip2 $input => \e$buffer
 357 \&        or die "bzip2 failed: $Bzip2Error\en";
 358 .Ve
 359 .PP
 360 To compress all files in the directory \*(L"/my/home\*(R" that match \*(L"*.txt\*(R"
 361 and store the compressed data in the same directory
 362 .PP
 363 .Vb 3
 364 \&    use strict ;
 365 \&    use warnings ;
 366 \&    use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
 367 .Ve
 368 .PP
 369 .Vb 2
 370 \&    bzip2 '</my/home/*.txt>' => '<*.bz2>'
 371 \&        or die "bzip2 failed: $Bzip2Error\en";
 372 .Ve
 373 .PP
 374 and if you want to compress each file one at a time, this will do the trick
 375 .PP
 376 .Vb 3
 377 \&    use strict ;
 378 \&    use warnings ;
 379 \&    use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
 380 .Ve
 381 .PP
 382 .Vb 6
 383 \&    for my $input ( glob "/my/home/*.txt" )
 384 \&    {
 385 \&        my $output = "$input.bz2" ;
 386 \&        bzip2 $input => $output
 387 \&            or die "Error compressing '$input': $Bzip2Error\en";
 388 \&    }
 389 .Ve
 390 .SH "OO Interface"
 391 .IX Header "OO Interface"
 392 .Sh "Constructor"
 393 .IX Subsection "Constructor"
 394 The format of the constructor for \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR is shown below
 395 .PP
 396 .Vb 2
 397 \&    my $z = new IO::Compress::Bzip2 $output [,OPTS]
 398 \&        or die "IO::Compress::Bzip2 failed: $Bzip2Error\en";
 399 .Ve
 400 .PP
 401 It returns an \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR object on success and undef on failure.
 402 The variable \f(CW$Bzip2Error\fR will contain an error message on failure.
 403 .PP
 404 If you are running Perl 5.005 or better the object, \f(CW$z\fR, returned from
 405 IO::Compress::Bzip2 can be used exactly like an IO::File filehandle.
 406 This means that all normal output file operations can be carried out
 407 with \f(CW$z\fR.
 408 For example, to write to a compressed file/buffer you can use either of
 409 these forms
 410 .PP
 411 .Vb 2
 412 \&    $z\->print("hello world\en");
 413 \&    print $z "hello world\en";
 414 .Ve
 415 .PP
 416 The mandatory parameter \f(CW$output\fR is used to control the destination
 417 of the compressed data. This parameter can take one of these forms.
 418 .IP "A filename" 5
 419 .IX Item "A filename"
 420 If the \f(CW$output\fR parameter is a simple scalar, it is assumed to be a
 421 filename. This file will be opened for writing and the compressed data
 422 will be written to it.
 423 .IP "A filehandle" 5
 424 .IX Item "A filehandle"
 425 If the \f(CW$output\fR parameter is a filehandle, the compressed data will be
 426 written to it.
 427 The string '\-' can be used as an alias for standard output.
 428 .IP "A scalar reference" 5
 429 .IX Item "A scalar reference"
 430 If \f(CW$output\fR is a scalar reference, the compressed data will be stored
 431 in \f(CW$$output\fR.
 432 .PP
 433 If the \f(CW$output\fR parameter is any other type, \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR::new will
 434 return undef.
 435 .Sh "Constructor Options"
 436 .IX Subsection "Constructor Options"
 437 \&\f(CW\*(C`OPTS\*(C'\fR is any combination of the following options:
 438 .ie n .IP """AutoClose => 0|1""" 5
 439 .el .IP "\f(CWAutoClose => 0|1\fR" 5
 440 .IX Item "AutoClose => 0|1"
 441 This option is only valid when the \f(CW$output\fR parameter is a filehandle. If
 442 specified, and the value is true, it will result in the \f(CW$output\fR being
 443 closed once either the \f(CW\*(C`close\*(C'\fR method is called or the \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR
 444 object is destroyed.
 445 .Sp
 446 This parameter defaults to 0.
 447 .ie n .IP """Append => 0|1""" 5
 448 .el .IP "\f(CWAppend => 0|1\fR" 5
 449 .IX Item "Append => 0|1"
 450 Opens \f(CW$output\fR in append mode.
 451 .Sp
 452 The behaviour of this option is dependent on the type of \f(CW$output\fR.
 453 .RS 5
 454 .IP "* A Buffer" 5
 455 .IX Item "A Buffer"
 456 If \f(CW$output\fR is a buffer and \f(CW\*(C`Append\*(C'\fR is enabled, all compressed data
 457 will be append to the end if \f(CW$output\fR. Otherwise \f(CW$output\fR will be
 458 cleared before any data is written to it.
 459 .IP "* A Filename" 5
 460 .IX Item "A Filename"
 461 If \f(CW$output\fR is a filename and \f(CW\*(C`Append\*(C'\fR is enabled, the file will be
 462 opened in append mode. Otherwise the contents of the file, if any, will be
 463 truncated before any compressed data is written to it.
 464 .IP "* A Filehandle" 5
 465 .IX Item "A Filehandle"
 466 If \f(CW$output\fR is a filehandle, the file pointer will be positioned to the
 467 end of the file via a call to \f(CW\*(C`seek\*(C'\fR before any compressed data is written
 468 to it.  Otherwise the file pointer will not be moved.
 469 .RE
 470 .RS 5
 471 .Sp
 472 This parameter defaults to 0.
 473 .RE
 474 .ie n .IP """BlockSize100K => number""" 5
 475 .el .IP "\f(CWBlockSize100K => number\fR" 5
 476 .IX Item "BlockSize100K => number"
 477 Specify the number of 100K blocks bzip2 uses during compression.
 478 .Sp
 479 Valid values are from 1 to 9, where 9 is best compression.
 480 .Sp
 481 The default is 1.
 482 .ie n .IP """WorkFactor => number""" 5
 483 .el .IP "\f(CWWorkFactor => number\fR" 5
 484 .IX Item "WorkFactor => number"
 485 Specifies how much effort bzip2 should take before resorting to a slower
 486 fallback compression algorithm.
 487 .Sp
 488 Valid values range from 0 to 250, where 0 means use the default value 30.
 489 .Sp
 490 The default is 0.
 491 .ie n .IP """Strict => 0|1""" 5
 492 .el .IP "\f(CWStrict => 0|1\fR" 5
 493 .IX Item "Strict => 0|1"
 494 This is a placeholder option.
 495 .Sh "Examples"
 496 .IX Subsection "Examples"
 497 \&\s-1TODO\s0
 498 .SH "Methods"
 499 .IX Header "Methods"
 500 .Sh "print"
 501 .IX Subsection "print"
 502 Usage is
 503 .PP
 504 .Vb 2
 505 \&    $z\->print($data)
 506 \&    print $z $data
 507 .Ve
 508 .PP
 509 Compresses and outputs the contents of the \f(CW$data\fR parameter. This
 510 has the same behaviour as the \f(CW\*(C`print\*(C'\fR built\-in.
 511 .PP
 512 Returns true if successful.
 513 .Sh "printf"
 514 .IX Subsection "printf"
 515 Usage is
 516 .PP
 517 .Vb 2
 518 \&    $z\->printf($format, $data)
 519 \&    printf $z $format, $data
 520 .Ve
 521 .PP
 522 Compresses and outputs the contents of the \f(CW$data\fR parameter.
 523 .PP
 524 Returns true if successful.
 525 .Sh "syswrite"
 526 .IX Subsection "syswrite"
 527 Usage is
 528 .PP
 529 .Vb 3
 530 \&    $z\->syswrite $data
 531 \&    $z\->syswrite $data, $length
 532 \&    $z\->syswrite $data, $length, $offset
 533 .Ve
 534 .PP
 535 Compresses and outputs the contents of the \f(CW$data\fR parameter.
 536 .PP
 537 Returns the number of uncompressed bytes written, or \f(CW\*(C`undef\*(C'\fR if
 538 unsuccessful.
 539 .Sh "write"
 540 .IX Subsection "write"
 541 Usage is
 542 .PP
 543 .Vb 3
 544 \&    $z\->write $data
 545 \&    $z\->write $data, $length
 546 \&    $z\->write $data, $length, $offset
 547 .Ve
 548 .PP
 549 Compresses and outputs the contents of the \f(CW$data\fR parameter.
 550 .PP
 551 Returns the number of uncompressed bytes written, or \f(CW\*(C`undef\*(C'\fR if
 552 unsuccessful.
 553 .Sh "flush"
 554 .IX Subsection "flush"
 555 Usage is
 556 .PP
 557 .Vb 1
 558 \&    $z\->flush;
 559 .Ve
 560 .PP
 561 Flushes any pending compressed data to the output file/buffer.
 562 .PP
 563 \&\s-1TODO\s0
 564 .PP
 565 Returns true on success.
 566 .Sh "tell"
 567 .IX Subsection "tell"
 568 Usage is
 569 .PP
 570 .Vb 2
 571 \&    $z\->tell()
 572 \&    tell $z
 573 .Ve
 574 .PP
 575 Returns the uncompressed file offset.
 576 .Sh "eof"
 577 .IX Subsection "eof"
 578 Usage is
 579 .PP
 580 .Vb 2
 581 \&    $z\->eof();
 582 \&    eof($z);
 583 .Ve
 584 .PP
 585 Returns true if the \f(CW\*(C`close\*(C'\fR method has been called.
 586 .Sh "seek"
 587 .IX Subsection "seek"
 588 .Vb 2
 589 \&    $z\->seek($position, $whence);
 590 \&    seek($z, $position, $whence);
 591 .Ve
 592 .PP
 593 Provides a sub-set of the \f(CW\*(C`seek\*(C'\fR functionality, with the restriction
 594 that it is only legal to seek forward in the output file/buffer.
 595 It is a fatal error to attempt to seek backward.
 596 .PP
 597 Empty parts of the file/buffer will have \s-1NULL\s0 (0x00) bytes written to them.
 598 .PP
 599 The \f(CW$whence\fR parameter takes one the usual values, namely \s-1SEEK_SET\s0,
 600 \&\s-1SEEK_CUR\s0 or \s-1SEEK_END\s0.
 601 .PP
 602 Returns 1 on success, 0 on failure.
 603 .Sh "binmode"
 604 .IX Subsection "binmode"
 605 Usage is
 606 .PP
 607 .Vb 2
 608 \&    $z\->binmode
 609 \&    binmode $z ;
 610 .Ve
 611 .PP
 612 This is a noop provided for completeness.
 613 .Sh "opened"
 614 .IX Subsection "opened"
 615 .Vb 1
 616 \&    $z\->opened()
 617 .Ve
 618 .PP
 619 Returns true if the object currently refers to a opened file/buffer.
 620 .Sh "autoflush"
 621 .IX Subsection "autoflush"
 622 .Vb 2
 623 \&    my $prev = $z\->autoflush()
 624 \&    my $prev = $z\->autoflush(EXPR)
 625 .Ve
 626 .PP
 627 If the \f(CW$z\fR object is associated with a file or a filehandle, this method
 628 returns the current autoflush setting for the underlying filehandle. If
 629 \&\f(CW\*(C`EXPR\*(C'\fR is present, and is non\-zero, it will enable flushing after every
 630 write/print operation.
 631 .PP
 632 If \f(CW$z\fR is associated with a buffer, this method has no effect and always
 633 returns \f(CW\*(C`undef\*(C'\fR.
 634 .PP
 635 \&\fBNote\fR that the special variable \f(CW$|\fR \fBcannot\fR be used to set or
 636 retrieve the autoflush setting.
 637 .Sh "input_line_number"
 638 .IX Subsection "input_line_number"
 639 .Vb 2
 640 \&    $z\->input_line_number()
 641 \&    $z\->input_line_number(EXPR)
 642 .Ve
 643 .PP
 644 This method always returns \f(CW\*(C`undef\*(C'\fR when compressing.
 645 .Sh "fileno"
 646 .IX Subsection "fileno"
 647 .Vb 2
 648 \&    $z\->fileno()
 649 \&    fileno($z)
 650 .Ve
 651 .PP
 652 If the \f(CW$z\fR object is associated with a file or a filehandle, \f(CW\*(C`fileno\*(C'\fR
 653 will return the underlying file descriptor. Once the \f(CW\*(C`close\*(C'\fR method is
 654 called \f(CW\*(C`fileno\*(C'\fR will return \f(CW\*(C`undef\*(C'\fR.
 655 .PP
 656 If the \f(CW$z\fR object is is associated with a buffer, this method will return
 657 \&\f(CW\*(C`undef\*(C'\fR.
 658 .Sh "close"
 659 .IX Subsection "close"
 660 .Vb 2
 661 \&    $z\->close() ;
 662 \&    close $z ;
 663 .Ve
 664 .PP
 665 Flushes any pending compressed data and then closes the output file/buffer.
 666 .PP
 667 For most versions of Perl this method will be automatically invoked if
 668 the IO::Compress::Bzip2 object is destroyed (either explicitly or by the
 669 variable with the reference to the object going out of scope). The
 670 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
 671 these cases, the \f(CW\*(C`close\*(C'\fR method will be called automatically, but
 672 not until global destruction of all live objects when the program is
 673 terminating.
 674 .PP
 675 Therefore, if you want your scripts to be able to run on all versions
 676 of Perl, you should call \f(CW\*(C`close\*(C'\fR explicitly and not rely on automatic
 677 closing.
 678 .PP
 679 Returns true on success, otherwise 0.
 680 .PP
 681 If the \f(CW\*(C`AutoClose\*(C'\fR option has been enabled when the IO::Compress::Bzip2
 682 object was created, and the object is associated with a file, the
 683 underlying file will also be closed.
 684 .Sh "newStream([\s-1OPTS\s0])"
 685 .IX Subsection "newStream([OPTS])"
 686 Usage is
 687 .PP
 688 .Vb 1
 689 \&    $z\->newStream( [OPTS] )
 690 .Ve
 691 .PP
 692 Closes the current compressed data stream and starts a new one.
 693 .PP
 694 \&\s-1OPTS\s0 consists of any of the the options that are available when creating
 695 the \f(CW$z\fR object.
 696 .PP
 697 See the \*(L"Constructor Options\*(R" section for more details.
 698 .SH "Importing"
 699 .IX Header "Importing"
 700 No symbolic constants are required by this IO::Compress::Bzip2 at present.
 701 .IP ":all" 5
 702 .IX Item ":all"
 703 Imports \f(CW\*(C`bzip2\*(C'\fR and \f(CW$Bzip2Error\fR.
 704 Same as doing this
 705 .Sp
 706 .Vb 1
 707 \&    use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
 708 .Ve
 709 .SH "EXAMPLES"
 710 .IX Header "EXAMPLES"
 711 .Sh "Apache::GZip Revisited"
 712 .IX Subsection "Apache::GZip Revisited"
 713 See IO::Compress::Bzip2::FAQ
 714 .Sh "Working with Net::FTP"
 715 .IX Subsection "Working with Net::FTP"
 716 See IO::Compress::Bzip2::FAQ
 717 .SH "SEE ALSO"
 718 .IX Header "SEE ALSO"
 719 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip, IO::Compress::Deflate, IO::Uncompress::Inflate, IO::Compress::RawDeflate, IO::Uncompress::RawInflate, IO::Uncompress::Bunzip2, IO::Compress::Lzop, IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress
 720 .PP
 721 Compress::Zlib::FAQ
 722 .PP
 723 File::GlobMapper, Archive::Zip,
 724 Archive::Tar,
 725 IO::Zlib
 726 .PP
 727 The primary site for the bzip2 program is \fIhttp://www.bzip.org\fR.
 728 .PP
 729 See the module Compress::Bzip2
 730 .SH "AUTHOR"
 731 .IX Header "AUTHOR"
 732 This module was written by Paul Marquess, \fIpmqs@cpan.org\fR.
 733 .SH "MODIFICATION HISTORY"
 734 .IX Header "MODIFICATION HISTORY"
 735 See the Changes file.
 736 .SH "COPYRIGHT AND LICENSE"
 737 .IX Header "COPYRIGHT AND LICENSE"
 738 Copyright (c) 2005\-2008 Paul Marquess. All rights reserved.
 739 .PP
 740 This program is free software; you can redistribute it and/or
 741 modify it under the same terms as Perl itself.