Debian Codegraph @

upstream/mageia-cauldron/man3pm/Compress::Raw::Bzip2.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Compress::Raw::Bzip2 3pm"
61 .TH Compress::Raw::Bzip2 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Compress::Raw::Bzip2 \- Low\-Level Interface to bzip2 compression library
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use Compress::Raw::Bzip2 ;
72 \&
73 \& my ($bz, $status) = new Compress::Raw::Bzip2 [OPTS]
74 \& or die "Cannot create bzip2 object: $bzerno\en";
75 \&
76 \& $status = $bz\->bzdeflate($input, $output);
77 \& $status = $bz\->bzflush($output);
78 \& $status = $bz\->bzclose($output);
79 \&
80 \& my ($bz, $status) = new Compress::Raw::Bunzip2 [OPTS]
81 \& or die "Cannot create bunzip2 object: $bzerno\en";
82 \&
83 \& $status = $bz\->bzinflate($input, $output);
84 \&
85 \& my $version = Compress::Raw::Bzip2::bzlibversion();
86 .Ve
87 .SH DESCRIPTION
88 .IX Header "DESCRIPTION"
89 \&\f(CW\*(C`Compress::Raw::Bzip2\*(C'\fR provides an interface to the in\-memory
90 compression/uncompression functions from the bzip2 compression library.
91 .PP
92 Although the primary purpose for the existence of \f(CW\*(C`Compress::Raw::Bzip2\*(C'\fR
93 is for use by the \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR and \f(CW\*(C`IO::Compress::Bunzip2\*(C'\fR
94 modules, it can be used on its own for simple compression/uncompression
95 tasks.
96 .SH Compression
97 .IX Header "Compression"
98 .ie n .SS "($z, $status) = new Compress::Raw::Bzip2 $appendOutput, $blockSize100k, $workfactor;"
99 .el .SS "($z, \f(CW$status\fP) = new Compress::Raw::Bzip2 \f(CW$appendOutput\fP, \f(CW$blockSize100k\fP, \f(CW$workfactor\fP;"
100 .IX Subsection "($z, $status) = new Compress::Raw::Bzip2 $appendOutput, $blockSize100k, $workfactor;"
101 Creates a new compression object.
102 .PP
103 If successful, it will return the initialised compression object, \f(CW$z\fR
104 and a \f(CW$status\fR of \f(CW\*(C`BZ_OK\*(C'\fR in a list context. In scalar context it
105 returns the deflation object, \f(CW$z\fR, only.
106 .PP
107 If not successful, the returned compression object, \f(CW$z\fR, will be
108 \&\fIundef\fR and \f(CW$status\fR will hold the a \fIbzip2\fR error code.
109 .PP
110 Below is a list of the valid options:
111 .ie n .IP \fR\fB$appendOutput\fR\fB\fR 5
112 .el .IP \fR\f(CB$appendOutput\fR\fB\fR 5
113 .IX Item "$appendOutput"
114 Controls whether the compressed data is appended to the output buffer in
115 the \f(CW\*(C`bzdeflate\*(C'\fR, \f(CW\*(C`bzflush\*(C'\fR and \f(CW\*(C`bzclose\*(C'\fR methods.
116 .Sp
117 Defaults to 1.
118 .ie n .IP \fR\fB$blockSize100k\fR\fB\fR 5
119 .el .IP \fR\f(CB$blockSize100k\fR\fB\fR 5
120 .IX Item "$blockSize100k"
121 To quote the bzip2 documentation
122 .Sp
123 .Vb 4
124 \& blockSize100k specifies the block size to be used for compression. It
125 \& should be a value between 1 and 9 inclusive, and the actual block size
126 \& used is 100000 x this figure. 9 gives the best compression but takes
127 \& most memory.
128 .Ve
129 .Sp
130 Defaults to 1.
131 .ie n .IP \fR\fB$workfactor\fR\fB\fR 5
132 .el .IP \fR\f(CB$workfactor\fR\fB\fR 5
133 .IX Item "$workfactor"
134 To quote the bzip2 documentation
135 .Sp
136 .Vb 7
137 \& This parameter controls how the compression phase behaves when
138 \& presented with worst case, highly repetitive, input data. If
139 \& compression runs into difficulties caused by repetitive data, the
140 \& library switches from the standard sorting algorithm to a fallback
141 \& algorithm. The fallback is slower than the standard algorithm by
142 \& perhaps a factor of three, but always behaves reasonably, no matter how
143 \& bad the input.
144 \&
145 \& Lower values of workFactor reduce the amount of effort the standard
146 \& algorithm will expend before resorting to the fallback. You should set
147 \& this parameter carefully; too low, and many inputs will be handled by
148 \& the fallback algorithm and so compress rather slowly, too high, and
149 \& your average\-to\-worst case compression times can become very large. The
150 \& default value of 30 gives reasonable behaviour over a wide range of
151 \& circumstances.
152 \&
153 \& Allowable values range from 0 to 250 inclusive. 0 is a special case,
154 \& equivalent to using the default value of 30.
155 .Ve
156 .Sp
157 Defaults to 0.
158 .ie n .SS "$status = $bz\->bzdeflate($input, $output);"
159 .el .SS "\f(CW$status\fP = \f(CW$bz\fP\->bzdeflate($input, \f(CW$output\fP);"
160 .IX Subsection "$status = $bz->bzdeflate($input, $output);"
161 Reads the contents of \f(CW$input\fR, compresses it and writes the compressed
162 data to \f(CW$output\fR.
163 .PP
164 Returns \f(CW\*(C`BZ_RUN_OK\*(C'\fR on success and a \f(CW\*(C`bzip2\*(C'\fR error code on failure.
165 .PP
166 If \f(CW\*(C`appendOutput\*(C'\fR is enabled in the constructor for the bzip2 object, the
167 compressed data will be appended to \f(CW$output\fR. If not enabled, \f(CW$output\fR
168 will be truncated before the compressed data is written to it.
169 .ie n .SS "$status = $bz\->bzflush($output);"
170 .el .SS "\f(CW$status\fP = \f(CW$bz\fP\->bzflush($output);"
171 .IX Subsection "$status = $bz->bzflush($output);"
172 Flushes any pending compressed data to \f(CW$output\fR.
173 .PP
174 Returns \f(CW\*(C`BZ_RUN_OK\*(C'\fR on success and a \f(CW\*(C`bzip2\*(C'\fR error code on failure.
175 .ie n .SS "$status = $bz\->bzclose($output);"
176 .el .SS "\f(CW$status\fP = \f(CW$bz\fP\->bzclose($output);"
177 .IX Subsection "$status = $bz->bzclose($output);"
178 Terminates the compressed data stream and flushes any pending compressed
179 data to \f(CW$output\fR.
180 .PP
181 Returns \f(CW\*(C`BZ_STREAM_END\*(C'\fR on success and a \f(CW\*(C`bzip2\*(C'\fR error code on failure.
182 .SS Example
183 .IX Subsection "Example"
184 .SH Uncompression
185 .IX Header "Uncompression"
186 .ie n .SS "($z, $status) = new Compress::Raw::Bunzip2 $appendOutput, $consumeInput, $small, $verbosity, $limitOutput;"
187 .el .SS "($z, \f(CW$status\fP) = new Compress::Raw::Bunzip2 \f(CW$appendOutput\fP, \f(CW$consumeInput\fP, \f(CW$small\fP, \f(CW$verbosity\fP, \f(CW$limitOutput\fP;"
188 .IX Subsection "($z, $status) = new Compress::Raw::Bunzip2 $appendOutput, $consumeInput, $small, $verbosity, $limitOutput;"
189 If successful, it will return the initialised uncompression object, \f(CW$z\fR
190 and a \f(CW$status\fR of \f(CW\*(C`BZ_OK\*(C'\fR in a list context. In scalar context it
191 returns the deflation object, \f(CW$z\fR, only.
192 .PP
193 If not successful, the returned uncompression object, \f(CW$z\fR, will be
194 \&\fIundef\fR and \f(CW$status\fR will hold the a \fIbzip2\fR error code.
195 .PP
196 Below is a list of the valid options:
197 .ie n .IP \fR\fB$appendOutput\fR\fB\fR 5
198 .el .IP \fR\f(CB$appendOutput\fR\fB\fR 5
199 .IX Item "$appendOutput"
200 Controls whether the compressed data is appended to the output buffer in the
201 \&\f(CW\*(C`bzinflate\*(C'\fR, \f(CW\*(C`bzflush\*(C'\fR and \f(CW\*(C`bzclose\*(C'\fR methods.
202 .Sp
203 Defaults to 1.
204 .ie n .IP \fR\fB$consumeInput\fR\fB\fR 5
205 .el .IP \fR\f(CB$consumeInput\fR\fB\fR 5
206 .IX Item "$consumeInput"
207 .PD 0
208 .ie n .IP \fR\fB$small\fR\fB\fR 5
209 .el .IP \fR\f(CB$small\fR\fB\fR 5
210 .IX Item "$small"
211 .PD
212 To quote the bzip2 documentation
213 .Sp
214 .Vb 4
215 \& If small is nonzero, the library will use an alternative decompression
216 \& algorithm which uses less memory but at the cost of decompressing more
217 \& slowly (roughly speaking, half the speed, but the maximum memory
218 \& requirement drops to around 2300k).
219 .Ve
220 .Sp
221 Defaults to 0.
222 .ie n .IP \fR\fB$limitOutput\fR\fB\fR 5
223 .el .IP \fR\f(CB$limitOutput\fR\fB\fR 5
224 .IX Item "$limitOutput"
225 The \f(CW\*(C`LimitOutput\*(C'\fR option changes the behavior of the \f(CW\*(C`$i\->bzinflate\*(C'\fR
226 method so that the amount of memory used by the output buffer can be
227 limited.
228 .Sp
229 When \f(CW\*(C`LimitOutput\*(C'\fR is used the size of the output buffer used will either
230 be the 16k or the amount of memory already allocated to \f(CW$output\fR,
231 whichever is larger. Predicting the output size available is tricky, so
232 don\*(Aqt rely on getting an exact output buffer size.
233 .Sp
234 When \f(CW\*(C`LimitOutout\*(C'\fR is not specified \f(CW\*(C`$i\->bzinflate\*(C'\fR will use as much
235 memory as it takes to write all the uncompressed data it creates by
236 uncompressing the input buffer.
237 .Sp
238 If \f(CW\*(C`LimitOutput\*(C'\fR is enabled, the \f(CW\*(C`ConsumeInput\*(C'\fR option will also be
239 enabled.
240 .Sp
241 This option defaults to false.
242 .ie n .IP \fR\fB$verbosity\fR\fB\fR 5
243 .el .IP \fR\f(CB$verbosity\fR\fB\fR 5
244 .IX Item "$verbosity"
245 This parameter is ignored.
246 .Sp
247 Defaults to 0.
248 .ie n .SS "$status = $z\->bzinflate($input, $output);"
249 .el .SS "\f(CW$status\fP = \f(CW$z\fP\->bzinflate($input, \f(CW$output\fP);"
250 .IX Subsection "$status = $z->bzinflate($input, $output);"
251 Uncompresses \f(CW$input\fR and writes the uncompressed data to \f(CW$output\fR.
252 .PP
253 Returns \f(CW\*(C`BZ_OK\*(C'\fR if the uncompression was successful, but the end of the
254 compressed data stream has not been reached. Returns \f(CW\*(C`BZ_STREAM_END\*(C'\fR on
255 successful uncompression and the end of the compression stream has been
256 reached.
257 .PP
258 If \f(CW\*(C`consumeInput\*(C'\fR is enabled in the constructor for the bunzip2 object,
259 \&\f(CW$input\fR will have all compressed data removed from it after
260 uncompression. On \f(CW\*(C`BZ_OK\*(C'\fR return this will mean that \f(CW$input\fR will be an
261 empty string; when \f(CW\*(C`BZ_STREAM_END\*(C'\fR \f(CW$input\fR will either be an empty
262 string or will contain whatever data immediately followed the compressed
263 data stream.
264 .PP
265 If \f(CW\*(C`appendOutput\*(C'\fR is enabled in the constructor for the bunzip2 object,
266 the uncompressed data will be appended to \f(CW$output\fR. If not enabled,
267 \&\f(CW$output\fR will be truncated before the uncompressed data is written to it.
268 .SH Misc
269 .IX Header "Misc"
270 .ie n .SS "my $version = \fBCompress::Raw::Bzip2::bzlibversion()\fP;"
271 .el .SS "my \f(CW$version\fP = \fBCompress::Raw::Bzip2::bzlibversion()\fP;"
272 .IX Subsection "my $version = Compress::Raw::Bzip2::bzlibversion();"
273 Returns the version of the underlying bzip2 library.
274 .SH Constants
275 .IX Header "Constants"
276 The following bzip2 constants are exported by this module
277 .PP
278 .Vb 3
279 \& BZ_RUN
280 \& BZ_FLUSH
281 \& BZ_FINISH
282 \&
283 \& BZ_OK
284 \& BZ_RUN_OK
285 \& BZ_FLUSH_OK
286 \& BZ_FINISH_OK
287 \& BZ_STREAM_END
288 \& BZ_SEQUENCE_ERROR
289 \& BZ_PARAM_ERROR
290 \& BZ_MEM_ERROR
291 \& BZ_DATA_ERROR
292 \& BZ_DATA_ERROR_MAGIC
293 \& BZ_IO_ERROR
294 \& BZ_UNEXPECTED_EOF
295 \& BZ_OUTBUFF_FULL
296 \& BZ_CONFIG_ERROR
297 .Ve
298 .SH SUPPORT
299 .IX Header "SUPPORT"
300 General feedback/questions/bug reports should be sent to
301 <https://github.com/pmqs/Compress\-Raw\-Bzip2/issues> (preferred) or
302 <https://rt.cpan.org/Public/Dist/Display.html?Name=Compress\-Raw\-Bzip2>.
303 .SH "SEE ALSO"
304 .IX Header "SEE ALSO"
305 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::Lzip, IO::Uncompress::UnLzip, IO::Compress::Lzop, IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Compress::Zstd, IO::Uncompress::UnZstd, IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress
306 .PP
307 IO::Compress::FAQ
308 .PP
309 File::GlobMapper, Archive::Zip,
310 Archive::Tar,
311 IO::Zlib
312 .PP
313 The primary site for the bzip2 program is <https://sourceware.org/bzip2/>.
314 .PP
315 See the module Compress::Bzip2
316 .SH AUTHOR
317 .IX Header "AUTHOR"
318 This module was written by Paul Marquess, \f(CW\*(C`[email protected]\*(C'\fR.
319 .SH "MODIFICATION HISTORY"
320 .IX Header "MODIFICATION HISTORY"
321 See the Changes file.
322 .SH "COPYRIGHT AND LICENSE"
323 .IX Header "COPYRIGHT AND LICENSE"
324 Copyright (c) 2005\-2024 Paul Marquess. All rights reserved.
325 .PP
326 This program is free software; you can redistribute it and/or
327 modify it under the same terms as Perl itself.