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 com‐
50 pression library (see "AUTHOR" for details about where to get Bzip2). A
51 relevant subset of the functionality provided by Bzip2 is available in
52 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
69 bzip2 methods.
70 The mode parameter is used to specify both whether the file is
72 opened for reading or writing, with "r" or "w" respectively.
73 If a reference to an open filehandle is passed in place of the
75 filename, it better be positioned to the start of a compres‐
76 sion/decompression sequence.
77 $bz = Compress::Bzip2->new( [PARAMS] )
79 Create a Compress::Bzip2 object. Optionally, provide compres‐
81 sion/decompression parameters as a keyword => setting list. See
82 bzsetparams() for a description of the parameters.
83 $bz->bzopen(filename or filehandle, mode)
85 This is bzopen, but it uses an object previously created by the
87 new method. Other than that, it is identical to the above bzopen.
88 $bytesread = $bz->bzread($buffer [, $size]) ;
90 Reads $size bytes from the compressed file into $buffer. If $size
92 is not specified, it will default to 4096. If the scalar $buffer
93 is not large enough, it will be extended automatically.
94 Returns the number of bytes actually read. On EOF it returns 0 and
96 in the case of an error, -1.
97 $bytesread = $bz->bzreadline($line) ;
99 Reads the next line from the compressed file into $line.
101 Returns the number of bytes actually read. On EOF it returns 0 and
103 in the case of an error, -1.
104 It IS legal to intermix calls to bzread and bzreadline.
106 At this time bzreadline ignores the variable $/
108 ($INPUT_RECORD_SEPARATOR or $RS when "English" is in use). The end
109 of a line is denoted by the C character '\n'.
110 $byteswritten = $bz->bzwrite($buffer [, $limit]) ;
112 Writes the contents of $buffer to the compressed file. Returns the
114 number of bytes actually written, or 0 on error.
115 If $limit is given and non-zero, then only that many bytes from
117 $buffer will be written.
118 $status = $bz->bzflush($flush) ;
120 Flushes all pending output to the compressed file. Works identi‐
122 cally to the zlib function it interfaces to. Note that the use of
123 bzflush can degrade compression.
124 Returns "BZ_OK" if $flush is "BZ_FINISH" and all output could be
126 flushed. Otherwise the bzlib error code is returned.
127 Refer to the bzlib documentation for the valid values of $flush.
129 $status = $bz->bzeof() ;
131 Returns 1 if the end of file has been detected while reading the
133 input file, otherwise returns 0.
134 $bz->bzclose
136 Closes the compressed file. Any pending data is flushed to the
138 file before it is closed.
139 $bz->bzsetparams( [PARAMS] );
141 Change settings for the deflate stream $bz.
143 The list of the valid options is shown below. Options not speci‐
145 fied will remain unchanged.
146 -verbosity
148 Defines the verbosity level. Valid values are 0 through 4,
149 The default is "-verbosity => 0".
151 -blockSize100k
153 For bzip object opened for stream deflation or write.
154 Defines the buffering factor of compression method. The
156 algorithm buffers all data until the buffer is full, then it
157 flushes all the data out. Use -blockSize100k to specify the
158 size of the buffer.
159 Valid settings are 1 through 9, representing a blocking in
161 multiples of 100k.
162 Note that each such block has an overhead of leading and
164 trailing synchronization bytes. bzip2 recovery uses this
165 information to pull useable data out of a corrupted file.
166 A streaming application would probably want to set the block‐
168 ing low.
169 -workFactor
171 For bzip object opened for stream deflation or write.
172 The workFactor setting tells the deflation algorithm how much
174 work to invest to compensate for repetitive data.
175 workFactor may be a number from 0 to 250 inclusive. The
177 default setting is 30.
178 See the bzip documentation for more information.
180 -small
182 For bzip object opened for stream inflation or read.
183 small may be 0 or 1. Set "small" to one to use a slower,
185 less memory intensive algorithm.
186 $bz->bzerror
188 Returns the bzlib error message or number for the last operation
190 associated with $bz. The return value will be the bzlib error num‐
191 ber when used in a numeric context and the bzlib error message
192 when used in a string context. The bzlib error number constants,
193 shown below, are available for use.
194 BZ_CONFIG_ERROR
196 BZ_DATA_ERROR
197 BZ_DATA_ERROR_MAGIC
198 BZ_FINISH
199 BZ_FINISH_OK
200 BZ_FLUSH
201 BZ_FLUSH_OK
202 BZ_IO_ERROR
203 BZ_MAX_UNUSED
204 BZ_MEM_ERROR
205 BZ_OK
206 BZ_OUTBUFF_FULL
207 BZ_PARAM_ERROR
208 BZ_RUN
209 BZ_RUN_OK
210 BZ_SEQUENCE_ERROR
211 BZ_STREAM_END
212 BZ_UNEXPECTED_EOF
213 $bzerrno
215 The $bzerrno scalar holds the error code associated with the most
217 recent bzip2 routine. Note that unlike bzerror(), the error is not
218 associated with a particular file.
219 As with bzerror() it returns an error number in numeric context
221 and an error message in string context. Unlike bzerror() though,
222 the error message will correspond to the bzlib message when the
223 error is associated with bzlib itself, or the UNIX error message
224 when it is not (i.e. bzlib returned "Z_ERRORNO").
225 As there is an overlap between the error numbers used by bzlib and
227 UNIX, $bzerrno should only be used to check for the presence of an
228 error in numeric context. Use bzerror() to check for specific
229 bzlib errors. The bzcat example below shows how the variable can
230 be used safely.
231
233 While the 2.x thread forked off of 1.00, another line of development
234 came to a head at 1.03. The 1.03 version worked with bzlib 1.0.2, had
235 improvements to the error handling, single buffer inflate/deflate, a
236 streaming interface to inflate/deflate, and a cpan style test suite.
237 $dest = compress( $string, [$level] )
239 Alias to memBzip, this compresses string, using the optional com‐
241 pression level, 1 through 9, the default being 1. Returns a
242 string containing the compressed data.
243 On error undef is returned.
245 $dest = decompress($string)
247 Alias to memBunzip, this decompresses the data in string, return‐
249 ing a string containing the decompressed data.
250 On error undef is returned.
252 $stream = compress_init( [PARAMS] )
254 Alias to bzdeflateInit. In addition to the named parameters docu‐
256 mented for bzdeflateInit, the following are accepted:
257 -level, alias to -blockSize100k
259 -buffer, to set the buffer size.
260 The -buffer option is ignored. The intermediate buffer size is
262 not changeable.
263 $stream = decompress_init( [PARAMS] )
265 Alias to bzinflateInit. See bzinflateInit for a description of
267 the parameters. The option "-buffer" is accepted, but ignored.
268 $output = $stream->add( $string )
270 Add data to be compressed/decompressed. Returns whatever output
272 is available (possibly none, if it's still buffering it), or undef
273 on error.
274 $output = $stream->finish( [$string] )
276 Finish the operation; takes an optional final data string. What‐
278 ever is returned completes the output; returns undef on error.
279 $stream->error
281 Like the function, but applies to the current object only. Note
283 that errors in a stream object are also returned by the function.
284 $stream->input_size
286 Alias to total_in. Total bytes passed to the stream.
288 $stream->output_size
290 Alias to total_out. Total bytes received from the stream.
292
294 Except for the exact state and error numbers, this package presents an
295 interface very much like that given by the Compress::Zlib package.
296 Mostly, if you take the method name, state or error number from Com‐
297 press::Zlib and replace the "g" with a "b", your code should work.
298 To make the interoperability even easier, all the Compress::Zlib method
300 names have been used as aliases or cover functions for the bzip2 meth‐
301 ods.
302 Therefore, most code that uses Compress::Zlib should be able to use
304 this package, with a one line change.
305 Simply change
307 $gz = Compress::Zlib::gzopen( "filename", "w" );
309 to
311 $gz = Compress::Bzip2::gzopen( "filename", "w" );
313 Some of the Compress::Zlib aliases don't return anything useful, like
315 crc32 or adler32, cause bzip2 doesn't do that sort of thing.
316 $gz = gzopen( $filename, $mode )
318 Alias for bzopen.
320 $gz->gzread( $buffer, [ $length ] )
322 Alias for bzread.
324 $gz->gzreadline( $buffer )
326 Alias for bzreadline.
328 $gz->gzwrite( $buffer )
330 Alias for bzwrite.
332 $gz->gzflush( [$flushtype] )
334 Alias for bzflush, with return code translation.
336 $gz->gzclose( )
338 Alias for bzclose.
340 $gz->gzeof( )
342 Alias for bzeof.
344 $gz->gzerror( )
346 Alias for bzerror.
348 $gz->gzsetparams( $level, $strategy )
350 This is a no-op.
352 $d = deflateInit( [OPTS] )
354 Alias for bzdeflateInit, with return code translation.
356 All OPTS are ignored.
358 $d->deflate( $buffer )
360 Alias for bzdeflate, with return code translation.
362 $d->deflateParams( [OPTS] )
364 This is a no-op.
366 $d->flush( [$flushtype] )
368 Cover function for bzflush or bzclose, depending on $flushtype.
370 See the Compress::Zlib documentation for more information.
372 $d->dict_adler( )
374 This is a no-op.
376 $d->msg( )
378 This is a no-op.
380 $d = inflateInit( [OPTS] )
382 Alias for bzinflateInit, with return code translation.
384 All OPTS are ignored.
386 $d->inflate( )
388 Alias for bzinflate, with return code translation.
390 $d->inflateSync( )
392 This is a no-op.
394 $d->adler32( $crc )
396 This is a no-op.
398 $d->crc32( $crc )
400 This is a no-op.
402 $buffer = memGzip( $buffer )
404 Alias for memBzip.
406 $buffer = memGunzip( $buffer )
408 Alias for memBunzip.
410
412 Two high-level functions are provided by bzlib to perform in-memory
413 compression. They are memBzip and memBunzip. Two Perl subs are provided
414 which provide similar functionality.
415 $compressed = memBzip($buffer);
417 Compresses $source. If successful it returns the compressed data.
419 Otherwise it returns undef.
420 The buffer parameter can either be a scalar or a scalar reference.
422 Essentially, an in-memory bzip file is created. It creates a mini‐
424 mal bzip header.
425 $uncompressed = memBunzip($buffer);
427 Uncompresses $source. If successful it returns the uncompressed
429 data. Otherwise it returns undef.
430 The source buffer can either be a scalar or a scalar reference.
432 The buffer parameter can either be a scalar or a scalar reference.
434 The contents of the buffer parameter are destroyed after calling
435 this function.
436
438 The Perl interface will always consume the complete input buffer before
439 returning. Also the output buffer returned will be automatically grown
440 to fit the amount of output available.
441 Here is a definition of the interface available:
443 ($d, $status) = bzdeflateInit( [PARAMS] )
445 Initialises a deflation stream.
447 If successful, it will return the initialised deflation stream, $d and
449 $status of "BZ_OK" in a list context. In scalar context it returns the
450 deflation stream, $d, only.
451 If not successful, the returned deflation stream ($d) will be undef and
453 $status will hold the exact bzip2 error code.
454 The function optionally takes a number of named options specified as
456 "-Name=>value" pairs. This allows individual options to be tailored
457 without having to specify them all in the parameter list.
458 Here is a list of the valid options:
460 -verbosity
462 Defines the verbosity level. Valid values are 0 through 4,
463 The default is "-verbosity => 0".
465 -blockSize100k
467 Defines the buffering factor of compression method. The algorithm
468 buffers all data until the buffer is full, then it flushes all the
469 data out. Use -blockSize100k to specify the size of the buffer.
470 Valid settings are 1 through 9, representing a blocking in multi‐
472 ples of 100k.
473 Note that each such block has an overhead of leading and trailing
475 synchronization bytes. bzip2 recovery uses this information to
476 pull useable data out of a corrupted file.
477 A streaming application would probably want to set the blocking
479 low.
480 -workFactor
482 The workFactor setting tells the deflation algorithm how much work
483 to invest to compensate for repetitive data.
484 workFactor may be a number from 0 to 250 inclusive. The default
486 setting is 30.
487 See the bzip documentation for more information.
489 Here is an example of using the deflateInit optional parameter list to
491 override the default buffer size and compression level. All other
492 options will take their default values.
493 bzdeflateInit( -blockSize100k => 1, -verbosity => 1 );
495 ($out, $status) = $d->bzdeflate($buffer)
497 Deflates the contents of $buffer. The buffer can either be a scalar or
499 a scalar reference. When finished, $buffer will be completely pro‐
500 cessed (assuming there were no errors). If the deflation was successful
501 it returns deflated output, $out, and a status value, $status, of
502 "Z_OK".
503 On error, $out will be undef and $status will contain the zlib error
505 code.
506 In a scalar context bzdeflate will return $out only.
508 As with the internal buffering of the deflate function in bzip2, it is
510 not necessarily the case that any output will be produced by this
511 method. So don't rely on the fact that $out is empty for an error test.
512 In fact, given the size of bzdeflates internal buffer, with most files
513 it's likely you won't see any output at all until flush or close.
514 ($out, $status) = $d->bzflush([flush_type])
516 Typically used to finish the deflation. Any pending output will be
518 returned via $out. $status will have a value "BZ_OK" if successful.
519 In a scalar context bzflush will return $out only.
521 Note that flushing can seriously degrade the compression ratio, so it
523 should only be used to terminate a decompression (using "BZ_FLUSH") or
524 when you want to create a full flush point (using "BZ_FINISH").
525 The allowable values for "flush_type" are "BZ_FLUSH" and "BZ_FINISH".
527 For a handle opened for "w" (bzwrite), the default is "BZ_FLUSH". For
529 a stream, the default for "flush_type" is "BZ_FINISH" (which is essen‐
530 tially a close and reopen).
531 It is strongly recommended that you only set the "flush_type" parameter
533 if you fully understand the implications of what it does. See the
534 "bzip2" documentation for details.
535 Example
537 Here is a trivial example of using bzdeflate. It simply reads standard
539 input, deflates it and writes it to standard output.
540 use strict ;
542 use warnings ;
543 use Compress::Bzip2 ;
545 binmode STDIN;
547 binmode STDOUT;
548 my $x = bzdeflateInit()
549 or die "Cannot create a deflation stream\n" ;
550 my ($output, $status) ;
552 while (<>)
553 {
554 ($output, $status) = $x->bzdeflate($_) ;
555 $status == BZ_OK
557 or die "deflation failed\n" ;
558 print $output ;
560 }
561 ($output, $status) = $x->bzclose() ;
563 $status == BZ_OK
565 or die "deflation failed\n" ;
566 print $output ;
568
570 Here is a definition of the interface:
571 ($i, $status) = inflateInit()
573 Initialises an inflation stream.
575 In a list context it returns the inflation stream, $i, and the zlib
577 status code ($status). In a scalar context it returns the inflation
578 stream only.
579 If successful, $i will hold the inflation stream and $status will be
581 "BZ_OK".
582 If not successful, $i will be undef and $status will hold the bzlib.h
584 error code.
585 The function optionally takes a number of named options specified as
587 "-Name=>value" pairs. This allows individual options to be tailored
588 without having to specify them all in the parameter list.
589 For backward compatibility, it is also possible to pass the parameters
591 as a reference to a hash containing the name=>value pairs.
592 The function takes one optional parameter, a reference to a hash. The
594 contents of the hash allow the deflation interface to be tailored.
595 Here is a list of the valid options:
597 -small
599 small may be 0 or 1. Set "small" to one to use a slower, less
600 memory intensive algorithm.
601 -verbosity
603 Defines the verbosity level. Valid values are 0 through 4,
604 The default is "-verbosity => 0".
606 Here is an example of using the bzinflateInit optional parameter.
608 bzinflateInit( -small => 1, -verbosity => 1 );
610 ($out, $status) = $i->bzinflate($buffer)
612 Inflates the complete contents of $buffer. The buffer can either be a
614 scalar or a scalar reference.
615 Returns "BZ_OK" if successful and "BZ_STREAM_END" if the end of the
617 compressed data has been successfully reached. If not successful, $out
618 will be undef and $status will hold the bzlib error code.
619 The $buffer parameter is modified by "bzinflate". On completion it will
621 contain what remains of the input buffer after inflation. This means
622 that $buffer will be an empty string when the return status is "BZ_OK".
623 When the return status is "BZ_STREAM_END" the $buffer parameter will
624 contains what (if anything) was stored in the input buffer after the
625 deflated data stream.
626 This feature is useful when processing a file format that encapsulates
628 a compressed data stream.
629 Example
631 Here is an example of using bzinflate.
633 use strict ;
635 use warnings ;
636 use Compress::Bzip2;
638 my $x = bzinflateInit()
640 or die "Cannot create a inflation stream\n" ;
641 my $input = '' ;
643 binmode STDIN;
644 binmode STDOUT;
645 my ($output, $status) ;
647 while (read(STDIN, $input, 4096))
648 {
649 ($output, $status) = $x->bzinflate(\$input) ;
650 print $output
652 if $status == BZ_OK or $status == BZ_STREAM_END ;
653 last if $status != BZ_OK ;
655 }
656 die "inflation failed\n"
658 unless $status == BZ_STREAM_END ;
659
661 Here are some example scripts of using the interface.
662 A bzcat function
664 use strict ;
666 use warnings ;
667 use Compress::Bzip2 ;
669 die "Usage: bzcat file...\n" unless @ARGV ;
671 my $file ;
673 foreach $file (@ARGV) {
675 my $buffer ;
676 my $bz = bzopen($file, "rb")
678 or die "Cannot open $file: $bzerrno\n" ;
679 print $buffer while $bz->bzread($buffer) > 0 ;
681 die "Error reading from $file: $bzerrno" . ($bzerrno+0) . "\n"
683 if $bzerrno != BZ_STREAM_END ;
684 $bz->bzclose() ;
686 }
687 A grep using bzreadline
689 use strict ;
691 use warnings ;
692 use Compress::Bzip2 ;
694 die "Usage: bzgrep pattern file...\n" unless @ARGV >= 2;
696 my $pattern = shift ;
698 my $file ;
700 foreach $file (@ARGV) {
702 my $bz = bzopen($file, "rb")
703 or die "Cannot open $file: $bzerrno\n" ;
704 while ($bz->bzreadline($_) > 0) {
706 print if /$pattern/ ;
707 }
708 die "Error reading from $file: $bzerrno\n"
710 if $bzerrno != Z_STREAM_END ;
711 $bz->bzclose() ;
713 }
714 Streaming Compression
716 This script, bzstream, does the opposite of the bzcat script
718 above. It reads from standard input and writes a bzip file to
719 standard output.
720 use strict ;
722 use warnings ;
723 use Compress::Bzip2 ;
725 binmode STDOUT; # bzopen only sets it on the fd
727 my $bz = bzopen(\*STDOUT, "wb")
729 or die "Cannot open stdout: $bzerrno\n" ;
730 while (<>) {
732 $bz->bzwrite($_) or die "error writing: $bzerrno\n" ;
733 }
734 $bz->bzclose ;
736
738 Use the tags :all, :utilities, :constants, :bzip1 and :gzip.
739 Export tag :all
741 This exports all the exportable methods.
743 Export tag :constants
745 This exports only the BZ_* constants.
747 Export tag :bzip1
749 This exports the Compress::Bzip2 1.x functions, for compatibility.
751 compress
753 decompress
754 compress_init
755 decompress_init
756 version
757 These are actually aliases to memBzip and memBunzip.
759 Export tag :utilities
761 This gives an interface to the bzip2 methods.
763 bzopen
765 bzinflateInit
766 bzdeflateInit
767 memBzip
768 memBunzip
769 bzip2
770 bunzip2
771 bzcat
772 bzlibversion
773 $bzerrno
774 Export tag :gzip
776 This gives compatibility with Compress::Zlib.
778 gzopen
780 gzinflateInit
781 gzdeflateInit
782 memGzip
783 memGunzip
784 $gzerrno
785
787 All the bzlib constants are automatically imported when you make use of
788 Compress::Bzip2.
789 BZ_CONFIG_ERROR
791 BZ_DATA_ERROR
792 BZ_DATA_ERROR_MAGIC
793 BZ_FINISH
794 BZ_FINISH_OK
795 BZ_FLUSH
796 BZ_FLUSH_OK
797 BZ_IO_ERROR
798 BZ_MAX_UNUSED
799 BZ_MEM_ERROR
800 BZ_OK
801 BZ_OUTBUFF_FULL
802 BZ_PARAM_ERROR
803 BZ_RUN
804 BZ_RUN_OK
805 BZ_SEQUENCE_ERROR
806 BZ_STREAM_END
807 BZ_UNEXPECTED_EOF
808
810 The documentation for zlib, bzip2 and Compress::Zlib.
811
813 Rob Janes, <arjay at cpan.org>
814
816 Copyright (C) 2005 by Rob Janes
817 This library is free software; you can redistribute it and/or modify it
819 under the same terms as Perl itself, either Perl version 5.8.3 or, at
820 your option, any later version of Perl 5 you may have available.
821
823 The Compress::Bzip2 module was originally written by Gawdi Azem
824 azemgi@rupert.informatik.uni-stuttgart.de.
825 The first Compress::Bzip2 module was written by Gawdi Azem
827 azemgi@rupert.informatik.uni-stuttgart.de. It provided an interface to
828 the in memory inflate and deflate routines.
829 Compress::Bzip2 was subsequently passed on to Marco Carnut kiko@tem‐
831 pest.com.br who shepharded it through to version 1.03, a set of changes
832 which included upgrades to handle bzlib 1.0.2, and improvements to the
833 in memory inflate and deflate routines. The streaming interface and
834 error information were added by David Robins dbrobins@davidrobins.net.
835 Version 2 of Compress::Bzip2 is due to Rob Janes, of arjay@cpan.org.
837 This release is intended to give an interface close to that of Com‐
838 press::Zlib. It's development forks from 1.00, not 1.03, so the
839 streaming interface is not the same as that in 1.03, although appar‐
840 ently compatible as it passes the 1.03 test suite.
841
843 See the Changes file.
844 2.00 Second public release of Compress::Bzip2.
846perl v5.8.8 2005-08-09 Compress::Bzip2(3)