1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
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<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
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
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.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
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
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
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'
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 \
129 .\" ========================================================================
131 .IX Title "Compress::Raw::Bzip2 3"
132 .TH Compress::Raw::Bzip2 3 "2009-11-09" "perl v5.8.7" "User Contributed Perl Documentation"
134 Compress::Raw::Bzip2 \- Low\-Level Interface to bzip2 compression library
136 .IX Header "SYNOPSIS"
138 \& use Compress::Raw::Bzip2 ;
142 \& my ($bz, $status) = new Compress::Raw::Bzip2 [OPTS]
143 \& or die "Cannot create bzip2 object: $bzerno\en";
147 \& $status = $bz\->bzdeflate($input, $output);
148 \& $status = $bz\->bzflush($output);
149 \& $status = $bz\->bzclose($output);
153 \& my ($bz, $status) = new Compress::Raw::Bunzip2 [OPTS]
154 \& or die "Cannot create bunzip2 object: $bzerno\en";
158 \& $status = $bz\->bzinflate($input, $output);
162 \& my $version = Compress::Raw::Bzip2::bzlibversion();
165 .IX Header "DESCRIPTION"
166 \&\f(CW\*(C`Compress::Raw::Bzip2\*(C'\fR provides an interface to the in-memory
167 compression/uncompression functions from the bzip2 compression library.
169 Although the primary purpose for the existence of \f(CW\*(C`Compress::Raw::Bzip2\*(C'\fR
170 is for use by the \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR and \f(CW\*(C`IO::Compress::Bunzip2\*(C'\fR
171 modules, it can be used on its own for simple compression/uncompression
174 .IX Header "Compression"
175 .ie n .Sh "($z, $status\fP) = new Compress::Raw::Bzip2 \f(CW$appendOutput\fP, \f(CW$blockSize100k\fP, \f(CW$workfactor;"
176 .el .Sh "($z, \f(CW$status\fP) = new Compress::Raw::Bzip2 \f(CW$appendOutput\fP, \f(CW$blockSize100k\fP, \f(CW$workfactor\fP;"
177 .IX Subsection "($z, $status) = new Compress::Raw::Bzip2 $appendOutput, $blockSize100k, $workfactor;"
178 Creates a new compression object.
180 If successful, it will return the initialised compression object, \f(CW$z\fR
181 and a \f(CW$status\fR of \f(CW\*(C`BZ_OK\*(C'\fR in a list context. In scalar context it
182 returns the deflation object, \f(CW$z\fR, only.
184 If not successful, the returned compression object, \f(CW$z\fR, will be
185 \&\fIundef\fR and \f(CW$status\fR will hold the a \fIbzip2\fR error code.
187 Below is a list of the valid options:
188 .IP "\fB$appendOutput\fR" 5
189 .IX Item "$appendOutput"
190 Controls whether the compressed data is appended to the output buffer in
191 the \f(CW\*(C`bzdeflate\*(C'\fR, \f(CW\*(C`bzflush\*(C'\fR and \f(CW\*(C`bzclose\*(C'\fR methods.
194 .IP "\fB$blockSize100k\fR" 5
195 .IX Item "$blockSize100k"
196 To quote the bzip2 documentation
199 \& blockSize100k specifies the block size to be used for compression. It
200 \& should be a value between 1 and 9 inclusive, and the actual block size
201 \& used is 100000 x this figure. 9 gives the best compression but takes
206 .IP "\fB$workfactor\fR" 5
207 .IX Item "$workfactor"
208 To quote the bzip2 documentation
211 \& This parameter controls how the compression phase behaves when
212 \& presented with worst case, highly repetitive, input data. If
213 \& compression runs into difficulties caused by repetitive data, the
214 \& library switches from the standard sorting algorithm to a fallback
215 \& algorithm. The fallback is slower than the standard algorithm by
216 \& perhaps a factor of three, but always behaves reasonably, no matter how
221 \& Lower values of workFactor reduce the amount of effort the standard
222 \& algorithm will expend before resorting to the fallback. You should set
223 \& this parameter carefully; too low, and many inputs will be handled by
224 \& the fallback algorithm and so compress rather slowly, too high, and
225 \& your average\-to\-worst case compression times can become very large. The
226 \& default value of 30 gives reasonable behaviour over a wide range of
231 \& Allowable values range from 0 to 250 inclusive. 0 is a special case,
232 \& equivalent to using the default value of 30.
236 .ie n .Sh "$status = $bz\fP\->bzdeflate($input, \f(CW$output);"
237 .el .Sh "$status = \f(CW$bz\fP\->bzdeflate($input, \f(CW$output\fP);"
238 .IX Subsection "$status = $bz->bzdeflate($input, $output);"
239 Reads the contents of \f(CW$input\fR, compresses it and writes the compressed
240 data to \f(CW$output\fR.
242 Returns \f(CW\*(C`BZ_RUN_OK\*(C'\fR on success and a \f(CW\*(C`bzip2\*(C'\fR error code on failure.
244 If \f(CW\*(C`appendOutput\*(C'\fR is enabled in the constructor for the bzip2 object, the
245 compressed data will be appended to \f(CW$output\fR. If not enabled, \f(CW$output\fR
246 will be truncated before the compressed data is written to it.
247 .ie n .Sh "$status = $bz\->bzflush($output);"
248 .el .Sh "$status = \f(CW$bz\fP\->bzflush($output);"
249 .IX Subsection "$status = $bz->bzflush($output);"
250 Flushes any pending compressed data to \f(CW$output\fR.
252 Returns \f(CW\*(C`BZ_RUN_OK\*(C'\fR on success and a \f(CW\*(C`bzip2\*(C'\fR error code on failure.
253 .ie n .Sh "$status = $bz\->bzclose($output);"
254 .el .Sh "$status = \f(CW$bz\fP\->bzclose($output);"
255 .IX Subsection "$status = $bz->bzclose($output);"
256 Terminates the compressed data stream and flushes any pending compressed
257 data to \f(CW$output\fR.
259 Returns \f(CW\*(C`BZ_STREAM_END\*(C'\fR on success and a \f(CW\*(C`bzip2\*(C'\fR error code on failure.
261 .IX Subsection "Example"
263 .IX Header "Uncompression"
264 .ie n .Sh "($z, $status\fP) = new Compress::Raw::Bunzip2 \f(CW$appendOutput\fP, \f(CW$consumeInput\fP, \f(CW$small\fP, \f(CW$limitOutput;"
265 .el .Sh "($z, \f(CW$status\fP) = new Compress::Raw::Bunzip2 \f(CW$appendOutput\fP, \f(CW$consumeInput\fP, \f(CW$small\fP, \f(CW$limitOutput\fP;"
266 .IX Subsection "($z, $status) = new Compress::Raw::Bunzip2 $appendOutput, $consumeInput, $small, $limitOutput;"
267 If successful, it will return the initialised uncompression object, \f(CW$z\fR
268 and a \f(CW$status\fR of \f(CW\*(C`BZ_OK\*(C'\fR in a list context. In scalar context it
269 returns the deflation object, \f(CW$z\fR, only.
271 If not successful, the returned uncompression object, \f(CW$z\fR, will be
272 \&\fIundef\fR and \f(CW$status\fR will hold the a \fIbzip2\fR error code.
274 Below is a list of the valid options:
275 .IP "\fB$appendOutput\fR" 5
276 .IX Item "$appendOutput"
277 Controls whether the compressed data is appended to the output buffer in the
278 \&\f(CW\*(C`bzinflate\*(C'\fR, \f(CW\*(C`bzflush\*(C'\fR and \f(CW\*(C`bzclose\*(C'\fR methods.
281 .IP "\fB$consumeInput\fR" 5
282 .IX Item "$consumeInput"
287 To quote the bzip2 documentation
290 \& If small is nonzero, the library will use an alternative decompression
291 \& algorithm which uses less memory but at the cost of decompressing more
292 \& slowly (roughly speaking, half the speed, but the maximum memory
293 \& requirement drops to around 2300k).
297 .IP "\fB$limitOutput\fR" 5
298 .IX Item "$limitOutput"
299 The \f(CW\*(C`LimitOutput\*(C'\fR option changes the behavior of the \f(CW\*(C`$i\->bzinflate\*(C'\fR
300 method so that the amount of memory used by the output buffer can be
303 When \f(CW\*(C`LimitOutput\*(C'\fR is used the size of the output buffer used will either
304 be the 16k or the amount of memory already allocated to \f(CW$output\fR,
305 whichever is larger. Predicting the output size available is tricky, so
306 don't rely on getting an exact output buffer size.
308 When \f(CW\*(C`LimitOutout\*(C'\fR is not specified \f(CW\*(C`$i\->bzinflate\*(C'\fR will use as much
309 memory as it takes to write all the uncompressed data it creates by
310 uncompressing the input buffer.
312 If \f(CW\*(C`LimitOutput\*(C'\fR is enabled, the \f(CW\*(C`ConsumeInput\*(C'\fR option will also be
315 This option defaults to false.
316 .ie n .Sh "$status = $z\fP\->bzinflate($input, \f(CW$output);"
317 .el .Sh "$status = \f(CW$z\fP\->bzinflate($input, \f(CW$output\fP);"
318 .IX Subsection "$status = $z->bzinflate($input, $output);"
319 Uncompresses \f(CW$input\fR and writes the uncompressed data to \f(CW$output\fR.
321 Returns \f(CW\*(C`BZ_OK\*(C'\fR if the uncompression was successful, but the end of the
322 compressed data stream has not been reached. Returns \f(CW\*(C`BZ_STREAM_END\*(C'\fR on
323 successful uncompression and the end of the compression stream has been
326 If \f(CW\*(C`consumeInput\*(C'\fR is enabled in the constructor for the bunzip2 object,
327 \&\f(CW$input\fR will have all compressed data removed from it after
328 uncompression. On \f(CW\*(C`BZ_OK\*(C'\fR return this will mean that \f(CW$input\fR will be an
329 empty string; when \f(CW\*(C`BZ_STREAM_END\*(C'\fR \f(CW$input\fR will either be an empty
330 string or will contain whatever data immediately followed the compressed
333 If \f(CW\*(C`appendOutput\*(C'\fR is enabled in the constructor for the bunzip2 object,
334 the uncompressed data will be appended to \f(CW$output\fR. If not enabled,
335 \&\f(CW$output\fR will be truncated before the uncompressed data is written to it.
338 .ie n .Sh "my $version\fP = \fICompress::Raw::Bzip2::bzlibversion();"
339 .el .Sh "my \f(CW$version\fP = \fICompress::Raw::Bzip2::bzlibversion()\fP;"
340 .IX Subsection "my $version = Compress::Raw::Bzip2::bzlibversion();"
341 Returns the version of the underlying bzip2 library.
343 .IX Header "Constants"
344 The following bzip2 constants are exported by this module
362 \& BZ_DATA_ERROR_MAGIC
369 .IX Header "SEE ALSO"
370 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip, IO::Compress::Deflate, IO::Uncompress::Inflate, IO::Compress::RawDeflate, IO::Uncompress::RawInflate, IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma, IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz, IO::Compress::Lzop, IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress
374 File::GlobMapper, Archive::Zip,
378 The primary site for the bzip2 program is \fIhttp://www.bzip.org\fR.
380 See the module Compress::Bzip2
383 This module was written by Paul Marquess, \fIpmqs@cpan.org\fR.
384 .SH "MODIFICATION HISTORY"
385 .IX Header "MODIFICATION HISTORY"
386 See the Changes file.
387 .SH "COPYRIGHT AND LICENSE"
388 .IX Header "COPYRIGHT AND LICENSE"
389 Copyright (c) 2005\-2009 Paul Marquess. All rights reserved.
391 This program is free software; you can redistribute it and/or
392 modify it under the same terms as Perl itself.