1IO::Compress::Bzip2(3)User Contributed Perl DocumentationIO::Compress::Bzip2(3)
2
6 IO::Compress::Bzip2 - Write bzip2 files/buffers
7
9 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
10 my $status = bzip2 $input => $output [,OPTS]
12 or die "bzip2 failed: $Bzip2Error\n";
13 my $z = IO::Compress::Bzip2->new( $output [,OPTS] )
15 or die "bzip2 failed: $Bzip2Error\n";
16 $z->print($string);
18 $z->printf($format, $string);
19 $z->write($string);
20 $z->syswrite($string [, $length, $offset]);
21 $z->flush();
22 $z->tell();
23 $z->eof();
24 $z->seek($position, $whence);
25 $z->binmode();
26 $z->fileno();
27 $z->opened();
28 $z->autoflush();
29 $z->input_line_number();
30 $z->newStream( [OPTS] );
31 $z->close() ;
33 $Bzip2Error ;
35 # IO::File mode
37 print $z $string;
39 printf $z $format, $string;
40 tell $z
41 eof $z
42 seek $z, $position, $whence
43 binmode $z
44 fileno $z
45 close $z ;
46
48 This module provides a Perl interface that allows writing bzip2
49 compressed data to files or buffer.
50 For reading bzip2 files/buffers, see the companion module
52 IO::Uncompress::Bunzip2.
53
55 A top-level function, "bzip2", is provided to carry out "one-shot"
56 compression between buffers and/or files. For finer control over the
57 compression process, see the "OO Interface" section.
58 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
60 bzip2 $input_filename_or_reference => $output_filename_or_reference [,OPTS]
62 or die "bzip2 failed: $Bzip2Error\n";
63 The functional interface needs Perl5.005 or better.
65 bzip2 $input_filename_or_reference => $output_filename_or_reference [,
67 OPTS]
68 "bzip2" expects at least two parameters, $input_filename_or_reference
69 and $output_filename_or_reference and zero or more optional parameters
70 (see "Optional Parameters")
71 The $input_filename_or_reference parameter
73 The parameter, $input_filename_or_reference, is used to define the
75 source of the uncompressed data.
76 It can take one of the following forms:
78 A filename
80 If the $input_filename_or_reference parameter is a simple scalar,
81 it is assumed to be a filename. This file will be opened for
82 reading and the input data will be read from it.
83 A filehandle
85 If the $input_filename_or_reference parameter is a filehandle, the
86 input data will be read from it. The string '-' can be used as an
87 alias for standard input.
88 A scalar reference
90 If $input_filename_or_reference is a scalar reference, the input
91 data will be read from $$input_filename_or_reference.
92 An array reference
94 If $input_filename_or_reference is an array reference, each
95 element in the array must be a filename.
96 The input data will be read from each file in turn.
98 The complete array will be walked to ensure that it only contains
100 valid filenames before any data is compressed.
101 An Input FileGlob string
103 If $input_filename_or_reference is a string that is delimited by
104 the characters "<" and ">" "bzip2" will assume that it is an input
105 fileglob string. The input is the list of files that match the
106 fileglob.
107 See File::GlobMapper for more details.
109 If the $input_filename_or_reference parameter is any other type,
111 "undef" will be returned.
112 The $output_filename_or_reference parameter
114 The parameter $output_filename_or_reference is used to control the
116 destination of the compressed data. This parameter can take one of
117 these forms.
118 A filename
120 If the $output_filename_or_reference parameter is a simple scalar,
121 it is assumed to be a filename. This file will be opened for
122 writing and the compressed data will be written to it.
123 A filehandle
125 If the $output_filename_or_reference parameter is a filehandle,
126 the compressed data will be written to it. The string '-' can be
127 used as an alias for standard output.
128 A scalar reference
130 If $output_filename_or_reference is a scalar reference, the
131 compressed data will be stored in $$output_filename_or_reference.
132 An Array Reference
134 If $output_filename_or_reference is an array reference, the
135 compressed data will be pushed onto the array.
136 An Output FileGlob
138 If $output_filename_or_reference is a string that is delimited by
139 the characters "<" and ">" "bzip2" will assume that it is an
140 output fileglob string. The output is the list of files that match
141 the fileglob.
142 When $output_filename_or_reference is an fileglob string,
144 $input_filename_or_reference must also be a fileglob string.
145 Anything else is an error.
146 See File::GlobMapper for more details.
148 If the $output_filename_or_reference parameter is any other type,
150 "undef" will be returned.
151 Notes
153 When $input_filename_or_reference maps to multiple files/buffers and
154 $output_filename_or_reference is a single file/buffer the input
155 files/buffers will be stored in $output_filename_or_reference as a
156 concatenated series of compressed data streams.
157 Optional Parameters
159 The optional parameters for the one-shot function "bzip2" are (for the
160 most part) identical to those used with the OO interface defined in the
161 "Constructor Options" section. The exceptions are listed below
162 "AutoClose => 0|1"
164 This option applies to any input or output data streams to "bzip2"
165 that are filehandles.
166 If "AutoClose" is specified, and the value is true, it will result
168 in all input and/or output filehandles being closed once "bzip2"
169 has completed.
170 This parameter defaults to 0.
172 "BinModeIn => 0|1"
174 This option is now a no-op. All files will be read in binmode.
175 "Append => 0|1"
177 The behaviour of this option is dependent on the type of output
178 data stream.
179 • A Buffer
181 If "Append" is enabled, all compressed data will be append to
183 the end of the output buffer. Otherwise the output buffer
184 will be cleared before any compressed data is written to it.
185 • A Filename
187 If "Append" is enabled, the file will be opened in append
189 mode. Otherwise the contents of the file, if any, will be
190 truncated before any compressed data is written to it.
191 • A Filehandle
193 If "Append" is enabled, the filehandle will be positioned to
195 the end of the file via a call to "seek" before any
196 compressed data is written to it. Otherwise the file pointer
197 will not be moved.
198 When "Append" is specified, and set to true, it will append all
200 compressed data to the output data stream.
201 So when the output is a filehandle it will carry out a seek to the
203 eof before writing any compressed data. If the output is a
204 filename, it will be opened for appending. If the output is a
205 buffer, all compressed data will be appended to the existing
206 buffer.
207 Conversely when "Append" is not specified, or it is present and is
209 set to false, it will operate as follows.
210 When the output is a filename, it will truncate the contents of
212 the file before writing any compressed data. If the output is a
213 filehandle its position will not be changed. If the output is a
214 buffer, it will be wiped before any compressed data is output.
215 Defaults to 0.
217 Examples
219 Here are a few example that show the capabilities of the module.
220 Streaming
222 This very simple command line example demonstrates the streaming
224 capabilities of the module. The code reads data from STDIN, compresses
225 it, and writes the compressed data to STDOUT.
226 $ echo hello world | perl -MIO::Compress::Bzip2=bzip2 -e 'bzip2 \*STDIN => \*STDOUT' >output.bz2
228 The special filename "-" can be used as a standin for both "\*STDIN"
230 and "\*STDOUT", so the above can be rewritten as
231 $ echo hello world | perl -MIO::Compress::Bzip2=bzip2 -e 'bzip2 "-" => "-"' >output.bz2
233 Compressing a file from the filesystem
235 To read the contents of the file "file1.txt" and write the compressed
237 data to the file "file1.txt.bz2".
238 use strict ;
240 use warnings ;
241 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
242 my $input = "file1.txt";
244 bzip2 $input => "$input.bz2"
245 or die "bzip2 failed: $Bzip2Error\n";
246 Reading from a Filehandle and writing to an in-memory buffer
248 To read from an existing Perl filehandle, $input, and write the
250 compressed data to a buffer, $buffer.
251 use strict ;
253 use warnings ;
254 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
255 use IO::File ;
256 my $input = IO::File->new( "<file1.txt" )
258 or die "Cannot open 'file1.txt': $!\n" ;
259 my $buffer ;
260 bzip2 $input => \$buffer
261 or die "bzip2 failed: $Bzip2Error\n";
262 Compressing multiple files
264 To compress all files in the directory "/my/home" that match "*.txt"
266 and store the compressed data in the same directory
267 use strict ;
269 use warnings ;
270 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
271 bzip2 '</my/home/*.txt>' => '<*.bz2>'
273 or die "bzip2 failed: $Bzip2Error\n";
274 and if you want to compress each file one at a time, this will do the
276 trick
277 use strict ;
279 use warnings ;
280 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
281 for my $input ( glob "/my/home/*.txt" )
283 {
284 my $output = "$input.bz2" ;
285 bzip2 $input => $output
286 or die "Error compressing '$input': $Bzip2Error\n";
287 }
288
290 Constructor
291 The format of the constructor for "IO::Compress::Bzip2" is shown below
292 my $z = IO::Compress::Bzip2->new( $output [,OPTS] )
294 or die "IO::Compress::Bzip2 failed: $Bzip2Error\n";
295 It returns an "IO::Compress::Bzip2" object on success and undef on
297 failure. The variable $Bzip2Error will contain an error message on
298 failure.
299 If you are running Perl 5.005 or better the object, $z, returned from
301 IO::Compress::Bzip2 can be used exactly like an IO::File filehandle.
302 This means that all normal output file operations can be carried out
303 with $z. For example, to write to a compressed file/buffer you can use
304 either of these forms
305 $z->print("hello world\n");
307 print $z "hello world\n";
308 The mandatory parameter $output is used to control the destination of
310 the compressed data. This parameter can take one of these forms.
311 A filename
313 If the $output parameter is a simple scalar, it is assumed to be a
314 filename. This file will be opened for writing and the compressed
315 data will be written to it.
316 A filehandle
318 If the $output parameter is a filehandle, the compressed data will
319 be written to it. The string '-' can be used as an alias for
320 standard output.
321 A scalar reference
323 If $output is a scalar reference, the compressed data will be
324 stored in $$output.
325 If the $output parameter is any other type, "IO::Compress::Bzip2"::new
327 will return undef.
328 Constructor Options
330 "OPTS" is any combination of zero or more the following options:
331 "AutoClose => 0|1"
333 This option is only valid when the $output parameter is a
334 filehandle. If specified, and the value is true, it will result in
335 the $output being closed once either the "close" method is called
336 or the "IO::Compress::Bzip2" object is destroyed.
337 This parameter defaults to 0.
339 "Append => 0|1"
341 Opens $output in append mode.
342 The behaviour of this option is dependent on the type of $output.
344 • A Buffer
346 If $output is a buffer and "Append" is enabled, all
348 compressed data will be append to the end of $output.
349 Otherwise $output will be cleared before any data is written
350 to it.
351 • A Filename
353 If $output is a filename and "Append" is enabled, the file
355 will be opened in append mode. Otherwise the contents of the
356 file, if any, will be truncated before any compressed data is
357 written to it.
358 • A Filehandle
360 If $output is a filehandle, the file pointer will be
362 positioned to the end of the file via a call to "seek" before
363 any compressed data is written to it. Otherwise the file
364 pointer will not be moved.
365 This parameter defaults to 0.
367 "BlockSize100K => number"
369 Specify the number of 100K blocks bzip2 uses during compression.
370 Valid values are from 1 to 9, where 9 is best compression.
372 The default is 1.
374 "WorkFactor => number"
376 Specifies how much effort bzip2 should take before resorting to a
377 slower fallback compression algorithm.
378 Valid values range from 0 to 250, where 0 means use the default
380 value 30.
381 The default is 0.
383 "Strict => 0|1"
385 This is a placeholder option.
386 Examples
388 TODO
389
391 print
392 Usage is
393 $z->print($data)
395 print $z $data
396 Compresses and outputs the contents of the $data parameter. This has
398 the same behaviour as the "print" built-in.
399 Returns true if successful.
401 printf
403 Usage is
404 $z->printf($format, $data)
406 printf $z $format, $data
407 Compresses and outputs the contents of the $data parameter.
409 Returns true if successful.
411 syswrite
413 Usage is
414 $z->syswrite $data
416 $z->syswrite $data, $length
417 $z->syswrite $data, $length, $offset
418 Compresses and outputs the contents of the $data parameter.
420 Returns the number of uncompressed bytes written, or "undef" if
422 unsuccessful.
423 write
425 Usage is
426 $z->write $data
428 $z->write $data, $length
429 $z->write $data, $length, $offset
430 Compresses and outputs the contents of the $data parameter.
432 Returns the number of uncompressed bytes written, or "undef" if
434 unsuccessful.
435 flush
437 Usage is
438 $z->flush;
440 Flushes any pending compressed data to the output file/buffer.
442 TODO
444 Returns true on success.
446 tell
448 Usage is
449 $z->tell()
451 tell $z
452 Returns the uncompressed file offset.
454 eof
456 Usage is
457 $z->eof();
459 eof($z);
460 Returns true if the "close" method has been called.
462 seek
464 $z->seek($position, $whence);
465 seek($z, $position, $whence);
466 Provides a sub-set of the "seek" functionality, with the restriction
468 that it is only legal to seek forward in the output file/buffer. It is
469 a fatal error to attempt to seek backward.
470 Empty parts of the file/buffer will have NULL (0x00) bytes written to
472 them.
473 The $whence parameter takes one the usual values, namely SEEK_SET,
475 SEEK_CUR or SEEK_END.
476 Returns 1 on success, 0 on failure.
478 binmode
480 Usage is
481 $z->binmode
483 binmode $z ;
484 This is a noop provided for completeness.
486 opened
488 $z->opened()
489 Returns true if the object currently refers to a opened file/buffer.
491 autoflush
493 my $prev = $z->autoflush()
494 my $prev = $z->autoflush(EXPR)
495 If the $z object is associated with a file or a filehandle, this method
497 returns the current autoflush setting for the underlying filehandle. If
498 "EXPR" is present, and is non-zero, it will enable flushing after every
499 write/print operation.
500 If $z is associated with a buffer, this method has no effect and always
502 returns "undef".
503 Note that the special variable $| cannot be used to set or retrieve the
505 autoflush setting.
506 input_line_number
508 $z->input_line_number()
509 $z->input_line_number(EXPR)
510 This method always returns "undef" when compressing.
512 fileno
514 $z->fileno()
515 fileno($z)
516 If the $z object is associated with a file or a filehandle, "fileno"
518 will return the underlying file descriptor. Once the "close" method is
519 called "fileno" will return "undef".
520 If the $z object is associated with a buffer, this method will return
522 "undef".
523 close
525 $z->close() ;
526 close $z ;
527 Flushes any pending compressed data and then closes the output
529 file/buffer.
530 For most versions of Perl this method will be automatically invoked if
532 the IO::Compress::Bzip2 object is destroyed (either explicitly or by
533 the variable with the reference to the object going out of scope). The
534 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
535 cases, the "close" method will be called automatically, but not until
536 global destruction of all live objects when the program is terminating.
537 Therefore, if you want your scripts to be able to run on all versions
539 of Perl, you should call "close" explicitly and not rely on automatic
540 closing.
541 Returns true on success, otherwise 0.
543 If the "AutoClose" option has been enabled when the IO::Compress::Bzip2
545 object was created, and the object is associated with a file, the
546 underlying file will also be closed.
547 newStream([OPTS])
549 Usage is
550 $z->newStream( [OPTS] )
552 Closes the current compressed data stream and starts a new one.
554 OPTS consists of any of the options that are available when creating
556 the $z object.
557 See the "Constructor Options" section for more details.
559
561 No symbolic constants are required by IO::Compress::Bzip2 at present.
562 :all Imports "bzip2" and $Bzip2Error. Same as doing this
564 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
566
568 Apache::GZip Revisited
569 See IO::Compress::FAQ
570 Working with Net::FTP
572 See IO::Compress::FAQ
573
575 General feedback/questions/bug reports should be sent to
576 <https://github.com/pmqs/IO-Compress/issues> (preferred) or
577 <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress>.
578
580 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
581 IO::Compress::Deflate, IO::Uncompress::Inflate,
582 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
583 IO::Uncompress::Bunzip2, IO::Compress::Lzma, IO::Uncompress::UnLzma,
584 IO::Compress::Xz, IO::Uncompress::UnXz, IO::Compress::Lzip,
585 IO::Uncompress::UnLzip, IO::Compress::Lzop, IO::Uncompress::UnLzop,
586 IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Compress::Zstd,
587 IO::Uncompress::UnZstd, IO::Uncompress::AnyInflate,
588 IO::Uncompress::AnyUncompress
589 IO::Compress::FAQ
591 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
593 The primary site for the bzip2 program is
595 <https://sourceware.org/bzip2/>.
596 See the module Compress::Bzip2
598
600 This module was written by Paul Marquess, "pmqs@cpan.org".
601
603 See the Changes file.
604
606 Copyright (c) 2005-2023 Paul Marquess. All rights reserved.
607 This program is free software; you can redistribute it and/or modify it
609 under the same terms as Perl itself.
610perl v5.36.0 2023-02-09 IO::Compress::Bzip2(3)