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 => $output [,OPTS]
62 or die "bzip2 failed: $Bzip2Error\n";
63 The functional interface needs Perl5.005 or better.
65 bzip2 $input => $output [, OPTS]
67 "bzip2" expects at least two parameters, $input and $output.
68 The $input parameter
70 The parameter, $input, is used to define the source of the uncompressed
72 data.
73 It can take one of the following forms:
75 A filename
77 If the $input parameter is a simple scalar, it is assumed to be a
78 filename. This file will be opened for reading and the input data
79 will be read from it.
80 A filehandle
82 If the $input parameter is a filehandle, the input data will be
83 read from it. The string '-' can be used as an alias for standard
84 input.
85 A scalar reference
87 If $input is a scalar reference, the input data will be read from
88 $$input.
89 An array reference
91 If $input is an array reference, each element in the array must be
92 a filename.
93 The input data will be read from each file in turn.
95 The complete array will be walked to ensure that it only contains
97 valid filenames before any data is compressed.
98 An Input FileGlob string
100 If $input is a string that is delimited by the characters "<" and
101 ">" "bzip2" will assume that it is an input fileglob string. The
102 input is the list of files that match the fileglob.
103 If the fileglob does not match any files ...
105 See File::GlobMapper for more details.
107 If the $input parameter is any other type, "undef" will be returned.
109 The $output parameter
111 The parameter $output is used to control the destination of the
113 compressed data. This parameter can take one of these forms.
114 A filename
116 If the $output parameter is a simple scalar, it is assumed to be a
117 filename. This file will be opened for writing and the compressed
118 data will be written to it.
119 A filehandle
121 If the $output parameter is a filehandle, the compressed data will
122 be written to it. The string '-' can be used as an alias for
123 standard output.
124 A scalar reference
126 If $output is a scalar reference, the compressed data will be
127 stored in $$output.
128 An Array Reference
130 If $output is an array reference, the compressed data will be
131 pushed onto the array.
132 An Output FileGlob
134 If $output is a string that is delimited by the characters "<" and
135 ">" "bzip2" will assume that it is an output fileglob string. The
136 output is the list of files that match the fileglob.
137 When $output is an fileglob string, $input must also be a fileglob
139 string. Anything else is an error.
140 If the $output parameter is any other type, "undef" will be returned.
142 Notes
144 When $input maps to multiple files/buffers and $output is a single
145 file/buffer the input files/buffers will be stored in $output as a
146 concatenated series of compressed data streams.
147 Optional Parameters
149 Unless specified below, the optional parameters for "bzip2", "OPTS",
150 are the same as those used with the OO interface defined in the
151 "Constructor Options" section below.
152 "AutoClose => 0|1"
154 This option applies to any input or output data streams to "bzip2"
155 that are filehandles.
156 If "AutoClose" is specified, and the value is true, it will result
158 in all input and/or output filehandles being closed once "bzip2"
159 has completed.
160 This parameter defaults to 0.
162 "BinModeIn => 0|1"
164 When reading from a file or filehandle, set "binmode" before
165 reading.
166 Defaults to 0.
168 "Append => 0|1"
170 TODO
171 Examples
173 To read the contents of the file "file1.txt" and write the compressed
174 data to the file "file1.txt.bz2".
175 use strict ;
177 use warnings ;
178 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
179 my $input = "file1.txt";
181 bzip2 $input => "$input.bz2"
182 or die "bzip2 failed: $Bzip2Error\n";
183 To read from an existing Perl filehandle, $input, and write the
185 compressed data to a buffer, $buffer.
186 use strict ;
188 use warnings ;
189 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
190 use IO::File ;
191 my $input = new IO::File "<file1.txt"
193 or die "Cannot open 'file1.txt': $!\n" ;
194 my $buffer ;
195 bzip2 $input => \$buffer
196 or die "bzip2 failed: $Bzip2Error\n";
197 To compress all files in the directory "/my/home" that match "*.txt"
199 and store the compressed data in the same directory
200 use strict ;
202 use warnings ;
203 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
204 bzip2 '</my/home/*.txt>' => '<*.bz2>'
206 or die "bzip2 failed: $Bzip2Error\n";
207 and if you want to compress each file one at a time, this will do the
209 trick
210 use strict ;
212 use warnings ;
213 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
214 for my $input ( glob "/my/home/*.txt" )
216 {
217 my $output = "$input.bz2" ;
218 bzip2 $input => $output
219 or die "Error compressing '$input': $Bzip2Error\n";
220 }
221
223 Constructor
224 The format of the constructor for "IO::Compress::Bzip2" is shown below
225 my $z = new IO::Compress::Bzip2 $output [,OPTS]
227 or die "IO::Compress::Bzip2 failed: $Bzip2Error\n";
228 It returns an "IO::Compress::Bzip2" object on success and undef on
230 failure. The variable $Bzip2Error will contain an error message on
231 failure.
232 If you are running Perl 5.005 or better the object, $z, returned from
234 IO::Compress::Bzip2 can be used exactly like an IO::File filehandle.
235 This means that all normal output file operations can be carried out
236 with $z. For example, to write to a compressed file/buffer you can use
237 either of these forms
238 $z->print("hello world\n");
240 print $z "hello world\n";
241 The mandatory parameter $output is used to control the destination of
243 the compressed data. This parameter can take one of these forms.
244 A filename
246 If the $output parameter is a simple scalar, it is assumed to be a
247 filename. This file will be opened for writing and the compressed
248 data will be written to it.
249 A filehandle
251 If the $output parameter is a filehandle, the compressed data will
252 be written to it. The string '-' can be used as an alias for
253 standard output.
254 A scalar reference
256 If $output is a scalar reference, the compressed data will be
257 stored in $$output.
258 If the $output parameter is any other type, "IO::Compress::Bzip2"::new
260 will return undef.
261 Constructor Options
263 "OPTS" is any combination of the following options:
264 "AutoClose => 0|1"
266 This option is only valid when the $output parameter is a
267 filehandle. If specified, and the value is true, it will result in
268 the $output being closed once either the "close" method is called
269 or the "IO::Compress::Bzip2" object is destroyed.
270 This parameter defaults to 0.
272 "Append => 0|1"
274 Opens $output in append mode.
275 The behaviour of this option is dependent on the type of $output.
277 · A Buffer
279 If $output is a buffer and "Append" is enabled, all
281 compressed data will be append to the end if $output.
282 Otherwise $output will be cleared before any data is written
283 to it.
284 · A Filename
286 If $output is a filename and "Append" is enabled, the file
288 will be opened in append mode. Otherwise the contents of the
289 file, if any, will be truncated before any compressed data is
290 written to it.
291 · A Filehandle
293 If $output is a filehandle, the file pointer will be
295 positioned to the end of the file via a call to "seek" before
296 any compressed data is written to it. Otherwise the file
297 pointer will not be moved.
298 This parameter defaults to 0.
300 "BlockSize100K => number"
302 Specify the number of 100K blocks bzip2 uses during compression.
303 Valid values are from 1 to 9, where 9 is best compression.
305 The default is 1.
307 "WorkFactor => number"
309 Specifies how much effort bzip2 should take before resorting to a
310 slower fallback compression algorithm.
311 Valid values range from 0 to 250, where 0 means use the default
313 value 30.
314 The default is 0.
316 "Strict => 0|1"
318 This is a placeholder option.
319 Examples
321 TODO
322
324 print
325 Usage is
326 $z->print($data)
328 print $z $data
329 Compresses and outputs the contents of the $data parameter. This has
331 the same behaviour as the "print" built-in.
332 Returns true if successful.
334 printf
336 Usage is
337 $z->printf($format, $data)
339 printf $z $format, $data
340 Compresses and outputs the contents of the $data parameter.
342 Returns true if successful.
344 syswrite
346 Usage is
347 $z->syswrite $data
349 $z->syswrite $data, $length
350 $z->syswrite $data, $length, $offset
351 Compresses and outputs the contents of the $data parameter.
353 Returns the number of uncompressed bytes written, or "undef" if
355 unsuccessful.
356 write
358 Usage is
359 $z->write $data
361 $z->write $data, $length
362 $z->write $data, $length, $offset
363 Compresses and outputs the contents of the $data parameter.
365 Returns the number of uncompressed bytes written, or "undef" if
367 unsuccessful.
368 flush
370 Usage is
371 $z->flush;
373 Flushes any pending compressed data to the output file/buffer.
375 TODO
377 Returns true on success.
379 tell
381 Usage is
382 $z->tell()
384 tell $z
385 Returns the uncompressed file offset.
387 eof
389 Usage is
390 $z->eof();
392 eof($z);
393 Returns true if the "close" method has been called.
395 seek
397 $z->seek($position, $whence);
398 seek($z, $position, $whence);
399 Provides a sub-set of the "seek" functionality, with the restriction
401 that it is only legal to seek forward in the output file/buffer. It is
402 a fatal error to attempt to seek backward.
403 Empty parts of the file/buffer will have NULL (0x00) bytes written to
405 them.
406 The $whence parameter takes one the usual values, namely SEEK_SET,
408 SEEK_CUR or SEEK_END.
409 Returns 1 on success, 0 on failure.
411 binmode
413 Usage is
414 $z->binmode
416 binmode $z ;
417 This is a noop provided for completeness.
419 opened
421 $z->opened()
422 Returns true if the object currently refers to a opened file/buffer.
424 autoflush
426 my $prev = $z->autoflush()
427 my $prev = $z->autoflush(EXPR)
428 If the $z object is associated with a file or a filehandle, this method
430 returns the current autoflush setting for the underlying filehandle. If
431 "EXPR" is present, and is non-zero, it will enable flushing after every
432 write/print operation.
433 If $z is associated with a buffer, this method has no effect and always
435 returns "undef".
436 Note that the special variable $| cannot be used to set or retrieve the
438 autoflush setting.
439 input_line_number
441 $z->input_line_number()
442 $z->input_line_number(EXPR)
443 This method always returns "undef" when compressing.
445 fileno
447 $z->fileno()
448 fileno($z)
449 If the $z object is associated with a file or a filehandle, "fileno"
451 will return the underlying file descriptor. Once the "close" method is
452 called "fileno" will return "undef".
453 If the $z object is is associated with a buffer, this method will
455 return "undef".
456 close
458 $z->close() ;
459 close $z ;
460 Flushes any pending compressed data and then closes the output
462 file/buffer.
463 For most versions of Perl this method will be automatically invoked if
465 the IO::Compress::Bzip2 object is destroyed (either explicitly or by
466 the variable with the reference to the object going out of scope). The
467 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
468 cases, the "close" method will be called automatically, but not until
469 global destruction of all live objects when the program is terminating.
470 Therefore, if you want your scripts to be able to run on all versions
472 of Perl, you should call "close" explicitly and not rely on automatic
473 closing.
474 Returns true on success, otherwise 0.
476 If the "AutoClose" option has been enabled when the IO::Compress::Bzip2
478 object was created, and the object is associated with a file, the
479 underlying file will also be closed.
480 newStream([OPTS])
482 Usage is
483 $z->newStream( [OPTS] )
485 Closes the current compressed data stream and starts a new one.
487 OPTS consists of any of the the options that are available when
489 creating the $z object.
490 See the "Constructor Options" section for more details.
492
494 No symbolic constants are required by this IO::Compress::Bzip2 at
495 present.
496 :all Imports "bzip2" and $Bzip2Error. Same as doing this
498 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
500
502 Apache::GZip Revisited
503 See IO::Compress::Bzip2::FAQ
504 Working with Net::FTP
506 See IO::Compress::Bzip2::FAQ
507
509 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
510 IO::Compress::Deflate, IO::Uncompress::Inflate,
511 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
512 IO::Uncompress::Bunzip2, IO::Compress::Lzop, IO::Uncompress::UnLzop,
513 IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Uncompress::AnyInflate,
514 IO::Uncompress::AnyUncompress
515 Compress::Zlib::FAQ
517 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
519 The primary site for the bzip2 program is http://www.bzip.org.
521 See the module Compress::Bzip2
523
525 This module was written by Paul Marquess, pmqs@cpan.org.
526
528 See the Changes file.
529
531 Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
532 This program is free software; you can redistribute it and/or modify it
534 under the same terms as Perl itself.
535perl v5.16.3 2013-05-19 IO::Compress::Bzip2(3)