Debian Codegraph @

upstream/debian-unstable/man3/IO::Compress::Bzip2.3perl

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