Add built local::lib
[catagits/Gitalist.git] / local-lib5 / man / man3 / Compress::Raw::Bzip2.3pm
CommitLineData
3fea05b9 1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
13.de Sp \" Vertical space (when we can't use .PP)
14.if t .sp .5v
15.if n .sp
16..
17.de Vb \" Begin verbatim text
18.ft CW
19.nf
20.ne \\$1
21..
22.de Ve \" End verbatim text
23.ft R
24.fi
25..
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<>.
32.tr \(*W-|\(bv\*(Tr
33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34.ie n \{\
35. ds -- \(*W-
36. ds PI pi
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
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
43'br\}
44.el\{\
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
49'br\}
50.\"
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.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
58..
59. nr % 0
60. rr F
61.\}
62.\"
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
66.if n .na
67.\"
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
71.if n \{\
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
77.\}
78.if t \{\
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
84.\}
85. \" simple accents for nroff and troff
86.if n \{\
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
93.\}
94.if t \{\
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'
101.\}
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 \
117\{\
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
127.\}
128.rm #[ #] #H #V #F C
129.\" ========================================================================
130.\"
131.IX Title "Compress::Raw::Bzip2 3"
132.TH Compress::Raw::Bzip2 3 "2009-11-09" "perl v5.8.7" "User Contributed Perl Documentation"
133.SH "NAME"
134Compress::Raw::Bzip2 \- Low\-Level Interface to bzip2 compression library
135.SH "SYNOPSIS"
136.IX Header "SYNOPSIS"
137.Vb 1
138\& use Compress::Raw::Bzip2 ;
139.Ve
140.PP
141.Vb 2
142\& my ($bz, $status) = new Compress::Raw::Bzip2 [OPTS]
143\& or die "Cannot create bzip2 object: $bzerno\en";
144.Ve
145.PP
146.Vb 3
147\& $status = $bz\->bzdeflate($input, $output);
148\& $status = $bz\->bzflush($output);
149\& $status = $bz\->bzclose($output);
150.Ve
151.PP
152.Vb 2
153\& my ($bz, $status) = new Compress::Raw::Bunzip2 [OPTS]
154\& or die "Cannot create bunzip2 object: $bzerno\en";
155.Ve
156.PP
157.Vb 1
158\& $status = $bz\->bzinflate($input, $output);
159.Ve
160.PP
161.Vb 1
162\& my $version = Compress::Raw::Bzip2::bzlibversion();
163.Ve
164.SH "DESCRIPTION"
165.IX Header "DESCRIPTION"
166\&\f(CW\*(C`Compress::Raw::Bzip2\*(C'\fR provides an interface to the in-memory
167compression/uncompression functions from the bzip2 compression library.
168.PP
169Although the primary purpose for the existence of \f(CW\*(C`Compress::Raw::Bzip2\*(C'\fR
170is for use by the \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR and \f(CW\*(C`IO::Compress::Bunzip2\*(C'\fR
171modules, it can be used on its own for simple compression/uncompression
172tasks.
173.SH "Compression"
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;"
178Creates a new compression object.
179.PP
180If successful, it will return the initialised compression object, \f(CW$z\fR
181and a \f(CW$status\fR of \f(CW\*(C`BZ_OK\*(C'\fR in a list context. In scalar context it
182returns the deflation object, \f(CW$z\fR, only.
183.PP
184If 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.
186.PP
187Below is a list of the valid options:
188.IP "\fB$appendOutput\fR" 5
189.IX Item "$appendOutput"
190Controls whether the compressed data is appended to the output buffer in
191the \f(CW\*(C`bzdeflate\*(C'\fR, \f(CW\*(C`bzflush\*(C'\fR and \f(CW\*(C`bzclose\*(C'\fR methods.
192.Sp
193Defaults to 1.
194.IP "\fB$blockSize100k\fR" 5
195.IX Item "$blockSize100k"
196To quote the bzip2 documentation
197.Sp
198.Vb 4
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
202\& most memory.
203.Ve
204.Sp
205Defaults to 1.
206.IP "\fB$workfactor\fR" 5
207.IX Item "$workfactor"
208To quote the bzip2 documentation
209.Sp
210.Vb 7
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
217\& bad the input.
218.Ve
219.Sp
220.Vb 7
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
227\& circumstances.
228.Ve
229.Sp
230.Vb 2
231\& Allowable values range from 0 to 250 inclusive. 0 is a special case,
232\& equivalent to using the default value of 30.
233.Ve
234.Sp
235Defaults to 0.
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);"
239Reads the contents of \f(CW$input\fR, compresses it and writes the compressed
240data to \f(CW$output\fR.
241.PP
242Returns \f(CW\*(C`BZ_RUN_OK\*(C'\fR on success and a \f(CW\*(C`bzip2\*(C'\fR error code on failure.
243.PP
244If \f(CW\*(C`appendOutput\*(C'\fR is enabled in the constructor for the bzip2 object, the
245compressed data will be appended to \f(CW$output\fR. If not enabled, \f(CW$output\fR
246will 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);"
250Flushes any pending compressed data to \f(CW$output\fR.
251.PP
252Returns \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);"
256Terminates the compressed data stream and flushes any pending compressed
257data to \f(CW$output\fR.
258.PP
259Returns \f(CW\*(C`BZ_STREAM_END\*(C'\fR on success and a \f(CW\*(C`bzip2\*(C'\fR error code on failure.
260.Sh "Example"
261.IX Subsection "Example"
262.SH "Uncompression"
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;"
267If successful, it will return the initialised uncompression object, \f(CW$z\fR
268and a \f(CW$status\fR of \f(CW\*(C`BZ_OK\*(C'\fR in a list context. In scalar context it
269returns the deflation object, \f(CW$z\fR, only.
270.PP
271If 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.
273.PP
274Below is a list of the valid options:
275.IP "\fB$appendOutput\fR" 5
276.IX Item "$appendOutput"
277Controls 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.
279.Sp
280Defaults to 1.
281.IP "\fB$consumeInput\fR" 5
282.IX Item "$consumeInput"
283.PD 0
284.IP "\fB$small\fR" 5
285.IX Item "$small"
286.PD
287To quote the bzip2 documentation
288.Sp
289.Vb 4
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).
294.Ve
295.Sp
296Defaults to 0.
297.IP "\fB$limitOutput\fR" 5
298.IX Item "$limitOutput"
299The \f(CW\*(C`LimitOutput\*(C'\fR option changes the behavior of the \f(CW\*(C`$i\->bzinflate\*(C'\fR
300method so that the amount of memory used by the output buffer can be
301limited.
302.Sp
303When \f(CW\*(C`LimitOutput\*(C'\fR is used the size of the output buffer used will either
304be the 16k or the amount of memory already allocated to \f(CW$output\fR,
305whichever is larger. Predicting the output size available is tricky, so
306don't rely on getting an exact output buffer size.
307.Sp
308When \f(CW\*(C`LimitOutout\*(C'\fR is not specified \f(CW\*(C`$i\->bzinflate\*(C'\fR will use as much
309memory as it takes to write all the uncompressed data it creates by
310uncompressing the input buffer.
311.Sp
312If \f(CW\*(C`LimitOutput\*(C'\fR is enabled, the \f(CW\*(C`ConsumeInput\*(C'\fR option will also be
313enabled.
314.Sp
315This 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);"
319Uncompresses \f(CW$input\fR and writes the uncompressed data to \f(CW$output\fR.
320.PP
321Returns \f(CW\*(C`BZ_OK\*(C'\fR if the uncompression was successful, but the end of the
322compressed data stream has not been reached. Returns \f(CW\*(C`BZ_STREAM_END\*(C'\fR on
323successful uncompression and the end of the compression stream has been
324reached.
325.PP
326If \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
328uncompression. On \f(CW\*(C`BZ_OK\*(C'\fR return this will mean that \f(CW$input\fR will be an
329empty string; when \f(CW\*(C`BZ_STREAM_END\*(C'\fR \f(CW$input\fR will either be an empty
330string or will contain whatever data immediately followed the compressed
331data stream.
332.PP
333If \f(CW\*(C`appendOutput\*(C'\fR is enabled in the constructor for the bunzip2 object,
334the 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.
336.SH "Misc"
337.IX Header "Misc"
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();"
341Returns the version of the underlying bzip2 library.
342.SH "Constants"
343.IX Header "Constants"
344The following bzip2 constants are exported by this module
345.PP
346.Vb 3
347\& BZ_RUN
348\& BZ_FLUSH
349\& BZ_FINISH
350.Ve
351.PP
352.Vb 14
353\& BZ_OK
354\& BZ_RUN_OK
355\& BZ_FLUSH_OK
356\& BZ_FINISH_OK
357\& BZ_STREAM_END
358\& BZ_SEQUENCE_ERROR
359\& BZ_PARAM_ERROR
360\& BZ_MEM_ERROR
361\& BZ_DATA_ERROR
362\& BZ_DATA_ERROR_MAGIC
363\& BZ_IO_ERROR
364\& BZ_UNEXPECTED_EOF
365\& BZ_OUTBUFF_FULL
366\& BZ_CONFIG_ERROR
367.Ve
368.SH "SEE ALSO"
369.IX Header "SEE ALSO"
370Compress::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
371.PP
372Compress::Zlib::FAQ
373.PP
374File::GlobMapper, Archive::Zip,
375Archive::Tar,
376IO::Zlib
377.PP
378The primary site for the bzip2 program is \fIhttp://www.bzip.org\fR.
379.PP
380See the module Compress::Bzip2
381.SH "AUTHOR"
382.IX Header "AUTHOR"
383This module was written by Paul Marquess, \fIpmqs@cpan.org\fR.
384.SH "MODIFICATION HISTORY"
385.IX Header "MODIFICATION HISTORY"
386See the Changes file.
387.SH "COPYRIGHT AND LICENSE"
388.IX Header "COPYRIGHT AND LICENSE"
389Copyright (c) 2005\-2009 Paul Marquess. All rights reserved.
390.PP
391This program is free software; you can redistribute it and/or
392modify it under the same terms as Perl itself.