Debian Codegraph @

upstream/mageia-cauldron/man3pm/IO::Compress::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 "IO::Compress::Bzip2 3pm"
61 .TH IO::Compress::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 IO::Compress::Bzip2 \- Write bzip2 files/buffers
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
72 \&
73 \& my $status = bzip2 $input => $output [,OPTS]
74 \& or die "bzip2 failed: $Bzip2Error\en";
75 \&
76 \& my $z = IO::Compress::Bzip2\->new( $output [,OPTS] )
77 \& or die "bzip2 failed: $Bzip2Error\en";
78 \&
79 \& $z\->print($string);
80 \& $z\->printf($format, $string);
81 \& $z\->write($string);
82 \& $z\->syswrite($string [, $length, $offset]);
83 \& $z\->flush();
84 \& $z\->tell();
85 \& $z\->eof();
86 \& $z\->seek($position, $whence);
87 \& $z\->binmode();
88 \& $z\->fileno();
89 \& $z\->opened();
90 \& $z\->autoflush();
91 \& $z\->input_line_number();
92 \& $z\->newStream( [OPTS] );
93 \&
94 \& $z\->close() ;
95 \&
96 \& $Bzip2Error ;
97 \&
98 \& # IO::File mode
99 \&
100 \& print $z $string;
101 \& printf $z $format, $string;
102 \& tell $z
103 \& eof $z
104 \& seek $z, $position, $whence
105 \& binmode $z
106 \& fileno $z
107 \& close $z ;
108 .Ve
109 .SH DESCRIPTION
110 .IX Header "DESCRIPTION"
111 This module provides a Perl interface that allows writing bzip2
112 compressed data to files or buffer.
113 .PP
114 For reading bzip2 files/buffers, see the companion module
115 IO::Uncompress::Bunzip2.
116 .SH "Functional Interface"
117 .IX Header "Functional Interface"
118 A top\-level function, \f(CW\*(C`bzip2\*(C'\fR, is provided to carry out
119 "one\-shot" compression between buffers and/or files. For finer
120 control over the compression process, see the "OO Interface"
121 section.
122 .PP
123 .Vb 1
124 \& use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
125 \&
126 \& bzip2 $input_filename_or_reference => $output_filename_or_reference [,OPTS]
127 \& or die "bzip2 failed: $Bzip2Error\en";
128 .Ve
129 .PP
130 The functional interface needs Perl5.005 or better.
131 .ie n .SS "bzip2 $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
132 .el .SS "bzip2 \f(CW$input_filename_or_reference\fP => \f(CW$output_filename_or_reference\fP [, OPTS]"
133 .IX Subsection "bzip2 $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
134 \&\f(CW\*(C`bzip2\*(C'\fR expects at least two parameters,
135 \&\f(CW$input_filename_or_reference\fR and \f(CW$output_filename_or_reference\fR
136 and zero or more optional parameters (see "Optional Parameters")
137 .PP
138 \fIThe \fR\f(CI$input_filename_or_reference\fR\fI parameter\fR
139 .IX Subsection "The $input_filename_or_reference parameter"
140 .PP
141 The parameter, \f(CW$input_filename_or_reference\fR, is used to define the
142 source of the uncompressed data.
143 .PP
144 It can take one of the following forms:
145 .IP "A filename" 5
146 .IX Item "A filename"
147 If the \f(CW$input_filename_or_reference\fR parameter is a simple scalar, it is
148 assumed to be a filename. This file will be opened for reading and the
149 input data will be read from it.
150 .IP "A filehandle" 5
151 .IX Item "A filehandle"
152 If the \f(CW$input_filename_or_reference\fR parameter is a filehandle, the input
153 data will be read from it. The string \*(Aq\-\*(Aq can be used as an alias for
154 standard input.
155 .IP "A scalar reference" 5
156 .IX Item "A scalar reference"
157 If \f(CW$input_filename_or_reference\fR is a scalar reference, the input data
158 will be read from \f(CW$$input_filename_or_reference\fR.
159 .IP "An array reference" 5
160 .IX Item "An array reference"
161 If \f(CW$input_filename_or_reference\fR is an array reference, each element in
162 the array must be a filename.
163 .Sp
164 The input data will be read from each file in turn.
165 .Sp
166 The complete array will be walked to ensure that it only
167 contains valid filenames before any data is compressed.
168 .IP "An Input FileGlob string" 5
169 .IX Item "An Input FileGlob string"
170 If \f(CW$input_filename_or_reference\fR is a string that is delimited by the
171 characters "<" and ">" \f(CW\*(C`bzip2\*(C'\fR will assume that it is an
172 \&\fIinput fileglob string\fR. The input is the list of files that match the
173 fileglob.
174 .Sp
175 See File::GlobMapper for more details.
176 .PP
177 If the \f(CW$input_filename_or_reference\fR parameter is any other type,
178 \&\f(CW\*(C`undef\*(C'\fR will be returned.
179 .PP
180 \fIThe \fR\f(CI$output_filename_or_reference\fR\fI parameter\fR
181 .IX Subsection "The $output_filename_or_reference parameter"
182 .PP
183 The parameter \f(CW$output_filename_or_reference\fR is used to control the
184 destination of the compressed data. This parameter can take one of
185 these forms.
186 .IP "A filename" 5
187 .IX Item "A filename"
188 If the \f(CW$output_filename_or_reference\fR parameter is a simple scalar, it is
189 assumed to be a filename. This file will be opened for writing and the
190 compressed data will be written to it.
191 .IP "A filehandle" 5
192 .IX Item "A filehandle"
193 If the \f(CW$output_filename_or_reference\fR parameter is a filehandle, the
194 compressed data will be written to it. The string \*(Aq\-\*(Aq can be used as
195 an alias for standard output.
196 .IP "A scalar reference" 5
197 .IX Item "A scalar reference"
198 If \f(CW$output_filename_or_reference\fR is a scalar reference, the
199 compressed data will be stored in \f(CW$$output_filename_or_reference\fR.
200 .IP "An Array Reference" 5
201 .IX Item "An Array Reference"
202 If \f(CW$output_filename_or_reference\fR is an array reference,
203 the compressed data will be pushed onto the array.
204 .IP "An Output FileGlob" 5
205 .IX Item "An Output FileGlob"
206 If \f(CW$output_filename_or_reference\fR is a string that is delimited by the
207 characters "<" and ">" \f(CW\*(C`bzip2\*(C'\fR will assume that it is an
208 \&\fIoutput fileglob string\fR. The output is the list of files that match the
209 fileglob.
210 .Sp
211 When \f(CW$output_filename_or_reference\fR is an fileglob string,
212 \&\f(CW$input_filename_or_reference\fR must also be a fileglob string. Anything
213 else is an error.
214 .Sp
215 See File::GlobMapper for more details.
216 .PP
217 If the \f(CW$output_filename_or_reference\fR parameter is any other type,
218 \&\f(CW\*(C`undef\*(C'\fR will be returned.
219 .SS Notes
220 .IX Subsection "Notes"
221 When \f(CW$input_filename_or_reference\fR maps to multiple files/buffers and
222 \&\f(CW$output_filename_or_reference\fR is a single
223 file/buffer the input files/buffers will be stored
224 in \f(CW$output_filename_or_reference\fR as a concatenated series of compressed data streams.
225 .SS "Optional Parameters"
226 .IX Subsection "Optional Parameters"
227 The optional parameters for the one\-shot function \f(CW\*(C`bzip2\*(C'\fR
228 are (for the most part) identical to those used with the OO interface defined in the
229 "Constructor Options" section. The exceptions are listed below
230 .ie n .IP """AutoClose => 0|1""" 5
231 .el .IP "\f(CWAutoClose => 0|1\fR" 5
232 .IX Item "AutoClose => 0|1"
233 This option applies to any input or output data streams to
234 \&\f(CW\*(C`bzip2\*(C'\fR that are filehandles.
235 .Sp
236 If \f(CW\*(C`AutoClose\*(C'\fR is specified, and the value is true, it will result in all
237 input and/or output filehandles being closed once \f(CW\*(C`bzip2\*(C'\fR has
238 completed.
239 .Sp
240 This parameter defaults to 0.
241 .ie n .IP """BinModeIn => 0|1""" 5
242 .el .IP "\f(CWBinModeIn => 0|1\fR" 5
243 .IX Item "BinModeIn => 0|1"
244 This option is now a no\-op. All files will be read in binmode.
245 .ie n .IP """Append => 0|1""" 5
246 .el .IP "\f(CWAppend => 0|1\fR" 5
247 .IX Item "Append => 0|1"
248 The behaviour of this option is dependent on the type of output data
249 stream.
250 .RS 5
251 .IP \(bu 5
252 A Buffer
253 .Sp
254 If \f(CW\*(C`Append\*(C'\fR is enabled, all compressed data will be append to the end of
255 the output buffer. Otherwise the output buffer will be cleared before any
256 compressed data is written to it.
257 .IP \(bu 5
258 A Filename
259 .Sp
260 If \f(CW\*(C`Append\*(C'\fR is enabled, the file will be opened in append mode. Otherwise
261 the contents of the file, if any, will be truncated before any compressed
262 data is written to it.
263 .IP \(bu 5
264 A Filehandle
265 .Sp
266 If \f(CW\*(C`Append\*(C'\fR is enabled, the filehandle will be positioned to the end of
267 the file via a call to \f(CW\*(C`seek\*(C'\fR before any compressed data is
268 written to it. Otherwise the file pointer will not be moved.
269 .RE
270 .RS 5
271 .Sp
272 When \f(CW\*(C`Append\*(C'\fR is specified, and set to true, it will \fIappend\fR all compressed
273 data to the output data stream.
274 .Sp
275 So when the output is a filehandle it will carry out a seek to the eof
276 before writing any compressed data. If the output is a filename, it will be opened for
277 appending. If the output is a buffer, all compressed data will be
278 appended to the existing buffer.
279 .Sp
280 Conversely when \f(CW\*(C`Append\*(C'\fR is not specified, or it is present and is set to
281 false, it will operate as follows.
282 .Sp
283 When the output is a filename, it will truncate the contents of the file
284 before writing any compressed data. If the output is a filehandle
285 its position will not be changed. If the output is a buffer, it will be
286 wiped before any compressed data is output.
287 .Sp
288 Defaults to 0.
289 .RE
290 .SS "Oneshot Examples"
291 .IX Subsection "Oneshot Examples"
292 Here are a few example that show the capabilities of the module.
293 .PP
294 \fIStreaming\fR
295 .IX Subsection "Streaming"
296 .PP
297 This very simple command line example demonstrates the streaming capabilities of the module.
298 The code reads data from STDIN, compresses it, and writes the compressed data to STDOUT.
299 .PP
300 .Vb 1
301 \& $ echo hello world | perl \-MIO::Compress::Bzip2=bzip2 \-e \*(Aqbzip2 \e*STDIN => \e*STDOUT\*(Aq >output.bz2
302 .Ve
303 .PP
304 The special filename "\-" can be used as a standin for both \f(CW\*(C`\e*STDIN\*(C'\fR and \f(CW\*(C`\e*STDOUT\*(C'\fR,
305 so the above can be rewritten as
306 .PP
307 .Vb 1
308 \& $ echo hello world | perl \-MIO::Compress::Bzip2=bzip2 \-e \*(Aqbzip2 "\-" => "\-"\*(Aq >output.bz2
309 .Ve
310 .PP
311 \fICompressing a file from the filesystem\fR
312 .IX Subsection "Compressing a file from the filesystem"
313 .PP
314 To read the contents of the file \f(CW\*(C`file1.txt\*(C'\fR and write the compressed
315 data to the file \f(CW\*(C`file1.txt.bz2\*(C'\fR.
316 .PP
317 .Vb 3
318 \& use strict ;
319 \& use warnings ;
320 \& use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
321 \&
322 \& my $input = "file1.txt";
323 \& bzip2 $input => "$input.bz2"
324 \& or die "bzip2 failed: $Bzip2Error\en";
325 .Ve
326 .PP
327 \fIReading from a Filehandle and writing to an in\-memory buffer\fR
328 .IX Subsection "Reading from a Filehandle and writing to an in-memory buffer"
329 .PP
330 To read from an existing Perl filehandle, \f(CW$input\fR, and write the
331 compressed data to a buffer, \f(CW$buffer\fR.
332 .PP
333 .Vb 4
334 \& use strict ;
335 \& use warnings ;
336 \& use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
337 \& use IO::File ;
338 \&
339 \& my $input = IO::File\->new( "<file1.txt" )
340 \& or die "Cannot open \*(Aqfile1.txt\*(Aq: $!\en" ;
341 \& my $buffer ;
342 \& bzip2 $input => \e$buffer
343 \& or die "bzip2 failed: $Bzip2Error\en";
344 .Ve
345 .PP
346 \fICompressing multiple files\fR
347 .IX Subsection "Compressing multiple files"
348 .PP
349 To compress all files in the directory "/my/home" that match "*.txt"
350 and store the compressed data in the same directory
351 .PP
352 .Vb 3
353 \& use strict ;
354 \& use warnings ;
355 \& use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
356 \&
357 \& bzip2 \*(Aq</my/home/*.txt>\*(Aq => \*(Aq<*.bz2>\*(Aq
358 \& or die "bzip2 failed: $Bzip2Error\en";
359 .Ve
360 .PP
361 and if you want to compress each file one at a time, this will do the trick
362 .PP
363 .Vb 3
364 \& use strict ;
365 \& use warnings ;
366 \& use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
367 \&
368 \& for my $input ( glob "/my/home/*.txt" )
369 \& {
370 \& my $output = "$input.bz2" ;
371 \& bzip2 $input => $output
372 \& or die "Error compressing \*(Aq$input\*(Aq: $Bzip2Error\en";
373 \& }
374 .Ve
375 .SH "OO Interface"
376 .IX Header "OO Interface"
377 .SS Constructor
378 .IX Subsection "Constructor"
379 The format of the constructor for \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR is shown below
380 .PP
381 .Vb 2
382 \& my $z = IO::Compress::Bzip2\->new( $output [,OPTS] )
383 \& or die "IO::Compress::Bzip2 failed: $Bzip2Error\en";
384 .Ve
385 .PP
386 The constructor takes one mandatory parameter, \f(CW$output\fR, defined below and
387 zero or more \f(CW\*(C`OPTS\*(C'\fR, defined in "Constructor Options".
388 .PP
389 It returns an \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR object on success and \f(CW\*(C`undef\*(C'\fR on failure.
390 The variable \f(CW$Bzip2Error\fR will contain an error message on failure.
391 .PP
392 If you are running Perl 5.005 or better the object, \f(CW$z\fR, returned from
393 IO::Compress::Bzip2 can be used exactly like an IO::File filehandle.
394 This means that all normal output file operations can be carried out
395 with \f(CW$z\fR.
396 For example, to write to a compressed file/buffer you can use either of
397 these forms
398 .PP
399 .Vb 2
400 \& $z\->print("hello world\en");
401 \& print $z "hello world\en";
402 .Ve
403 .PP
404 Below is a simple exaple of using the OO interface to create an output file
405 \&\f(CW\*(C`myfile.bz2\*(C'\fR and write some data to it.
406 .PP
407 .Vb 3
408 \& my $filename = "myfile.bz2";
409 \& my $z = IO::Compress::Bzip2\->new($filename)
410 \& or die "IO::Compress::Bzip2 failed: $Bzip2Error\en";
411 \&
412 \& $z\->print("abcde");
413 \& $z\->close();
414 .Ve
415 .PP
416 See the "Examples" for more.
417 .PP
418 The mandatory parameter \f(CW$output\fR is used to control the destination
419 of the compressed data. This parameter can take one of these forms.
420 .IP "A filename" 5
421 .IX Item "A filename"
422 If the \f(CW$output\fR parameter is a simple scalar, it is assumed to be a
423 filename. This file will be opened for writing and the compressed data
424 will be written to it.
425 .IP "A filehandle" 5
426 .IX Item "A filehandle"
427 If the \f(CW$output\fR parameter is a filehandle, the compressed data will be
428 written to it.
429 The string \*(Aq\-\*(Aq can be used as an alias for standard output.
430 .IP "A scalar reference" 5
431 .IX Item "A scalar reference"
432 If \f(CW$output\fR is a scalar reference, the compressed data will be stored
433 in \f(CW$$output\fR.
434 .PP
435 If the \f(CW$output\fR parameter is any other type, \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR::new will
436 return undef.
437 .SS "Constructor Options"
438 .IX Subsection "Constructor Options"
439 \&\f(CW\*(C`OPTS\*(C'\fR is any combination of zero or more the following options:
440 .ie n .IP """AutoClose => 0|1""" 5
441 .el .IP "\f(CWAutoClose => 0|1\fR" 5
442 .IX Item "AutoClose => 0|1"
443 This option is only valid when the \f(CW$output\fR parameter is a filehandle. If
444 specified, and the value is true, it will result in the \f(CW$output\fR being
445 closed once either the \f(CW\*(C`close\*(C'\fR method is called or the \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR
446 object is destroyed.
447 .Sp
448 This parameter defaults to 0.
449 .ie n .IP """Append => 0|1""" 5
450 .el .IP "\f(CWAppend => 0|1\fR" 5
451 .IX Item "Append => 0|1"
452 Opens \f(CW$output\fR in append mode.
453 .Sp
454 The behaviour of this option is dependent on the type of \f(CW$output\fR.
455 .RS 5
456 .IP \(bu 5
457 A Buffer
458 .Sp
459 If \f(CW$output\fR is a buffer and \f(CW\*(C`Append\*(C'\fR is enabled, all compressed data
460 will be append to the end of \f(CW$output\fR. Otherwise \f(CW$output\fR will be
461 cleared before any data is written to it.
462 .IP \(bu 5
463 A Filename
464 .Sp
465 If \f(CW$output\fR is a filename and \f(CW\*(C`Append\*(C'\fR is enabled, the file will be
466 opened in append mode. Otherwise the contents of the file, if any, will be
467 truncated before any compressed data is written to it.
468 .IP \(bu 5
469 A Filehandle
470 .Sp
471 If \f(CW$output\fR is a filehandle, the file pointer will be positioned to the
472 end of the file via a call to \f(CW\*(C`seek\*(C'\fR before any compressed data is written
473 to it. Otherwise the file pointer will not be moved.
474 .RE
475 .RS 5
476 .Sp
477 This parameter defaults to 0.
478 .RE
479 .ie n .IP """BlockSize100K => number""" 5
480 .el .IP "\f(CWBlockSize100K => number\fR" 5
481 .IX Item "BlockSize100K => number"
482 Specify the number of 100K blocks bzip2 uses during compression.
483 .Sp
484 Valid values are from 1 to 9, where 9 is best compression.
485 .Sp
486 The default is 1.
487 .ie n .IP """WorkFactor => number""" 5
488 .el .IP "\f(CWWorkFactor => number\fR" 5
489 .IX Item "WorkFactor => number"
490 Specifies how much effort bzip2 should take before resorting to a slower
491 fallback compression algorithm.
492 .Sp
493 Valid values range from 0 to 250, where 0 means use the default value 30.
494 .Sp
495 The default is 0.
496 .ie n .IP """Strict => 0|1""" 5
497 .el .IP "\f(CWStrict => 0|1\fR" 5
498 .IX Item "Strict => 0|1"
499 This is a placeholder option.
500 .SS Examples
501 .IX Subsection "Examples"
502 \fIStreaming\fR
503 .IX Subsection "Streaming"
504 .PP
505 This very simple command line example demonstrates the streaming capabilities
506 of the module. The code reads data from STDIN or all the files given on the
507 commandline, compresses it, and writes the compressed data to STDOUT.
508 .PP
509 .Vb 3
510 \& use strict ;
511 \& use warnings ;
512 \& use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
513 \&
514 \& my $z = IO::Compress::Bzip2\->new("\-", Stream => 1)
515 \& or die "IO::Compress::Bzip2 failed: $Bzip2Error\en";
516 \&
517 \& while (<>) {
518 \& $z\->print("abcde");
519 \& }
520 \& $z\->close();
521 .Ve
522 .PP
523 Note the use of \f(CW"\-"\fR to means \f(CW\*(C`STDOUT\*(C'\fR. Alternatively you can use \f(CW\*(C`\e*STDOUT\*(C'\fR.
524 .PP
525 \fICompressing a file from the filesystem\fR
526 .IX Subsection "Compressing a file from the filesystem"
527 .PP
528 To read the contents of the file \f(CW\*(C`file1.txt\*(C'\fR and write the compressed
529 data to the file \f(CW\*(C`file1.txt.bz2\*(C'\fR there are a few options
530 .PP
531 Start by creating the compression object and opening the input file
532 .PP
533 .Vb 3
534 \& use strict ;
535 \& use warnings ;
536 \& use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
537 \&
538 \& my $input = "file1.txt";
539 \& my $z = IO::Compress::Bzip2\->new("file1.txt.bz2")
540 \& or die "IO::Compress::Bzip2 failed: $Bzip2Error\en";
541 \&
542 \& # open the input file
543 \& open my $fh, "<", "file1.txt"
544 \& or die "Cannot open file1.txt: $!\en";
545 \&
546 \& # loop through the input file & write to the compressed file
547 \& while (<$fh>) {
548 \& $z\->print($_);
549 \& }
550 \&
551 \& # not forgetting to close the compressed file
552 \& $z\->close();
553 .Ve
554 .SH Methods
555 .IX Header "Methods"
556 .SS print
557 .IX Subsection "print"
558 Usage is
559 .PP
560 .Vb 2
561 \& $z\->print($data)
562 \& print $z $data
563 .Ve
564 .PP
565 Compresses and outputs the contents of the \f(CW$data\fR parameter. This
566 has the same behaviour as the \f(CW\*(C`print\*(C'\fR built\-in.
567 .PP
568 Returns true if successful.
569 .SS printf
570 .IX Subsection "printf"
571 Usage is
572 .PP
573 .Vb 2
574 \& $z\->printf($format, $data)
575 \& printf $z $format, $data
576 .Ve
577 .PP
578 Compresses and outputs the contents of the \f(CW$data\fR parameter.
579 .PP
580 Returns true if successful.
581 .SS syswrite
582 .IX Subsection "syswrite"
583 Usage is
584 .PP
585 .Vb 3
586 \& $z\->syswrite $data
587 \& $z\->syswrite $data, $length
588 \& $z\->syswrite $data, $length, $offset
589 .Ve
590 .PP
591 Compresses and outputs the contents of the \f(CW$data\fR parameter.
592 .PP
593 Returns the number of uncompressed bytes written, or \f(CW\*(C`undef\*(C'\fR if
594 unsuccessful.
595 .SS write
596 .IX Subsection "write"
597 Usage is
598 .PP
599 .Vb 3
600 \& $z\->write $data
601 \& $z\->write $data, $length
602 \& $z\->write $data, $length, $offset
603 .Ve
604 .PP
605 Compresses and outputs the contents of the \f(CW$data\fR parameter.
606 .PP
607 Returns the number of uncompressed bytes written, or \f(CW\*(C`undef\*(C'\fR if
608 unsuccessful.
609 .SS flush
610 .IX Subsection "flush"
611 Usage is
612 .PP
613 .Vb 1
614 \& $z\->flush;
615 .Ve
616 .PP
617 Flushes any pending compressed data to the output file/buffer.
618 .PP
619 TODO
620 .PP
621 Returns true on success.
622 .SS tell
623 .IX Subsection "tell"
624 Usage is
625 .PP
626 .Vb 2
627 \& $z\->tell()
628 \& tell $z
629 .Ve
630 .PP
631 Returns the uncompressed file offset.
632 .SS eof
633 .IX Subsection "eof"
634 Usage is
635 .PP
636 .Vb 2
637 \& $z\->eof();
638 \& eof($z);
639 .Ve
640 .PP
641 Returns true if the \f(CW\*(C`close\*(C'\fR method has been called.
642 .SS seek
643 .IX Subsection "seek"
644 .Vb 2
645 \& $z\->seek($position, $whence);
646 \& seek($z, $position, $whence);
647 .Ve
648 .PP
649 Provides a sub\-set of the \f(CW\*(C`seek\*(C'\fR functionality, with the restriction
650 that it is only legal to seek forward in the output file/buffer.
651 It is a fatal error to attempt to seek backward.
652 .PP
653 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
654 .PP
655 The \f(CW$whence\fR parameter takes one the usual values, namely SEEK_SET,
656 SEEK_CUR or SEEK_END.
657 .PP
658 Returns 1 on success, 0 on failure.
659 .SS binmode
660 .IX Subsection "binmode"
661 Usage is
662 .PP
663 .Vb 2
664 \& $z\->binmode
665 \& binmode $z ;
666 .Ve
667 .PP
668 This is a noop provided for completeness.
669 .SS opened
670 .IX Subsection "opened"
671 .Vb 1
672 \& $z\->opened()
673 .Ve
674 .PP
675 Returns true if the object currently refers to a opened file/buffer.
676 .SS autoflush
677 .IX Subsection "autoflush"
678 .Vb 2
679 \& my $prev = $z\->autoflush()
680 \& my $prev = $z\->autoflush(EXPR)
681 .Ve
682 .PP
683 If the \f(CW$z\fR object is associated with a file or a filehandle, this method
684 returns the current autoflush setting for the underlying filehandle. If
685 \&\f(CW\*(C`EXPR\*(C'\fR is present, and is non\-zero, it will enable flushing after every
686 write/print operation.
687 .PP
688 If \f(CW$z\fR is associated with a buffer, this method has no effect and always
689 returns \f(CW\*(C`undef\*(C'\fR.
690 .PP
691 \&\fBNote\fR that the special variable \f(CW$|\fR \fBcannot\fR be used to set or
692 retrieve the autoflush setting.
693 .SS input_line_number
694 .IX Subsection "input_line_number"
695 .Vb 2
696 \& $z\->input_line_number()
697 \& $z\->input_line_number(EXPR)
698 .Ve
699 .PP
700 This method always returns \f(CW\*(C`undef\*(C'\fR when compressing.
701 .SS fileno
702 .IX Subsection "fileno"
703 .Vb 2
704 \& $z\->fileno()
705 \& fileno($z)
706 .Ve
707 .PP
708 If the \f(CW$z\fR object is associated with a file or a filehandle, \f(CW\*(C`fileno\*(C'\fR
709 will return the underlying file descriptor. Once the \f(CW\*(C`close\*(C'\fR method is
710 called \f(CW\*(C`fileno\*(C'\fR will return \f(CW\*(C`undef\*(C'\fR.
711 .PP
712 If the \f(CW$z\fR object is associated with a buffer, this method will return
713 \&\f(CW\*(C`undef\*(C'\fR.
714 .SS close
715 .IX Subsection "close"
716 .Vb 2
717 \& $z\->close() ;
718 \& close $z ;
719 .Ve
720 .PP
721 Flushes any pending compressed data and then closes the output file/buffer.
722 .PP
723 For most versions of Perl this method will be automatically invoked if
724 the IO::Compress::Bzip2 object is destroyed (either explicitly or by the
725 variable with the reference to the object going out of scope). The
726 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
727 these cases, the \f(CW\*(C`close\*(C'\fR method will be called automatically, but
728 not until global destruction of all live objects when the program is
729 terminating.
730 .PP
731 Therefore, if you want your scripts to be able to run on all versions
732 of Perl, you should call \f(CW\*(C`close\*(C'\fR explicitly and not rely on automatic
733 closing.
734 .PP
735 Returns true on success, otherwise 0.
736 .PP
737 If the \f(CW\*(C`AutoClose\*(C'\fR option has been enabled when the IO::Compress::Bzip2
738 object was created, and the object is associated with a file, the
739 underlying file will also be closed.
740 .SS newStream([OPTS])
741 .IX Subsection "newStream([OPTS])"
742 Usage is
743 .PP
744 .Vb 1
745 \& $z\->newStream( [OPTS] )
746 .Ve
747 .PP
748 Closes the current compressed data stream and starts a new one.
749 .PP
750 OPTS consists of any of the options that are available when creating
751 the \f(CW$z\fR object.
752 .PP
753 See the "Constructor Options" section for more details.
754 .SH Importing
755 .IX Header "Importing"
756 No symbolic constants are required by IO::Compress::Bzip2 at present.
757 .IP :all 5
758 .IX Item ":all"
759 Imports \f(CW\*(C`bzip2\*(C'\fR and \f(CW$Bzip2Error\fR.
760 Same as doing this
761 .Sp
762 .Vb 1
763 \& use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
764 .Ve
765 .SH EXAMPLES
766 .IX Header "EXAMPLES"
767 .SS "Apache::GZip Revisited"
768 .IX Subsection "Apache::GZip Revisited"
769 See IO::Compress::FAQ
770 .SS "Working with Net::FTP"
771 .IX Subsection "Working with Net::FTP"
772 See IO::Compress::FAQ
773 .SH SUPPORT
774 .IX Header "SUPPORT"
775 General feedback/questions/bug reports should be sent to
776 <https://github.com/pmqs/IO\-Compress/issues> (preferred) or
777 <https://rt.cpan.org/Public/Dist/Display.html?Name=IO\-Compress>.
778 .SH "SEE ALSO"
779 .IX Header "SEE ALSO"
780 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip, IO::Compress::Deflate, IO::Uncompress::Inflate, IO::Compress::RawDeflate, IO::Uncompress::RawInflate, 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
781 .PP
782 IO::Compress::FAQ
783 .PP
784 File::GlobMapper, Archive::Zip,
785 Archive::Tar,
786 IO::Zlib
787 .PP
788 The primary site for the bzip2 program is <https://sourceware.org/bzip2/>.
789 .PP
790 See the module Compress::Bzip2
791 .SH AUTHOR
792 .IX Header "AUTHOR"
793 This module was written by Paul Marquess, \f(CW\*(C`[email protected]\*(C'\fR.
794 .SH "MODIFICATION HISTORY"
795 .IX Header "MODIFICATION HISTORY"
796 See the Changes file.
797 .SH "COPYRIGHT AND LICENSE"
798 .IX Header "COPYRIGHT AND LICENSE"
799 Copyright (c) 2005\-2024 Paul Marquess. All rights reserved.
800 .PP
801 This program is free software; you can redistribute it and/or
802 modify it under the same terms as Perl itself.