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 = new IO::Compress::Bzip2 $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.
70
71       The $input_filename_or_reference parameter
72
73       The parameter, $input_filename_or_reference, is used to define the
74       source of the uncompressed data.
75
76       It can take one of the following forms:
77
78       A filename
79            If the <$input_filename_or_reference> parameter is a simple
80            scalar, it is assumed to be a filename. This file will be opened
81            for reading and the input data will be read from it.
82
83       A filehandle
84            If the $input_filename_or_reference parameter is a filehandle, the
85            input data will be read from it.  The string '-' can be used as an
86            alias for standard input.
87
88       A scalar reference
89            If $input_filename_or_reference is a scalar reference, the input
90            data will be read from $$input_filename_or_reference.
91
92       An array reference
93            If $input_filename_or_reference is an array reference, each
94            element in the array must be a filename.
95
96            The input data will be read from each file in turn.
97
98            The complete array will be walked to ensure that it only contains
99            valid filenames before any data is compressed.
100
101       An Input FileGlob string
102            If $input_filename_or_reference is a string that is delimited by
103            the characters "<" and ">" "bzip2" will assume that it is an input
104            fileglob string. The input is the list of files that match the
105            fileglob.
106
107            See File::GlobMapper for more details.
108
109       If the $input_filename_or_reference parameter is any other type,
110       "undef" will be returned.
111
112       The $output_filename_or_reference parameter
113
114       The parameter $output_filename_or_reference is used to control the
115       destination of the compressed data. This parameter can take one of
116       these forms.
117
118       A filename
119            If the $output_filename_or_reference parameter is a simple scalar,
120            it is assumed to be a filename.  This file will be opened for
121            writing and the compressed data will be written to it.
122
123       A filehandle
124            If the $output_filename_or_reference parameter is a filehandle,
125            the compressed data will be written to it.  The string '-' can be
126            used as an alias for standard output.
127
128       A scalar reference
129            If $output_filename_or_reference is a scalar reference, the
130            compressed data will be stored in $$output_filename_or_reference.
131
132       An Array Reference
133            If $output_filename_or_reference is an array reference, the
134            compressed data will be pushed onto the array.
135
136       An Output FileGlob
137            If $output_filename_or_reference is a string that is delimited by
138            the characters "<" and ">" "bzip2" will assume that it is an
139            output fileglob string. The output is the list of files that match
140            the fileglob.
141
142            When $output_filename_or_reference is an fileglob string,
143            $input_filename_or_reference must also be a fileglob string.
144            Anything else is an error.
145
146            See File::GlobMapper for more details.
147
148       If the $output_filename_or_reference parameter is any other type,
149       "undef" will be returned.
150
151   Notes
152       When $input_filename_or_reference maps to multiple files/buffers and
153       $output_filename_or_reference is a single file/buffer the input
154       files/buffers will be stored in $output_filename_or_reference as a
155       concatenated series of compressed data streams.
156
157   Optional Parameters
158       Unless specified below, the optional parameters for "bzip2", "OPTS",
159       are the same as those used with the OO interface defined in the
160       "Constructor Options" section below.
161
162       "AutoClose => 0|1"
163            This option applies to any input or output data streams to "bzip2"
164            that are filehandles.
165
166            If "AutoClose" is specified, and the value is true, it will result
167            in all input and/or output filehandles being closed once "bzip2"
168            has completed.
169
170            This parameter defaults to 0.
171
172       "BinModeIn => 0|1"
173            When reading from a file or filehandle, set "binmode" before
174            reading.
175
176            Defaults to 0.
177
178       "Append => 0|1"
179            The behaviour of this option is dependent on the type of output
180            data stream.
181
182            ·    A Buffer
183
184                 If "Append" is enabled, all compressed data will be append to
185                 the end of the output buffer. Otherwise the output buffer
186                 will be cleared before any compressed data is written to it.
187
188            ·    A Filename
189
190                 If "Append" is enabled, the file will be opened in append
191                 mode. Otherwise the contents of the file, if any, will be
192                 truncated before any compressed data is written to it.
193
194            ·    A Filehandle
195
196                 If "Append" is enabled, the filehandle will be positioned to
197                 the end of the file via a call to "seek" before any
198                 compressed data is written to it.  Otherwise the file pointer
199                 will not be moved.
200
201            When "Append" is specified, and set to true, it will append all
202            compressed data to the output data stream.
203
204            So when the output is a filehandle it will carry out a seek to the
205            eof before writing any compressed data. If the output is a
206            filename, it will be opened for appending. If the output is a
207            buffer, all compressed data will be appended to the existing
208            buffer.
209
210            Conversely when "Append" is not specified, or it is present and is
211            set to false, it will operate as follows.
212
213            When the output is a filename, it will truncate the contents of
214            the file before writing any compressed data. If the output is a
215            filehandle its position will not be changed. If the output is a
216            buffer, it will be wiped before any compressed data is output.
217
218            Defaults to 0.
219
220   Examples
221       To read the contents of the file "file1.txt" and write the compressed
222       data to the file "file1.txt.bz2".
223
224           use strict ;
225           use warnings ;
226           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
227
228           my $input = "file1.txt";
229           bzip2 $input => "$input.bz2"
230               or die "bzip2 failed: $Bzip2Error\n";
231
232       To read from an existing Perl filehandle, $input, and write the
233       compressed data to a buffer, $buffer.
234
235           use strict ;
236           use warnings ;
237           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
238           use IO::File ;
239
240           my $input = new IO::File "<file1.txt"
241               or die "Cannot open 'file1.txt': $!\n" ;
242           my $buffer ;
243           bzip2 $input => \$buffer
244               or die "bzip2 failed: $Bzip2Error\n";
245
246       To compress all files in the directory "/my/home" that match "*.txt"
247       and store the compressed data in the same directory
248
249           use strict ;
250           use warnings ;
251           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
252
253           bzip2 '</my/home/*.txt>' => '<*.bz2>'
254               or die "bzip2 failed: $Bzip2Error\n";
255
256       and if you want to compress each file one at a time, this will do the
257       trick
258
259           use strict ;
260           use warnings ;
261           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
262
263           for my $input ( glob "/my/home/*.txt" )
264           {
265               my $output = "$input.bz2" ;
266               bzip2 $input => $output
267                   or die "Error compressing '$input': $Bzip2Error\n";
268           }
269

OO Interface

271   Constructor
272       The format of the constructor for "IO::Compress::Bzip2" is shown below
273
274           my $z = new IO::Compress::Bzip2 $output [,OPTS]
275               or die "IO::Compress::Bzip2 failed: $Bzip2Error\n";
276
277       It returns an "IO::Compress::Bzip2" object on success and undef on
278       failure.  The variable $Bzip2Error will contain an error message on
279       failure.
280
281       If you are running Perl 5.005 or better the object, $z, returned from
282       IO::Compress::Bzip2 can be used exactly like an IO::File filehandle.
283       This means that all normal output file operations can be carried out
284       with $z.  For example, to write to a compressed file/buffer you can use
285       either of these forms
286
287           $z->print("hello world\n");
288           print $z "hello world\n";
289
290       The mandatory parameter $output is used to control the destination of
291       the compressed data. This parameter can take one of these forms.
292
293       A filename
294            If the $output parameter is a simple scalar, it is assumed to be a
295            filename. This file will be opened for writing and the compressed
296            data will be written to it.
297
298       A filehandle
299            If the $output parameter is a filehandle, the compressed data will
300            be written to it.  The string '-' can be used as an alias for
301            standard output.
302
303       A scalar reference
304            If $output is a scalar reference, the compressed data will be
305            stored in $$output.
306
307       If the $output parameter is any other type, "IO::Compress::Bzip2"::new
308       will return undef.
309
310   Constructor Options
311       "OPTS" is any combination of the following options:
312
313       "AutoClose => 0|1"
314            This option is only valid when the $output parameter is a
315            filehandle. If specified, and the value is true, it will result in
316            the $output being closed once either the "close" method is called
317            or the "IO::Compress::Bzip2" object is destroyed.
318
319            This parameter defaults to 0.
320
321       "Append => 0|1"
322            Opens $output in append mode.
323
324            The behaviour of this option is dependent on the type of $output.
325
326            ·    A Buffer
327
328                 If $output is a buffer and "Append" is enabled, all
329                 compressed data will be append to the end of $output.
330                 Otherwise $output will be cleared before any data is written
331                 to it.
332
333            ·    A Filename
334
335                 If $output is a filename and "Append" is enabled, the file
336                 will be opened in append mode. Otherwise the contents of the
337                 file, if any, will be truncated before any compressed data is
338                 written to it.
339
340            ·    A Filehandle
341
342                 If $output is a filehandle, the file pointer will be
343                 positioned to the end of the file via a call to "seek" before
344                 any compressed data is written to it.  Otherwise the file
345                 pointer will not be moved.
346
347            This parameter defaults to 0.
348
349       "BlockSize100K => number"
350            Specify the number of 100K blocks bzip2 uses during compression.
351
352            Valid values are from 1 to 9, where 9 is best compression.
353
354            The default is 1.
355
356       "WorkFactor => number"
357            Specifies how much effort bzip2 should take before resorting to a
358            slower fallback compression algorithm.
359
360            Valid values range from 0 to 250, where 0 means use the default
361            value 30.
362
363            The default is 0.
364
365       "Strict => 0|1"
366            This is a placeholder option.
367
368   Examples
369       TODO
370

Methods

372   print
373       Usage is
374
375           $z->print($data)
376           print $z $data
377
378       Compresses and outputs the contents of the $data parameter. This has
379       the same behaviour as the "print" built-in.
380
381       Returns true if successful.
382
383   printf
384       Usage is
385
386           $z->printf($format, $data)
387           printf $z $format, $data
388
389       Compresses and outputs the contents of the $data parameter.
390
391       Returns true if successful.
392
393   syswrite
394       Usage is
395
396           $z->syswrite $data
397           $z->syswrite $data, $length
398           $z->syswrite $data, $length, $offset
399
400       Compresses and outputs the contents of the $data parameter.
401
402       Returns the number of uncompressed bytes written, or "undef" if
403       unsuccessful.
404
405   write
406       Usage is
407
408           $z->write $data
409           $z->write $data, $length
410           $z->write $data, $length, $offset
411
412       Compresses and outputs the contents of the $data parameter.
413
414       Returns the number of uncompressed bytes written, or "undef" if
415       unsuccessful.
416
417   flush
418       Usage is
419
420           $z->flush;
421
422       Flushes any pending compressed data to the output file/buffer.
423
424       TODO
425
426       Returns true on success.
427
428   tell
429       Usage is
430
431           $z->tell()
432           tell $z
433
434       Returns the uncompressed file offset.
435
436   eof
437       Usage is
438
439           $z->eof();
440           eof($z);
441
442       Returns true if the "close" method has been called.
443
444   seek
445           $z->seek($position, $whence);
446           seek($z, $position, $whence);
447
448       Provides a sub-set of the "seek" functionality, with the restriction
449       that it is only legal to seek forward in the output file/buffer.  It is
450       a fatal error to attempt to seek backward.
451
452       Empty parts of the file/buffer will have NULL (0x00) bytes written to
453       them.
454
455       The $whence parameter takes one the usual values, namely SEEK_SET,
456       SEEK_CUR or SEEK_END.
457
458       Returns 1 on success, 0 on failure.
459
460   binmode
461       Usage is
462
463           $z->binmode
464           binmode $z ;
465
466       This is a noop provided for completeness.
467
468   opened
469           $z->opened()
470
471       Returns true if the object currently refers to a opened file/buffer.
472
473   autoflush
474           my $prev = $z->autoflush()
475           my $prev = $z->autoflush(EXPR)
476
477       If the $z object is associated with a file or a filehandle, this method
478       returns the current autoflush setting for the underlying filehandle. If
479       "EXPR" is present, and is non-zero, it will enable flushing after every
480       write/print operation.
481
482       If $z is associated with a buffer, this method has no effect and always
483       returns "undef".
484
485       Note that the special variable $| cannot be used to set or retrieve the
486       autoflush setting.
487
488   input_line_number
489           $z->input_line_number()
490           $z->input_line_number(EXPR)
491
492       This method always returns "undef" when compressing.
493
494   fileno
495           $z->fileno()
496           fileno($z)
497
498       If the $z object is associated with a file or a filehandle, "fileno"
499       will return the underlying file descriptor. Once the "close" method is
500       called "fileno" will return "undef".
501
502       If the $z object is associated with a buffer, this method will return
503       "undef".
504
505   close
506           $z->close() ;
507           close $z ;
508
509       Flushes any pending compressed data and then closes the output
510       file/buffer.
511
512       For most versions of Perl this method will be automatically invoked if
513       the IO::Compress::Bzip2 object is destroyed (either explicitly or by
514       the variable with the reference to the object going out of scope). The
515       exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
516       cases, the "close" method will be called automatically, but not until
517       global destruction of all live objects when the program is terminating.
518
519       Therefore, if you want your scripts to be able to run on all versions
520       of Perl, you should call "close" explicitly and not rely on automatic
521       closing.
522
523       Returns true on success, otherwise 0.
524
525       If the "AutoClose" option has been enabled when the IO::Compress::Bzip2
526       object was created, and the object is associated with a file, the
527       underlying file will also be closed.
528
529   newStream([OPTS])
530       Usage is
531
532           $z->newStream( [OPTS] )
533
534       Closes the current compressed data stream and starts a new one.
535
536       OPTS consists of any of the options that are available when creating
537       the $z object.
538
539       See the "Constructor Options" section for more details.
540

Importing

542       No symbolic constants are required by this IO::Compress::Bzip2 at
543       present.
544
545       :all Imports "bzip2" and $Bzip2Error.  Same as doing this
546
547                use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
548

EXAMPLES

550   Apache::GZip Revisited
551       See IO::Compress::FAQ
552
553   Working with Net::FTP
554       See IO::Compress::FAQ
555

SEE ALSO

557       Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
558       IO::Compress::Deflate, IO::Uncompress::Inflate,
559       IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
560       IO::Uncompress::Bunzip2, IO::Compress::Lzma, IO::Uncompress::UnLzma,
561       IO::Compress::Xz, IO::Uncompress::UnXz, IO::Compress::Lzop,
562       IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf,
563       IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress
564
565       IO::Compress::FAQ
566
567       File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
568
569       The primary site for the bzip2 program is <http://www.bzip.org>.
570
571       See the module Compress::Bzip2
572

AUTHOR

574       This module was written by Paul Marquess, "pmqs@cpan.org".
575

MODIFICATION HISTORY

577       See the Changes file.
578
580       Copyright (c) 2005-2018 Paul Marquess. All rights reserved.
581
582       This program is free software; you can redistribute it and/or modify it
583       under the same terms as Perl itself.
584
585
586
587perl v5.28.0                      2018-04-05            IO::Compress::Bzip2(3)
Impressum