IO::Compress::Gzip(3pm)

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

NAME

6       IO::Compress::Gzip - Write RFC 1952 files/buffers
7

SYNOPSIS

9           use IO::Compress::Gzip qw(gzip $GzipError) ;
10
11           my $status = gzip $input => $output [,OPTS]
12               or die "gzip failed: $GzipError\n";
13
14           my $z = new IO::Compress::Gzip $output [,OPTS]
15               or die "gzip failed: $GzipError\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->deflateParams();
33
34           $z->close() ;
35
36           $GzipError ;
37
38           # IO::File mode
39
40           print $z $string;
41           printf $z $format, $string;
42           tell $z
43           eof $z
44           seek $z, $position, $whence
45           binmode $z
46           fileno $z
47           close $z ;
48

DESCRIPTION

50       This module provides a Perl interface that allows writing compressed
51       data to files or buffer as defined in RFC 1952.
52
53       All the gzip headers defined in RFC 1952 can be created using this mod‐
54       ule.
55
56       For reading RFC 1952 files/buffers, see the companion module IO::Uncom‐
57       press::Gunzip.
58

Functional Interface

60       A top-level function, "gzip", is provided to carry out "one-shot" com‐
61       pression between buffers and/or files. For finer control over the com‐
62       pression process, see the "OO Interface" section.
63
64           use IO::Compress::Gzip qw(gzip $GzipError) ;
65
66           gzip $input => $output [,OPTS]
67               or die "gzip failed: $GzipError\n";
68
69       The functional interface needs Perl5.005 or better.
70
71       gzip $input => $output [, OPTS]
72
73       "gzip" expects at least two parameters, $input and $output.
74
75       The $input parameter
76
77       The parameter, $input, is used to define the source of the uncompressed
78       data.
79
80       It can take one of the following forms:
81
82       A filename
83            If the $input parameter is a simple scalar, it is assumed to be a
84            filename. This file will be opened for reading and the input data
85            will be read from it.
86
87       A filehandle
88            If the $input parameter is a filehandle, the input data will be
89            read from it.  The string '-' can be used as an alias for standard
90            input.
91
92       A scalar reference
93            If $input is a scalar reference, the input data will be read from
94            $$input.
95
96       An array reference
97            If $input is an array reference, each element in the array must be
98            a filename.
99
100            The input data will be read from each file in turn.
101
102            The complete array will be walked to ensure that it only contains
103            valid filenames before any data is compressed.
104
105       An Input FileGlob string
106            If $input is a string that is delimited by the characters "<" and
107            ">" "gzip" will assume that it is an input fileglob string. The
108            input is the list of files that match the fileglob.
109
110            If the fileglob does not match any files ...
111
112            See File::GlobMapper for more details.
113
114       If the $input parameter is any other type, "undef" will be returned.
115
116       In addition, if $input is a simple filename, the default values for the
117       "Name" and "Time" options will be sourced from that file.
118
119       If you do not want to use these defaults they can be overridden by
120       explicitly setting the "Name" and "Time" options or by setting the
121       "Minimal" parameter.
122
123       The $output parameter
124
125       The parameter $output is used to control the destination of the com‐
126       pressed data. This parameter can take one of these forms.
127
128       A filename
129            If the $output parameter is a simple scalar, it is assumed to be a
130            filename.  This file will be opened for writing and the compressed
131            data will be written to it.
132
133       A filehandle
134            If the $output parameter is a filehandle, the compressed data will
135            be written to it.  The string '-' can be used as an alias for
136            standard output.
137
138       A scalar reference
139            If $output is a scalar reference, the compressed data will be
140            stored in $$output.
141
142       An Array Reference
143            If $output is an array reference, the compressed data will be
144            pushed onto the array.
145
146       An Output FileGlob
147            If $output is a string that is delimited by the characters "<" and
148            ">" "gzip" will assume that it is an output fileglob string. The
149            output is the list of files that match the fileglob.
150
151            When $output is an fileglob string, $input must also be a fileglob
152            string. Anything else is an error.
153
154       If the $output parameter is any other type, "undef" will be returned.
155
156       Notes
157
158       When $input maps to multiple files/buffers and $output is a single
159       file/buffer the input files/buffers will be stored in $output as a con‐
160       catenated series of compressed data streams.
161
162       Optional Parameters
163
164       Unless specified below, the optional parameters for "gzip", "OPTS", are
165       the same as those used with the OO interface defined in the "Construc‐
166       tor Options" section below.
167
168       "AutoClose => 0⎪1"
169            This option applies to any input or output data streams to "gzip"
170            that are filehandles.
171
172            If "AutoClose" is specified, and the value is true, it will result
173            in all input and/or output filehandles being closed once "gzip"
174            has completed.
175
176            This parameter defaults to 0.
177
178       "BinModeIn => 0⎪1"
179            When reading from a file or filehandle, set "binmode" before read‐
180            ing.
181
182            Defaults to 0.
183
184       "Append => 0⎪1"
185            TODO
186
187       Examples
188
189       To read the contents of the file "file1.txt" and write the compressed
190       data to the file "file1.txt.gz".
191
192           use strict ;
193           use warnings ;
194           use IO::Compress::Gzip qw(gzip $GzipError) ;
195
196           my $input = "file1.txt";
197           gzip $input => "$input.gz"
198               or die "gzip failed: $GzipError\n";
199
200       To read from an existing Perl filehandle, $input, and write the com‐
201       pressed data to a buffer, $buffer.
202
203           use strict ;
204           use warnings ;
205           use IO::Compress::Gzip qw(gzip $GzipError) ;
206           use IO::File ;
207
208           my $input = new IO::File "<file1.txt"
209               or die "Cannot open 'file1.txt': $!\n" ;
210           my $buffer ;
211           gzip $input => \$buffer
212               or die "gzip failed: $GzipError\n";
213
214       To compress all files in the directory "/my/home" that match "*.txt"
215       and store the compressed data in the same directory
216
217           use strict ;
218           use warnings ;
219           use IO::Compress::Gzip qw(gzip $GzipError) ;
220
221           gzip '</my/home/*.txt>' => '<*.gz>'
222               or die "gzip failed: $GzipError\n";
223
224       and if you want to compress each file one at a time, this will do the
225       trick
226
227           use strict ;
228           use warnings ;
229           use IO::Compress::Gzip qw(gzip $GzipError) ;
230
231           for my $input ( glob "/my/home/*.txt" )
232           {
233               my $output = "$input.gz" ;
234               gzip $input => $output
235                   or die "Error compressing '$input': $GzipError\n";
236           }
237

OO Interface

239       Constructor
240
241       The format of the constructor for "IO::Compress::Gzip" is shown below
242
243           my $z = new IO::Compress::Gzip $output [,OPTS]
244               or die "IO::Compress::Gzip failed: $GzipError\n";
245
246       It returns an "IO::Compress::Gzip" object on success and undef on fail‐
247       ure.  The variable $GzipError will contain an error message on failure.
248
249       If you are running Perl 5.005 or better the object, $z, returned from
250       IO::Compress::Gzip can be used exactly like an IO::File filehandle.
251       This means that all normal output file operations can be carried out
252       with $z.  For example, to write to a compressed file/buffer you can use
253       either of these forms
254
255           $z->print("hello world\n");
256           print $z "hello world\n";
257
258       The mandatory parameter $output is used to control the destination of
259       the compressed data. This parameter can take one of these forms.
260
261       A filename
262            If the $output parameter is a simple scalar, it is assumed to be a
263            filename. This file will be opened for writing and the compressed
264            data will be written to it.
265
266       A filehandle
267            If the $output parameter is a filehandle, the compressed data will
268            be written to it.  The string '-' can be used as an alias for
269            standard output.
270
271       A scalar reference
272            If $output is a scalar reference, the compressed data will be
273            stored in $$output.
274
275       If the $output parameter is any other type, "IO::Compress::Gzip"::new
276       will return undef.
277
278       Constructor Options
279
280       "OPTS" is any combination of the following options:
281
282       "AutoClose => 0⎪1"
283            This option is only valid when the $output parameter is a filehan‐
284            dle. If specified, and the value is true, it will result in the
285            $output being closed once either the "close" method is called or
286            the "IO::Compress::Gzip" object is destroyed.
287
288            This parameter defaults to 0.
289
290       "Append => 0⎪1"
291            Opens $output in append mode.
292
293            The behaviour of this option is dependent on the type of $output.
294
295            * A Buffer
296                 If $output is a buffer and "Append" is enabled, all com‐
297                 pressed data will be append to the end if $output. Otherwise
298                 $output will be cleared before any data is written to it.
299
300            * A Filename
301                 If $output is a filename and "Append" is enabled, the file
302                 will be opened in append mode. Otherwise the contents of the
303                 file, if any, will be truncated before any compressed data is
304                 written to it.
305
306            * A Filehandle
307                 If $output is a filehandle, the file pointer will be posi‐
308                 tioned to the end of the file via a call to "seek" before any
309                 compressed data is written to it.  Otherwise the file pointer
310                 will not be moved.
311
312            This parameter defaults to 0.
313
314       "Merge => 0⎪1"
315            This option is used to compress input data and append it to an
316            existing compressed data stream in $output. The end result is a
317            single compressed data stream stored in $output.
318
319            It is a fatal error to attempt to use this option when $output is
320            not an RFC 1952 data stream.
321
322            There are a number of other limitations with the "Merge" option:
323
324            1    This module needs to have been built with zlib 1.2.1 or bet‐
325                 ter to work. A fatal error will be thrown if "Merge" is used
326                 with an older version of zlib.
327
328            2    If $output is a file or a filehandle, it must be seekable.
329
330            This parameter defaults to 0.
331
332       -Level
333            Defines the compression level used by zlib. The value should
334            either be a number between 0 and 9 (0 means no compression and 9
335            is maximum compression), or one of the symbolic constants defined
336            below.
337
338               Z_NO_COMPRESSION
339               Z_BEST_SPEED
340               Z_BEST_COMPRESSION
341               Z_DEFAULT_COMPRESSION
342
343            The default is Z_DEFAULT_COMPRESSION.
344
345            Note, these constants are not imported by "IO::Compress::Gzip" by
346            default.
347
348                use IO::Compress::Gzip qw(:strategy);
349                use IO::Compress::Gzip qw(:constants);
350                use IO::Compress::Gzip qw(:all);
351
352       -Strategy
353            Defines the strategy used to tune the compression. Use one of the
354            symbolic constants defined below.
355
356               Z_FILTERED
357               Z_HUFFMAN_ONLY
358               Z_RLE
359               Z_FIXED
360               Z_DEFAULT_STRATEGY
361
362            The default is Z_DEFAULT_STRATEGY.
363
364       "Minimal => 0⎪1"
365            If specified, this option will force the creation of the smallest
366            possible compliant gzip header (which is exactly 10 bytes long) as
367            defined in RFC 1952.
368
369            See the section titled "Compliance" in RFC 1952 for a definition
370            of the values used for the fields in the gzip header.
371
372            All other parameters that control the content of the gzip header
373            will be ignored if this parameter is set to 1.
374
375            This parameter defaults to 0.
376
377       "Comment => $comment"
378            Stores the contents of $comment in the COMMENT field in the gzip
379            header.  By default, no comment field is written to the gzip file.
380
381            If the "-Strict" option is enabled, the comment can only consist
382            of ISO 8859-1 characters plus line feed.
383
384            If the "-Strict" option is disabled, the comment field can contain
385            any character except NULL. If any null characters are present, the
386            field will be truncated at the first NULL.
387
388       "Name => $string"
389            Stores the contents of $string in the gzip NAME header field. If
390            "Name" is not specified, no gzip NAME field will be created.
391
392            If the "-Strict" option is enabled, $string can only consist of
393            ISO 8859-1 characters.
394
395            If "-Strict" is disabled, then $string can contain any character
396            except NULL. If any null characters are present, the field will be
397            truncated at the first NULL.
398
399       "Time => $number"
400            Sets the MTIME field in the gzip header to $number.
401
402            This field defaults to the time the "IO::Compress::Gzip" object
403            was created if this option is not specified.
404
405       "TextFlag => 0⎪1"
406            This parameter controls the setting of the FLG.FTEXT bit in the
407            gzip header. It is used to signal that the data stored in the gzip
408            file/buffer is probably text.
409
410            The default is 0.
411
412       "HeaderCRC => 0⎪1"
413            When true this parameter will set the FLG.FHCRC bit to 1 in the
414            gzip header and set the CRC16 header field to the CRC of the com‐
415            plete gzip header except the CRC16 field itself.
416
417            Note that gzip files created with the "HeaderCRC" flag set to 1
418            cannot be read by most, if not all, of the the standard gunzip
419            utilities, most notably gzip version 1.2.4. You should therefore
420            avoid using this option if you want to maximize the portability of
421            your gzip files.
422
423            This parameter defaults to 0.
424
425       "OS_Code => $value"
426            Stores $value in the gzip OS header field. A number between 0 and
427            255 is valid.
428
429            If not specified, this parameter defaults to the OS code of the
430            Operating System this module was built on. The value 3 is used as
431            a catch-all for all Unix variants and unknown Operating Systems.
432
433       "ExtraField => $data"
434            This parameter allows additional metadata to be stored in the
435            ExtraField in the gzip header. An RFC 1952 compliant ExtraField
436            consists of zero or more subfields. Each subfield consists of a
437            two byte header followed by the subfield data.
438
439            The list of subfields can be supplied in any of the following for‐
440            mats
441
442                -ExtraField => [$id1, $data1,
443                                $id2, $data2,
444                                 ...
445                               ]
446                -ExtraField => [ [$id1 => $data1],
447                                 [$id2 => $data2],
448                                 ...
449                               ]
450                -ExtraField => { $id1 => $data1,
451                                 $id2 => $data2,
452                                 ...
453                               }
454
455            Where $id1, $id2 are two byte subfield ID's. The second byte of
456            the ID cannot be 0, unless the "Strict" option has been disabled.
457
458            If you use the hash syntax, you have no control over the order in
459            which the ExtraSubFields are stored, plus you cannot have Sub‐
460            Fields with duplicate ID.
461
462            Alternatively the list of subfields can by supplied as a scalar,
463            thus
464
465                -ExtraField => $rawdata
466
467            If you use the raw format, and the "Strict" option is enabled,
468            "IO::Compress::Gzip" will check that $rawdata consists of zero or
469            more conformant sub-fields. When "Strict" is disabled, $rawdata
470            can consist of any arbitrary byte stream.
471
472            The maximum size of the Extra Field 65535 bytes.
473
474       "ExtraFlags => $value"
475            Sets the XFL byte in the gzip header to $value.
476
477            If this option is not present, the value stored in XFL field will
478            be determined by the setting of the "Level" option.
479
480            If "Level => Z_BEST_SPEED" has been specified then XFL is set to
481            2.  If "Level => Z_BEST_COMPRESSION" has been specified then XFL
482            is set to 4.  Otherwise XFL is set to 0.
483
484       "Strict => 0⎪1"
485            "Strict" will optionally police the values supplied with other
486            options to ensure they are compliant with RFC1952.
487
488            This option is enabled by default.
489
490            If "Strict" is enabled the following behaviour will be policed:
491
492            *    The value supplied with the "Name" option can only contain
493                 ISO 8859-1 characters.
494
495            *    The value supplied with the "Comment" option can only contain
496                 ISO 8859-1 characters plus line-feed.
497
498            *    The values supplied with the "-Name" and "-Comment" options
499                 cannot contain multiple embedded nulls.
500
501            *    If an "ExtraField" option is specified and it is a simple
502                 scalar, it must conform to the sub-field structure as defined
503                 in RFC 1952.
504
505            *    If an "ExtraField" option is specified the second byte of the
506                 ID will be checked in each subfield to ensure that it does
507                 not contain the reserved value 0x00.
508
509            When "Strict" is disabled the following behaviour will be policed:
510
511            *    The value supplied with "-Name" option can contain any char‐
512                 acter except NULL.
513
514            *    The value supplied with "-Comment" option can contain any
515                 character except NULL.
516
517            *    The values supplied with the "-Name" and "-Comment" options
518                 can contain multiple embedded nulls. The string written to
519                 the gzip header will consist of the characters up to, but not
520                 including, the first embedded NULL.
521
522            *    If an "ExtraField" option is specified and it is a simple
523                 scalar, the structure will not be checked. The only error is
524                 if the length is too big.
525
526            *    The ID header in an "ExtraField" sub-field can consist of any
527                 two bytes.
528
529       Examples
530
531       TODO
532

Methods

534       print
535
536       Usage is
537
538           $z->print($data)
539           print $z $data
540
541       Compresses and outputs the contents of the $data parameter. This has
542       the same behaviour as the "print" built-in.
543
544       Returns true if successful.
545
546       printf
547
548       Usage is
549
550           $z->printf($format, $data)
551           printf $z $format, $data
552
553       Compresses and outputs the contents of the $data parameter.
554
555       Returns true if successful.
556
557       syswrite
558
559       Usage is
560
561           $z->syswrite $data
562           $z->syswrite $data, $length
563           $z->syswrite $data, $length, $offset
564
565       Compresses and outputs the contents of the $data parameter.
566
567       Returns the number of uncompressed bytes written, or "undef" if unsuc‐
568       cessful.
569
570       write
571
572       Usage is
573
574           $z->write $data
575           $z->write $data, $length
576           $z->write $data, $length, $offset
577
578       Compresses and outputs the contents of the $data parameter.
579
580       Returns the number of uncompressed bytes written, or "undef" if unsuc‐
581       cessful.
582
583       flush
584
585       Usage is
586
587           $z->flush;
588           $z->flush($flush_type);
589
590       Flushes any pending compressed data to the output file/buffer.
591
592       This method takes an optional parameter, $flush_type, that controls how
593       the flushing will be carried out. By default the $flush_type used is
594       "Z_FINISH". Other valid values for $flush_type are "Z_NO_FLUSH",
595       "Z_SYNC_FLUSH", "Z_FULL_FLUSH" and "Z_BLOCK". It is strongly recom‐
596       mended that you only set the "flush_type" parameter if you fully under‐
597       stand the implications of what it does - overuse of "flush" can seri‐
598       ously degrade the level of compression achieved. See the "zlib" docu‐
599       mentation for details.
600
601       Returns true on success.
602
603       tell
604
605       Usage is
606
607           $z->tell()
608           tell $z
609
610       Returns the uncompressed file offset.
611
612       eof
613
614       Usage is
615
616           $z->eof();
617           eof($z);
618
619       Returns true if the "close" method has been called.
620
621       seek
622
623           $z->seek($position, $whence);
624           seek($z, $position, $whence);
625
626       Provides a sub-set of the "seek" functionality, with the restriction
627       that it is only legal to seek forward in the output file/buffer.  It is
628       a fatal error to attempt to seek backward.
629
630       Empty parts of the file/buffer will have NULL (0x00) bytes written to
631       them.
632
633       The $whence parameter takes one the usual values, namely SEEK_SET,
634       SEEK_CUR or SEEK_END.
635
636       Returns 1 on success, 0 on failure.
637
638       binmode
639
640       Usage is
641
642           $z->binmode
643           binmode $z ;
644
645       This is a noop provided for completeness.
646
647       opened
648
649           $z->opened()
650
651       Returns true if the object currently refers to a opened file/buffer.
652
653       autoflush
654
655           my $prev = $z->autoflush()
656           my $prev = $z->autoflush(EXPR)
657
658       If the $z object is associated with a file or a filehandle, this method
659       returns the current autoflush setting for the underlying filehandle. If
660       "EXPR" is present, and is non-zero, it will enable flushing after every
661       write/print operation.
662
663       If $z is associated with a buffer, this method has no effect and always
664       returns "undef".
665
666       Note that the special variable $⎪ cannot be used to set or retrieve the
667       autoflush setting.
668
669       input_line_number
670
671           $z->input_line_number()
672           $z->input_line_number(EXPR)
673
674       This method always returns "undef" when compressing.
675
676       fileno
677
678           $z->fileno()
679           fileno($z)
680
681       If the $z object is associated with a file or a filehandle, this method
682       will return the underlying file descriptor.
683
684       If the $z object is is associated with a buffer, this method will
685       return undef.
686
687       close
688
689           $z->close() ;
690           close $z ;
691
692       Flushes any pending compressed data and then closes the output
693       file/buffer.
694
695       For most versions of Perl this method will be automatically invoked if
696       the IO::Compress::Gzip object is destroyed (either explicitly or by the
697       variable with the reference to the object going out of scope). The
698       exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
699       cases, the "close" method will be called automatically, but not until
700       global destruction of all live objects when the program is terminating.
701
702       Therefore, if you want your scripts to be able to run on all versions
703       of Perl, you should call "close" explicitly and not rely on automatic
704       closing.
705
706       Returns true on success, otherwise 0.
707
708       If the "AutoClose" option has been enabled when the IO::Compress::Gzip
709       object was created, and the object is associated with a file, the
710       underlying file will also be closed.
711
712       newStream([OPTS])
713
714       Usage is
715
716           $z->newStream( [OPTS] )
717
718       Closes the current compressed data stream and starts a new one.
719
720       OPTS consists of any of the the options that are available when creat‐
721       ing the $z object.
722
723       See the "Constructor Options" section for more details.
724
725       deflateParams
726
727       Usage is
728
729           $z->deflateParams
730
731       TODO
732

Importing

734       A number of symbolic constants are required by some methods in
735       "IO::Compress::Gzip". None are imported by default.
736
737       :all Imports "gzip", $GzipError and all symbolic constants that can be
738            used by "IO::Compress::Gzip". Same as doing this
739
740                use IO::Compress::Gzip qw(gzip $GzipError :constants) ;
741
742       :constants
743            Import all symbolic constants. Same as doing this
744
745                use IO::Compress::Gzip qw(:flush :level :strategy) ;
746
747       :flush
748            These symbolic constants are used by the "flush" method.
749
750                Z_NO_FLUSH
751                Z_PARTIAL_FLUSH
752                Z_SYNC_FLUSH
753                Z_FULL_FLUSH
754                Z_FINISH
755                Z_BLOCK
756
757       :level
758            These symbolic constants are used by the "Level" option in the
759            constructor.
760
761                Z_NO_COMPRESSION
762                Z_BEST_SPEED
763                Z_BEST_COMPRESSION
764                Z_DEFAULT_COMPRESSION
765
766       :strategy
767            These symbolic constants are used by the "Strategy" option in the
768            constructor.
769
770                Z_FILTERED
771                Z_HUFFMAN_ONLY
772                Z_RLE
773                Z_FIXED
774                Z_DEFAULT_STRATEGY
775
776       For
777

EXAMPLES

779       TODO
780

AUTHOR

805       This module was written by Paul Marquess, pmqs@cpan.org.
806

MODIFICATION HISTORY

808       See the Changes file.
809

COPYRIGHT AND LICENSE

811       Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
812
813       This program is free software; you can redistribute it and/or modify it
814       under the same terms as Perl itself.
815
816
817
818perl v5.8.8                       2007-06-18             IO::Compress::Gzip(3)