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 = 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            This option is now a no-op. All files will be read in binmode.
174
175       "Append => 0|1"
176            The behaviour of this option is dependent on the type of output
177            data stream.
178
179            ·    A Buffer
180
181                 If "Append" is enabled, all compressed data will be append to
182                 the end of the output buffer. Otherwise the output buffer
183                 will be cleared before any compressed data is written to it.
184
185            ·    A Filename
186
187                 If "Append" is enabled, the file will be opened in append
188                 mode. Otherwise the contents of the file, if any, will be
189                 truncated before any compressed data is written to it.
190
191            ·    A Filehandle
192
193                 If "Append" is enabled, the filehandle will be positioned to
194                 the end of the file via a call to "seek" before any
195                 compressed data is written to it.  Otherwise the file pointer
196                 will not be moved.
197
198            When "Append" is specified, and set to true, it will append all
199            compressed data to the output data stream.
200
201            So when the output is a filehandle it will carry out a seek to the
202            eof before writing any compressed data. If the output is a
203            filename, it will be opened for appending. If the output is a
204            buffer, all compressed data will be appended to the existing
205            buffer.
206
207            Conversely when "Append" is not specified, or it is present and is
208            set to false, it will operate as follows.
209
210            When the output is a filename, it will truncate the contents of
211            the file before writing any compressed data. If the output is a
212            filehandle its position will not be changed. If the output is a
213            buffer, it will be wiped before any compressed data is output.
214
215            Defaults to 0.
216
217   Examples
218       To read the contents of the file "file1.txt" and write the compressed
219       data to the file "file1.txt.bz2".
220
221           use strict ;
222           use warnings ;
223           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
224
225           my $input = "file1.txt";
226           bzip2 $input => "$input.bz2"
227               or die "bzip2 failed: $Bzip2Error\n";
228
229       To read from an existing Perl filehandle, $input, and write the
230       compressed data to a buffer, $buffer.
231
232           use strict ;
233           use warnings ;
234           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
235           use IO::File ;
236
237           my $input = new IO::File "<file1.txt"
238               or die "Cannot open 'file1.txt': $!\n" ;
239           my $buffer ;
240           bzip2 $input => \$buffer
241               or die "bzip2 failed: $Bzip2Error\n";
242
243       To compress all files in the directory "/my/home" that match "*.txt"
244       and store the compressed data in the same directory
245
246           use strict ;
247           use warnings ;
248           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
249
250           bzip2 '</my/home/*.txt>' => '<*.bz2>'
251               or die "bzip2 failed: $Bzip2Error\n";
252
253       and if you want to compress each file one at a time, this will do the
254       trick
255
256           use strict ;
257           use warnings ;
258           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
259
260           for my $input ( glob "/my/home/*.txt" )
261           {
262               my $output = "$input.bz2" ;
263               bzip2 $input => $output
264                   or die "Error compressing '$input': $Bzip2Error\n";
265           }
266

OO Interface

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

Methods

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

Importing

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

EXAMPLES

547   Apache::GZip Revisited
548       See IO::Compress::FAQ
549
550   Working with Net::FTP
551       See IO::Compress::FAQ
552

AUTHOR

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

MODIFICATION HISTORY

576       See the Changes file.
577

COPYRIGHT AND LICENSE

579       Copyright (c) 2005-2019 Paul Marquess. All rights reserved.
580
581       This program is free software; you can redistribute it and/or modify it
582       under the same terms as Perl itself.
583
584
585
586perl v5.28.1                      2019-01-05            IO::Compress::Bzip2(3)