IO::Compress::Gzip(3pm)

1IO::Compress::Gzip(3pm)Perl Programmers Reference GuideIO::Compress::Gzip(3pm)
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
54       module.
55
56       For reading RFC 1952 files/buffers, see the companion module
57       IO::Uncompress::Gunzip.
58

Functional Interface

60       A top-level function, "gzip", is provided to carry out "one-shot"
61       compression between buffers and/or files. For finer control over the
62       compression 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       "gzip" expects at least two parameters, $input and $output.
73
74       The $input parameter
75
76       The parameter, $input, is used to define the source of the uncompressed
77       data.
78
79       It can take one of the following forms:
80
81       A filename
82            If the $input parameter is a simple scalar, it is assumed to be a
83            filename. This file will be opened for reading and the input data
84            will be read from it.
85
86       A filehandle
87            If the $input parameter is a filehandle, the input data will be
88            read from it.  The string '-' can be used as an alias for standard
89            input.
90
91       A scalar reference
92            If $input is a scalar reference, the input data will be read from
93            $$input.
94
95       An array reference
96            If $input is an array reference, each element in the array must be
97            a filename.
98
99            The input data will be read from each file in turn.
100
101            The complete array will be walked to ensure that it only contains
102            valid filenames before any data is compressed.
103
104       An Input FileGlob string
105            If $input is a string that is delimited by the characters "<" and
106            ">" "gzip" will assume that it is an input fileglob string. The
107            input is the list of files that match the fileglob.
108
109            If the fileglob does not match any files ...
110
111            See File::GlobMapper for more details.
112
113       If the $input parameter is any other type, "undef" will be returned.
114
115       In addition, if $input is a simple filename, the default values for the
116       "Name" and "Time" options will be sourced from that file.
117
118       If you do not want to use these defaults they can be overridden by
119       explicitly setting the "Name" and "Time" options or by setting the
120       "Minimal" parameter.
121
122       The $output parameter
123
124       The parameter $output is used to control the destination of the
125       compressed data. This parameter can take one of these forms.
126
127       A filename
128            If the $output parameter is a simple scalar, it is assumed to be a
129            filename.  This file will be opened for writing and the compressed
130            data will be written to it.
131
132       A filehandle
133            If the $output parameter is a filehandle, the compressed data will
134            be written to it.  The string '-' can be used as an alias for
135            standard output.
136
137       A scalar reference
138            If $output is a scalar reference, the compressed data will be
139            stored in $$output.
140
141       An Array Reference
142            If $output is an array reference, the compressed data will be
143            pushed onto the array.
144
145       An Output FileGlob
146            If $output is a string that is delimited by the characters "<" and
147            ">" "gzip" will assume that it is an output fileglob string. The
148            output is the list of files that match the fileglob.
149
150            When $output is an fileglob string, $input must also be a fileglob
151            string. Anything else is an error.
152
153       If the $output parameter is any other type, "undef" will be returned.
154
155   Notes
156       When $input maps to multiple files/buffers and $output is a single
157       file/buffer the input files/buffers will be stored in $output as a
158       concatenated series of compressed data streams.
159
160   Optional Parameters
161       Unless specified below, the optional parameters for "gzip", "OPTS", are
162       the same as those used with the OO interface defined in the
163       "Constructor Options" section below.
164
165       "AutoClose => 0|1"
166            This option applies to any input or output data streams to "gzip"
167            that are filehandles.
168
169            If "AutoClose" is specified, and the value is true, it will result
170            in all input and/or output filehandles being closed once "gzip"
171            has completed.
172
173            This parameter defaults to 0.
174
175       "BinModeIn => 0|1"
176            When reading from a file or filehandle, set "binmode" before
177            reading.
178
179            Defaults to 0.
180
181       "Append => 0|1"
182            The behaviour of this option is dependent on the type of output
183            data stream.
184
185            ·    A Buffer
186
187                 If "Append" is enabled, all compressed data will be append to
188                 the end of the output buffer. Otherwise the output buffer
189                 will be cleared before any compressed data is written to it.
190
191            ·    A Filename
192
193                 If "Append" is enabled, the file will be opened in append
194                 mode. Otherwise the contents of the file, if any, will be
195                 truncated before any compressed data is written to it.
196
197            ·    A Filehandle
198
199                 If "Append" is enabled, the filehandle will be positioned to
200                 the end of the file via a call to "seek" before any
201                 compressed data is written to it.  Otherwise the file pointer
202                 will not be moved.
203
204            When "Append" is specified, and set to true, it will append all
205            compressed data to the output data stream.
206
207            So when the output is a filehandle it will carry out a seek to the
208            eof before writing any compressed data. If the output is a
209            filename, it will be opened for appending. If the output is a
210            buffer, all compressed data will be appened to the existing
211            buffer.
212
213            Conversely when "Append" is not specified, or it is present and is
214            set to false, it will operate as follows.
215
216            When the output is a filename, it will truncate the contents of
217            the file before writing any compressed data. If the output is a
218            filehandle its position will not be changed. If the output is a
219            buffer, it will be wiped before any compressed data is output.
220
221            Defaults to 0.
222
223   Examples
224       To read the contents of the file "file1.txt" and write the compressed
225       data to the file "file1.txt.gz".
226
227           use strict ;
228           use warnings ;
229           use IO::Compress::Gzip qw(gzip $GzipError) ;
230
231           my $input = "file1.txt";
232           gzip $input => "$input.gz"
233               or die "gzip failed: $GzipError\n";
234
235       To read from an existing Perl filehandle, $input, and write the
236       compressed data to a buffer, $buffer.
237
238           use strict ;
239           use warnings ;
240           use IO::Compress::Gzip qw(gzip $GzipError) ;
241           use IO::File ;
242
243           my $input = new IO::File "<file1.txt"
244               or die "Cannot open 'file1.txt': $!\n" ;
245           my $buffer ;
246           gzip $input => \$buffer
247               or die "gzip failed: $GzipError\n";
248
249       To compress all files in the directory "/my/home" that match "*.txt"
250       and store the compressed data in the same directory
251
252           use strict ;
253           use warnings ;
254           use IO::Compress::Gzip qw(gzip $GzipError) ;
255
256           gzip '</my/home/*.txt>' => '<*.gz>'
257               or die "gzip failed: $GzipError\n";
258
259       and if you want to compress each file one at a time, this will do the
260       trick
261
262           use strict ;
263           use warnings ;
264           use IO::Compress::Gzip qw(gzip $GzipError) ;
265
266           for my $input ( glob "/my/home/*.txt" )
267           {
268               my $output = "$input.gz" ;
269               gzip $input => $output
270                   or die "Error compressing '$input': $GzipError\n";
271           }
272

OO Interface

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

Methods

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

Importing

756       A number of symbolic constants are required by some methods in
757       "IO::Compress::Gzip". None are imported by default.
758
759       :all Imports "gzip", $GzipError and all symbolic constants that can be
760            used by "IO::Compress::Gzip". Same as doing this
761
762                use IO::Compress::Gzip qw(gzip $GzipError :constants) ;
763
764       :constants
765            Import all symbolic constants. Same as doing this
766
767                use IO::Compress::Gzip qw(:flush :level :strategy) ;
768
769       :flush
770            These symbolic constants are used by the "flush" method.
771
772                Z_NO_FLUSH
773                Z_PARTIAL_FLUSH
774                Z_SYNC_FLUSH
775                Z_FULL_FLUSH
776                Z_FINISH
777                Z_BLOCK
778
779       :level
780            These symbolic constants are used by the "Level" option in the
781            constructor.
782
783                Z_NO_COMPRESSION
784                Z_BEST_SPEED
785                Z_BEST_COMPRESSION
786                Z_DEFAULT_COMPRESSION
787
788       :strategy
789            These symbolic constants are used by the "Strategy" option in the
790            constructor.
791
792                Z_FILTERED
793                Z_HUFFMAN_ONLY
794                Z_RLE
795                Z_FIXED
796                Z_DEFAULT_STRATEGY
797

EXAMPLES

799   Apache::GZip Revisited
800       See IO::Compress::FAQ
801
802   Working with Net::FTP
803       See IO::Compress::FAQ
804

AUTHOR

831       This module was written by Paul Marquess, pmqs@cpan.org.
832

MODIFICATION HISTORY

834       See the Changes file.
835

COPYRIGHT AND LICENSE

837       Copyright (c) 2005-2010 Paul Marquess. All rights reserved.
838
839       This program is free software; you can redistribute it and/or modify it
840       under the same terms as Perl itself.
841
842
843
844perl v5.12.4                      2011-06-07           IO::Compress::Gzip(3pm)