1IO::Compress::Lzip(3) User Contributed Perl DocumentationIO::Compress::Lzip(3)
2
3
4

NAME

6       IO::Compress::Lzip - Write lzip files/buffers
7

SYNOPSIS

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

DESCRIPTION

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

Functional Interface

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

OO Interface

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

Methods

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

Importing

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

EXAMPLES

SEE ALSO

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

AUTHOR

549       This module was written by Paul Marquess, "pmqs@cpan.org".
550

MODIFICATION HISTORY

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.28.1                      2019-01-05             IO::Compress::Lzip(3)
Impressum