IO::Compress::Bzip2(3pm)

1IO::Compress::Bzip2(3)User Contributed Perl DocumentationIO::Compress::Bzip2(3)
2
3
4

NAME

6       IO::Compress::Bzip2 - Write bzip2 files/buffers
7

SYNOPSIS

9           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
10
11           my $status = bzip2 $input => $output [,OPTS]
12               or die "bzip2 failed: $Bzip2Error\n";
13
14           my $z = IO::Compress::Bzip2->new( $output [,OPTS] )
15               or die "bzip2 failed: $Bzip2Error\n";
16
17           $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
32           $z->close() ;
33
34           $Bzip2Error ;
35
36           # IO::File mode
37
38           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

DESCRIPTION

48       This module provides a Perl interface that allows writing bzip2
49       compressed data to files or buffer.
50
51       For reading bzip2 files/buffers, see the companion module
52       IO::Uncompress::Bunzip2.
53

Functional Interface

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
59           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
60
61           bzip2 $input_filename_or_reference => $output_filename_or_reference [,OPTS]
62               or die "bzip2 failed: $Bzip2Error\n";
63
64       The functional interface needs Perl5.005 or better.
65
66   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
72       The $input_filename_or_reference parameter
73
74       The parameter, $input_filename_or_reference, is used to define the
75       source of the uncompressed data.
76
77       It can take one of the following forms:
78
79       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
84       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
89       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
93       An array reference
94            If $input_filename_or_reference is an array reference, each
95            element in the array must be a filename.
96
97            The input data will be read from each file in turn.
98
99            The complete array will be walked to ensure that it only contains
100            valid filenames before any data is compressed.
101
102       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
108            See File::GlobMapper for more details.
109
110       If the $input_filename_or_reference parameter is any other type,
111       "undef" will be returned.
112
113       The $output_filename_or_reference parameter
114
115       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
119       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
124       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
129       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
133       An Array Reference
134            If $output_filename_or_reference is an array reference, the
135            compressed data will be pushed onto the array.
136
137       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
143            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
147            See File::GlobMapper for more details.
148
149       If the $output_filename_or_reference parameter is any other type,
150       "undef" will be returned.
151
152   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
158   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
163       "AutoClose => 0|1"
164            This option applies to any input or output data streams to "bzip2"
165            that are filehandles.
166
167            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
171            This parameter defaults to 0.
172
173       "BinModeIn => 0|1"
174            This option is now a no-op. All files will be read in binmode.
175
176       "Append => 0|1"
177            The behaviour of this option is dependent on the type of output
178            data stream.
179
180            •    A Buffer
181
182                 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
186            •    A Filename
187
188                 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
192            •    A Filehandle
193
194                 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
199            When "Append" is specified, and set to true, it will append all
200            compressed data to the output data stream.
201
202            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
208            Conversely when "Append" is not specified, or it is present and is
209            set to false, it will operate as follows.
210
211            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
216            Defaults to 0.
217
218   Oneshot Examples
219       Here are a few example that show the capabilities of the module.
220
221       Streaming
222
223       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
227           $ echo hello world | perl -MIO::Compress::Bzip2=bzip2 -e 'bzip2 \*STDIN => \*STDOUT' >output.bz2
228
229       The special filename "-" can be used as a standin for both "\*STDIN"
230       and "\*STDOUT", so the above can be rewritten as
231
232           $ echo hello world | perl -MIO::Compress::Bzip2=bzip2 -e 'bzip2 "-" => "-"' >output.bz2
233
234       Compressing a file from the filesystem
235
236       To read the contents of the file "file1.txt" and write the compressed
237       data to the file "file1.txt.bz2".
238
239           use strict ;
240           use warnings ;
241           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
242
243           my $input = "file1.txt";
244           bzip2 $input => "$input.bz2"
245               or die "bzip2 failed: $Bzip2Error\n";
246
247       Reading from a Filehandle and writing to an in-memory buffer
248
249       To read from an existing Perl filehandle, $input, and write the
250       compressed data to a buffer, $buffer.
251
252           use strict ;
253           use warnings ;
254           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
255           use IO::File ;
256
257           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
263       Compressing multiple files
264
265       To compress all files in the directory "/my/home" that match "*.txt"
266       and store the compressed data in the same directory
267
268           use strict ;
269           use warnings ;
270           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
271
272           bzip2 '</my/home/*.txt>' => '<*.bz2>'
273               or die "bzip2 failed: $Bzip2Error\n";
274
275       and if you want to compress each file one at a time, this will do the
276       trick
277
278           use strict ;
279           use warnings ;
280           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
281
282           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

OO Interface

290   Constructor
291       The format of the constructor for "IO::Compress::Bzip2" is shown below
292
293           my $z = IO::Compress::Bzip2->new( $output [,OPTS] )
294               or die "IO::Compress::Bzip2 failed: $Bzip2Error\n";
295
296       The constructor takes one mandatory parameter, $output, defined below
297       and zero or more "OPTS", defined in "Constructor Options".
298
299       It returns an "IO::Compress::Bzip2" object on success and "undef" on
300       failure.  The variable $Bzip2Error will contain an error message on
301       failure.
302
303       If you are running Perl 5.005 or better the object, $z, returned from
304       IO::Compress::Bzip2 can be used exactly like an IO::File filehandle.
305       This means that all normal output file operations can be carried out
306       with $z.  For example, to write to a compressed file/buffer you can use
307       either of these forms
308
309           $z->print("hello world\n");
310           print $z "hello world\n";
311
312       Below is a simple exaple of using the OO interface to create an output
313       file "myfile.bz2" and write some data to it.
314
315           my $filename = "myfile.bz2";
316           my $z = IO::Compress::Bzip2->new($filename)
317               or die "IO::Compress::Bzip2 failed: $Bzip2Error\n";
318
319           $z->print("abcde");
320           $z->close();
321
322       See the "Examples" for more.
323
324       The mandatory parameter $output is used to control the destination of
325       the compressed data. This parameter can take one of these forms.
326
327       A filename
328            If the $output parameter is a simple scalar, it is assumed to be a
329            filename. This file will be opened for writing and the compressed
330            data will be written to it.
331
332       A filehandle
333            If the $output parameter is a filehandle, the compressed data will
334            be written to it.  The string '-' can be used as an alias for
335            standard output.
336
337       A scalar reference
338            If $output is a scalar reference, the compressed data will be
339            stored in $$output.
340
341       If the $output parameter is any other type, "IO::Compress::Bzip2"::new
342       will return undef.
343
344   Constructor Options
345       "OPTS" is any combination of zero or more the following options:
346
347       "AutoClose => 0|1"
348            This option is only valid when the $output parameter is a
349            filehandle. If specified, and the value is true, it will result in
350            the $output being closed once either the "close" method is called
351            or the "IO::Compress::Bzip2" object is destroyed.
352
353            This parameter defaults to 0.
354
355       "Append => 0|1"
356            Opens $output in append mode.
357
358            The behaviour of this option is dependent on the type of $output.
359
360            •    A Buffer
361
362                 If $output is a buffer and "Append" is enabled, all
363                 compressed data will be append to the end of $output.
364                 Otherwise $output will be cleared before any data is written
365                 to it.
366
367            •    A Filename
368
369                 If $output is a filename and "Append" is enabled, the file
370                 will be opened in append mode. Otherwise the contents of the
371                 file, if any, will be truncated before any compressed data is
372                 written to it.
373
374            •    A Filehandle
375
376                 If $output is a filehandle, the file pointer will be
377                 positioned to the end of the file via a call to "seek" before
378                 any compressed data is written to it.  Otherwise the file
379                 pointer will not be moved.
380
381            This parameter defaults to 0.
382
383       "BlockSize100K => number"
384            Specify the number of 100K blocks bzip2 uses during compression.
385
386            Valid values are from 1 to 9, where 9 is best compression.
387
388            The default is 1.
389
390       "WorkFactor => number"
391            Specifies how much effort bzip2 should take before resorting to a
392            slower fallback compression algorithm.
393
394            Valid values range from 0 to 250, where 0 means use the default
395            value 30.
396
397            The default is 0.
398
399       "Strict => 0|1"
400            This is a placeholder option.
401
402   Examples
403       Streaming
404
405       This very simple command line example demonstrates the streaming
406       capabilities of the module. The code reads data from STDIN or all the
407       files given on the commandline, compresses it, and writes the
408       compressed data to STDOUT.
409
410           use strict ;
411           use warnings ;
412           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
413
414           my $z = IO::Compress::Bzip2->new("-", Stream => 1)
415               or die "IO::Compress::Bzip2 failed: $Bzip2Error\n";
416
417           while (<>) {
418               $z->print("abcde");
419           }
420           $z->close();
421
422       Note the use of "-" to means "STDOUT". Alternatively you can use
423       "\*STDOUT".
424
425       Compressing a file from the filesystem
426
427       To read the contents of the file "file1.txt" and write the compressed
428       data to the file "file1.txt.bz2" there are a few options
429
430       Start by creating the compression object and opening the input file
431
432           use strict ;
433           use warnings ;
434           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
435
436           my $input = "file1.txt";
437           my $z = IO::Compress::Bzip2->new("file1.txt.bz2")
438               or die "IO::Compress::Bzip2 failed: $Bzip2Error\n";
439
440           # open the input file
441           open my $fh, "<", "file1.txt"
442               or die "Cannot open file1.txt: $!\n";
443
444           # loop through the input file & write to the compressed file
445           while (<$fh>) {
446               $z->print($_);
447           }
448
449           # not forgetting to close the compressed file
450           $z->close();
451

Methods

453   print
454       Usage is
455
456           $z->print($data)
457           print $z $data
458
459       Compresses and outputs the contents of the $data parameter. This has
460       the same behaviour as the "print" built-in.
461
462       Returns true if successful.
463
464   printf
465       Usage is
466
467           $z->printf($format, $data)
468           printf $z $format, $data
469
470       Compresses and outputs the contents of the $data parameter.
471
472       Returns true if successful.
473
474   syswrite
475       Usage is
476
477           $z->syswrite $data
478           $z->syswrite $data, $length
479           $z->syswrite $data, $length, $offset
480
481       Compresses and outputs the contents of the $data parameter.
482
483       Returns the number of uncompressed bytes written, or "undef" if
484       unsuccessful.
485
486   write
487       Usage is
488
489           $z->write $data
490           $z->write $data, $length
491           $z->write $data, $length, $offset
492
493       Compresses and outputs the contents of the $data parameter.
494
495       Returns the number of uncompressed bytes written, or "undef" if
496       unsuccessful.
497
498   flush
499       Usage is
500
501           $z->flush;
502
503       Flushes any pending compressed data to the output file/buffer.
504
505       TODO
506
507       Returns true on success.
508
509   tell
510       Usage is
511
512           $z->tell()
513           tell $z
514
515       Returns the uncompressed file offset.
516
517   eof
518       Usage is
519
520           $z->eof();
521           eof($z);
522
523       Returns true if the "close" method has been called.
524
525   seek
526           $z->seek($position, $whence);
527           seek($z, $position, $whence);
528
529       Provides a sub-set of the "seek" functionality, with the restriction
530       that it is only legal to seek forward in the output file/buffer.  It is
531       a fatal error to attempt to seek backward.
532
533       Empty parts of the file/buffer will have NULL (0x00) bytes written to
534       them.
535
536       The $whence parameter takes one the usual values, namely SEEK_SET,
537       SEEK_CUR or SEEK_END.
538
539       Returns 1 on success, 0 on failure.
540
541   binmode
542       Usage is
543
544           $z->binmode
545           binmode $z ;
546
547       This is a noop provided for completeness.
548
549   opened
550           $z->opened()
551
552       Returns true if the object currently refers to a opened file/buffer.
553
554   autoflush
555           my $prev = $z->autoflush()
556           my $prev = $z->autoflush(EXPR)
557
558       If the $z object is associated with a file or a filehandle, this method
559       returns the current autoflush setting for the underlying filehandle. If
560       "EXPR" is present, and is non-zero, it will enable flushing after every
561       write/print operation.
562
563       If $z is associated with a buffer, this method has no effect and always
564       returns "undef".
565
566       Note that the special variable $| cannot be used to set or retrieve the
567       autoflush setting.
568
569   input_line_number
570           $z->input_line_number()
571           $z->input_line_number(EXPR)
572
573       This method always returns "undef" when compressing.
574
575   fileno
576           $z->fileno()
577           fileno($z)
578
579       If the $z object is associated with a file or a filehandle, "fileno"
580       will return the underlying file descriptor. Once the "close" method is
581       called "fileno" will return "undef".
582
583       If the $z object is associated with a buffer, this method will return
584       "undef".
585
586   close
587           $z->close() ;
588           close $z ;
589
590       Flushes any pending compressed data and then closes the output
591       file/buffer.
592
593       For most versions of Perl this method will be automatically invoked if
594       the IO::Compress::Bzip2 object is destroyed (either explicitly or by
595       the variable with the reference to the object going out of scope). The
596       exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
597       cases, the "close" method will be called automatically, but not until
598       global destruction of all live objects when the program is terminating.
599
600       Therefore, if you want your scripts to be able to run on all versions
601       of Perl, you should call "close" explicitly and not rely on automatic
602       closing.
603
604       Returns true on success, otherwise 0.
605
606       If the "AutoClose" option has been enabled when the IO::Compress::Bzip2
607       object was created, and the object is associated with a file, the
608       underlying file will also be closed.
609
610   newStream([OPTS])
611       Usage is
612
613           $z->newStream( [OPTS] )
614
615       Closes the current compressed data stream and starts a new one.
616
617       OPTS consists of any of the options that are available when creating
618       the $z object.
619
620       See the "Constructor Options" section for more details.
621

Importing

623       No symbolic constants are required by IO::Compress::Bzip2 at present.
624
625       :all Imports "bzip2" and $Bzip2Error.  Same as doing this
626
627                use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
628

EXAMPLES

630   Apache::GZip Revisited
631       See IO::Compress::FAQ
632
633   Working with Net::FTP
634       See IO::Compress::FAQ
635

SUPPORT

637       General feedback/questions/bug reports should be sent to
638       <https://github.com/pmqs/IO-Compress/issues> (preferred) or
639       <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress>.
640

AUTHOR

662       This module was written by Paul Marquess, "pmqs@cpan.org".
663

MODIFICATION HISTORY

665       See the Changes file.
666

COPYRIGHT AND LICENSE

668       Copyright (c) 2005-2023 Paul Marquess. All rights reserved.
669
670       This program is free software; you can redistribute it and/or modify it
671       under the same terms as Perl itself.
672
673
674
675perl v5.38.0                      2023-07-26            IO::Compress::Bzip2(3)