1IO::Compress::Lzip(3) User Contributed Perl DocumentationIO::Compress::Lzip(3)
2
3
4
6 IO::Compress::Lzip - Write lzip files/buffers
7
9 use IO::Compress::Lzip qw(lzip $LzipError) ;
10
11 my $status = lzip $input => $output [,OPTS]
12 or die "lzip failed: $LzipError\n";
13
14 my $z = new IO::Compress::Lzip $output [,OPTS]
15 or die "lzip failed: $LzipError\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 $LzipError ;
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
48 This module provides a Perl interface that allows writing lzip
49 compressed data to files or buffer.
50
51 For reading lzip files/buffers, see the companion module
52 IO::Uncompress::UnLzip.
53
55 A top-level function, "lzip", 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::Lzip qw(lzip $LzipError) ;
60
61 lzip $input_filename_or_reference => $output_filename_or_reference [,OPTS]
62 or die "lzip failed: $LzipError\n";
63
64 The functional interface needs Perl5.005 or better.
65
66 lzip $input_filename_or_reference => $output_filename_or_reference [, OPTS]
67 "lzip" expects at least two parameters, $input_filename_or_reference
68 and $output_filename_or_reference.
69
70 The $input_filename_or_reference parameter
71
72 The parameter, $input_filename_or_reference, is used to define the
73 source of the uncompressed data.
74
75 It can take one of the following forms:
76
77 A filename
78 If the <$input_filename_or_reference> parameter is a simple
79 scalar, it is assumed to be a filename. This file will be opened
80 for reading and the input data will be read from it.
81
82 A filehandle
83 If the $input_filename_or_reference parameter is a filehandle, the
84 input data will be read from it. The string '-' can be used as an
85 alias for standard input.
86
87 A scalar reference
88 If $input_filename_or_reference is a scalar reference, the input
89 data will be read from $$input_filename_or_reference.
90
91 An array reference
92 If $input_filename_or_reference is an array reference, each
93 element in the array must be a filename.
94
95 The input data will be read from each file in turn.
96
97 The complete array will be walked to ensure that it only contains
98 valid filenames before any data is compressed.
99
100 An Input FileGlob string
101 If $input_filename_or_reference is a string that is delimited by
102 the characters "<" and ">" "lzip" will assume that it is an input
103 fileglob string. The input is the list of files that match the
104 fileglob.
105
106 See File::GlobMapper for more details.
107
108 If the $input_filename_or_reference parameter is any other type,
109 "undef" will be returned.
110
111 The $output_filename_or_reference parameter
112
113 The parameter $output_filename_or_reference is used to control the
114 destination of the compressed data. This parameter can take one of
115 these forms.
116
117 A filename
118 If the $output_filename_or_reference parameter is a simple scalar,
119 it is assumed to be a filename. This file will be opened for
120 writing and the compressed data will be written to it.
121
122 A filehandle
123 If the $output_filename_or_reference parameter is a filehandle,
124 the compressed data will be written to it. The string '-' can be
125 used as an alias for standard output.
126
127 A scalar reference
128 If $output_filename_or_reference is a scalar reference, the
129 compressed data will be stored in $$output_filename_or_reference.
130
131 An Array Reference
132 If $output_filename_or_reference is an array reference, the
133 compressed data will be pushed onto the array.
134
135 An Output FileGlob
136 If $output_filename_or_reference is a string that is delimited by
137 the characters "<" and ">" "lzip" will assume that it is an output
138 fileglob string. The output is the list of files that match the
139 fileglob.
140
141 When $output_filename_or_reference is an fileglob string,
142 $input_filename_or_reference must also be a fileglob string.
143 Anything else is an error.
144
145 See File::GlobMapper for more details.
146
147 If the $output_filename_or_reference parameter is any other type,
148 "undef" will be returned.
149
150 Notes
151 When $input_filename_or_reference maps to multiple files/buffers and
152 $output_filename_or_reference is a single file/buffer the input
153 files/buffers will be stored in $output_filename_or_reference as a
154 concatenated series of compressed data streams.
155
156 Optional Parameters
157 Unless specified below, the optional parameters for "lzip", "OPTS", are
158 the same as those used with the OO interface defined in the
159 "Constructor Options" section below.
160
161 "AutoClose => 0|1"
162 This option applies to any input or output data streams to "lzip"
163 that are filehandles.
164
165 If "AutoClose" is specified, and the value is true, it will result
166 in all input and/or output filehandles being closed once "lzip"
167 has completed.
168
169 This parameter defaults to 0.
170
171 "BinModeIn => 0|1"
172 This option is now a no-op. All files will be read in binmode.
173
174 "Append => 0|1"
175 The behaviour of this option is dependent on the type of output
176 data stream.
177
178 · A Buffer
179
180 If "Append" is enabled, all compressed data will be append to
181 the end of the output buffer. Otherwise the output buffer
182 will be cleared before any compressed data is written to it.
183
184 · A Filename
185
186 If "Append" is enabled, the file will be opened in append
187 mode. Otherwise the contents of the file, if any, will be
188 truncated before any compressed data is written to it.
189
190 · A Filehandle
191
192 If "Append" is enabled, the filehandle will be positioned to
193 the end of the file via a call to "seek" before any
194 compressed data is written to it. Otherwise the file pointer
195 will not be moved.
196
197 When "Append" is specified, and set to true, it will append all
198 compressed data to the output data stream.
199
200 So when the output is a filehandle it will carry out a seek to the
201 eof before writing any compressed data. If the output is a
202 filename, it will be opened for appending. If the output is a
203 buffer, all compressed data will be appended to the existing
204 buffer.
205
206 Conversely when "Append" is not specified, or it is present and is
207 set to false, it will operate as follows.
208
209 When the output is a filename, it will truncate the contents of
210 the file before writing any compressed data. If the output is a
211 filehandle its position will not be changed. If the output is a
212 buffer, it will be wiped before any compressed data is output.
213
214 Defaults to 0.
215
216 Examples
217 To read the contents of the file "file1.txt" and write the compressed
218 data to the file "file1.txt.lz".
219
220 use strict ;
221 use warnings ;
222 use IO::Compress::Lzip qw(lzip $LzipError) ;
223
224 my $input = "file1.txt";
225 lzip $input => "$input.lz"
226 or die "lzip failed: $LzipError\n";
227
228 To read from an existing Perl filehandle, $input, and write the
229 compressed data to a buffer, $buffer.
230
231 use strict ;
232 use warnings ;
233 use IO::Compress::Lzip qw(lzip $LzipError) ;
234 use IO::File ;
235
236 my $input = new IO::File "<file1.txt"
237 or die "Cannot open 'file1.txt': $!\n" ;
238 my $buffer ;
239 lzip $input => \$buffer
240 or die "lzip failed: $LzipError\n";
241
242 To compress all files in the directory "/my/home" that match "*.txt"
243 and store the compressed data in the same directory
244
245 use strict ;
246 use warnings ;
247 use IO::Compress::Lzip qw(lzip $LzipError) ;
248
249 lzip '</my/home/*.txt>' => '<*.lz>'
250 or die "lzip failed: $LzipError\n";
251
252 and if you want to compress each file one at a time, this will do the
253 trick
254
255 use strict ;
256 use warnings ;
257 use IO::Compress::Lzip qw(lzip $LzipError) ;
258
259 for my $input ( glob "/my/home/*.txt" )
260 {
261 my $output = "$input.lz" ;
262 lzip $input => $output
263 or die "Error compressing '$input': $LzipError\n";
264 }
265
267 Constructor
268 The format of the constructor for "IO::Compress::Lzip" is shown below
269
270 my $z = new IO::Compress::Lzip $output [,OPTS]
271 or die "IO::Compress::Lzip failed: $LzipError\n";
272
273 It returns an "IO::Compress::Lzip" object on success and undef on
274 failure. The variable $LzipError will contain an error message on
275 failure.
276
277 If you are running Perl 5.005 or better the object, $z, returned from
278 IO::Compress::Lzip can be used exactly like an IO::File filehandle.
279 This means that all normal output file operations can be carried out
280 with $z. For example, to write to a compressed file/buffer you can use
281 either of these forms
282
283 $z->print("hello world\n");
284 print $z "hello world\n";
285
286 The mandatory parameter $output is used to control the destination of
287 the compressed data. This parameter can take one of these forms.
288
289 A filename
290 If the $output parameter is a simple scalar, it is assumed to be a
291 filename. This file will be opened for writing and the compressed
292 data will be written to it.
293
294 A filehandle
295 If the $output parameter is a filehandle, the compressed data will
296 be written to it. The string '-' can be used as an alias for
297 standard output.
298
299 A scalar reference
300 If $output is a scalar reference, the compressed data will be
301 stored in $$output.
302
303 If the $output parameter is any other type, "IO::Compress::Lzip"::new
304 will return undef.
305
306 Constructor Options
307 "OPTS" is any combination of the following options:
308
309 "AutoClose => 0|1"
310 This option is only valid when the $output parameter is a
311 filehandle. If specified, and the value is true, it will result in
312 the $output being closed once either the "close" method is called
313 or the "IO::Compress::Lzip" object is destroyed.
314
315 This parameter defaults to 0.
316
317 "Append => 0|1"
318 Opens $output in append mode.
319
320 The behaviour of this option is dependent on the type of $output.
321
322 · A Buffer
323
324 If $output is a buffer and "Append" is enabled, all
325 compressed data will be append to the end of $output.
326 Otherwise $output will be cleared before any data is written
327 to it.
328
329 · A Filename
330
331 If $output is a filename and "Append" is enabled, the file
332 will be opened in append mode. Otherwise the contents of the
333 file, if any, will be truncated before any compressed data is
334 written to it.
335
336 · A Filehandle
337
338 If $output is a filehandle, the file pointer will be
339 positioned to the end of the file via a call to "seek" before
340 any compressed data is written to it. Otherwise the file
341 pointer will not be moved.
342
343 This parameter defaults to 0.
344
345 "DictSize => number"
346 Valid values are between 4K and 128Meg
347
348 Defaults to 8 Meg.
349
350 "Strict => 0|1"
351 This is a placeholder option.
352
353 Examples
354 TODO
355
357 print
358 Usage is
359
360 $z->print($data)
361 print $z $data
362
363 Compresses and outputs the contents of the $data parameter. This has
364 the same behaviour as the "print" built-in.
365
366 Returns true if successful.
367
368 printf
369 Usage is
370
371 $z->printf($format, $data)
372 printf $z $format, $data
373
374 Compresses and outputs the contents of the $data parameter.
375
376 Returns true if successful.
377
378 syswrite
379 Usage is
380
381 $z->syswrite $data
382 $z->syswrite $data, $length
383 $z->syswrite $data, $length, $offset
384
385 Compresses and outputs the contents of the $data parameter.
386
387 Returns the number of uncompressed bytes written, or "undef" if
388 unsuccessful.
389
390 write
391 Usage is
392
393 $z->write $data
394 $z->write $data, $length
395 $z->write $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 flush
403 Usage is
404
405 $z->flush;
406
407 Flushes any pending compressed data to the output file/buffer.
408
409 Returns true on success.
410
411 tell
412 Usage is
413
414 $z->tell()
415 tell $z
416
417 Returns the uncompressed file offset.
418
419 eof
420 Usage is
421
422 $z->eof();
423 eof($z);
424
425 Returns true if the "close" method has been called.
426
427 seek
428 $z->seek($position, $whence);
429 seek($z, $position, $whence);
430
431 Provides a sub-set of the "seek" functionality, with the restriction
432 that it is only legal to seek forward in the output file/buffer. It is
433 a fatal error to attempt to seek backward.
434
435 Empty parts of the file/buffer will have NULL (0x00) bytes written to
436 them.
437
438 The $whence parameter takes one the usual values, namely SEEK_SET,
439 SEEK_CUR or SEEK_END.
440
441 Returns 1 on success, 0 on failure.
442
443 binmode
444 Usage is
445
446 $z->binmode
447 binmode $z ;
448
449 This is a noop provided for completeness.
450
451 opened
452 $z->opened()
453
454 Returns true if the object currently refers to a opened file/buffer.
455
456 autoflush
457 my $prev = $z->autoflush()
458 my $prev = $z->autoflush(EXPR)
459
460 If the $z object is associated with a file or a filehandle, this method
461 returns the current autoflush setting for the underlying filehandle. If
462 "EXPR" is present, and is non-zero, it will enable flushing after every
463 write/print operation.
464
465 If $z is associated with a buffer, this method has no effect and always
466 returns "undef".
467
468 Note that the special variable $| cannot be used to set or retrieve the
469 autoflush setting.
470
471 input_line_number
472 $z->input_line_number()
473 $z->input_line_number(EXPR)
474
475 This method always returns "undef" when compressing.
476
477 fileno
478 $z->fileno()
479 fileno($z)
480
481 If the $z object is associated with a file or a filehandle, "fileno"
482 will return the underlying file descriptor. Once the "close" method is
483 called "fileno" will return "undef".
484
485 If the $z object is associated with a buffer, this method will return
486 "undef".
487
488 close
489 $z->close() ;
490 close $z ;
491
492 Flushes any pending compressed data and then closes the output
493 file/buffer.
494
495 For most versions of Perl this method will be automatically invoked if
496 the IO::Compress::Lzip object is destroyed (either explicitly or by the
497 variable with the reference to the object going out of scope). The
498 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
499 cases, the "close" method will be called automatically, but not until
500 global destruction of all live objects when the program is terminating.
501
502 Therefore, if you want your scripts to be able to run on all versions
503 of Perl, you should call "close" explicitly and not rely on automatic
504 closing.
505
506 Returns true on success, otherwise 0.
507
508 If the "AutoClose" option has been enabled when the IO::Compress::Lzip
509 object was created, and the object is associated with a file, the
510 underlying file will also be closed.
511
512 newStream([OPTS])
513 Usage is
514
515 $z->newStream( [OPTS] )
516
517 Closes the current compressed data stream and starts a new one.
518
519 OPTS consists of any of the options that are available when creating
520 the $z object.
521
522 See the "Constructor Options" section for more details.
523
525 No symbolic constants are required by this IO::Compress::Lzip at
526 present.
527
528 :all Imports "lzip" and $LzipError. Same as doing this
529
530 use IO::Compress::Lzip qw(lzip $LzipError) ;
531
534 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
535 IO::Compress::Deflate, IO::Uncompress::Inflate,
536 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
537 IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma,
538 IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz,
539 IO::Uncompress::UnLzip, IO::Compress::Lzop, IO::Uncompress::UnLzop,
540 IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Compress::Zstd,
541 IO::Uncompress::UnZstd, IO::Uncompress::AnyInflate,
542 IO::Uncompress::AnyUncompress
543
544 IO::Compress::FAQ
545
546 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
547
549 This module was written by Paul Marquess, "pmqs@cpan.org".
550
552 See the Changes file.
553
555 Copyright (c) 2005-2019 Paul Marquess. All rights reserved.
556
557 This program is free software; you can redistribute it and/or modify it
558 under the same terms as Perl itself.
559
560
561
562perl v5.30.0 2019-08-12 IO::Compress::Lzip(3)