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 = new IO::Compress::Bzip2 $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.
70 The $input_filename_or_reference parameter
72 The parameter, $input_filename_or_reference, is used to define the
74 source of the uncompressed data.
75 It can take one of the following forms:
77 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 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 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 An array reference
93 If $input_filename_or_reference is an array reference, each
94 element in the array must be a filename.
95 The input data will be read from each file in turn.
97 The complete array will be walked to ensure that it only contains
99 valid filenames before any data is compressed.
100 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 See File::GlobMapper for more details.
108 If the $input_filename_or_reference parameter is any other type,
110 "undef" will be returned.
111 The $output_filename_or_reference parameter
113 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 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 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 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 An Array Reference
133 If $output_filename_or_reference is an array reference, the
134 compressed data will be pushed onto the array.
135 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 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 See File::GlobMapper for more details.
147 If the $output_filename_or_reference parameter is any other type,
149 "undef" will be returned.
150 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 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 "AutoClose => 0|1"
163 This option applies to any input or output data streams to "bzip2"
164 that are filehandles.
165 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 This parameter defaults to 0.
171 "BinModeIn => 0|1"
173 When reading from a file or filehandle, set "binmode" before
174 reading.
175 Defaults to 0.
177 "Append => 0|1"
179 The behaviour of this option is dependent on the type of output
180 data stream.
181 · A Buffer
183 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 · A Filename
189 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 · A Filehandle
195 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 When "Append" is specified, and set to true, it will append all
202 compressed data to the output data stream.
203 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 Conversely when "Append" is not specified, or it is present and is
211 set to false, it will operate as follows.
212 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 Defaults to 0.
219 Examples
221 To read the contents of the file "file1.txt" and write the compressed
222 data to the file "file1.txt.bz2".
223 use strict ;
225 use warnings ;
226 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
227 my $input = "file1.txt";
229 bzip2 $input => "$input.bz2"
230 or die "bzip2 failed: $Bzip2Error\n";
231 To read from an existing Perl filehandle, $input, and write the
233 compressed data to a buffer, $buffer.
234 use strict ;
236 use warnings ;
237 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
238 use IO::File ;
239 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 To compress all files in the directory "/my/home" that match "*.txt"
247 and store the compressed data in the same directory
248 use strict ;
250 use warnings ;
251 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
252 bzip2 '</my/home/*.txt>' => '<*.bz2>'
254 or die "bzip2 failed: $Bzip2Error\n";
255 and if you want to compress each file one at a time, this will do the
257 trick
258 use strict ;
260 use warnings ;
261 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
262 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
271 Constructor
272 The format of the constructor for "IO::Compress::Bzip2" is shown below
273 my $z = new IO::Compress::Bzip2 $output [,OPTS]
275 or die "IO::Compress::Bzip2 failed: $Bzip2Error\n";
276 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 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 $z->print("hello world\n");
288 print $z "hello world\n";
289 The mandatory parameter $output is used to control the destination of
291 the compressed data. This parameter can take one of these forms.
292 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 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 A scalar reference
304 If $output is a scalar reference, the compressed data will be
305 stored in $$output.
306 If the $output parameter is any other type, "IO::Compress::Bzip2"::new
308 will return undef.
309 Constructor Options
311 "OPTS" is any combination of the following options:
312 "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 This parameter defaults to 0.
320 "Append => 0|1"
322 Opens $output in append mode.
323 The behaviour of this option is dependent on the type of $output.
325 · A Buffer
327 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 · A Filename
334 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 · A Filehandle
341 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 This parameter defaults to 0.
348 "BlockSize100K => number"
350 Specify the number of 100K blocks bzip2 uses during compression.
351 Valid values are from 1 to 9, where 9 is best compression.
353 The default is 1.
355 "WorkFactor => number"
357 Specifies how much effort bzip2 should take before resorting to a
358 slower fallback compression algorithm.
359 Valid values range from 0 to 250, where 0 means use the default
361 value 30.
362 The default is 0.
364 "Strict => 0|1"
366 This is a placeholder option.
367 Examples
369 TODO
370
372 print
373 Usage is
374 $z->print($data)
376 print $z $data
377 Compresses and outputs the contents of the $data parameter. This has
379 the same behaviour as the "print" built-in.
380 Returns true if successful.
382 printf
384 Usage is
385 $z->printf($format, $data)
387 printf $z $format, $data
388 Compresses and outputs the contents of the $data parameter.
390 Returns true if successful.
392 syswrite
394 Usage is
395 $z->syswrite $data
397 $z->syswrite $data, $length
398 $z->syswrite $data, $length, $offset
399 Compresses and outputs the contents of the $data parameter.
401 Returns the number of uncompressed bytes written, or "undef" if
403 unsuccessful.
404 write
406 Usage is
407 $z->write $data
409 $z->write $data, $length
410 $z->write $data, $length, $offset
411 Compresses and outputs the contents of the $data parameter.
413 Returns the number of uncompressed bytes written, or "undef" if
415 unsuccessful.
416 flush
418 Usage is
419 $z->flush;
421 Flushes any pending compressed data to the output file/buffer.
423 TODO
425 Returns true on success.
427 tell
429 Usage is
430 $z->tell()
432 tell $z
433 Returns the uncompressed file offset.
435 eof
437 Usage is
438 $z->eof();
440 eof($z);
441 Returns true if the "close" method has been called.
443 seek
445 $z->seek($position, $whence);
446 seek($z, $position, $whence);
447 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 Empty parts of the file/buffer will have NULL (0x00) bytes written to
453 them.
454 The $whence parameter takes one the usual values, namely SEEK_SET,
456 SEEK_CUR or SEEK_END.
457 Returns 1 on success, 0 on failure.
459 binmode
461 Usage is
462 $z->binmode
464 binmode $z ;
465 This is a noop provided for completeness.
467 opened
469 $z->opened()
470 Returns true if the object currently refers to a opened file/buffer.
472 autoflush
474 my $prev = $z->autoflush()
475 my $prev = $z->autoflush(EXPR)
476 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 If $z is associated with a buffer, this method has no effect and always
483 returns "undef".
484 Note that the special variable $| cannot be used to set or retrieve the
486 autoflush setting.
487 input_line_number
489 $z->input_line_number()
490 $z->input_line_number(EXPR)
491 This method always returns "undef" when compressing.
493 fileno
495 $z->fileno()
496 fileno($z)
497 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 If the $z object is associated with a buffer, this method will return
503 "undef".
504 close
506 $z->close() ;
507 close $z ;
508 Flushes any pending compressed data and then closes the output
510 file/buffer.
511 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 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 Returns true on success, otherwise 0.
524 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 newStream([OPTS])
530 Usage is
531 $z->newStream( [OPTS] )
533 Closes the current compressed data stream and starts a new one.
535 OPTS consists of any of the options that are available when creating
537 the $z object.
538 See the "Constructor Options" section for more details.
540
542 No symbolic constants are required by this IO::Compress::Bzip2 at
543 present.
544 :all Imports "bzip2" and $Bzip2Error. Same as doing this
546 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
548
550 Apache::GZip Revisited
551 See IO::Compress::FAQ
552 Working with Net::FTP
554 See IO::Compress::FAQ
555
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 IO::Compress::FAQ
566 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
568 The primary site for the bzip2 program is <http://www.bzip.org>.
570 See the module Compress::Bzip2
572
574 This module was written by Paul Marquess, "pmqs@cpan.org".
575
577 See the Changes file.
578
580 Copyright (c) 2005-2018 Paul Marquess. All rights reserved.
581 This program is free software; you can redistribute it and/or modify it
583 under the same terms as Perl itself.
584perl v5.28.0 2018-04-05 IO::Compress::Bzip2(3)