1Compress::Bzip2(3) User Contributed Perl Documentation Compress::Bzip2(3)
2
6 Compress::Bzip2 - Interface to Bzip2 compression library
7
9 use Compress::Bzip2 qw(:all :constant :utilities :gzip);
10 ($bz, $status) = bzdeflateInit( [PARAMS] ) ;
12 ($out, $status) = $bz->bzdeflate($buffer) ;
13 ($bz, $status) = bzinflateInit( [PARAMS] ) ;
15 ($out, $status) = $bz->bzinflate($buffer) ;
16 ($out, $status) = $bz->bzflush() ;
18 ($out, $status) = $bz->bzclose() ;
19 $dest = memBzip($source);
21 alias compress
22 $dest = memBunzip($source);
23 alias decompress
24 $bz = Compress::Bzip2->new( [PARAMS] );
26 $bz = bzopen($filename or filehandle, $mode);
28 alternate, with $bz created by new():
29 $bz->bzopen($filename or filehandle, $mode);
30 $bytesread = $bz->bzread($buffer [,$size]) ;
32 $bytesread = $bz->bzreadline($line);
33 $byteswritten = $bz->bzwrite($buffer [,$limit]);
34 $errstring = $bz->bzerror();
35 $status = $bz->bzeof();
36 $status = $bz->bzflush();
37 $status = $bz->bzclose() ;
38 $status = $bz->bzsetparams( $param => $setting );
40 $bz->total_in() ;
42 $bz->total_out() ;
43 $verstring = $bz->bzversion();
45 $Compress::Bzip2::bzerrno
47
49 The Compress::Bzip2 module provides a Perl interface to the Bzip2
50 compression library (see "AUTHOR" for details about where to get
51 Bzip2). A relevant subset of the functionality provided by Bzip2 is
52 available in Compress::Bzip2.
53 All string parameters can either be a scalar or a scalar reference.
55 The module can be split into two general areas of functionality, namely
57 in-memory compression/decompression and read/write access to bzip2
58 files. Each of these areas will be discussed separately below.
59
61 A number of functions are supplied in bzlib for reading and writing
62 bzip2 files. Unfortunately, most of them are not suitable. So, this
63 module provides another interface, built over top of the low level
64 bzlib methods.
65 $bz = bzopen(filename or filehandle, mode)
67 This function returns an object which is used to access the other bzip2
68 methods.
69 The mode parameter is used to specify both whether the file is opened
71 for reading or writing, with "r" or "w" respectively.
72 If a reference to an open filehandle is passed in place of the
74 filename, it better be positioned to the start of a
75 compression/decompression sequence.
76 $bz = Compress::Bzip2->new( [PARAMS] )
78 Create a Compress::Bzip2 object. Optionally, provide
79 compression/decompression parameters as a keyword => setting list. See
80 bzsetparams() for a description of the parameters.
81 $bz->bzopen(filename or filehandle, mode)
83 This is bzopen, but it uses an object previously created by the new
84 method. Other than that, it is identical to the above bzopen.
85 $bytesread = $bz->bzread($buffer [, $size]) ;
87 Reads $size bytes from the compressed file into $buffer. If $size is
88 not specified, it will default to 4096. If the scalar $buffer is not
89 large enough, it will be extended automatically.
90 Returns the number of bytes actually read. On EOF it returns 0 and in
92 the case of an error, -1.
93 $bytesread = $bz->bzreadline($line) ;
95 Reads the next line from the compressed file into $line.
96 Returns the number of bytes actually read. On EOF it returns 0 and in
98 the case of an error, -1.
99 It IS legal to intermix calls to bzread and bzreadline.
101 At this time bzreadline ignores the variable $/
103 ($INPUT_RECORD_SEPARATOR or $RS when "English" is in use). The end of a
104 line is denoted by the C character '\n'.
105 $byteswritten = $bz->bzwrite($buffer [, $limit]) ;
107 Writes the contents of $buffer to the compressed file. Returns the
108 number of bytes actually written, or 0 on error.
109 If $limit is given and non-zero, then only that many bytes from $buffer
111 will be written.
112 $status = $bz->bzflush($flush) ;
114 Flushes all pending output to the compressed file. Works identically
115 to the zlib function it interfaces to. Note that the use of bzflush can
116 degrade compression.
117 Returns "BZ_OK" if $flush is "BZ_FINISH" and all output could be
119 flushed. Otherwise the bzlib error code is returned.
120 Refer to the bzlib documentation for the valid values of $flush.
122 $status = $bz->bzeof() ;
124 Returns 1 if the end of file has been detected while reading the input
125 file, otherwise returns 0.
126 $bz->bzclose
128 Closes the compressed file. Any pending data is flushed to the file
129 before it is closed.
130 $bz->bzsetparams( [PARAMS] );
132 Change settings for the deflate stream $bz.
133 The list of the valid options is shown below. Options not specified
135 will remain unchanged.
136 -verbosity
138 Defines the verbosity level. Valid values are 0 through 4,
139 The default is "-verbosity => 0".
141 -blockSize100k
143 For bzip object opened for stream deflation or write.
144 Defines the buffering factor of compression method. The algorithm
146 buffers all data until the buffer is full, then it flushes all the
147 data out. Use -blockSize100k to specify the size of the buffer.
148 Valid settings are 1 through 9, representing a blocking in
150 multiples of 100k.
151 Note that each such block has an overhead of leading and trailing
153 synchronization bytes. bzip2 recovery uses this information to
154 pull useable data out of a corrupted file.
155 A streaming application would probably want to set the blocking
157 low.
158 -workFactor
160 For bzip object opened for stream deflation or write.
161 The workFactor setting tells the deflation algorithm how much work
163 to invest to compensate for repetitive data.
164 workFactor may be a number from 0 to 250 inclusive. The default
166 setting is 30.
167 See the bzip documentation for more information.
169 -small
171 For bzip object opened for stream inflation or read.
172 small may be 0 or 1. Set "small" to one to use a slower, less
174 memory intensive algorithm.
175 $bz->bzerror
177 Returns the bzlib error message or number for the last operation
178 associated with $bz. The return value will be the bzlib error number
179 when used in a numeric context and the bzlib error message when used in
180 a string context. The bzlib error number constants, shown below, are
181 available for use.
182 BZ_CONFIG_ERROR
184 BZ_DATA_ERROR
185 BZ_DATA_ERROR_MAGIC
186 BZ_FINISH
187 BZ_FINISH_OK
188 BZ_FLUSH
189 BZ_FLUSH_OK
190 BZ_IO_ERROR
191 BZ_MAX_UNUSED
192 BZ_MEM_ERROR
193 BZ_OK
194 BZ_OUTBUFF_FULL
195 BZ_PARAM_ERROR
196 BZ_RUN
197 BZ_RUN_OK
198 BZ_SEQUENCE_ERROR
199 BZ_STREAM_END
200 BZ_UNEXPECTED_EOF
201 $bzerrno
203 The $bzerrno scalar holds the error code associated with the most
204 recent bzip2 routine. Note that unlike bzerror(), the error is not
205 associated with a particular file.
206 As with bzerror() it returns an error number in numeric context and an
208 error message in string context. Unlike bzerror() though, the error
209 message will correspond to the bzlib message when the error is
210 associated with bzlib itself, or the UNIX error message when it is not
211 (i.e. bzlib returned "Z_ERRORNO").
212 As there is an overlap between the error numbers used by bzlib and
214 UNIX, $bzerrno should only be used to check for the presence of an
215 error in numeric context. Use bzerror() to check for specific bzlib
216 errors. The bzcat example below shows how the variable can be used
217 safely.
218
220 While the 2.x thread forked off of 1.00, another line of development
221 came to a head at 1.03. The 1.03 version worked with bzlib 1.0.2, had
222 improvements to the error handling, single buffer inflate/deflate, a
223 streaming interface to inflate/deflate, and a cpan style test suite.
224 $dest = compress( $string, [$level] )
226 Alias to memBzip, this compresses string, using the optional
227 compression level, 1 through 9, the default being 1. Returns a string
228 containing the compressed data.
229 On error undef is returned.
231 $dest = decompress($string)
233 Alias to memBunzip, this decompresses the data in string, returning a
234 string containing the decompressed data.
235 On error undef is returned.
237 $stream = compress_init( [PARAMS] )
239 Alias to bzdeflateInit. In addition to the named parameters documented
240 for bzdeflateInit, the following are accepted:
241 -level, alias to -blockSize100k
243 -buffer, to set the buffer size.
244 The -buffer option is ignored. The intermediate buffer size is not
246 changeable.
247 $stream = decompress_init( [PARAMS] )
249 Alias to bzinflateInit. See bzinflateInit for a description of the
250 parameters. The option "-buffer" is accepted, but ignored.
251 $output = $stream->add( $string )
253 Add data to be compressed/decompressed. Returns whatever output is
254 available (possibly none, if it's still buffering it), or undef on
255 error.
256 $output = $stream->finish( [$string] )
258 Finish the operation; takes an optional final data string. Whatever is
259 returned completes the output; returns undef on error.
260 $stream->error
262 Like the function, but applies to the current object only. Note that
263 errors in a stream object are also returned by the function.
264 $stream->input_size
266 Alias to total_in. Total bytes passed to the stream.
267 $stream->output_size
269 Alias to total_out. Total bytes received from the stream.
270
272 Except for the exact state and error numbers, this package presents an
273 interface very much like that given by the Compress::Zlib package.
274 Mostly, if you take the method name, state or error number from
275 Compress::Zlib and replace the "g" with a "b", your code should work.
276 To make the interoperability even easier, all the Compress::Zlib method
278 names have been used as aliases or cover functions for the bzip2
279 methods.
280 Therefore, most code that uses Compress::Zlib should be able to use
282 this package, with a one line change.
283 Simply change
285 $gz = Compress::Zlib::gzopen( "filename", "w" );
287 to
289 $gz = Compress::Bzip2::gzopen( "filename", "w" );
291 Some of the Compress::Zlib aliases don't return anything useful, like
293 crc32 or adler32, cause bzip2 doesn't do that sort of thing.
294 $gz = gzopen( $filename, $mode )
296 Alias for bzopen.
297 $gz->gzread( $buffer, [ $length ] )
299 Alias for bzread.
300 $gz->gzreadline( $buffer )
302 Alias for bzreadline.
303 $gz->gzwrite( $buffer )
305 Alias for bzwrite.
306 $gz->gzflush( [$flushtype] )
308 Alias for bzflush, with return code translation.
309 $gz->gzclose( )
311 Alias for bzclose.
312 $gz->gzeof( )
314 Alias for bzeof.
315 $gz->gzerror( )
317 Alias for bzerror.
318 $gz->gzsetparams( $level, $strategy )
320 This is a no-op.
321 $d = deflateInit( [OPTS] )
323 Alias for bzdeflateInit, with return code translation.
324 All OPTS are ignored.
326 $d->deflate( $buffer )
328 Alias for bzdeflate, with return code translation.
329 $d->deflateParams( [OPTS] )
331 This is a no-op.
332 $d->flush( [$flushtype] )
334 Cover function for bzflush or bzclose, depending on $flushtype.
335 See the Compress::Zlib documentation for more information.
337 $d->dict_adler( )
339 This is a no-op.
340 $d->msg( )
342 This is a no-op.
343 $d = inflateInit( [OPTS] )
345 Alias for bzinflateInit, with return code translation.
346 All OPTS are ignored.
348 $d->inflate( )
350 Alias for bzinflate, with return code translation.
351 $d->inflateSync( )
353 This is a no-op.
354 $d->adler32( $crc )
356 This is a no-op.
357 $d->crc32( $crc )
359 This is a no-op.
360 $buffer = memGzip( $buffer )
362 Alias for memBzip.
363 $buffer = memGunzip( $buffer )
365 Alias for memBunzip.
366
368 Two high-level functions are provided by bzlib to perform in-memory
369 compression. They are memBzip and memBunzip. Two Perl subs are provided
370 which provide similar functionality.
371 $compressed = memBzip($buffer);
373 Compresses $source. If successful it returns the compressed data.
374 Otherwise it returns undef.
375 The buffer parameter can either be a scalar or a scalar reference.
377 Essentially, an in-memory bzip file is created. It creates a minimal
379 bzip header.
380 $uncompressed = memBunzip($buffer);
382 Uncompresses $source. If successful it returns the uncompressed data.
383 Otherwise it returns undef.
384 The source buffer can either be a scalar or a scalar reference.
386 The buffer parameter can either be a scalar or a scalar reference. The
388 contents of the buffer parameter are destroyed after calling this
389 function.
390
392 The Perl interface will always consume the complete input buffer before
393 returning. Also the output buffer returned will be automatically grown
394 to fit the amount of output available.
395 Here is a definition of the interface available:
397 ($d, $status) = bzdeflateInit( [PARAMS] )
399 Initialises a deflation stream.
400 If successful, it will return the initialised deflation stream, $d and
402 $status of "BZ_OK" in a list context. In scalar context it returns the
403 deflation stream, $d, only.
404 If not successful, the returned deflation stream ($d) will be undef and
406 $status will hold the exact bzip2 error code.
407 The function optionally takes a number of named options specified as
409 "-Name=>value" pairs. This allows individual options to be tailored
410 without having to specify them all in the parameter list.
411 Here is a list of the valid options:
413 -verbosity
415 Defines the verbosity level. Valid values are 0 through 4,
416 The default is "-verbosity => 0".
418 -blockSize100k
420 Defines the buffering factor of compression method. The algorithm
421 buffers all data until the buffer is full, then it flushes all the
422 data out. Use -blockSize100k to specify the size of the buffer.
423 Valid settings are 1 through 9, representing a blocking in
425 multiples of 100k.
426 Note that each such block has an overhead of leading and trailing
428 synchronization bytes. bzip2 recovery uses this information to
429 pull useable data out of a corrupted file.
430 A streaming application would probably want to set the blocking
432 low.
433 -workFactor
435 The workFactor setting tells the deflation algorithm how much work
436 to invest to compensate for repetitive data.
437 workFactor may be a number from 0 to 250 inclusive. The default
439 setting is 30.
440 See the bzip documentation for more information.
442 Here is an example of using the deflateInit optional parameter list to
444 override the default buffer size and compression level. All other
445 options will take their default values.
446 bzdeflateInit( -blockSize100k => 1, -verbosity => 1 );
448 ($out, $status) = $d->bzdeflate($buffer)
450 Deflates the contents of $buffer. The buffer can either be a scalar or
451 a scalar reference. When finished, $buffer will be completely
452 processed (assuming there were no errors). If the deflation was
453 successful it returns deflated output, $out, and a status value,
454 $status, of "Z_OK".
455 On error, $out will be undef and $status will contain the zlib error
457 code.
458 In a scalar context bzdeflate will return $out only.
460 As with the internal buffering of the deflate function in bzip2, it is
462 not necessarily the case that any output will be produced by this
463 method. So don't rely on the fact that $out is empty for an error test.
464 In fact, given the size of bzdeflates internal buffer, with most files
465 it's likely you won't see any output at all until flush or close.
466 ($out, $status) = $d->bzflush([flush_type])
468 Typically used to finish the deflation. Any pending output will be
469 returned via $out. $status will have a value "BZ_OK" if successful.
470 In a scalar context bzflush will return $out only.
472 Note that flushing can seriously degrade the compression ratio, so it
474 should only be used to terminate a decompression (using "BZ_FLUSH") or
475 when you want to create a full flush point (using "BZ_FINISH").
476 The allowable values for "flush_type" are "BZ_FLUSH" and "BZ_FINISH".
478 For a handle opened for "w" (bzwrite), the default is "BZ_FLUSH". For
480 a stream, the default for "flush_type" is "BZ_FINISH" (which is
481 essentially a close and reopen).
482 It is strongly recommended that you only set the "flush_type" parameter
484 if you fully understand the implications of what it does. See the
485 "bzip2" documentation for details.
486 Example
488 Here is a trivial example of using bzdeflate. It simply reads standard
489 input, deflates it and writes it to standard output.
490 use strict ;
492 use warnings ;
493 use Compress::Bzip2 ;
495 binmode STDIN;
497 binmode STDOUT;
498 my $x = bzdeflateInit()
499 or die "Cannot create a deflation stream\n" ;
500 my ($output, $status) ;
502 while (<>)
503 {
504 ($output, $status) = $x->bzdeflate($_) ;
505 $status == BZ_OK
507 or die "deflation failed\n" ;
508 print $output ;
510 }
511 ($output, $status) = $x->bzclose() ;
513 $status == BZ_OK
515 or die "deflation failed\n" ;
516 print $output ;
518
520 Here is a definition of the interface:
521 ($i, $status) = inflateInit()
523 Initialises an inflation stream.
524 In a list context it returns the inflation stream, $i, and the zlib
526 status code ($status). In a scalar context it returns the inflation
527 stream only.
528 If successful, $i will hold the inflation stream and $status will be
530 "BZ_OK".
531 If not successful, $i will be undef and $status will hold the bzlib.h
533 error code.
534 The function optionally takes a number of named options specified as
536 "-Name=>value" pairs. This allows individual options to be tailored
537 without having to specify them all in the parameter list.
538 For backward compatibility, it is also possible to pass the parameters
540 as a reference to a hash containing the name=>value pairs.
541 The function takes one optional parameter, a reference to a hash. The
543 contents of the hash allow the deflation interface to be tailored.
544 Here is a list of the valid options:
546 -small
548 small may be 0 or 1. Set "small" to one to use a slower, less
549 memory intensive algorithm.
550 -verbosity
552 Defines the verbosity level. Valid values are 0 through 4,
553 The default is "-verbosity => 0".
555 Here is an example of using the bzinflateInit optional parameter.
557 bzinflateInit( -small => 1, -verbosity => 1 );
559 ($out, $status) = $i->bzinflate($buffer)
561 Inflates the complete contents of $buffer. The buffer can either be a
562 scalar or a scalar reference.
563 Returns "BZ_OK" if successful and "BZ_STREAM_END" if the end of the
565 compressed data has been successfully reached. If not successful, $out
566 will be undef and $status will hold the bzlib error code.
567 The $buffer parameter is modified by "bzinflate". On completion it will
569 contain what remains of the input buffer after inflation. This means
570 that $buffer will be an empty string when the return status is "BZ_OK".
571 When the return status is "BZ_STREAM_END" the $buffer parameter will
572 contains what (if anything) was stored in the input buffer after the
573 deflated data stream.
574 This feature is useful when processing a file format that encapsulates
576 a compressed data stream.
577 Example
579 Here is an example of using bzinflate.
580 use strict ;
582 use warnings ;
583 use Compress::Bzip2;
585 my $x = bzinflateInit()
587 or die "Cannot create a inflation stream\n" ;
588 my $input = '' ;
590 binmode STDIN;
591 binmode STDOUT;
592 my ($output, $status) ;
594 while (read(STDIN, $input, 4096))
595 {
596 ($output, $status) = $x->bzinflate(\$input) ;
597 print $output
599 if $status == BZ_OK or $status == BZ_STREAM_END ;
600 last if $status != BZ_OK ;
602 }
603 die "inflation failed\n"
605 unless $status == BZ_STREAM_END ;
606
608 Here are some example scripts of using the interface.
609 A bzcat function
611 use strict ;
612 use warnings ;
613 use Compress::Bzip2 ;
615 die "Usage: bzcat file...\n" unless @ARGV ;
617 my $file ;
619 foreach $file (@ARGV) {
621 my $buffer ;
622 my $bz = bzopen($file, "rb")
624 or die "Cannot open $file: $bzerrno\n" ;
625 print $buffer while $bz->bzread($buffer) > 0 ;
627 die "Error reading from $file: $bzerrno" . ($bzerrno+0) . "\n"
629 if $bzerrno != BZ_STREAM_END ;
630 $bz->bzclose() ;
632 }
633 A grep using bzreadline
635 use strict ;
636 use warnings ;
637 use Compress::Bzip2 ;
639 die "Usage: bzgrep pattern file...\n" unless @ARGV >= 2;
641 my $pattern = shift ;
643 my $file ;
645 foreach $file (@ARGV) {
647 my $bz = bzopen($file, "rb")
648 or die "Cannot open $file: $bzerrno\n" ;
649 while ($bz->bzreadline($_) > 0) {
651 print if /$pattern/ ;
652 }
653 die "Error reading from $file: $bzerrno\n"
655 if $bzerrno != Z_STREAM_END ;
656 $bz->bzclose() ;
658 }
659 Streaming Compression
661 This script, bzstream, does the opposite of the bzcat script above. It
662 reads from standard input and writes a bzip file to standard output.
663 use strict ;
665 use warnings ;
666 use Compress::Bzip2 ;
668 binmode STDOUT; # bzopen only sets it on the fd
670 my $bz = bzopen(\*STDOUT, "wb")
672 or die "Cannot open stdout: $bzerrno\n" ;
673 while (<>) {
675 $bz->bzwrite($_) or die "error writing: $bzerrno\n" ;
676 }
677 $bz->bzclose ;
679
681 Use the tags :all, :utilities, :constants, :bzip1 and :gzip.
682 Export tag :all
684 This exports all the exportable methods.
685 Export tag :constants
687 This exports only the BZ_* constants.
688 Export tag :bzip1
690 This exports the Compress::Bzip2 1.x functions, for compatibility.
691 compress
693 decompress
694 compress_init
695 decompress_init
696 version
697 These are actually aliases to memBzip and memBunzip.
699 Export tag :utilities
701 This gives an interface to the bzip2 methods.
702 bzopen
704 bzinflateInit
705 bzdeflateInit
706 memBzip
707 memBunzip
708 bzip2
709 bunzip2
710 bzcat
711 bzlibversion
712 $bzerrno
713 Export tag :gzip
715 This gives compatibility with Compress::Zlib.
716 gzopen
718 gzinflateInit
719 gzdeflateInit
720 memGzip
721 memGunzip
722 $gzerrno
723
725 All the bzlib constants are automatically imported when you make use of
726 Compress::Bzip2.
727 BZ_CONFIG_ERROR
729 BZ_DATA_ERROR
730 BZ_DATA_ERROR_MAGIC
731 BZ_FINISH
732 BZ_FINISH_OK
733 BZ_FLUSH
734 BZ_FLUSH_OK
735 BZ_IO_ERROR
736 BZ_MAX_UNUSED
737 BZ_MEM_ERROR
738 BZ_OK
739 BZ_OUTBUFF_FULL
740 BZ_PARAM_ERROR
741 BZ_RUN
742 BZ_RUN_OK
743 BZ_SEQUENCE_ERROR
744 BZ_STREAM_END
745 BZ_UNEXPECTED_EOF
746
748 The documentation for zlib, bzip2 and Compress::Zlib.
749
751 Rob Janes, <arjay at cpan.org>
752
754 Copyright (C) 2005 by Rob Janes
755 This library is free software; you can redistribute it and/or modify it
757 under the same terms as Perl itself, either Perl version 5.8.3 or, at
758 your option, any later version of Perl 5 you may have available.
759
761 The Compress::Bzip2 module was originally written by Gawdi Azem
762 azemgi@rupert.informatik.uni-stuttgart.de.
763 The first Compress::Bzip2 module was written by Gawdi Azem
765 azemgi@rupert.informatik.uni-stuttgart.de. It provided an interface to
766 the in memory inflate and deflate routines.
767 Compress::Bzip2 was subsequently passed on to Marco Carnut
769 kiko@tempest.com.br who shepharded it through to version 1.03, a set of
770 changes which included upgrades to handle bzlib 1.0.2, and improvements
771 to the in memory inflate and deflate routines. The streaming interface
772 and error information were added by David Robins
773 dbrobins@davidrobins.net.
774 Version 2 of Compress::Bzip2 is due to Rob Janes, of arjay@cpan.org.
776 This release is intended to give an interface close to that of
777 Compress::Zlib. It's development forks from 1.00, not 1.03, so the
778 streaming interface is not the same as that in 1.03, although
779 apparently compatible as it passes the 1.03 test suite.
780
782 See the Changes file.
783 2.00 Second public release of Compress::Bzip2.
785
787 Hey! The above document had some coding errors, which are explained
788 below:
789 Around line 746:
791 You forgot a '=back' before '=head2'
792 Around line 918:
794 =back without =over
795 Around line 929:
797 You forgot a '=back' before '=head2'
798 Around line 983:
800 =back without =over
801 Around line 1011:
803 You forgot a '=back' before '=head2'
804 Around line 1105:
806 =back without =over
807 Around line 1115:
809 You forgot a '=back' before '=head2'
810 Around line 1136:
812 =back without =over
813 Around line 1384:
815 You forgot a '=back' before '=head2'
816 Around line 1458:
818 =back without =over
819perl v5.12.0 2005-08-09 Compress::Bzip2(3)