1 package IO::Compress::Bzip2 ;
8 use IO::Compress::Base 2.096 ;
10 use IO::Compress::Base::Common 2.096 qw();
11 use IO::Compress::Adapter::Bzip2 2.096 ;
15 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $Bzip2Error);
20 @ISA = qw(IO::Compress::Base Exporter);
21 @EXPORT_OK = qw( $Bzip2Error bzip2 ) ;
22 %EXPORT_TAGS = %IO::Compress::Base::EXPORT_TAGS ;
23 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
24 Exporter::export_ok_tags('all');
32 my $obj = IO::Compress::Base::Common::createSelfTiedObject($class, \$Bzip2Error);
33 return $obj->_create(undef, @_);
38 my $obj = IO::Compress::Base::Common::createSelfTiedObject(undef, \$Bzip2Error);
54 use IO::Compress::Base::Common 2.096 qw(:Parse);
57 'blocksize100k' => [IO::Compress::Base::Common::Parse_unsigned, 1],
58 'workfactor' => [IO::Compress::Base::Common::Parse_unsigned, 0],
59 'verbosity' => [IO::Compress::Base::Common::Parse_boolean, 0],
70 # check that BlockSize100K is a number between 1 & 9
71 if ($got->parsed('blocksize100k')) {
72 my $value = $got->getValue('blocksize100k');
73 return $self->saveErrorString(undef, "Parameter 'BlockSize100K' not between 1 and 9, got $value")
74 unless defined $value && $value >= 1 && $value <= 9;
78 # check that WorkFactor between 0 & 250
79 if ($got->parsed('workfactor')) {
80 my $value = $got->getValue('workfactor');
81 return $self->saveErrorString(undef, "Parameter 'WorkFactor' not between 0 and 250, got $value")
82 unless $value >= 0 && $value <= 250;
94 my $BlockSize100K = $got->getValue('blocksize100k');
95 my $WorkFactor = $got->getValue('workfactor');
96 my $Verbosity = $got->getValue('verbosity');
98 my ($obj, $errstr, $errno) = IO::Compress::Adapter::Bzip2::mkCompObject(
99 $BlockSize100K, $WorkFactor,
102 return $self->saveErrorString(undef, $errstr, $errno)
128 return ('IO::Uncompress::Bunzip2');
145 IO::Compress::Bzip2 - Write bzip2 files/buffers
149 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
151 my $status = bzip2 $input => $output [,OPTS]
152 or die "bzip2 failed: $Bzip2Error\n";
154 my $z = new IO::Compress::Bzip2 $output [,OPTS]
155 or die "bzip2 failed: $Bzip2Error\n";
158 $z->printf($format, $string);
160 $z->syswrite($string [, $length, $offset]);
164 $z->seek($position, $whence);
169 $z->input_line_number();
170 $z->newStream( [OPTS] );
179 printf $z $format, $string;
182 seek $z, $position, $whence
189 This module provides a Perl interface that allows writing bzip2
190 compressed data to files or buffer.
192 For reading bzip2 files/buffers, see the companion module
193 L<IO::Uncompress::Bunzip2|IO::Uncompress::Bunzip2>.
195 =head1 Functional Interface
197 A top-level function, C<bzip2>, is provided to carry out
198 "one-shot" compression between buffers and/or files. For finer
199 control over the compression process, see the L</"OO Interface">
202 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
204 bzip2 $input_filename_or_reference => $output_filename_or_reference [,OPTS]
205 or die "bzip2 failed: $Bzip2Error\n";
207 The functional interface needs Perl5.005 or better.
209 =head2 bzip2 $input_filename_or_reference => $output_filename_or_reference [, OPTS]
211 C<bzip2> expects at least two parameters,
212 C<$input_filename_or_reference> and C<$output_filename_or_reference>
213 and zero or more optional parameters (see L</Optional Parameters>)
215 =head3 The C<$input_filename_or_reference> parameter
217 The parameter, C<$input_filename_or_reference>, is used to define the
218 source of the uncompressed data.
220 It can take one of the following forms:
226 If the C<$input_filename_or_reference> parameter is a simple scalar, it is
227 assumed to be a filename. This file will be opened for reading and the
228 input data will be read from it.
232 If the C<$input_filename_or_reference> parameter is a filehandle, the input
233 data will be read from it. The string '-' can be used as an alias for
236 =item A scalar reference
238 If C<$input_filename_or_reference> is a scalar reference, the input data
239 will be read from C<$$input_filename_or_reference>.
241 =item An array reference
243 If C<$input_filename_or_reference> is an array reference, each element in
244 the array must be a filename.
246 The input data will be read from each file in turn.
248 The complete array will be walked to ensure that it only
249 contains valid filenames before any data is compressed.
251 =item An Input FileGlob string
253 If C<$input_filename_or_reference> is a string that is delimited by the
254 characters "<" and ">" C<bzip2> will assume that it is an
255 I<input fileglob string>. The input is the list of files that match the
258 See L<File::GlobMapper|File::GlobMapper> for more details.
262 If the C<$input_filename_or_reference> parameter is any other type,
263 C<undef> will be returned.
265 =head3 The C<$output_filename_or_reference> parameter
267 The parameter C<$output_filename_or_reference> is used to control the
268 destination of the compressed data. This parameter can take one of
275 If the C<$output_filename_or_reference> parameter is a simple scalar, it is
276 assumed to be a filename. This file will be opened for writing and the
277 compressed data will be written to it.
281 If the C<$output_filename_or_reference> parameter is a filehandle, the
282 compressed data will be written to it. The string '-' can be used as
283 an alias for standard output.
285 =item A scalar reference
287 If C<$output_filename_or_reference> is a scalar reference, the
288 compressed data will be stored in C<$$output_filename_or_reference>.
290 =item An Array Reference
292 If C<$output_filename_or_reference> is an array reference,
293 the compressed data will be pushed onto the array.
295 =item An Output FileGlob
297 If C<$output_filename_or_reference> is a string that is delimited by the
298 characters "<" and ">" C<bzip2> will assume that it is an
299 I<output fileglob string>. The output is the list of files that match the
302 When C<$output_filename_or_reference> is an fileglob string,
303 C<$input_filename_or_reference> must also be a fileglob string. Anything
306 See L<File::GlobMapper|File::GlobMapper> for more details.
310 If the C<$output_filename_or_reference> parameter is any other type,
311 C<undef> will be returned.
315 When C<$input_filename_or_reference> maps to multiple files/buffers and
316 C<$output_filename_or_reference> is a single
317 file/buffer the input files/buffers will be stored
318 in C<$output_filename_or_reference> as a concatenated series of compressed data streams.
320 =head2 Optional Parameters
322 The optional parameters for the one-shot function C<bzip2>
323 are (for the most part) identical to those used with the OO interface defined in the
324 L</"Constructor Options"> section. The exceptions are listed below
328 =item C<< AutoClose => 0|1 >>
330 This option applies to any input or output data streams to
331 C<bzip2> that are filehandles.
333 If C<AutoClose> is specified, and the value is true, it will result in all
334 input and/or output filehandles being closed once C<bzip2> has
337 This parameter defaults to 0.
339 =item C<< BinModeIn => 0|1 >>
341 This option is now a no-op. All files will be read in binmode.
343 =item C<< Append => 0|1 >>
345 The behaviour of this option is dependent on the type of output data
352 If C<Append> is enabled, all compressed data will be append to the end of
353 the output buffer. Otherwise the output buffer will be cleared before any
354 compressed data is written to it.
358 If C<Append> is enabled, the file will be opened in append mode. Otherwise
359 the contents of the file, if any, will be truncated before any compressed
360 data is written to it.
364 If C<Append> is enabled, the filehandle will be positioned to the end of
365 the file via a call to C<seek> before any compressed data is
366 written to it. Otherwise the file pointer will not be moved.
370 When C<Append> is specified, and set to true, it will I<append> all compressed
371 data to the output data stream.
373 So when the output is a filehandle it will carry out a seek to the eof
374 before writing any compressed data. If the output is a filename, it will be opened for
375 appending. If the output is a buffer, all compressed data will be
376 appended to the existing buffer.
378 Conversely when C<Append> is not specified, or it is present and is set to
379 false, it will operate as follows.
381 When the output is a filename, it will truncate the contents of the file
382 before writing any compressed data. If the output is a filehandle
383 its position will not be changed. If the output is a buffer, it will be
384 wiped before any compressed data is output.
392 Here are a few example that show the capabilities of the module.
396 This very simple command line example demonstrates the streaming capabilities of the module.
397 The code reads data from STDIN, compresses it, and writes the compressed data to STDOUT.
399 $ echo hello world | perl -MIO::Compress::Bzip2=bzip2 -e 'bzip2 \*STDIN => \*STDOUT' >output.bz2
401 The special filename "-" can be used as a standin for both C<\*STDIN> and C<\*STDOUT>,
402 so the above can be rewritten as
404 $ echo hello world | perl -MIO::Compress::Bzip2=bzip2 -e 'bzip2 "-" => "-"' >output.bz2
406 =head3 Compressing a file from the filesystem
408 To read the contents of the file C<file1.txt> and write the compressed
409 data to the file C<file1.txt.bz2>.
413 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
415 my $input = "file1.txt";
416 bzip2 $input => "$input.bz2"
417 or die "bzip2 failed: $Bzip2Error\n";
419 =head3 Reading from a Filehandle and writing to an in-memory buffer
421 To read from an existing Perl filehandle, C<$input>, and write the
422 compressed data to a buffer, C<$buffer>.
426 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
429 my $input = new IO::File "<file1.txt"
430 or die "Cannot open 'file1.txt': $!\n" ;
432 bzip2 $input => \$buffer
433 or die "bzip2 failed: $Bzip2Error\n";
435 =head3 Compressing multiple files
437 To compress all files in the directory "/my/home" that match "*.txt"
438 and store the compressed data in the same directory
442 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
444 bzip2 '</my/home/*.txt>' => '<*.bz2>'
445 or die "bzip2 failed: $Bzip2Error\n";
447 and if you want to compress each file one at a time, this will do the trick
451 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
453 for my $input ( glob "/my/home/*.txt" )
455 my $output = "$input.bz2" ;
456 bzip2 $input => $output
457 or die "Error compressing '$input': $Bzip2Error\n";
464 The format of the constructor for C<IO::Compress::Bzip2> is shown below
466 my $z = new IO::Compress::Bzip2 $output [,OPTS]
467 or die "IO::Compress::Bzip2 failed: $Bzip2Error\n";
469 It returns an C<IO::Compress::Bzip2> object on success and undef on failure.
470 The variable C<$Bzip2Error> will contain an error message on failure.
472 If you are running Perl 5.005 or better the object, C<$z>, returned from
473 IO::Compress::Bzip2 can be used exactly like an L<IO::File|IO::File> filehandle.
474 This means that all normal output file operations can be carried out
476 For example, to write to a compressed file/buffer you can use either of
479 $z->print("hello world\n");
480 print $z "hello world\n";
482 The mandatory parameter C<$output> is used to control the destination
483 of the compressed data. This parameter can take one of these forms.
489 If the C<$output> parameter is a simple scalar, it is assumed to be a
490 filename. This file will be opened for writing and the compressed data
491 will be written to it.
495 If the C<$output> parameter is a filehandle, the compressed data will be
497 The string '-' can be used as an alias for standard output.
499 =item A scalar reference
501 If C<$output> is a scalar reference, the compressed data will be stored
506 If the C<$output> parameter is any other type, C<IO::Compress::Bzip2>::new will
509 =head2 Constructor Options
511 C<OPTS> is any combination of zero or more the following options:
515 =item C<< AutoClose => 0|1 >>
517 This option is only valid when the C<$output> parameter is a filehandle. If
518 specified, and the value is true, it will result in the C<$output> being
519 closed once either the C<close> method is called or the C<IO::Compress::Bzip2>
522 This parameter defaults to 0.
524 =item C<< Append => 0|1 >>
526 Opens C<$output> in append mode.
528 The behaviour of this option is dependent on the type of C<$output>.
534 If C<$output> is a buffer and C<Append> is enabled, all compressed data
535 will be append to the end of C<$output>. Otherwise C<$output> will be
536 cleared before any data is written to it.
540 If C<$output> is a filename and C<Append> is enabled, the file will be
541 opened in append mode. Otherwise the contents of the file, if any, will be
542 truncated before any compressed data is written to it.
546 If C<$output> is a filehandle, the file pointer will be positioned to the
547 end of the file via a call to C<seek> before any compressed data is written
548 to it. Otherwise the file pointer will not be moved.
552 This parameter defaults to 0.
554 =item C<< BlockSize100K => number >>
556 Specify the number of 100K blocks bzip2 uses during compression.
558 Valid values are from 1 to 9, where 9 is best compression.
562 =item C<< WorkFactor => number >>
564 Specifies how much effort bzip2 should take before resorting to a slower
565 fallback compression algorithm.
567 Valid values range from 0 to 250, where 0 means use the default value 30.
571 =item C<< Strict => 0|1 >>
573 This is a placeholder option.
590 Compresses and outputs the contents of the C<$data> parameter. This
591 has the same behaviour as the C<print> built-in.
593 Returns true if successful.
599 $z->printf($format, $data)
600 printf $z $format, $data
602 Compresses and outputs the contents of the C<$data> parameter.
604 Returns true if successful.
611 $z->syswrite $data, $length
612 $z->syswrite $data, $length, $offset
614 Compresses and outputs the contents of the C<$data> parameter.
616 Returns the number of uncompressed bytes written, or C<undef> if
624 $z->write $data, $length
625 $z->write $data, $length, $offset
627 Compresses and outputs the contents of the C<$data> parameter.
629 Returns the number of uncompressed bytes written, or C<undef> if
638 Flushes any pending compressed data to the output file/buffer.
642 Returns true on success.
651 Returns the uncompressed file offset.
660 Returns true if the C<close> method has been called.
664 $z->seek($position, $whence);
665 seek($z, $position, $whence);
667 Provides a sub-set of the C<seek> functionality, with the restriction
668 that it is only legal to seek forward in the output file/buffer.
669 It is a fatal error to attempt to seek backward.
671 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
673 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
674 SEEK_CUR or SEEK_END.
676 Returns 1 on success, 0 on failure.
685 This is a noop provided for completeness.
691 Returns true if the object currently refers to a opened file/buffer.
695 my $prev = $z->autoflush()
696 my $prev = $z->autoflush(EXPR)
698 If the C<$z> object is associated with a file or a filehandle, this method
699 returns the current autoflush setting for the underlying filehandle. If
700 C<EXPR> is present, and is non-zero, it will enable flushing after every
701 write/print operation.
703 If C<$z> is associated with a buffer, this method has no effect and always
706 B<Note> that the special variable C<$|> B<cannot> be used to set or
707 retrieve the autoflush setting.
709 =head2 input_line_number
711 $z->input_line_number()
712 $z->input_line_number(EXPR)
714 This method always returns C<undef> when compressing.
721 If the C<$z> object is associated with a file or a filehandle, C<fileno>
722 will return the underlying file descriptor. Once the C<close> method is
723 called C<fileno> will return C<undef>.
725 If the C<$z> object is associated with a buffer, this method will return
733 Flushes any pending compressed data and then closes the output file/buffer.
735 For most versions of Perl this method will be automatically invoked if
736 the IO::Compress::Bzip2 object is destroyed (either explicitly or by the
737 variable with the reference to the object going out of scope). The
738 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
739 these cases, the C<close> method will be called automatically, but
740 not until global destruction of all live objects when the program is
743 Therefore, if you want your scripts to be able to run on all versions
744 of Perl, you should call C<close> explicitly and not rely on automatic
747 Returns true on success, otherwise 0.
749 If the C<AutoClose> option has been enabled when the IO::Compress::Bzip2
750 object was created, and the object is associated with a file, the
751 underlying file will also be closed.
753 =head2 newStream([OPTS])
757 $z->newStream( [OPTS] )
759 Closes the current compressed data stream and starts a new one.
761 OPTS consists of any of the options that are available when creating
764 See the L</"Constructor Options"> section for more details.
768 No symbolic constants are required by IO::Compress::Bzip2 at present.
774 Imports C<bzip2> and C<$Bzip2Error>.
777 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
783 =head2 Apache::GZip Revisited
785 See L<IO::Compress::FAQ|IO::Compress::FAQ/"Apache::GZip Revisited">
787 =head2 Working with Net::FTP
789 See L<IO::Compress::FAQ|IO::Compress::FAQ/"Compressed files and Net::FTP">
793 General feedback/questions/bug reports should be sent to
794 L<https://github.com/pmqs/IO-Compress/issues> (preferred) or
795 L<https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress>.
799 L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzma>, L<IO::Uncompress::UnLzma>, L<IO::Compress::Xz>, L<IO::Uncompress::UnXz>, L<IO::Compress::Lzip>, L<IO::Uncompress::UnLzip>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Compress::Zstd>, L<IO::Uncompress::UnZstd>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
801 L<IO::Compress::FAQ|IO::Compress::FAQ>
803 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
804 L<Archive::Tar|Archive::Tar>,
807 The primary site for the bzip2 program is L<https://sourceware.org/bzip2/>.
809 See the module L<Compress::Bzip2|Compress::Bzip2>
813 This module was written by Paul Marquess, C<pmqs@cpan.org>.
815 =head1 MODIFICATION HISTORY
817 See the Changes file.
819 =head1 COPYRIGHT AND LICENSE
821 Copyright (c) 2005-2020 Paul Marquess. All rights reserved.
823 This program is free software; you can redistribute it and/or
824 modify it under the same terms as Perl itself.