--- /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::Zip 3"
+.TH IO::Compress::Zip 3 "2009-11-09" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+IO::Compress::Zip \- Write zip files/buffers
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\& use IO::Compress::Zip qw(zip $ZipError) ;
+.Ve
+.PP
+.Vb 2
+\& my $status = zip $input => $output [,OPTS]
+\& or die "zip failed: $ZipError\en";
+.Ve
+.PP
+.Vb 2
+\& my $z = new IO::Compress::Zip $output [,OPTS]
+\& or die "zip failed: $ZipError\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
+\& $ZipError ;
+.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 zip
+compressed data to files or buffer.
+.PP
+The primary purpose of this module is to provide streaming write access to
+zip files and buffers. It is not a general-purpose file archiver. If that
+is what you want, check out \f(CW\*(C`Archive::Zip\*(C'\fR.
+.PP
+At present three compression methods are supported by IO::Compress::Zip,
+namely Store (no compression at all), Deflate and Bzip2.
+.PP
+Note that to create Bzip2 content, the module \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR must
+be installed.
+.PP
+For reading zip files/buffers, see the companion module
+IO::Uncompress::Unzip.
+.SH "Functional Interface"
+.IX Header "Functional Interface"
+A top-level function, \f(CW\*(C`zip\*(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::Zip qw(zip $ZipError) ;
+.Ve
+.PP
+.Vb 2
+\& zip $input => $output [,OPTS]
+\& or die "zip failed: $ZipError\en";
+.Ve
+.PP
+The functional interface needs Perl5.005 or better.
+.ie n .Sh "zip $input\fP => \f(CW$output [, \s-1OPTS\s0]"
+.el .Sh "zip \f(CW$input\fP => \f(CW$output\fP [, \s-1OPTS\s0]"
+.IX Subsection "zip $input => $output [, OPTS]"
+\&\f(CW\*(C`zip\*(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`zip\*(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, \f(CW\*(C`Time\*(C'\fR, \f(CW\*(C`ExtAttr\*(C'\fR and \f(CW\*(C`exTime\*(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, \f(CW\*(C`Time\*(C'\fR, \f(CW\*(C`ExtAttr\*(C'\fR and \f(CW\*(C`exTime\*(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`zip\*(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 each be stored
+in \f(CW$output\fR as a distinct entry.
+.Sh "Optional Parameters"
+.IX Subsection "Optional Parameters"
+Unless specified below, the optional parameters for \f(CW\*(C`zip\*(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`zip\*(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`zip\*(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.zip\*(C'\fR.
+.PP
+.Vb 3
+\& use strict ;
+\& use warnings ;
+\& use IO::Compress::Zip qw(zip $ZipError) ;
+.Ve
+.PP
+.Vb 3
+\& my $input = "file1.txt";
+\& zip $input => "$input.zip"
+\& or die "zip failed: $ZipError\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::Zip qw(zip $ZipError) ;
+\& use IO::File ;
+.Ve
+.PP
+.Vb 5
+\& my $input = new IO::File "<file1.txt"
+\& or die "Cannot open 'file1.txt': $!\en" ;
+\& my $buffer ;
+\& zip $input => \e$buffer
+\& or die "zip failed: $ZipError\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::Zip qw(zip $ZipError) ;
+.Ve
+.PP
+.Vb 2
+\& zip '</my/home/*.txt>' => '<*.zip>'
+\& or die "zip failed: $ZipError\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::Zip qw(zip $ZipError) ;
+.Ve
+.PP
+.Vb 6
+\& for my $input ( glob "/my/home/*.txt" )
+\& {
+\& my $output = "$input.zip" ;
+\& zip $input => $output
+\& or die "Error compressing '$input': $ZipError\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::Zip\*(C'\fR is shown below
+.PP
+.Vb 2
+\& my $z = new IO::Compress::Zip $output [,OPTS]
+\& or die "IO::Compress::Zip failed: $ZipError\en";
+.Ve
+.PP
+It returns an \f(CW\*(C`IO::Compress::Zip\*(C'\fR object on success and undef on failure.
+The variable \f(CW$ZipError\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::Zip 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::Zip\*(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::Zip\*(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 """Name => $string""" 5
+.el .IP "\f(CWName => $string\fR" 5
+.IX Item "Name => $string"
+Stores the contents of \f(CW$string\fR in the zip filename header field. If
+\&\f(CW\*(C`Name\*(C'\fR is not specified, no zip filename field will be created.
+.ie n .IP """Time => $number""" 5
+.el .IP "\f(CWTime => $number\fR" 5
+.IX Item "Time => $number"
+Sets the last modified time field in the zip header to \f(CW$number\fR.
+.Sp
+This field defaults to the time the \f(CW\*(C`IO::Compress::Zip\*(C'\fR object was created
+if this option is not specified.
+.ie n .IP """ExtAttr => $attr""" 5
+.el .IP "\f(CWExtAttr => $attr\fR" 5
+.IX Item "ExtAttr => $attr"
+This option controls the \*(L"external file attributes\*(R" field in the central
+header of the zip file. This is a 4 byte field.
+.Sp
+If you are running a Unix derivative this value defaults to
+.Sp
+.Vb 1
+\& 0666 << 16
+.Ve
+.Sp
+This should allow read/write access to any files that are extracted from
+the zip file/buffer.
+.Sp
+For all other systems it defaults to 0.
+.ie n .IP """exTime => [$atime, $mtime, $ctime]""" 5
+.el .IP "\f(CWexTime => [$atime, $mtime, $ctime]\fR" 5
+.IX Item "exTime => [$atime, $mtime, $ctime]"
+This option expects an array reference with exactly three elements:
+\&\f(CW$atime\fR, \f(CW\*(C`mtime\*(C'\fR and \f(CW$ctime\fR. These correspond to the last access
+time, last modification time and creation time respectively.
+.Sp
+It uses these values to set the extended timestamp field (\s-1ID\s0 is \*(L"\s-1UT\s0\*(R") in
+the local zip header using the three values, \f(CW$atime\fR, \f(CW$mtime\fR, \f(CW$ctime\fR. In
+addition it sets the extended timestamp field in the central zip header
+using \f(CW$mtime\fR.
+.Sp
+If any of the three values is \f(CW\*(C`undef\*(C'\fR that time value will not be used.
+So, for example, to set only the \f(CW$mtime\fR you would use this
+.Sp
+.Vb 1
+\& exTime => [undef, $mtime, undef]
+.Ve
+.Sp
+If the \f(CW\*(C`Minimal\*(C'\fR option is set to true, this option will be ignored.
+.Sp
+By default no extended time field is created.
+.ie n .IP """exUnix2 => [$uid, $gid]""" 5
+.el .IP "\f(CWexUnix2 => [$uid, $gid]\fR" 5
+.IX Item "exUnix2 => [$uid, $gid]"
+This option expects an array reference with exactly two elements: \f(CW$uid\fR
+and \f(CW$gid\fR. These values correspond to the numeric user \s-1ID\s0 and group \s-1ID\s0
+of the owner of the files respectively.
+.Sp
+When the \f(CW\*(C`exUnix2\*(C'\fR option is present it will trigger the creation of a
+Unix2 extra field (\s-1ID\s0 is \*(L"Ux\*(R") in the local zip. This will be populated
+with \f(CW$uid\fR and \f(CW$gid\fR. In addition an empty Unix2 extra field will also
+be created in the central zip header
+.Sp
+If the \f(CW\*(C`Minimal\*(C'\fR option is set to true, this option will be ignored.
+.Sp
+By default no Unix2 extra field is created.
+.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 Central File Header of
+the zip file.
+.Sp
+By default, no comment field is written to the zip file.
+.ie n .IP """ZipComment => $comment""" 5
+.el .IP "\f(CWZipComment => $comment\fR" 5
+.IX Item "ZipComment => $comment"
+Stores the contents of \f(CW$comment\fR in the End of Central Directory record
+of the zip file.
+.Sp
+By default, no comment field is written to the zip file.
+.ie n .IP """Method => $method""" 5
+.el .IP "\f(CWMethod => $method\fR" 5
+.IX Item "Method => $method"
+Controls which compression method is used. At present three compression
+methods are supported, namely Store (no compression at all), Deflate and
+Bzip2.
+.Sp
+The symbols, \s-1ZIP_CM_STORE\s0, \s-1ZIP_CM_DEFLATE\s0 and \s-1ZIP_CM_BZIP2\s0 are used to
+select the compression method.
+.Sp
+These constants are not imported by \f(CW\*(C`IO::Compress::Zip\*(C'\fR by default.
+.Sp
+.Vb 3
+\& use IO::Compress::Zip qw(:zip_method);
+\& use IO::Compress::Zip qw(:constants);
+\& use IO::Compress::Zip qw(:all);
+.Ve
+.Sp
+Note that to create Bzip2 content, the module \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR must
+be installed. A fatal error will be thrown if you attempt to create Bzip2
+content when \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR is not available.
+.Sp
+The default method is \s-1ZIP_CM_DEFLATE\s0.
+.ie n .IP """Stream => 0|1""" 5
+.el .IP "\f(CWStream => 0|1\fR" 5
+.IX Item "Stream => 0|1"
+This option controls whether the zip file/buffer output is created in
+streaming mode.
+.Sp
+Note that when outputting to a file with streaming mode disabled (\f(CW\*(C`Stream\*(C'\fR
+is 0), the output file must be seekable.
+.Sp
+The default is 1.
+.ie n .IP """Zip64 => 0|1""" 5
+.el .IP "\f(CWZip64 => 0|1\fR" 5
+.IX Item "Zip64 => 0|1"
+Create a Zip64 zip file/buffer. This option should only be used if you want
+to store files larger than 4 Gig.
+.Sp
+If you intend to manipulate the Zip64 zip files created with this module
+using an external zip/unzip make sure that it supports Zip64.
+.Sp
+In particular, if you are using Info-Zip you need to have zip version 3.x
+or better to update a Zip64 archive and unzip version 6.x to read a zip64
+archive.
+.Sp
+The default is 0.
+.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 a bit in the zip central header. It
+is used to signal that the data stored in the zip file/buffer is probably
+text.
+.Sp
+The default is 0.
+.ie n .IP """ExtraFieldLocal => $data""\fR =item \f(CW""ExtraFieldCentral => $data""" 5
+.el .IP "\f(CWExtraFieldLocal => $data\fR =item \f(CWExtraFieldCentral => $data\fR" 5
+.IX Item "ExtraFieldLocal => $data =item ExtraFieldCentral => $data"
+The \f(CW\*(C`ExtraFieldLocal\*(C'\fR option is used to store additional metadata in the
+local header for the zip file/buffer. The \f(CW\*(C`ExtraFieldCentral\*(C'\fR does the
+same for the matching central header.
+.Sp
+An extra field 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 4
+\& ExtraFieldLocal => [$id1, $data1,
+\& $id2, $data2,
+\& ...
+\& ]
+.Ve
+.Sp
+.Vb 4
+\& ExtraFieldLocal => [ [$id1 => $data1],
+\& [$id2 => $data2],
+\& ...
+\& ]
+.Ve
+.Sp
+.Vb 4
+\& ExtraFieldLocal => { $id1 => $data1,
+\& $id2 => $data2,
+\& ...
+\& }
+.Ve
+.Sp
+Where \f(CW$id1\fR, \f(CW$id2\fR are two byte subfield \s-1ID\s0's.
+.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
+The Extended Time field (\s-1ID\s0 \*(L"\s-1UT\s0\*(R"), set using the \f(CW\*(C`exTime\*(C'\fR option, and the
+Unix2 extra field (\s-1ID\s0 "Ux), set using the \f(CW\*(C`exUnix2\*(C'\fR option, are examples
+of extra fields.
+.Sp
+If the \f(CW\*(C`Minimal\*(C'\fR option is set to true, this option will be ignored.
+.Sp
+The maximum size of an extra field 65535 bytes.
+.ie n .IP """Minimal => 1|0""" 5
+.el .IP "\f(CWMinimal => 1|0\fR" 5
+.IX Item "Minimal => 1|0"
+If specified, this option will disable the creation of all extra fields
+in the zip local and central headers. So the \f(CW\*(C`exTime\*(C'\fR, \f(CW\*(C`exUnix2\*(C'\fR,
+\&\f(CW\*(C`ExtraFieldLocal\*(C'\fR and \f(CW\*(C`ExtraFieldCentral\*(C'\fR options will be ignored.
+.Sp
+This parameter defaults to 0.
+.ie n .IP """BlockSize100K => number""" 5
+.el .IP "\f(CWBlockSize100K => number\fR" 5
+.IX Item "BlockSize100K => number"
+Specify the number of 100K blocks bzip2 uses during compression.
+.Sp
+Valid values are from 1 to 9, where 9 is best compression.
+.Sp
+This option is only valid if the \f(CW\*(C`Method\*(C'\fR is \s-1ZIP_CM_BZIP2\s0. It is ignored
+otherwise.
+.Sp
+The default is 1.
+.ie n .IP """WorkFactor => number""" 5
+.el .IP "\f(CWWorkFactor => number\fR" 5
+.IX Item "WorkFactor => number"
+Specifies how much effort bzip2 should take before resorting to a slower
+fallback compression algorithm.
+.Sp
+Valid values range from 0 to 250, where 0 means use the default value 30.
+.Sp
+This option is only valid if the \f(CW\*(C`Method\*(C'\fR is \s-1ZIP_CM_BZIP2\s0. It is ignored
+otherwise.
+.Sp
+The default is 0.
+.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::Zip\*(C'\fR by default.
+.Sp
+.Vb 3
+\& use IO::Compress::Zip qw(:strategy);
+\& use IO::Compress::Zip qw(:constants);
+\& use IO::Compress::Zip 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 """Strict => 0|1""" 5
+.el .IP "\f(CWStrict => 0|1\fR" 5
+.IX Item "Strict => 0|1"
+This is a placeholder option.
+.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::Zip 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::Zip
+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::Zip\*(C'\fR. None are imported by default.
+.IP ":all" 5
+.IX Item ":all"
+Imports \f(CW\*(C`zip\*(C'\fR, \f(CW$ZipError\fR and all symbolic
+constants that can be used by \f(CW\*(C`IO::Compress::Zip\*(C'\fR. Same as doing this
+.Sp
+.Vb 1
+\& use IO::Compress::Zip qw(zip $ZipError :constants) ;
+.Ve
+.IP ":constants" 5
+.IX Item ":constants"
+Import all symbolic constants. Same as doing this
+.Sp
+.Vb 1
+\& use IO::Compress::Zip qw(:flush :level :strategy :zip_method) ;
+.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
+.IP ":zip_method" 5
+.IX Item ":zip_method"
+These symbolic constants are used by the \f(CW\*(C`Method\*(C'\fR option in the
+constructor.
+.Sp
+.Vb 3
+\& ZIP_CM_STORE
+\& ZIP_CM_DEFLATE
+\& ZIP_CM_BZIP2
+.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::Compress::Gzip, 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