1Compress::Raw::Bzip2(3pmP)erl Programmers Reference GuidCeompress::Raw::Bzip2(3pm)
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, $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 $status = $z->bzinflate($input, $output);
159 Uncompresses $input and writes the uncompressed data to $output.
160 Returns "BZ_OK" if the uncompression was successful, but the end of the
162 compressed data stream has not been reached. Returns "BZ_STREAM_END" on
163 successful uncompression and the end of the compression stream has been
164 reached.
165 If "consumeInput" is enabled in the constructor for the bunzip2 object,
167 $input will have all compressed data removed from it after
168 uncompression. On "BZ_OK" return this will mean that $input will be an
169 empty string; when "BZ_STREAM_END" $input will either be an empty
170 string or will contain whatever data immediately followed the
171 compressed data stream.
172 If "appendOutput" is enabled in the constructor for the bunzip2 object,
174 the uncompressed data will be appended to $output. If not enabled,
175 $output will be truncated before the uncompressed data is written to
176 it.
177
179 my $version = Compress::Raw::Bzip2::bzlibversion();
180 Returns the version of the underlying bzip2 library.
181
183 The following bzip2 constants are exported by this module
184 BZ_RUN
186 BZ_FLUSH
187 BZ_FINISH
188 BZ_OK
190 BZ_RUN_OK
191 BZ_FLUSH_OK
192 BZ_FINISH_OK
193 BZ_STREAM_END
194 BZ_SEQUENCE_ERROR
195 BZ_PARAM_ERROR
196 BZ_MEM_ERROR
197 BZ_DATA_ERROR
198 BZ_DATA_ERROR_MAGIC
199 BZ_IO_ERROR
200 BZ_UNEXPECTED_EOF
201 BZ_OUTBUFF_FULL
202 BZ_CONFIG_ERROR
203
205 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
206 IO::Compress::Deflate, IO::Uncompress::Inflate,
207 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
208 IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzop,
209 IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf,
210 IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress
211 Compress::Zlib::FAQ
213 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
215 The primary site for the bzip2 program is http://www.bzip.org.
217 See the module Compress::Bzip2
219
221 This module was written by Paul Marquess, pmqs@cpan.org.
222
224 See the Changes file.
225
227 Copyright (c) 2005-2009 Paul Marquess. All rights reserved.
228 This program is free software; you can redistribute it and/or modify it
230 under the same terms as Perl itself.
231perl v5.10.1 2017-03-22 Compress::Raw::Bzip2(3pm)