--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "IO::Compress::Gzip 3"
+.TH IO::Compress::Gzip 3 "2009-11-09" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+IO::Compress::Gzip \- Write RFC 1952 files/buffers
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\& use IO::Compress::Gzip qw(gzip $GzipError) ;
+.Ve
+.PP
+.Vb 2
+\& my $status = gzip $input => $output [,OPTS]
+\& or die "gzip failed: $GzipError\en";
+.Ve
+.PP
+.Vb 2
+\& my $z = new IO::Compress::Gzip $output [,OPTS]
+\& or die "gzip failed: $GzipError\en";
+.Ve
+.PP
+.Vb 14
+\& $z\->print($string);
+\& $z\->printf($format, $string);
+\& $z\->write($string);
+\& $z\->syswrite($string [, $length, $offset]);
+\& $z\->flush();
+\& $z\->tell();
+\& $z\->eof();
+\& $z\->seek($position, $whence);
+\& $z\->binmode();
+\& $z\->fileno();
+\& $z\->opened();
+\& $z\->autoflush();
+\& $z\->input_line_number();
+\& $z\->newStream( [OPTS] );
+.Ve
+.PP
+.Vb 1
+\& $z\->deflateParams();
+.Ve
+.PP
+.Vb 1
+\& $z\->close() ;
+.Ve
+.PP
+.Vb 1
+\& $GzipError ;
+.Ve
+.PP
+.Vb 1
+\& # IO::File mode
+.Ve
+.PP
+.Vb 8
+\& print $z $string;
+\& printf $z $format, $string;
+\& tell $z
+\& eof $z
+\& seek $z, $position, $whence
+\& binmode $z
+\& fileno $z
+\& close $z ;
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+This module provides a Perl interface that allows writing compressed
+data to files or buffer as defined in \s-1RFC\s0 1952.
+.PP
+All the gzip headers defined in \s-1RFC\s0 1952 can be created using
+this module.
+.PP
+For reading \s-1RFC\s0 1952 files/buffers, see the companion module
+IO::Uncompress::Gunzip.
+.SH "Functional Interface"
+.IX Header "Functional Interface"
+A top-level function, \f(CW\*(C`gzip\*(C'\fR, is provided to carry out
+\&\*(L"one\-shot\*(R" compression between buffers and/or files. For finer
+control over the compression process, see the \*(L"\s-1OO\s0 Interface\*(R"
+section.
+.PP
+.Vb 1
+\& use IO::Compress::Gzip qw(gzip $GzipError) ;
+.Ve
+.PP
+.Vb 2
+\& gzip $input => $output [,OPTS]
+\& or die "gzip failed: $GzipError\en";
+.Ve
+.PP
+The functional interface needs Perl5.005 or better.
+.ie n .Sh "gzip $input\fP => \f(CW$output [, \s-1OPTS\s0]"
+.el .Sh "gzip \f(CW$input\fP => \f(CW$output\fP [, \s-1OPTS\s0]"
+.IX Subsection "gzip $input => $output [, OPTS]"
+\&\f(CW\*(C`gzip\*(C'\fR expects at least two parameters, \f(CW$input\fR and \f(CW$output\fR.
+.PP
+\fIThe \f(CI$input\fI parameter\fR
+.IX Subsection "The $input parameter"
+.PP
+The parameter, \f(CW$input\fR, is used to define the source of
+the uncompressed data.
+.PP
+It can take one of the following forms:
+.IP "A filename" 5
+.IX Item "A filename"
+If the \f(CW$input\fR parameter is a simple scalar, it is assumed to be a
+filename. This file will be opened for reading and the input data
+will be read from it.
+.IP "A filehandle" 5
+.IX Item "A filehandle"
+If the \f(CW$input\fR parameter is a filehandle, the input data will be
+read from it.
+The string '\-' can be used as an alias for standard input.
+.IP "A scalar reference" 5
+.IX Item "A scalar reference"
+If \f(CW$input\fR is a scalar reference, the input data will be read
+from \f(CW$$input\fR.
+.IP "An array reference" 5
+.IX Item "An array reference"
+If \f(CW$input\fR is an array reference, each element in the array must be a
+filename.
+.Sp
+The input data will be read from each file in turn.
+.Sp
+The complete array will be walked to ensure that it only
+contains valid filenames before any data is compressed.
+.IP "An Input FileGlob string" 5
+.IX Item "An Input FileGlob string"
+If \f(CW$input\fR is a string that is delimited by the characters \*(L"<\*(R" and \*(L">\*(R"
+\&\f(CW\*(C`gzip\*(C'\fR will assume that it is an \fIinput fileglob string\fR. The
+input is the list of files that match the fileglob.
+.Sp
+If the fileglob does not match any files ...
+.Sp
+See File::GlobMapper for more details.
+.PP
+If the \f(CW$input\fR parameter is any other type, \f(CW\*(C`undef\*(C'\fR will be returned.
+.PP
+In addition, if \f(CW$input\fR is a simple filename, the default values for
+the \f(CW\*(C`Name\*(C'\fR and \f(CW\*(C`Time\*(C'\fR options will be sourced from that file.
+.PP
+If you do not want to use these defaults they can be overridden by
+explicitly setting the \f(CW\*(C`Name\*(C'\fR and \f(CW\*(C`Time\*(C'\fR options or by setting the
+\&\f(CW\*(C`Minimal\*(C'\fR parameter.
+.PP
+\fIThe \f(CI$output\fI parameter\fR
+.IX Subsection "The $output parameter"
+.PP
+The parameter \f(CW$output\fR is used to control the destination of the
+compressed data. This parameter can take one of these forms.
+.IP "A filename" 5
+.IX Item "A filename"
+If the \f(CW$output\fR parameter is a simple scalar, it is assumed to be a
+filename. This file will be opened for writing and the compressed
+data will be written to it.
+.IP "A filehandle" 5
+.IX Item "A filehandle"
+If the \f(CW$output\fR parameter is a filehandle, the compressed data
+will be written to it.
+The string '\-' can be used as an alias for standard output.
+.IP "A scalar reference" 5
+.IX Item "A scalar reference"
+If \f(CW$output\fR is a scalar reference, the compressed data will be
+stored in \f(CW$$output\fR.
+.IP "An Array Reference" 5
+.IX Item "An Array Reference"
+If \f(CW$output\fR is an array reference, the compressed data will be
+pushed onto the array.
+.IP "An Output FileGlob" 5
+.IX Item "An Output FileGlob"
+If \f(CW$output\fR is a string that is delimited by the characters \*(L"<\*(R" and \*(L">\*(R"
+\&\f(CW\*(C`gzip\*(C'\fR will assume that it is an \fIoutput fileglob string\fR. The
+output is the list of files that match the fileglob.
+.Sp
+When \f(CW$output\fR is an fileglob string, \f(CW$input\fR must also be a fileglob
+string. Anything else is an error.
+.PP
+If the \f(CW$output\fR parameter is any other type, \f(CW\*(C`undef\*(C'\fR will be returned.
+.Sh "Notes"
+.IX Subsection "Notes"
+When \f(CW$input\fR maps to multiple files/buffers and \f(CW$output\fR is a single
+file/buffer the input files/buffers will be stored
+in \f(CW$output\fR as a concatenated series of compressed data streams.
+.Sh "Optional Parameters"
+.IX Subsection "Optional Parameters"
+Unless specified below, the optional parameters for \f(CW\*(C`gzip\*(C'\fR,
+\&\f(CW\*(C`OPTS\*(C'\fR, are the same as those used with the \s-1OO\s0 interface defined in the
+\&\*(L"Constructor Options\*(R" section below.
+.ie n .IP """AutoClose => 0|1""" 5
+.el .IP "\f(CWAutoClose => 0|1\fR" 5
+.IX Item "AutoClose => 0|1"
+This option applies to any input or output data streams to
+\&\f(CW\*(C`gzip\*(C'\fR that are filehandles.
+.Sp
+If \f(CW\*(C`AutoClose\*(C'\fR is specified, and the value is true, it will result in all
+input and/or output filehandles being closed once \f(CW\*(C`gzip\*(C'\fR has
+completed.
+.Sp
+This parameter defaults to 0.
+.ie n .IP """BinModeIn => 0|1""" 5
+.el .IP "\f(CWBinModeIn => 0|1\fR" 5
+.IX Item "BinModeIn => 0|1"
+When reading from a file or filehandle, set \f(CW\*(C`binmode\*(C'\fR before reading.
+.Sp
+Defaults to 0.
+.ie n .IP """Append => 0|1""" 5
+.el .IP "\f(CWAppend => 0|1\fR" 5
+.IX Item "Append => 0|1"
+The behaviour of this option is dependent on the type of output data
+stream.
+.RS 5
+.IP "* A Buffer" 5
+.IX Item "A Buffer"
+If \f(CW\*(C`Append\*(C'\fR is enabled, all compressed data will be append to the end of
+the output buffer. Otherwise the output buffer will be cleared before any
+compressed data is written to it.
+.IP "* A Filename" 5
+.IX Item "A Filename"
+If \f(CW\*(C`Append\*(C'\fR is enabled, the file will be opened in append mode. Otherwise
+the contents of the file, if any, will be truncated before any compressed
+data is written to it.
+.IP "* A Filehandle" 5
+.IX Item "A Filehandle"
+If \f(CW\*(C`Append\*(C'\fR is enabled, the filehandle will be positioned to the end of
+the file via a call to \f(CW\*(C`seek\*(C'\fR before any compressed data is
+written to it. Otherwise the file pointer will not be moved.
+.RE
+.RS 5
+.Sp
+When \f(CW\*(C`Append\*(C'\fR is specified, and set to true, it will \fIappend\fR all compressed
+data to the output data stream.
+.Sp
+So when the output is a filehandle it will carry out a seek to the eof
+before writing any compressed data. If the output is a filename, it will be opened for
+appending. If the output is a buffer, all compressed data will be appened to
+the existing buffer.
+.Sp
+Conversely when \f(CW\*(C`Append\*(C'\fR is not specified, or it is present and is set to
+false, it will operate as follows.
+.Sp
+When the output is a filename, it will truncate the contents of the file
+before writing any compressed data. If the output is a filehandle
+its position will not be changed. If the output is a buffer, it will be
+wiped before any compressed data is output.
+.Sp
+Defaults to 0.
+.RE
+.Sh "Examples"
+.IX Subsection "Examples"
+To read the contents of the file \f(CW\*(C`file1.txt\*(C'\fR and write the compressed
+data to the file \f(CW\*(C`file1.txt.gz\*(C'\fR.
+.PP
+.Vb 3
+\& use strict ;
+\& use warnings ;
+\& use IO::Compress::Gzip qw(gzip $GzipError) ;
+.Ve
+.PP
+.Vb 3
+\& my $input = "file1.txt";
+\& gzip $input => "$input.gz"
+\& or die "gzip failed: $GzipError\en";
+.Ve
+.PP
+To read from an existing Perl filehandle, \f(CW$input\fR, and write the
+compressed data to a buffer, \f(CW$buffer\fR.
+.PP
+.Vb 4
+\& use strict ;
+\& use warnings ;
+\& use IO::Compress::Gzip qw(gzip $GzipError) ;
+\& use IO::File ;
+.Ve
+.PP
+.Vb 5
+\& my $input = new IO::File "<file1.txt"
+\& or die "Cannot open 'file1.txt': $!\en" ;
+\& my $buffer ;
+\& gzip $input => \e$buffer
+\& or die "gzip failed: $GzipError\en";
+.Ve
+.PP
+To compress all files in the directory \*(L"/my/home\*(R" that match \*(L"*.txt\*(R"
+and store the compressed data in the same directory
+.PP
+.Vb 3
+\& use strict ;
+\& use warnings ;
+\& use IO::Compress::Gzip qw(gzip $GzipError) ;
+.Ve
+.PP
+.Vb 2
+\& gzip '</my/home/*.txt>' => '<*.gz>'
+\& or die "gzip failed: $GzipError\en";
+.Ve
+.PP
+and if you want to compress each file one at a time, this will do the trick
+.PP
+.Vb 3
+\& use strict ;
+\& use warnings ;
+\& use IO::Compress::Gzip qw(gzip $GzipError) ;
+.Ve
+.PP
+.Vb 6
+\& for my $input ( glob "/my/home/*.txt" )
+\& {
+\& my $output = "$input.gz" ;
+\& gzip $input => $output
+\& or die "Error compressing '$input': $GzipError\en";
+\& }
+.Ve
+.SH "OO Interface"
+.IX Header "OO Interface"
+.Sh "Constructor"
+.IX Subsection "Constructor"
+The format of the constructor for \f(CW\*(C`IO::Compress::Gzip\*(C'\fR is shown below
+.PP
+.Vb 2
+\& my $z = new IO::Compress::Gzip $output [,OPTS]
+\& or die "IO::Compress::Gzip failed: $GzipError\en";
+.Ve
+.PP
+It returns an \f(CW\*(C`IO::Compress::Gzip\*(C'\fR object on success and undef on failure.
+The variable \f(CW$GzipError\fR will contain an error message on failure.
+.PP
+If you are running Perl 5.005 or better the object, \f(CW$z\fR, returned from
+IO::Compress::Gzip can be used exactly like an IO::File filehandle.
+This means that all normal output file operations can be carried out
+with \f(CW$z\fR.
+For example, to write to a compressed file/buffer you can use either of
+these forms
+.PP
+.Vb 2
+\& $z\->print("hello world\en");
+\& print $z "hello world\en";
+.Ve
+.PP
+The mandatory parameter \f(CW$output\fR is used to control the destination
+of the compressed data. This parameter can take one of these forms.
+.IP "A filename" 5
+.IX Item "A filename"
+If the \f(CW$output\fR parameter is a simple scalar, it is assumed to be a
+filename. This file will be opened for writing and the compressed data
+will be written to it.
+.IP "A filehandle" 5
+.IX Item "A filehandle"
+If the \f(CW$output\fR parameter is a filehandle, the compressed data will be
+written to it.
+The string '\-' can be used as an alias for standard output.
+.IP "A scalar reference" 5
+.IX Item "A scalar reference"
+If \f(CW$output\fR is a scalar reference, the compressed data will be stored
+in \f(CW$$output\fR.
+.PP
+If the \f(CW$output\fR parameter is any other type, \f(CW\*(C`IO::Compress::Gzip\*(C'\fR::new will
+return undef.
+.Sh "Constructor Options"
+.IX Subsection "Constructor Options"
+\&\f(CW\*(C`OPTS\*(C'\fR is any combination of the following options:
+.ie n .IP """AutoClose => 0|1""" 5
+.el .IP "\f(CWAutoClose => 0|1\fR" 5
+.IX Item "AutoClose => 0|1"
+This option is only valid when the \f(CW$output\fR parameter is a filehandle. If
+specified, and the value is true, it will result in the \f(CW$output\fR being
+closed once either the \f(CW\*(C`close\*(C'\fR method is called or the \f(CW\*(C`IO::Compress::Gzip\*(C'\fR
+object is destroyed.
+.Sp
+This parameter defaults to 0.
+.ie n .IP """Append => 0|1""" 5
+.el .IP "\f(CWAppend => 0|1\fR" 5
+.IX Item "Append => 0|1"
+Opens \f(CW$output\fR in append mode.
+.Sp
+The behaviour of this option is dependent on the type of \f(CW$output\fR.
+.RS 5
+.IP "* A Buffer" 5
+.IX Item "A Buffer"
+If \f(CW$output\fR is a buffer and \f(CW\*(C`Append\*(C'\fR is enabled, all compressed data
+will be append to the end of \f(CW$output\fR. Otherwise \f(CW$output\fR will be
+cleared before any data is written to it.
+.IP "* A Filename" 5
+.IX Item "A Filename"
+If \f(CW$output\fR is a filename and \f(CW\*(C`Append\*(C'\fR is enabled, the file will be
+opened in append mode. Otherwise the contents of the file, if any, will be
+truncated before any compressed data is written to it.
+.IP "* A Filehandle" 5
+.IX Item "A Filehandle"
+If \f(CW$output\fR is a filehandle, the file pointer will be positioned to the
+end of the file via a call to \f(CW\*(C`seek\*(C'\fR before any compressed data is written
+to it. Otherwise the file pointer will not be moved.
+.RE
+.RS 5
+.Sp
+This parameter defaults to 0.
+.RE
+.ie n .IP """Merge => 0|1""" 5
+.el .IP "\f(CWMerge => 0|1\fR" 5
+.IX Item "Merge => 0|1"
+This option is used to compress input data and append it to an existing
+compressed data stream in \f(CW$output\fR. The end result is a single compressed
+data stream stored in \f(CW$output\fR.
+.Sp
+It is a fatal error to attempt to use this option when \f(CW$output\fR is not an
+\&\s-1RFC\s0 1952 data stream.
+.Sp
+There are a number of other limitations with the \f(CW\*(C`Merge\*(C'\fR option:
+.RS 5
+.IP "1" 5
+.IX Item "1"
+This module needs to have been built with zlib 1.2.1 or better to work. A
+fatal error will be thrown if \f(CW\*(C`Merge\*(C'\fR is used with an older version of
+zlib.
+.IP "2" 5
+.IX Item "2"
+If \f(CW$output\fR is a file or a filehandle, it must be seekable.
+.RE
+.RS 5
+.Sp
+This parameter defaults to 0.
+.RE
+.IP "\-Level" 5
+.IX Item "-Level"
+Defines the compression level used by zlib. The value should either be
+a number between 0 and 9 (0 means no compression and 9 is maximum
+compression), or one of the symbolic constants defined below.
+.Sp
+.Vb 4
+\& Z_NO_COMPRESSION
+\& Z_BEST_SPEED
+\& Z_BEST_COMPRESSION
+\& Z_DEFAULT_COMPRESSION
+.Ve
+.Sp
+The default is Z_DEFAULT_COMPRESSION.
+.Sp
+Note, these constants are not imported by \f(CW\*(C`IO::Compress::Gzip\*(C'\fR by default.
+.Sp
+.Vb 3
+\& use IO::Compress::Gzip qw(:strategy);
+\& use IO::Compress::Gzip qw(:constants);
+\& use IO::Compress::Gzip qw(:all);
+.Ve
+.IP "\-Strategy" 5
+.IX Item "-Strategy"
+Defines the strategy used to tune the compression. Use one of the symbolic
+constants defined below.
+.Sp
+.Vb 5
+\& Z_FILTERED
+\& Z_HUFFMAN_ONLY
+\& Z_RLE
+\& Z_FIXED
+\& Z_DEFAULT_STRATEGY
+.Ve
+.Sp
+The default is Z_DEFAULT_STRATEGY.
+.ie n .IP """Minimal => 0|1""" 5
+.el .IP "\f(CWMinimal => 0|1\fR" 5
+.IX Item "Minimal => 0|1"
+If specified, this option will force the creation of the smallest possible
+compliant gzip header (which is exactly 10 bytes long) as defined in
+\&\s-1RFC\s0 1952.
+.Sp
+See the section titled \*(L"Compliance\*(R" in \s-1RFC\s0 1952 for a definition
+of the values used for the fields in the gzip header.
+.Sp
+All other parameters that control the content of the gzip header will
+be ignored if this parameter is set to 1.
+.Sp
+This parameter defaults to 0.
+.ie n .IP """Comment => $comment""" 5
+.el .IP "\f(CWComment => $comment\fR" 5
+.IX Item "Comment => $comment"
+Stores the contents of \f(CW$comment\fR in the \s-1COMMENT\s0 field in
+the gzip header.
+By default, no comment field is written to the gzip file.
+.Sp
+If the \f(CW\*(C`\-Strict\*(C'\fR option is enabled, the comment can only consist of \s-1ISO\s0
+8859\-1 characters plus line feed.
+.Sp
+If the \f(CW\*(C`\-Strict\*(C'\fR option is disabled, the comment field can contain any
+character except \s-1NULL\s0. If any null characters are present, the field
+will be truncated at the first \s-1NULL\s0.
+.ie n .IP """Name => $string""" 5
+.el .IP "\f(CWName => $string\fR" 5
+.IX Item "Name => $string"
+Stores the contents of \f(CW$string\fR in the gzip \s-1NAME\s0 header field. If
+\&\f(CW\*(C`Name\*(C'\fR is not specified, no gzip \s-1NAME\s0 field will be created.
+.Sp
+If the \f(CW\*(C`\-Strict\*(C'\fR option is enabled, \f(CW$string\fR can only consist of \s-1ISO\s0
+8859\-1 characters.
+.Sp
+If \f(CW\*(C`\-Strict\*(C'\fR is disabled, then \f(CW$string\fR can contain any character
+except \s-1NULL\s0. If any null characters are present, the field will be
+truncated at the first \s-1NULL\s0.
+.ie n .IP """Time => $number""" 5
+.el .IP "\f(CWTime => $number\fR" 5
+.IX Item "Time => $number"
+Sets the \s-1MTIME\s0 field in the gzip header to \f(CW$number\fR.
+.Sp
+This field defaults to the time the \f(CW\*(C`IO::Compress::Gzip\*(C'\fR object was created
+if this option is not specified.
+.ie n .IP """TextFlag => 0|1""" 5
+.el .IP "\f(CWTextFlag => 0|1\fR" 5
+.IX Item "TextFlag => 0|1"
+This parameter controls the setting of the \s-1FLG\s0.FTEXT bit in the gzip
+header. It is used to signal that the data stored in the gzip file/buffer
+is probably text.
+.Sp
+The default is 0.
+.ie n .IP """HeaderCRC => 0|1""" 5
+.el .IP "\f(CWHeaderCRC => 0|1\fR" 5
+.IX Item "HeaderCRC => 0|1"
+When true this parameter will set the \s-1FLG\s0.FHCRC bit to 1 in the gzip header
+and set the \s-1CRC16\s0 header field to the \s-1CRC\s0 of the complete gzip header
+except the \s-1CRC16\s0 field itself.
+.Sp
+\&\fBNote\fR that gzip files created with the \f(CW\*(C`HeaderCRC\*(C'\fR flag set to 1 cannot
+be read by most, if not all, of the the standard gunzip utilities, most
+notably gzip version 1.2.4. You should therefore avoid using this option if
+you want to maximize the portability of your gzip files.
+.Sp
+This parameter defaults to 0.
+.ie n .IP """OS_Code => $value""" 5
+.el .IP "\f(CWOS_Code => $value\fR" 5
+.IX Item "OS_Code => $value"
+Stores \f(CW$value\fR in the gzip \s-1OS\s0 header field. A number between 0 and 255 is
+valid.
+.Sp
+If not specified, this parameter defaults to the \s-1OS\s0 code of the Operating
+System this module was built on. The value 3 is used as a catch-all for all
+Unix variants and unknown Operating Systems.
+.ie n .IP """ExtraField => $data""" 5
+.el .IP "\f(CWExtraField => $data\fR" 5
+.IX Item "ExtraField => $data"
+This parameter allows additional metadata to be stored in the ExtraField in
+the gzip header. An \s-1RFC\s0 1952 compliant ExtraField consists of zero or more
+subfields. Each subfield consists of a two byte header followed by the
+subfield data.
+.Sp
+The list of subfields can be supplied in any of the following formats
+.Sp
+.Vb 12
+\& \-ExtraField => [$id1, $data1,
+\& $id2, $data2,
+\& ...
+\& ]
+\& \-ExtraField => [ [$id1 => $data1],
+\& [$id2 => $data2],
+\& ...
+\& ]
+\& \-ExtraField => { $id1 => $data1,
+\& $id2 => $data2,
+\& ...
+\& }
+.Ve
+.Sp
+Where \f(CW$id1\fR, \f(CW$id2\fR are two byte subfield \s-1ID\s0's. The second byte of
+the \s-1ID\s0 cannot be 0, unless the \f(CW\*(C`Strict\*(C'\fR option has been disabled.
+.Sp
+If you use the hash syntax, you have no control over the order in which
+the ExtraSubFields are stored, plus you cannot have SubFields with
+duplicate \s-1ID\s0.
+.Sp
+Alternatively the list of subfields can by supplied as a scalar, thus
+.Sp
+.Vb 1
+\& \-ExtraField => $rawdata
+.Ve
+.Sp
+If you use the raw format, and the \f(CW\*(C`Strict\*(C'\fR option is enabled,
+\&\f(CW\*(C`IO::Compress::Gzip\*(C'\fR will check that \f(CW$rawdata\fR consists of zero or more
+conformant sub\-fields. When \f(CW\*(C`Strict\*(C'\fR is disabled, \f(CW$rawdata\fR can
+consist of any arbitrary byte stream.
+.Sp
+The maximum size of the Extra Field 65535 bytes.
+.ie n .IP """ExtraFlags => $value""" 5
+.el .IP "\f(CWExtraFlags => $value\fR" 5
+.IX Item "ExtraFlags => $value"
+Sets the \s-1XFL\s0 byte in the gzip header to \f(CW$value\fR.
+.Sp
+If this option is not present, the value stored in \s-1XFL\s0 field will be
+determined by the setting of the \f(CW\*(C`Level\*(C'\fR option.
+.Sp
+If \f(CW\*(C`Level => Z_BEST_SPEED\*(C'\fR has been specified then \s-1XFL\s0 is set to 2.
+If \f(CW\*(C`Level => Z_BEST_COMPRESSION\*(C'\fR has been specified then \s-1XFL\s0 is set to 4.
+Otherwise \s-1XFL\s0 is set to 0.
+.ie n .IP """Strict => 0|1""" 5
+.el .IP "\f(CWStrict => 0|1\fR" 5
+.IX Item "Strict => 0|1"
+\&\f(CW\*(C`Strict\*(C'\fR will optionally police the values supplied with other options
+to ensure they are compliant with \s-1RFC1952\s0.
+.Sp
+This option is enabled by default.
+.Sp
+If \f(CW\*(C`Strict\*(C'\fR is enabled the following behaviour will be policed:
+.RS 5
+.IP "*" 5
+The value supplied with the \f(CW\*(C`Name\*(C'\fR option can only contain \s-1ISO\s0 8859\-1
+characters.
+.IP "*" 5
+The value supplied with the \f(CW\*(C`Comment\*(C'\fR option can only contain \s-1ISO\s0 8859\-1
+characters plus line\-feed.
+.IP "*" 5
+The values supplied with the \f(CW\*(C`\-Name\*(C'\fR and \f(CW\*(C`\-Comment\*(C'\fR options cannot
+contain multiple embedded nulls.
+.IP "*" 5
+If an \f(CW\*(C`ExtraField\*(C'\fR option is specified and it is a simple scalar,
+it must conform to the sub-field structure as defined in \s-1RFC\s0 1952.
+.IP "*" 5
+If an \f(CW\*(C`ExtraField\*(C'\fR option is specified the second byte of the \s-1ID\s0 will be
+checked in each subfield to ensure that it does not contain the reserved
+value 0x00.
+.RE
+.RS 5
+.Sp
+When \f(CW\*(C`Strict\*(C'\fR is disabled the following behaviour will be policed:
+.IP "*" 5
+The value supplied with \f(CW\*(C`\-Name\*(C'\fR option can contain
+any character except \s-1NULL\s0.
+.IP "*" 5
+The value supplied with \f(CW\*(C`\-Comment\*(C'\fR option can contain any character
+except \s-1NULL\s0.
+.IP "*" 5
+The values supplied with the \f(CW\*(C`\-Name\*(C'\fR and \f(CW\*(C`\-Comment\*(C'\fR options can contain
+multiple embedded nulls. The string written to the gzip header will
+consist of the characters up to, but not including, the first embedded
+\&\s-1NULL\s0.
+.IP "*" 5
+If an \f(CW\*(C`ExtraField\*(C'\fR option is specified and it is a simple scalar, the
+structure will not be checked. The only error is if the length is too big.
+.IP "*" 5
+The \s-1ID\s0 header in an \f(CW\*(C`ExtraField\*(C'\fR sub-field can consist of any two bytes.
+.RE
+.RS 5
+.RE
+.Sh "Examples"
+.IX Subsection "Examples"
+\&\s-1TODO\s0
+.SH "Methods"
+.IX Header "Methods"
+.Sh "print"
+.IX Subsection "print"
+Usage is
+.PP
+.Vb 2
+\& $z\->print($data)
+\& print $z $data
+.Ve
+.PP
+Compresses and outputs the contents of the \f(CW$data\fR parameter. This
+has the same behaviour as the \f(CW\*(C`print\*(C'\fR built\-in.
+.PP
+Returns true if successful.
+.Sh "printf"
+.IX Subsection "printf"
+Usage is
+.PP
+.Vb 2
+\& $z\->printf($format, $data)
+\& printf $z $format, $data
+.Ve
+.PP
+Compresses and outputs the contents of the \f(CW$data\fR parameter.
+.PP
+Returns true if successful.
+.Sh "syswrite"
+.IX Subsection "syswrite"
+Usage is
+.PP
+.Vb 3
+\& $z\->syswrite $data
+\& $z\->syswrite $data, $length
+\& $z\->syswrite $data, $length, $offset
+.Ve
+.PP
+Compresses and outputs the contents of the \f(CW$data\fR parameter.
+.PP
+Returns the number of uncompressed bytes written, or \f(CW\*(C`undef\*(C'\fR if
+unsuccessful.
+.Sh "write"
+.IX Subsection "write"
+Usage is
+.PP
+.Vb 3
+\& $z\->write $data
+\& $z\->write $data, $length
+\& $z\->write $data, $length, $offset
+.Ve
+.PP
+Compresses and outputs the contents of the \f(CW$data\fR parameter.
+.PP
+Returns the number of uncompressed bytes written, or \f(CW\*(C`undef\*(C'\fR if
+unsuccessful.
+.Sh "flush"
+.IX Subsection "flush"
+Usage is
+.PP
+.Vb 2
+\& $z\->flush;
+\& $z\->flush($flush_type);
+.Ve
+.PP
+Flushes any pending compressed data to the output file/buffer.
+.PP
+This method takes an optional parameter, \f(CW$flush_type\fR, that controls
+how the flushing will be carried out. By default the \f(CW$flush_type\fR
+used is \f(CW\*(C`Z_FINISH\*(C'\fR. Other valid values for \f(CW$flush_type\fR are
+\&\f(CW\*(C`Z_NO_FLUSH\*(C'\fR, \f(CW\*(C`Z_SYNC_FLUSH\*(C'\fR, \f(CW\*(C`Z_FULL_FLUSH\*(C'\fR and \f(CW\*(C`Z_BLOCK\*(C'\fR. It is
+strongly recommended that you only set the \f(CW\*(C`flush_type\*(C'\fR parameter if
+you fully understand the implications of what it does \- overuse of \f(CW\*(C`flush\*(C'\fR
+can seriously degrade the level of compression achieved. See the \f(CW\*(C`zlib\*(C'\fR
+documentation for details.
+.PP
+Returns true on success.
+.Sh "tell"
+.IX Subsection "tell"
+Usage is
+.PP
+.Vb 2
+\& $z\->tell()
+\& tell $z
+.Ve
+.PP
+Returns the uncompressed file offset.
+.Sh "eof"
+.IX Subsection "eof"
+Usage is
+.PP
+.Vb 2
+\& $z\->eof();
+\& eof($z);
+.Ve
+.PP
+Returns true if the \f(CW\*(C`close\*(C'\fR method has been called.
+.Sh "seek"
+.IX Subsection "seek"
+.Vb 2
+\& $z\->seek($position, $whence);
+\& seek($z, $position, $whence);
+.Ve
+.PP
+Provides a sub-set of the \f(CW\*(C`seek\*(C'\fR functionality, with the restriction
+that it is only legal to seek forward in the output file/buffer.
+It is a fatal error to attempt to seek backward.
+.PP
+Empty parts of the file/buffer will have \s-1NULL\s0 (0x00) bytes written to them.
+.PP
+The \f(CW$whence\fR parameter takes one the usual values, namely \s-1SEEK_SET\s0,
+\&\s-1SEEK_CUR\s0 or \s-1SEEK_END\s0.
+.PP
+Returns 1 on success, 0 on failure.
+.Sh "binmode"
+.IX Subsection "binmode"
+Usage is
+.PP
+.Vb 2
+\& $z\->binmode
+\& binmode $z ;
+.Ve
+.PP
+This is a noop provided for completeness.
+.Sh "opened"
+.IX Subsection "opened"
+.Vb 1
+\& $z\->opened()
+.Ve
+.PP
+Returns true if the object currently refers to a opened file/buffer.
+.Sh "autoflush"
+.IX Subsection "autoflush"
+.Vb 2
+\& my $prev = $z\->autoflush()
+\& my $prev = $z\->autoflush(EXPR)
+.Ve
+.PP
+If the \f(CW$z\fR object is associated with a file or a filehandle, this method
+returns the current autoflush setting for the underlying filehandle. If
+\&\f(CW\*(C`EXPR\*(C'\fR is present, and is non\-zero, it will enable flushing after every
+write/print operation.
+.PP
+If \f(CW$z\fR is associated with a buffer, this method has no effect and always
+returns \f(CW\*(C`undef\*(C'\fR.
+.PP
+\&\fBNote\fR that the special variable \f(CW$|\fR \fBcannot\fR be used to set or
+retrieve the autoflush setting.
+.Sh "input_line_number"
+.IX Subsection "input_line_number"
+.Vb 2
+\& $z\->input_line_number()
+\& $z\->input_line_number(EXPR)
+.Ve
+.PP
+This method always returns \f(CW\*(C`undef\*(C'\fR when compressing.
+.Sh "fileno"
+.IX Subsection "fileno"
+.Vb 2
+\& $z\->fileno()
+\& fileno($z)
+.Ve
+.PP
+If the \f(CW$z\fR object is associated with a file or a filehandle, \f(CW\*(C`fileno\*(C'\fR
+will return the underlying file descriptor. Once the \f(CW\*(C`close\*(C'\fR method is
+called \f(CW\*(C`fileno\*(C'\fR will return \f(CW\*(C`undef\*(C'\fR.
+.PP
+If the \f(CW$z\fR object is is associated with a buffer, this method will return
+\&\f(CW\*(C`undef\*(C'\fR.
+.Sh "close"
+.IX Subsection "close"
+.Vb 2
+\& $z\->close() ;
+\& close $z ;
+.Ve
+.PP
+Flushes any pending compressed data and then closes the output file/buffer.
+.PP
+For most versions of Perl this method will be automatically invoked if
+the IO::Compress::Gzip object is destroyed (either explicitly or by the
+variable with the reference to the object going out of scope). The
+exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
+these cases, the \f(CW\*(C`close\*(C'\fR method will be called automatically, but
+not until global destruction of all live objects when the program is
+terminating.
+.PP
+Therefore, if you want your scripts to be able to run on all versions
+of Perl, you should call \f(CW\*(C`close\*(C'\fR explicitly and not rely on automatic
+closing.
+.PP
+Returns true on success, otherwise 0.
+.PP
+If the \f(CW\*(C`AutoClose\*(C'\fR option has been enabled when the IO::Compress::Gzip
+object was created, and the object is associated with a file, the
+underlying file will also be closed.
+.Sh "newStream([\s-1OPTS\s0])"
+.IX Subsection "newStream([OPTS])"
+Usage is
+.PP
+.Vb 1
+\& $z\->newStream( [OPTS] )
+.Ve
+.PP
+Closes the current compressed data stream and starts a new one.
+.PP
+\&\s-1OPTS\s0 consists of any of the the options that are available when creating
+the \f(CW$z\fR object.
+.PP
+See the \*(L"Constructor Options\*(R" section for more details.
+.Sh "deflateParams"
+.IX Subsection "deflateParams"
+Usage is
+.PP
+.Vb 1
+\& $z\->deflateParams
+.Ve
+.PP
+\&\s-1TODO\s0
+.SH "Importing"
+.IX Header "Importing"
+A number of symbolic constants are required by some methods in
+\&\f(CW\*(C`IO::Compress::Gzip\*(C'\fR. None are imported by default.
+.IP ":all" 5
+.IX Item ":all"
+Imports \f(CW\*(C`gzip\*(C'\fR, \f(CW$GzipError\fR and all symbolic
+constants that can be used by \f(CW\*(C`IO::Compress::Gzip\*(C'\fR. Same as doing this
+.Sp
+.Vb 1
+\& use IO::Compress::Gzip qw(gzip $GzipError :constants) ;
+.Ve
+.IP ":constants" 5
+.IX Item ":constants"
+Import all symbolic constants. Same as doing this
+.Sp
+.Vb 1
+\& use IO::Compress::Gzip qw(:flush :level :strategy) ;
+.Ve
+.IP ":flush" 5
+.IX Item ":flush"
+These symbolic constants are used by the \f(CW\*(C`flush\*(C'\fR method.
+.Sp
+.Vb 6
+\& Z_NO_FLUSH
+\& Z_PARTIAL_FLUSH
+\& Z_SYNC_FLUSH
+\& Z_FULL_FLUSH
+\& Z_FINISH
+\& Z_BLOCK
+.Ve
+.IP ":level" 5
+.IX Item ":level"
+These symbolic constants are used by the \f(CW\*(C`Level\*(C'\fR option in the constructor.
+.Sp
+.Vb 4
+\& Z_NO_COMPRESSION
+\& Z_BEST_SPEED
+\& Z_BEST_COMPRESSION
+\& Z_DEFAULT_COMPRESSION
+.Ve
+.IP ":strategy" 5
+.IX Item ":strategy"
+These symbolic constants are used by the \f(CW\*(C`Strategy\*(C'\fR option in the constructor.
+.Sp
+.Vb 5
+\& Z_FILTERED
+\& Z_HUFFMAN_ONLY
+\& Z_RLE
+\& Z_FIXED
+\& Z_DEFAULT_STRATEGY
+.Ve
+.SH "EXAMPLES"
+.IX Header "EXAMPLES"
+.Sh "Apache::GZip Revisited"
+.IX Subsection "Apache::GZip Revisited"
+See IO::Compress::FAQ
+.Sh "Working with Net::FTP"
+.IX Subsection "Working with Net::FTP"
+See IO::Compress::FAQ
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Compress::Zlib, IO::Uncompress::Gunzip, IO::Compress::Deflate, IO::Uncompress::Inflate, IO::Compress::RawDeflate, IO::Uncompress::RawInflate, IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma, IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz, IO::Compress::Lzop, IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress
+.PP
+Compress::Zlib::FAQ
+.PP
+File::GlobMapper, Archive::Zip,
+Archive::Tar,
+IO::Zlib
+.PP
+For \s-1RFC\s0 1950, 1951 and 1952 see
+\&\fIhttp://www.faqs.org/rfcs/rfc1950.html\fR,
+\&\fIhttp://www.faqs.org/rfcs/rfc1951.html\fR and
+\&\fIhttp://www.faqs.org/rfcs/rfc1952.html\fR
+.PP
+The \fIzlib\fR compression library was written by Jean-loup Gailly
+\&\fIgzip@prep.ai.mit.edu\fR and Mark Adler \fImadler@alumni.caltech.edu\fR.
+.PP
+The primary site for the \fIzlib\fR compression library is
+\&\fIhttp://www.zlib.org\fR.
+.PP
+The primary site for gzip is \fIhttp://www.gzip.org\fR.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+This module was written by Paul Marquess, \fIpmqs@cpan.org\fR.
+.SH "MODIFICATION HISTORY"
+.IX Header "MODIFICATION HISTORY"
+See the Changes file.
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright (c) 2005\-2009 Paul Marquess. All rights reserved.
+.PP
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
projects / catagits/Gitalist.git / blobdiff