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 compres‐
27       sion/uncompression functions from the bzip2 compression library.
28
29       Although the primary purpose for the existence of "Com‐
30       press::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
38       Creates a new compression object.
39
40       If successful, it will return the initialised compression object, $z
41       and a $status of "BZ_OK" in a list context. In scalar context it
42       returns the deflation object, $z, only.
43
44       If not successful, the returned compression object, $z, will be undef
45       and $status will hold the a bzip2 error code.
46
47       Below is a list of the valid options:
48
49       $appendOutput
50            Controls whether the compressed data is appended to the output
51            buffer in the "bzdeflate", "bzflush" and "bzclose" methods.
52
53            Defaults to 1.
54
55       $blockSize100k
56            To quote the bzip2 documentation
57
58                blockSize100k specifies the block size to be used for compression. It
59                should be a value between 1 and 9 inclusive, and the actual block size
60                used is 100000 x this figure. 9 gives the best compression but takes
61                most memory.
62
63            Defaults to 1.
64
65       $workfactor
66            To quote the bzip2 documentation
67
68                This parameter controls how the compression phase behaves when
69                presented with worst case, highly repetitive, input data. If
70                compression runs into difficulties caused by repetitive data, the
71                library switches from the standard sorting algorithm to a fallback
72                algorithm. The fallback is slower than the standard algorithm by
73                perhaps a factor of three, but always behaves reasonably, no matter how
74                bad the input.
75
76                Lower values of workFactor reduce the amount of effort the standard
77                algorithm will expend before resorting to the fallback. You should set
78                this parameter carefully; too low, and many inputs will be handled by
79                the fallback algorithm and so compress rather slowly, too high, and
80                your average-to-worst case compression times can become very large. The
81                default value of 30 gives reasonable behaviour over a wide range of
82                circumstances.
83
84                Allowable values range from 0 to 250 inclusive. 0 is a special case,
85                equivalent to using the default value of 30.
86
87            Defaults to 0.
88
89       $status = $bz->bzdeflate($input, $output);
90
91       Reads the contents of $input, compresses it and writes the compressed
92       data to $output.
93
94       Returns "BZ_RUN_OK" on success and a "bzip2" error code on failure.
95
96       If "appendOutput" is enabled in the constructor for the bzip2 object,
97       the compressed data will be appended to $output. If not enabled, $out‐
98       put will be truncated before the compressed data is written to it.
99
100       $status = $bz->bzflush($output);
101
102       Flushes any pending compressed data to $output.
103
104       Returns "BZ_RUN_OK" on success and a "bzip2" error code on failure.
105
106       $status = $bz->bzclose($output);
107
108       Terminates the compressed data stream and flushes any pending com‐
109       pressed data to $output.
110
111       Returns "BZ_STREAM_END" on success and a "bzip2" error code on failure.
112
113       Example
114

Uncompression

116       ($z, $status) = new Compress::Raw::Bunzip2 $appendOutput, $consumeIn‐
117       put, $small;
118
119       If successful, it will return the initialised uncompression object, $z
120       and a $status of "BZ_OK" in a list context. In scalar context it
121       returns the deflation object, $z, only.
122
123       If not successful, the returned uncompression object, $z, will be undef
124       and $status will hold the a bzip2 error code.
125
126       Below is a list of the valid options:
127
128       $appendOutput
129            Controls whether the compressed data is appended to the output
130            buffer in the "bzinflate", "bzflush" and "bzclose" methods.
131
132            Defaults to 1.
133
134       $consumeInput
135       $small
136            To quote the bzip2 documentation
137
138                If small is nonzero, the library will use an alternative decompression
139                algorithm which uses less memory but at the cost of decompressing more
140                slowly (roughly speaking, half the speed, but the maximum memory
141                requirement drops to around 2300k).
142
143            Defaults to 0.
144
145       $status = $z->bzinflate($input, $output);
146
147       Uncompresses $input and writes the uncompressed data to $output.
148
149       Returns "BZ_OK" if the uncompression was successful, but the end of the
150       compressed data stream has not been reached. Returns "BZ_STREAM_END" on
151       successful uncompression and the end of the compression stream has been
152       reached.
153
154       If "consumeInput" is enabled in the constructor for the bunzip2 object,
155       $input will have all compressed data removed from it after uncompres‐
156       sion. On "BZ_OK" return this will mean that $input will be an empty
157       string; when "BZ_STREAM_END" $input will either be an empty string or
158       will contain whatever data immediately followed the compressed data
159       stream.
160
161       If "appendOutput" is enabled in the constructor for the bunzip2 object,
162       the uncompressed data will be appended to $output. If not enabled,
163       $output will be truncated before the uncompressed data is written to
164       it.
165

Constants

167       The following bzip2 constants are exported by this module
168
169                       BZ_RUN
170                       BZ_FLUSH
171                       BZ_FINISH
172
173                       BZ_OK
174                       BZ_RUN_OK
175                       BZ_FLUSH_OK
176                       BZ_FINISH_OK
177                       BZ_STREAM_END
178                       BZ_SEQUENCE_ERROR
179                       BZ_PARAM_ERROR
180                       BZ_MEM_ERROR
181                       BZ_DATA_ERROR
182                       BZ_DATA_ERROR_MAGIC
183                       BZ_IO_ERROR
184                       BZ_UNEXPECTED_EOF
185                       BZ_OUTBUFF_FULL
186                       BZ_CONFIG_ERROR
187

AUTHOR

205       This module was written by Paul Marquess, pmqs@cpan.org.
206

MODIFICATION HISTORY

208       See the Changes file.
209

COPYRIGHT AND LICENSE

211       Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
212
213       This program is free software; you can redistribute it and/or modify it
214       under the same terms as Perl itself.
215
216
217
218perl v5.8.8                       2007-06-18           Compress::Raw::Bzip2(3)