Compress::Raw::Bzip2(3pm)

1Compress::Raw::Bzip2(3)User Contributed Perl DocumentatioCnompress::Raw::Bzip2(3)
2
3
4

NAME

6       Compress::Raw::Bzip2 - Low-Level Interface to bzip2 compression library
7

SYNOPSIS

9           use Compress::Raw::Bzip2 ;
10
11           my ($bz, $status) = new Compress::Raw::Bzip2 [OPTS]
12               or die "Cannot create bzip2 object: $bzerno\n";
13
14           $status = $bz->bzdeflate($input, $output);
15           $status = $bz->bzflush($output);
16           $status = $bz->bzclose($output);
17
18           my ($bz, $status) = new Compress::Raw::Bunzip2 [OPTS]
19               or die "Cannot create bunzip2 object: $bzerno\n";
20
21           $status = $bz->bzinflate($input, $output);
22
23           my $version = Compress::Raw::Bzip2::bzlibversion();
24

DESCRIPTION

26       "Compress::Raw::Bzip2" provides an interface to the in-memory
27       compression/uncompression functions from the bzip2 compression library.
28
29       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

Compression

35   ($z, $status) = new Compress::Raw::Bzip2 $appendOutput, $blockSize100k,
36       $workfactor;
37       Creates a new compression object.
38
39       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
43       If not successful, the returned compression object, $z, will be undef
44       and $status will hold the a bzip2 error code.
45
46       Below is a list of the valid options:
47
48       $appendOutput
49            Controls whether the compressed data is appended to the output
50            buffer in the "bzdeflate", "bzflush" and "bzclose" methods.
51
52            Defaults to 1.
53
54       $blockSize100k
55            To quote the bzip2 documentation
56
57                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
62            Defaults to 1.
63
64       $workfactor
65            To quote the bzip2 documentation
66
67                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
75                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
83                Allowable values range from 0 to 250 inclusive. 0 is a special case,
84                equivalent to using the default value of 30.
85
86            Defaults to 0.
87
88   $status = $bz->bzdeflate($input, $output);
89       Reads the contents of $input, compresses it and writes the compressed
90       data to $output.
91
92       Returns "BZ_RUN_OK" on success and a "bzip2" error code on failure.
93
94       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
98   $status = $bz->bzflush($output);
99       Flushes any pending compressed data to $output.
100
101       Returns "BZ_RUN_OK" on success and a "bzip2" error code on failure.
102
103   $status = $bz->bzclose($output);
104       Terminates the compressed data stream and flushes any pending
105       compressed data to $output.
106
107       Returns "BZ_STREAM_END" on success and a "bzip2" error code on failure.
108
109   Example

Uncompression

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
117       If not successful, the returned uncompression object, $z, will be undef
118       and $status will hold the a bzip2 error code.
119
120       Below is a list of the valid options:
121
122       $appendOutput
123            Controls whether the compressed data is appended to the output
124            buffer in the "bzinflate", "bzflush" and "bzclose" methods.
125
126            Defaults to 1.
127
128       $consumeInput
129       $small
130            To quote the bzip2 documentation
131
132                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
137            Defaults to 0.
138
139       $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
144            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
149            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
153            If "LimitOutput" is enabled, the "ConsumeInput" option will also
154            be enabled.
155
156            This option defaults to false.
157
158       $verbosity
159            This parameter is ignored.
160
161            Defaults to 0.
162
163   $status = $z->bzinflate($input, $output);
164       Uncompresses $input and writes the uncompressed data to $output.
165
166       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
171       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
178       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

Misc

184   my $version = Compress::Raw::Bzip2::bzlibversion();
185       Returns the version of the underlying bzip2 library.
186

Constants

188       The following bzip2 constants are exported by this module
189
190                       BZ_RUN
191                       BZ_FLUSH
192                       BZ_FINISH
193
194                       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

SUPPORT

210       General feedback/questions/bug reports should be sent to
211       <https://github.com/pmqs/Compress-Raw-Bzip2/issues> (preferred) or
212       <https://rt.cpan.org/Public/Dist/Display.html?Name=Compress-Raw-Bzip2>.
213

AUTHOR

235       This module was written by Paul Marquess, "pmqs@cpan.org".
236

MODIFICATION HISTORY

238       See the Changes file.
239

COPYRIGHT AND LICENSE

241       Copyright (c) 2005-2023 Paul Marquess. All rights reserved.
242
243       This program is free software; you can redistribute it and/or modify it
244       under the same terms as Perl itself.
245
246
247
248perl v5.38.0                      2023-07-26           Compress::Raw::Bzip2(3)