1Compress::Raw::Bzip2(3)User Contributed Perl DocumentatioCnompress::Raw::Bzip2(3)
2
6 Compress::Raw::Bzip2 - Low-Level Interface to bzip2 compression library
7
9 use Compress::Raw::Bzip2 ;
10 my ($bz, $status) = new Compress::Raw::Bzip2 [OPTS]
12 or die "Cannot create bzip2 object: $bzerno\n";
13 $status = $bz->bzdeflate($input, $output);
15 $status = $bz->bzflush($output);
16 $status = $bz->bzclose($output);
17 my ($bz, $status) = new Compress::Raw::Bunzip2 [OPTS]
19 or die "Cannot create bunzip2 object: $bzerno\n";
20 $status = $bz->bzinflate($input, $output);
22 my $version = Compress::Raw::Bzip2::bzlibversion();
24
26 "Compress::Raw::Bzip2" provides an interface to the in-memory
27 compression/uncompression functions from the bzip2 compression library.
28 Although the primary purpose for the existence of
30 "Compress::Raw::Bzip2" is for use by the "IO::Compress::Bzip2" and
31 "IO::Compress::Bunzip2" modules, it can be used on its own for simple
32 compression/uncompression tasks.
33
35 ($z, $status) = new Compress::Raw::Bzip2 $appendOutput, $blockSize100k,
36 $workfactor;
37 Creates a new compression object.
38 If successful, it will return the initialised compression object, $z
40 and a $status of "BZ_OK" in a list context. In scalar context it
41 returns the deflation object, $z, only.
42 If not successful, the returned compression object, $z, will be undef
44 and $status will hold the a bzip2 error code.
45 Below is a list of the valid options:
47 $appendOutput
49 Controls whether the compressed data is appended to the output
50 buffer in the "bzdeflate", "bzflush" and "bzclose" methods.
51 Defaults to 1.
53 $blockSize100k
55 To quote the bzip2 documentation
56 blockSize100k specifies the block size to be used for compression. It
58 should be a value between 1 and 9 inclusive, and the actual block size
59 used is 100000 x this figure. 9 gives the best compression but takes
60 most memory.
61 Defaults to 1.
63 $workfactor
65 To quote the bzip2 documentation
66 This parameter controls how the compression phase behaves when
68 presented with worst case, highly repetitive, input data. If
69 compression runs into difficulties caused by repetitive data, the
70 library switches from the standard sorting algorithm to a fallback
71 algorithm. The fallback is slower than the standard algorithm by
72 perhaps a factor of three, but always behaves reasonably, no matter how
73 bad the input.
74 Lower values of workFactor reduce the amount of effort the standard
76 algorithm will expend before resorting to the fallback. You should set
77 this parameter carefully; too low, and many inputs will be handled by
78 the fallback algorithm and so compress rather slowly, too high, and
79 your average-to-worst case compression times can become very large. The
80 default value of 30 gives reasonable behaviour over a wide range of
81 circumstances.
82 Allowable values range from 0 to 250 inclusive. 0 is a special case,
84 equivalent to using the default value of 30.
85 Defaults to 0.
87 $status = $bz->bzdeflate($input, $output);
89 Reads the contents of $input, compresses it and writes the compressed
90 data to $output.
91 Returns "BZ_RUN_OK" on success and a "bzip2" error code on failure.
93 If "appendOutput" is enabled in the constructor for the bzip2 object,
95 the compressed data will be appended to $output. If not enabled,
96 $output will be truncated before the compressed data is written to it.
97 $status = $bz->bzflush($output);
99 Flushes any pending compressed data to $output.
100 Returns "BZ_RUN_OK" on success and a "bzip2" error code on failure.
102 $status = $bz->bzclose($output);
104 Terminates the compressed data stream and flushes any pending
105 compressed data to $output.
106 Returns "BZ_STREAM_END" on success and a "bzip2" error code on failure.
108 Example
111 ($z, $status) = new Compress::Raw::Bunzip2 $appendOutput, $consumeInput,
112 $small, $verbosity, $limitOutput;
113 If successful, it will return the initialised uncompression object, $z
114 and a $status of "BZ_OK" in a list context. In scalar context it
115 returns the deflation object, $z, only.
116 If not successful, the returned uncompression object, $z, will be undef
118 and $status will hold the a bzip2 error code.
119 Below is a list of the valid options:
121 $appendOutput
123 Controls whether the compressed data is appended to the output
124 buffer in the "bzinflate", "bzflush" and "bzclose" methods.
125 Defaults to 1.
127 $consumeInput
129 $small
130 To quote the bzip2 documentation
131 If small is nonzero, the library will use an alternative decompression
133 algorithm which uses less memory but at the cost of decompressing more
134 slowly (roughly speaking, half the speed, but the maximum memory
135 requirement drops to around 2300k).
136 Defaults to 0.
138 $limitOutput
140 The "LimitOutput" option changes the behavior of the
141 "$i->bzinflate" method so that the amount of memory used by the
142 output buffer can be limited.
143 When "LimitOutput" is used the size of the output buffer used will
145 either be the 16k or the amount of memory already allocated to
146 $output, whichever is larger. Predicting the output size available
147 is tricky, so don't rely on getting an exact output buffer size.
148 When "LimitOutout" is not specified "$i->bzinflate" will use as
150 much memory as it takes to write all the uncompressed data it
151 creates by uncompressing the input buffer.
152 If "LimitOutput" is enabled, the "ConsumeInput" option will also
154 be enabled.
155 This option defaults to false.
157 $verbosity
159 This parameter is ignored.
160 Defaults to 0.
162 $status = $z->bzinflate($input, $output);
164 Uncompresses $input and writes the uncompressed data to $output.
165 Returns "BZ_OK" if the uncompression was successful, but the end of the
167 compressed data stream has not been reached. Returns "BZ_STREAM_END" on
168 successful uncompression and the end of the compression stream has been
169 reached.
170 If "consumeInput" is enabled in the constructor for the bunzip2 object,
172 $input will have all compressed data removed from it after
173 uncompression. On "BZ_OK" return this will mean that $input will be an
174 empty string; when "BZ_STREAM_END" $input will either be an empty
175 string or will contain whatever data immediately followed the
176 compressed data stream.
177 If "appendOutput" is enabled in the constructor for the bunzip2 object,
179 the uncompressed data will be appended to $output. If not enabled,
180 $output will be truncated before the uncompressed data is written to
181 it.
182
184 my $version = Compress::Raw::Bzip2::bzlibversion();
185 Returns the version of the underlying bzip2 library.
186
188 The following bzip2 constants are exported by this module
189 BZ_RUN
191 BZ_FLUSH
192 BZ_FINISH
193 BZ_OK
195 BZ_RUN_OK
196 BZ_FLUSH_OK
197 BZ_FINISH_OK
198 BZ_STREAM_END
199 BZ_SEQUENCE_ERROR
200 BZ_PARAM_ERROR
201 BZ_MEM_ERROR
202 BZ_DATA_ERROR
203 BZ_DATA_ERROR_MAGIC
204 BZ_IO_ERROR
205 BZ_UNEXPECTED_EOF
206 BZ_OUTBUFF_FULL
207 BZ_CONFIG_ERROR
208
210 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
211 IO::Compress::Deflate, IO::Uncompress::Inflate,
212 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
213 IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma,
214 IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz,
215 IO::Compress::Lzop, IO::Uncompress::UnLzop, IO::Compress::Lzf,
216 IO::Uncompress::UnLzf, IO::Uncompress::AnyInflate,
217 IO::Uncompress::AnyUncompress
218 IO::Compress::FAQ
220 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
222 The primary site for the bzip2 program is http://www.bzip.org.
224 See the module Compress::Bzip2
226
228 This module was written by Paul Marquess, pmqs@cpan.org.
229
231 See the Changes file.
232
234 Copyright (c) 2005-2013 Paul Marquess. All rights reserved.
235 This program is free software; you can redistribute it and/or modify it
237 under the same terms as Perl itself.
238perl v5.16.3 2013-05-19 Compress::Raw::Bzip2(3)