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

OO Interface

302   Constructor
303       The format of the constructor for "IO::Compress::Gzip" is shown below
304
305           my $z = IO::Compress::Gzip->new( $output [,OPTS] )
306               or die "IO::Compress::Gzip failed: $GzipError\n";
307
308       The constructor takes one mandatory parameter, $output, defined below
309       and zero or more "OPTS", defined in "Constructor Options".
310
311       It returns an "IO::Compress::Gzip" object on success and "undef" on
312       failure.  The variable $GzipError will contain an error message on
313       failure.
314
315       If you are running Perl 5.005 or better the object, $z, returned from
316       IO::Compress::Gzip can be used exactly like an IO::File filehandle.
317       This means that all normal output file operations can be carried out
318       with $z.  For example, to write to a compressed file/buffer you can use
319       either of these forms
320
321           $z->print("hello world\n");
322           print $z "hello world\n";
323
324       Below is a simple exaple of using the OO interface to create an output
325       file "myfile.gz" and write some data to it.
326
327           my $filename = "myfile.gz";
328           my $z = IO::Compress::Gzip->new($filename)
329               or die "IO::Compress::Gzip failed: $GzipError\n";
330
331           $z->print("abcde");
332           $z->close();
333
334       See the "Examples" for more.
335
336       The mandatory parameter $output is used to control the destination of
337       the compressed data. This parameter can take one of these forms.
338
339       A filename
340            If the $output parameter is a simple scalar, it is assumed to be a
341            filename. This file will be opened for writing and the compressed
342            data will be written to it.
343
344       A filehandle
345            If the $output parameter is a filehandle, the compressed data will
346            be written to it.  The string '-' can be used as an alias for
347            standard output.
348
349       A scalar reference
350            If $output is a scalar reference, the compressed data will be
351            stored in $$output.
352
353       If the $output parameter is any other type, "IO::Compress::Gzip"::new
354       will return undef.
355
356   Constructor Options
357       "OPTS" is any combination of zero or more the following options:
358
359       "AutoClose => 0|1"
360            This option is only valid when the $output parameter is a
361            filehandle. If specified, and the value is true, it will result in
362            the $output being closed once either the "close" method is called
363            or the "IO::Compress::Gzip" object is destroyed.
364
365            This parameter defaults to 0.
366
367       "Append => 0|1"
368            Opens $output in append mode.
369
370            The behaviour of this option is dependent on the type of $output.
371
372            •    A Buffer
373
374                 If $output is a buffer and "Append" is enabled, all
375                 compressed data will be append to the end of $output.
376                 Otherwise $output will be cleared before any data is written
377                 to it.
378
379            •    A Filename
380
381                 If $output is a filename and "Append" is enabled, the file
382                 will be opened in append mode. Otherwise the contents of the
383                 file, if any, will be truncated before any compressed data is
384                 written to it.
385
386            •    A Filehandle
387
388                 If $output is a filehandle, the file pointer will be
389                 positioned to the end of the file via a call to "seek" before
390                 any compressed data is written to it.  Otherwise the file
391                 pointer will not be moved.
392
393            This parameter defaults to 0.
394
395       "Merge => 0|1"
396            This option is used to compress input data and append it to an
397            existing compressed data stream in $output. The end result is a
398            single compressed data stream stored in $output.
399
400            It is a fatal error to attempt to use this option when $output is
401            not an RFC 1952 data stream.
402
403            There are a number of other limitations with the "Merge" option:
404
405            1.   This module needs to have been built with zlib 1.2.1 or
406                 better to work. A fatal error will be thrown if "Merge" is
407                 used with an older version of zlib.
408
409            2.   If $output is a file or a filehandle, it must be seekable.
410
411            This parameter defaults to 0.
412
413       -Level
414            Defines the compression level used by zlib. The value should
415            either be a number between 0 and 9 (0 means no compression and 9
416            is maximum compression), or one of the symbolic constants defined
417            below.
418
419               Z_NO_COMPRESSION
420               Z_BEST_SPEED
421               Z_BEST_COMPRESSION
422               Z_DEFAULT_COMPRESSION
423
424            The default is Z_DEFAULT_COMPRESSION.
425
426            Note, these constants are not imported by "IO::Compress::Gzip" by
427            default.
428
429                use IO::Compress::Gzip qw(:strategy);
430                use IO::Compress::Gzip qw(:constants);
431                use IO::Compress::Gzip qw(:all);
432
433       -Strategy
434            Defines the strategy used to tune the compression. Use one of the
435            symbolic constants defined below.
436
437               Z_FILTERED
438               Z_HUFFMAN_ONLY
439               Z_RLE
440               Z_FIXED
441               Z_DEFAULT_STRATEGY
442
443            The default is Z_DEFAULT_STRATEGY.
444
445       "Minimal => 0|1"
446            If specified, this option will force the creation of the smallest
447            possible compliant gzip header (which is exactly 10 bytes long) as
448            defined in RFC 1952.
449
450            See the section titled "Compliance" in RFC 1952 for a definition
451            of the values used for the fields in the gzip header.
452
453            All other parameters that control the content of the gzip header
454            will be ignored if this parameter is set to 1.
455
456            This parameter defaults to 0.
457
458       "Comment => $comment"
459            Stores the contents of $comment in the COMMENT field in the gzip
460            header.  By default, no comment field is written to the gzip file.
461
462            If the "-Strict" option is enabled, the comment can only consist
463            of ISO 8859-1 characters plus line feed.
464
465            If the "-Strict" option is disabled, the comment field can contain
466            any character except NULL. If any null characters are present, the
467            field will be truncated at the first NULL.
468
469       "Name => $string"
470            Stores the contents of $string in the gzip NAME header field. If
471            "Name" is not specified, no gzip NAME field will be created.
472
473            If the "-Strict" option is enabled, $string can only consist of
474            ISO 8859-1 characters.
475
476            If "-Strict" is disabled, then $string can contain any character
477            except NULL. If any null characters are present, the field will be
478            truncated at the first NULL.
479
480       "Time => $number"
481            Sets the MTIME field in the gzip header to $number.
482
483            This field defaults to the time the "IO::Compress::Gzip" object
484            was created if this option is not specified.
485
486       "TextFlag => 0|1"
487            This parameter controls the setting of the FLG.FTEXT bit in the
488            gzip header. It is used to signal that the data stored in the gzip
489            file/buffer is probably text.
490
491            The default is 0.
492
493       "HeaderCRC => 0|1"
494            When true this parameter will set the FLG.FHCRC bit to 1 in the
495            gzip header and set the CRC16 header field to the CRC of the
496            complete gzip header except the CRC16 field itself.
497
498            Note that gzip files created with the "HeaderCRC" flag set to 1
499            cannot be read by most, if not all, of the standard gunzip
500            utilities, most notably gzip version 1.2.4. You should therefore
501            avoid using this option if you want to maximize the portability of
502            your gzip files.
503
504            This parameter defaults to 0.
505
506       "OS_Code => $value"
507            Stores $value in the gzip OS header field. A number between 0 and
508            255 is valid.
509
510            If not specified, this parameter defaults to the OS code of the
511            Operating System this module was built on. The value 3 is used as
512            a catch-all for all Unix variants and unknown Operating Systems.
513
514       "ExtraField => $data"
515            This parameter allows additional metadata to be stored in the
516            ExtraField in the gzip header. An RFC 1952 compliant ExtraField
517            consists of zero or more subfields. Each subfield consists of a
518            two byte header followed by the subfield data.
519
520            The list of subfields can be supplied in any of the following
521            formats
522
523                -ExtraField => [$id1, $data1,
524                                $id2, $data2,
525                                 ...
526                               ]
527                -ExtraField => [ [$id1 => $data1],
528                                 [$id2 => $data2],
529                                 ...
530                               ]
531                -ExtraField => { $id1 => $data1,
532                                 $id2 => $data2,
533                                 ...
534                               }
535
536            Where $id1, $id2 are two byte subfield ID's. The second byte of
537            the ID cannot be 0, unless the "Strict" option has been disabled.
538
539            If you use the hash syntax, you have no control over the order in
540            which the ExtraSubFields are stored, plus you cannot have
541            SubFields with duplicate ID.
542
543            Alternatively the list of subfields can by supplied as a scalar,
544            thus
545
546                -ExtraField => $rawdata
547
548            If you use the raw format, and the "Strict" option is enabled,
549            "IO::Compress::Gzip" will check that $rawdata consists of zero or
550            more conformant sub-fields. When "Strict" is disabled, $rawdata
551            can consist of any arbitrary byte stream.
552
553            The maximum size of the Extra Field 65535 bytes.
554
555       "ExtraFlags => $value"
556            Sets the XFL byte in the gzip header to $value.
557
558            If this option is not present, the value stored in XFL field will
559            be determined by the setting of the "Level" option.
560
561            If "Level => Z_BEST_SPEED" has been specified then XFL is set to
562            2.  If "Level => Z_BEST_COMPRESSION" has been specified then XFL
563            is set to 4.  Otherwise XFL is set to 0.
564
565       "Strict => 0|1"
566            "Strict" will optionally police the values supplied with other
567            options to ensure they are compliant with RFC1952.
568
569            This option is enabled by default.
570
571            If "Strict" is enabled the following behaviour will be policed:
572
573            •    The value supplied with the "Name" option can only contain
574                 ISO 8859-1 characters.
575
576            •    The value supplied with the "Comment" option can only contain
577                 ISO 8859-1 characters plus line-feed.
578
579            •    The values supplied with the "-Name" and "-Comment" options
580                 cannot contain multiple embedded nulls.
581
582            •    If an "ExtraField" option is specified and it is a simple
583                 scalar, it must conform to the sub-field structure as defined
584                 in RFC 1952.
585
586            •    If an "ExtraField" option is specified the second byte of the
587                 ID will be checked in each subfield to ensure that it does
588                 not contain the reserved value 0x00.
589
590            When "Strict" is disabled the following behaviour will be policed:
591
592            •    The value supplied with "-Name" option can contain any
593                 character except NULL.
594
595            •    The value supplied with "-Comment" option can contain any
596                 character except NULL.
597
598            •    The values supplied with the "-Name" and "-Comment" options
599                 can contain multiple embedded nulls. The string written to
600                 the gzip header will consist of the characters up to, but not
601                 including, the first embedded NULL.
602
603            •    If an "ExtraField" option is specified and it is a simple
604                 scalar, the structure will not be checked. The only error is
605                 if the length is too big.
606
607            •    The ID header in an "ExtraField" sub-field can consist of any
608                 two bytes.
609
610   Examples
611       Streaming
612
613       This very simple command line example demonstrates the streaming
614       capabilities of the module. The code reads data from STDIN or all the
615       files given on the commandline, compresses it, and writes the
616       compressed data to STDOUT.
617
618           use strict ;
619           use warnings ;
620           use IO::Compress::Gzip qw(gzip $GzipError) ;
621
622           my $z = IO::Compress::Gzip->new("-", Stream => 1)
623               or die "IO::Compress::Gzip failed: $GzipError\n";
624
625           while (<>) {
626               $z->print("abcde");
627           }
628           $z->close();
629
630       Note the use of "-" to means "STDOUT". Alternatively you can use
631       "\*STDOUT".
632
633       Compressing a file from the filesystem
634
635       To read the contents of the file "file1.txt" and write the compressed
636       data to the file "file1.txt.gz" there are a few options
637
638       Start by creating the compression object and opening the input file
639
640           use strict ;
641           use warnings ;
642           use IO::Compress::Gzip qw(gzip $GzipError) ;
643
644           my $input = "file1.txt";
645           my $z = IO::Compress::Gzip->new("file1.txt.gz")
646               or die "IO::Compress::Gzip failed: $GzipError\n";
647
648           # open the input file
649           open my $fh, "<", "file1.txt"
650               or die "Cannot open file1.txt: $!\n";
651
652           # loop through the input file & write to the compressed file
653           while (<$fh>) {
654               $z->print($_);
655           }
656
657           # not forgetting to close the compressed file
658           $z->close();
659

Methods

661   print
662       Usage is
663
664           $z->print($data)
665           print $z $data
666
667       Compresses and outputs the contents of the $data parameter. This has
668       the same behaviour as the "print" built-in.
669
670       Returns true if successful.
671
672   printf
673       Usage is
674
675           $z->printf($format, $data)
676           printf $z $format, $data
677
678       Compresses and outputs the contents of the $data parameter.
679
680       Returns true if successful.
681
682   syswrite
683       Usage is
684
685           $z->syswrite $data
686           $z->syswrite $data, $length
687           $z->syswrite $data, $length, $offset
688
689       Compresses and outputs the contents of the $data parameter.
690
691       Returns the number of uncompressed bytes written, or "undef" if
692       unsuccessful.
693
694   write
695       Usage is
696
697           $z->write $data
698           $z->write $data, $length
699           $z->write $data, $length, $offset
700
701       Compresses and outputs the contents of the $data parameter.
702
703       Returns the number of uncompressed bytes written, or "undef" if
704       unsuccessful.
705
706   flush
707       Usage is
708
709           $z->flush;
710           $z->flush($flush_type);
711
712       Flushes any pending compressed data to the output file/buffer.
713
714       This method takes an optional parameter, $flush_type, that controls how
715       the flushing will be carried out. By default the $flush_type used is
716       "Z_FINISH". Other valid values for $flush_type are "Z_NO_FLUSH",
717       "Z_SYNC_FLUSH", "Z_FULL_FLUSH" and "Z_BLOCK". It is strongly
718       recommended that you only set the "flush_type" parameter if you fully
719       understand the implications of what it does - overuse of "flush" can
720       seriously degrade the level of compression achieved. See the "zlib"
721       documentation for details.
722
723       Returns true on success.
724
725   tell
726       Usage is
727
728           $z->tell()
729           tell $z
730
731       Returns the uncompressed file offset.
732
733   eof
734       Usage is
735
736           $z->eof();
737           eof($z);
738
739       Returns true if the "close" method has been called.
740
741   seek
742           $z->seek($position, $whence);
743           seek($z, $position, $whence);
744
745       Provides a sub-set of the "seek" functionality, with the restriction
746       that it is only legal to seek forward in the output file/buffer.  It is
747       a fatal error to attempt to seek backward.
748
749       Empty parts of the file/buffer will have NULL (0x00) bytes written to
750       them.
751
752       The $whence parameter takes one the usual values, namely SEEK_SET,
753       SEEK_CUR or SEEK_END.
754
755       Returns 1 on success, 0 on failure.
756
757   binmode
758       Usage is
759
760           $z->binmode
761           binmode $z ;
762
763       This is a noop provided for completeness.
764
765   opened
766           $z->opened()
767
768       Returns true if the object currently refers to a opened file/buffer.
769
770   autoflush
771           my $prev = $z->autoflush()
772           my $prev = $z->autoflush(EXPR)
773
774       If the $z object is associated with a file or a filehandle, this method
775       returns the current autoflush setting for the underlying filehandle. If
776       "EXPR" is present, and is non-zero, it will enable flushing after every
777       write/print operation.
778
779       If $z is associated with a buffer, this method has no effect and always
780       returns "undef".
781
782       Note that the special variable $| cannot be used to set or retrieve the
783       autoflush setting.
784
785   input_line_number
786           $z->input_line_number()
787           $z->input_line_number(EXPR)
788
789       This method always returns "undef" when compressing.
790
791   fileno
792           $z->fileno()
793           fileno($z)
794
795       If the $z object is associated with a file or a filehandle, "fileno"
796       will return the underlying file descriptor. Once the "close" method is
797       called "fileno" will return "undef".
798
799       If the $z object is associated with a buffer, this method will return
800       "undef".
801
802   close
803           $z->close() ;
804           close $z ;
805
806       Flushes any pending compressed data and then closes the output
807       file/buffer.
808
809       For most versions of Perl this method will be automatically invoked if
810       the IO::Compress::Gzip object is destroyed (either explicitly or by the
811       variable with the reference to the object going out of scope). The
812       exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
813       cases, the "close" method will be called automatically, but not until
814       global destruction of all live objects when the program is terminating.
815
816       Therefore, if you want your scripts to be able to run on all versions
817       of Perl, you should call "close" explicitly and not rely on automatic
818       closing.
819
820       Returns true on success, otherwise 0.
821
822       If the "AutoClose" option has been enabled when the IO::Compress::Gzip
823       object was created, and the object is associated with a file, the
824       underlying file will also be closed.
825
826   newStream([OPTS])
827       Usage is
828
829           $z->newStream( [OPTS] )
830
831       Closes the current compressed data stream and starts a new one.
832
833       OPTS consists of any of the options that are available when creating
834       the $z object.
835
836       See the "Constructor Options" section for more details.
837
838   deflateParams
839       Usage is
840
841           $z->deflateParams
842
843       TODO
844

Importing

846       A number of symbolic constants are required by some methods in
847       "IO::Compress::Gzip". None are imported by default.
848
849       :all Imports "gzip", $GzipError and all symbolic constants that can be
850            used by "IO::Compress::Gzip". Same as doing this
851
852                use IO::Compress::Gzip qw(gzip $GzipError :constants) ;
853
854       :constants
855            Import all symbolic constants. Same as doing this
856
857                use IO::Compress::Gzip qw(:flush :level :strategy) ;
858
859       :flush
860            These symbolic constants are used by the "flush" method.
861
862                Z_NO_FLUSH
863                Z_PARTIAL_FLUSH
864                Z_SYNC_FLUSH
865                Z_FULL_FLUSH
866                Z_FINISH
867                Z_BLOCK
868
869       :level
870            These symbolic constants are used by the "Level" option in the
871            constructor.
872
873                Z_NO_COMPRESSION
874                Z_BEST_SPEED
875                Z_BEST_COMPRESSION
876                Z_DEFAULT_COMPRESSION
877
878       :strategy
879            These symbolic constants are used by the "Strategy" option in the
880            constructor.
881
882                Z_FILTERED
883                Z_HUFFMAN_ONLY
884                Z_RLE
885                Z_FIXED
886                Z_DEFAULT_STRATEGY
887

EXAMPLES

889   Apache::GZip Revisited
890       See IO::Compress::FAQ
891
892   Working with Net::FTP
893       See IO::Compress::FAQ
894

SUPPORT

896       General feedback/questions/bug reports should be sent to
897       <https://github.com/pmqs/IO-Copress/issues> (preferred) or
898       <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Copress>.
899

AUTHOR

932       This module was written by Paul Marquess, "pmqs@cpan.org".
933

MODIFICATION HISTORY

935       See the Changes file.
936

COPYRIGHT AND LICENSE

938       Copyright (c) 2005-2023 Paul Marquess. All rights reserved.
939
940       This program is free software; you can redistribute it and/or modify it
941       under the same terms as Perl itself.
942
943
944
945perl v5.38.0                      2023-07-26             IO::Compress::Gzip(3)