diff options
Diffstat (limited to 'upstream/debian-unstable/man3/IO::Uncompress::AnyInflate.3perl')
| -rw-r--r-- | upstream/debian-unstable/man3/IO::Uncompress::AnyInflate.3perl | 904 |
1 files changed, 904 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man3/IO::Uncompress::AnyInflate.3perl b/upstream/debian-unstable/man3/IO::Uncompress::AnyInflate.3perl new file mode 100644 index 00000000..affde0a7 --- /dev/null +++ b/upstream/debian-unstable/man3/IO::Uncompress::AnyInflate.3perl @@ -0,0 +1,904 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.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 +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "IO::Uncompress::AnyInflate 3perl" +.TH IO::Uncompress::AnyInflate 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +IO::Uncompress::AnyInflate \- Uncompress zlib\-based (zip, gzip) file/buffer +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ; +\& +\& my $status = anyinflate $input => $output [,OPTS] +\& or die "anyinflate failed: $AnyInflateError\en"; +\& +\& my $z = IO::Uncompress::AnyInflate\->new( $input [OPTS] ) +\& or die "anyinflate failed: $AnyInflateError\en"; +\& +\& $status = $z\->read($buffer) +\& $status = $z\->read($buffer, $length) +\& $status = $z\->read($buffer, $length, $offset) +\& $line = $z\->getline() +\& $char = $z\->getc() +\& $char = $z\->ungetc() +\& $char = $z\->opened() +\& +\& $status = $z\->inflateSync() +\& +\& $data = $z\->trailingData() +\& $status = $z\->nextStream() +\& $data = $z\->getHeaderInfo() +\& $z\->tell() +\& $z\->seek($position, $whence) +\& $z\->binmode() +\& $z\->fileno() +\& $z\->eof() +\& $z\->close() +\& +\& $AnyInflateError ; +\& +\& # IO::File mode +\& +\& <$z> +\& read($z, $buffer); +\& read($z, $buffer, $length); +\& read($z, $buffer, $length, $offset); +\& tell($z) +\& seek($z, $position, $whence) +\& binmode($z) +\& fileno($z) +\& eof($z) +\& close($z) +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This module provides a Perl interface that allows the reading of +files/buffers that have been compressed in a number of formats that use the +zlib compression library. +.PP +The formats supported are +.IP "RFC 1950" 5 +.IX Item "RFC 1950" +.PD 0 +.IP "RFC 1951 (optionally)" 5 +.IX Item "RFC 1951 (optionally)" +.IP "gzip (RFC 1952)" 5 +.IX Item "gzip (RFC 1952)" +.IP zip 5 +.IX Item "zip" +.PD +.PP +The module will auto-detect which, if any, of the supported +compression formats is being used. +.SH "Functional Interface" +.IX Header "Functional Interface" +A top-level function, \f(CW\*(C`anyinflate\*(C'\fR, is provided to carry out +"one-shot" uncompression between buffers and/or files. For finer +control over the uncompression process, see the "OO Interface" +section. +.PP +.Vb 1 +\& use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ; +\& +\& anyinflate $input_filename_or_reference => $output_filename_or_reference [,OPTS] +\& or die "anyinflate failed: $AnyInflateError\en"; +.Ve +.PP +The functional interface needs Perl5.005 or better. +.ie n .SS "anyinflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]" +.el .SS "anyinflate \f(CW$input_filename_or_reference\fP => \f(CW$output_filename_or_reference\fP [, OPTS]" +.IX Subsection "anyinflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]" +\&\f(CW\*(C`anyinflate\*(C'\fR expects at least two parameters, +\&\f(CW$input_filename_or_reference\fR and \f(CW$output_filename_or_reference\fR +and zero or more optional parameters (see "Optional Parameters") +.PP +\fIThe \fR\f(CI$input_filename_or_reference\fR\fI parameter\fR +.IX Subsection "The $input_filename_or_reference parameter" +.PP +The parameter, \f(CW$input_filename_or_reference\fR, is used to define the +source of the compressed data. +.PP +It can take one of the following forms: +.IP "A filename" 5 +.IX Item "A filename" +If the \f(CW$input_filename_or_reference\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_filename_or_reference\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_filename_or_reference\fR is a scalar reference, the input data +will be read from \f(CW$$input_filename_or_reference\fR. +.IP "An array reference" 5 +.IX Item "An array reference" +If \f(CW$input_filename_or_reference\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 uncompressed. +.IP "An Input FileGlob string" 5 +.IX Item "An Input FileGlob string" +If \f(CW$input_filename_or_reference\fR is a string that is delimited by the +characters "<" and ">" \f(CW\*(C`anyinflate\*(C'\fR will assume that it is an +\&\fIinput fileglob string\fR. The input is the list of files that match the +fileglob. +.Sp +See File::GlobMapper for more details. +.PP +If the \f(CW$input_filename_or_reference\fR parameter is any other type, +\&\f(CW\*(C`undef\*(C'\fR will be returned. +.PP +\fIThe \fR\f(CI$output_filename_or_reference\fR\fI parameter\fR +.IX Subsection "The $output_filename_or_reference parameter" +.PP +The parameter \f(CW$output_filename_or_reference\fR is used to control the +destination of the uncompressed data. This parameter can take one of +these forms. +.IP "A filename" 5 +.IX Item "A filename" +If the \f(CW$output_filename_or_reference\fR parameter is a simple scalar, it is +assumed to be a filename. This file will be opened for writing and the +uncompressed data will be written to it. +.IP "A filehandle" 5 +.IX Item "A filehandle" +If the \f(CW$output_filename_or_reference\fR parameter is a filehandle, the +uncompressed 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_filename_or_reference\fR is a scalar reference, the +uncompressed data will be stored in \f(CW$$output_filename_or_reference\fR. +.IP "An Array Reference" 5 +.IX Item "An Array Reference" +If \f(CW$output_filename_or_reference\fR is an array reference, +the uncompressed data will be pushed onto the array. +.IP "An Output FileGlob" 5 +.IX Item "An Output FileGlob" +If \f(CW$output_filename_or_reference\fR is a string that is delimited by the +characters "<" and ">" \f(CW\*(C`anyinflate\*(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_filename_or_reference\fR is an fileglob string, +\&\f(CW$input_filename_or_reference\fR must also be a fileglob string. Anything +else is an error. +.Sp +See File::GlobMapper for more details. +.PP +If the \f(CW$output_filename_or_reference\fR parameter is any other type, +\&\f(CW\*(C`undef\*(C'\fR will be returned. +.SS Notes +.IX Subsection "Notes" +When \f(CW$input_filename_or_reference\fR maps to multiple compressed +files/buffers and \f(CW$output_filename_or_reference\fR is +a single file/buffer, after uncompression \f(CW$output_filename_or_reference\fR will contain a +concatenation of all the uncompressed data from each of the input +files/buffers. +.SS "Optional Parameters" +.IX Subsection "Optional Parameters" +The optional parameters for the one-shot function \f(CW\*(C`anyinflate\*(C'\fR +are (for the most part) identical to those used with the OO interface defined in the +"Constructor Options" section. The exceptions are listed 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`anyinflate\*(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`anyinflate\*(C'\fR has +completed. +.Sp +This parameter defaults to 0. +.ie n .IP """BinModeOut => 0|1""" 5 +.el .IP "\f(CWBinModeOut => 0|1\fR" 5 +.IX Item "BinModeOut => 0|1" +This option is now a no-op. All files will be written in binmode. +.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 \(bu 5 +A Buffer +.Sp +If \f(CW\*(C`Append\*(C'\fR is enabled, all uncompressed data will be append to the end of +the output buffer. Otherwise the output buffer will be cleared before any +uncompressed data is written to it. +.IP \(bu 5 +A Filename +.Sp +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 uncompressed +data is written to it. +.IP \(bu 5 +A Filehandle +.Sp +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 uncompressed 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 uncompressed +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 uncompressed data. If the output is a filename, it will be opened for +appending. If the output is a buffer, all uncompressed data will be +appended 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 uncompressed 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 uncompressed data is output. +.Sp +Defaults to 0. +.RE +.ie n .IP """MultiStream => 0|1""" 5 +.el .IP "\f(CWMultiStream => 0|1\fR" 5 +.IX Item "MultiStream => 0|1" +If the input file/buffer contains multiple compressed data streams, this +option will uncompress the whole lot as a single data stream. +.Sp +Defaults to 0. +.ie n .IP """TrailingData => $scalar""" 5 +.el .IP "\f(CWTrailingData => $scalar\fR" 5 +.IX Item "TrailingData => $scalar" +Returns the data, if any, that is present immediately after the compressed +data stream once uncompression is complete. +.Sp +This option can be used when there is useful information immediately +following the compressed data stream, and you don't know the length of the +compressed data stream. +.Sp +If the input is a buffer, \f(CW\*(C`trailingData\*(C'\fR will return everything from the +end of the compressed data stream to the end of the buffer. +.Sp +If the input is a filehandle, \f(CW\*(C`trailingData\*(C'\fR will return the data that is +left in the filehandle input buffer once the end of the compressed data +stream has been reached. You can then use the filehandle to read the rest +of the input file. +.Sp +Don't bother using \f(CW\*(C`trailingData\*(C'\fR if the input is a filename. +.Sp +If you know the length of the compressed data stream before you start +uncompressing, you can avoid having to use \f(CW\*(C`trailingData\*(C'\fR by setting the +\&\f(CW\*(C`InputLength\*(C'\fR option. +.SS Examples +.IX Subsection "Examples" +To read the contents of the file \f(CW\*(C`file1.txt.Compressed\*(C'\fR and write the +uncompressed data to the file \f(CW\*(C`file1.txt\*(C'\fR. +.PP +.Vb 3 +\& use strict ; +\& use warnings ; +\& use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ; +\& +\& my $input = "file1.txt.Compressed"; +\& my $output = "file1.txt"; +\& anyinflate $input => $output +\& or die "anyinflate failed: $AnyInflateError\en"; +.Ve +.PP +To read from an existing Perl filehandle, \f(CW$input\fR, and write the +uncompressed data to a buffer, \f(CW$buffer\fR. +.PP +.Vb 4 +\& use strict ; +\& use warnings ; +\& use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ; +\& use IO::File ; +\& +\& my $input = IO::File\->new( "<file1.txt.Compressed" ) +\& or die "Cannot open \*(Aqfile1.txt.Compressed\*(Aq: $!\en" ; +\& my $buffer ; +\& anyinflate $input => \e$buffer +\& or die "anyinflate failed: $AnyInflateError\en"; +.Ve +.PP +To uncompress all files in the directory "/my/home" that match "*.txt.Compressed" and store the compressed data in the same directory +.PP +.Vb 3 +\& use strict ; +\& use warnings ; +\& use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ; +\& +\& anyinflate \*(Aq</my/home/*.txt.Compressed>\*(Aq => \*(Aq</my/home/#1.txt>\*(Aq +\& or die "anyinflate failed: $AnyInflateError\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::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ; +\& +\& for my $input ( glob "/my/home/*.txt.Compressed" ) +\& { +\& my $output = $input; +\& $output =~ s/.Compressed// ; +\& anyinflate $input => $output +\& or die "Error compressing \*(Aq$input\*(Aq: $AnyInflateError\en"; +\& } +.Ve +.SH "OO Interface" +.IX Header "OO Interface" +.SS Constructor +.IX Subsection "Constructor" +The format of the constructor for IO::Uncompress::AnyInflate is shown below +.PP +.Vb 2 +\& my $z = IO::Uncompress::AnyInflate\->new( $input [OPTS] ) +\& or die "IO::Uncompress::AnyInflate failed: $AnyInflateError\en"; +.Ve +.PP +Returns an \f(CW\*(C`IO::Uncompress::AnyInflate\*(C'\fR object on success and undef on failure. +The variable \f(CW$AnyInflateError\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::Uncompress::AnyInflate can be used exactly like an IO::File filehandle. +This means that all normal input file operations can be carried out with +\&\f(CW$z\fR. For example, to read a line from a compressed file/buffer you can +use either of these forms +.PP +.Vb 2 +\& $line = $z\->getline(); +\& $line = <$z>; +.Ve +.PP +The mandatory parameter \f(CW$input\fR is used to determine the source of the +compressed data. This parameter can take one of three forms. +.IP "A filename" 5 +.IX Item "A filename" +If the \f(CW$input\fR parameter is a scalar, it is assumed to be a filename. This +file will be opened for reading and the compressed 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 compressed 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 compressed data will be read from +\&\f(CW$$input\fR. +.SS "Constructor Options" +.IX Subsection "Constructor Options" +The option names defined below are case insensitive and can be optionally +prefixed by a '\-'. So all of the following are valid +.PP +.Vb 4 +\& \-AutoClose +\& \-autoclose +\& AUTOCLOSE +\& autoclose +.Ve +.PP +OPTS is a 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$input\fR parameter is a filehandle. If +specified, and the value is true, it will result in the file being closed once +either the \f(CW\*(C`close\*(C'\fR method is called or the IO::Uncompress::AnyInflate object is +destroyed. +.Sp +This parameter defaults to 0. +.ie n .IP """MultiStream => 0|1""" 5 +.el .IP "\f(CWMultiStream => 0|1\fR" 5 +.IX Item "MultiStream => 0|1" +Allows multiple concatenated compressed streams to be treated as a single +compressed stream. Decompression will stop once either the end of the +file/buffer is reached, an error is encountered (premature eof, corrupt +compressed data) or the end of a stream is not immediately followed by the +start of another stream. +.Sp +This parameter defaults to 0. +.ie n .IP """Prime => $string""" 5 +.el .IP "\f(CWPrime => $string\fR" 5 +.IX Item "Prime => $string" +This option will uncompress the contents of \f(CW$string\fR before processing the +input file/buffer. +.Sp +This option can be useful when the compressed data is embedded in another +file/data structure and it is not possible to work out where the compressed +data begins without having to read the first few bytes. If this is the +case, the uncompression can be \fIprimed\fR with these bytes using this +option. +.ie n .IP """Transparent => 0|1""" 5 +.el .IP "\f(CWTransparent => 0|1\fR" 5 +.IX Item "Transparent => 0|1" +If this option is set and the input file/buffer is not compressed data, +the module will allow reading of it anyway. +.Sp +In addition, if the input file/buffer does contain compressed data and +there is non-compressed data immediately following it, setting this option +will make this module treat the whole file/buffer as a single data stream. +.Sp +This option defaults to 1. +.ie n .IP """BlockSize => $num""" 5 +.el .IP "\f(CWBlockSize => $num\fR" 5 +.IX Item "BlockSize => $num" +When reading the compressed input data, IO::Uncompress::AnyInflate will read it in +blocks of \f(CW$num\fR bytes. +.Sp +This option defaults to 4096. +.ie n .IP """InputLength => $size""" 5 +.el .IP "\f(CWInputLength => $size\fR" 5 +.IX Item "InputLength => $size" +When present this option will limit the number of compressed bytes read +from the input file/buffer to \f(CW$size\fR. This option can be used in the +situation where there is useful data directly after the compressed data +stream and you know beforehand the exact length of the compressed data +stream. +.Sp +This option is mostly used when reading from a filehandle, in which case +the file pointer will be left pointing to the first byte directly after the +compressed data stream. +.Sp +This option defaults to off. +.ie n .IP """Append => 0|1""" 5 +.el .IP "\f(CWAppend => 0|1\fR" 5 +.IX Item "Append => 0|1" +This option controls what the \f(CW\*(C`read\*(C'\fR method does with uncompressed data. +.Sp +If set to 1, all uncompressed data will be appended to the output parameter +of the \f(CW\*(C`read\*(C'\fR method. +.Sp +If set to 0, the contents of the output parameter of the \f(CW\*(C`read\*(C'\fR method +will be overwritten by the uncompressed data. +.Sp +Defaults to 0. +.ie n .IP """Strict => 0|1""" 5 +.el .IP "\f(CWStrict => 0|1\fR" 5 +.IX Item "Strict => 0|1" +This option controls whether the extra checks defined below are used when +carrying out the decompression. When Strict is on, the extra tests are +carried out, when Strict is off they are not. +.Sp +The default for this option is off. +.Sp +If the input is an RFC 1950 data stream, the following will be checked: +.RS 5 +.IP 1. 5 +The ADLER32 checksum field must be present. +.IP 2. 5 +The value of the ADLER32 field read must match the adler32 value of the +uncompressed data actually contained in the file. +.RE +.RS 5 +.Sp +If the input is a gzip (RFC 1952) data stream, the following will be checked: +.IP 1. 5 +If the FHCRC bit is set in the gzip FLG header byte, the CRC16 bytes in the +header must match the crc16 value of the gzip header actually read. +.IP 2. 5 +If the gzip header contains a name field (FNAME) it consists solely of ISO +8859\-1 characters. +.IP 3. 5 +If the gzip header contains a comment field (FCOMMENT) it consists solely +of ISO 8859\-1 characters plus line-feed. +.IP 4. 5 +If the gzip FEXTRA header field is present it must conform to the sub-field +structure as defined in RFC 1952. +.IP 5. 5 +The CRC32 and ISIZE trailer fields must be present. +.IP 6. 5 +The value of the CRC32 field read must match the crc32 value of the +uncompressed data actually contained in the gzip file. +.IP 7. 5 +The value of the ISIZE fields read must match the length of the +uncompressed data actually read from the file. +.RE +.RS 5 +.RE +.ie n .IP """RawInflate => 0|1""" 5 +.el .IP "\f(CWRawInflate => 0|1\fR" 5 +.IX Item "RawInflate => 0|1" +When auto-detecting the compressed format, try to test for raw-deflate (RFC +1951) content using the \f(CW\*(C`IO::Uncompress::RawInflate\*(C'\fR module. +.Sp +The reason this is not default behaviour is because RFC 1951 content can +only be detected by attempting to uncompress it. This process is error +prone and can result is false positives. +.Sp +Defaults to 0. +.ie n .IP """ParseExtra => 0|1"" If the gzip FEXTRA header field is present and this option is set, it will force the module to check that it conforms to the sub-field structure as defined in RFC 1952." 5 +.el .IP "\f(CWParseExtra => 0|1\fR If the gzip FEXTRA header field is present and this option is set, it will force the module to check that it conforms to the sub-field structure as defined in RFC 1952." 5 +.IX Item "ParseExtra => 0|1 If the gzip FEXTRA header field is present and this option is set, it will force the module to check that it conforms to the sub-field structure as defined in RFC 1952." +If the \f(CW\*(C`Strict\*(C'\fR is on it will automatically enable this option. +.Sp +Defaults to 0. +.SS Examples +.IX Subsection "Examples" +TODO +.SH Methods +.IX Header "Methods" +.SS read +.IX Subsection "read" +Usage is +.PP +.Vb 1 +\& $status = $z\->read($buffer) +.Ve +.PP +Reads a block of compressed data (the size of the compressed block is +determined by the \f(CW\*(C`Buffer\*(C'\fR option in the constructor), uncompresses it and +writes any uncompressed data into \f(CW$buffer\fR. If the \f(CW\*(C`Append\*(C'\fR parameter is +set in the constructor, the uncompressed data will be appended to the +\&\f(CW$buffer\fR parameter. Otherwise \f(CW$buffer\fR will be overwritten. +.PP +Returns the number of uncompressed bytes written to \f(CW$buffer\fR, zero if eof +or a negative number on error. +.SS read +.IX Subsection "read" +Usage is +.PP +.Vb 2 +\& $status = $z\->read($buffer, $length) +\& $status = $z\->read($buffer, $length, $offset) +\& +\& $status = read($z, $buffer, $length) +\& $status = read($z, $buffer, $length, $offset) +.Ve +.PP +Attempt to read \f(CW$length\fR bytes of uncompressed data into \f(CW$buffer\fR. +.PP +The main difference between this form of the \f(CW\*(C`read\*(C'\fR method and the +previous one, is that this one will attempt to return \fIexactly\fR \f(CW$length\fR +bytes. The only circumstances that this function will not is if end-of-file +or an IO error is encountered. +.PP +Returns the number of uncompressed bytes written to \f(CW$buffer\fR, zero if eof +or a negative number on error. +.SS getline +.IX Subsection "getline" +Usage is +.PP +.Vb 2 +\& $line = $z\->getline() +\& $line = <$z> +.Ve +.PP +Reads a single line. +.PP +This method fully supports the use of the variable \f(CW$/\fR (or +\&\f(CW$INPUT_RECORD_SEPARATOR\fR or \f(CW$RS\fR when \f(CW\*(C`English\*(C'\fR is in use) to +determine what constitutes an end of line. Paragraph mode, record mode and +file slurp mode are all supported. +.SS getc +.IX Subsection "getc" +Usage is +.PP +.Vb 1 +\& $char = $z\->getc() +.Ve +.PP +Read a single character. +.SS ungetc +.IX Subsection "ungetc" +Usage is +.PP +.Vb 1 +\& $char = $z\->ungetc($string) +.Ve +.SS inflateSync +.IX Subsection "inflateSync" +Usage is +.PP +.Vb 1 +\& $status = $z\->inflateSync() +.Ve +.PP +TODO +.SS getHeaderInfo +.IX Subsection "getHeaderInfo" +Usage is +.PP +.Vb 2 +\& $hdr = $z\->getHeaderInfo(); +\& @hdrs = $z\->getHeaderInfo(); +.Ve +.PP +This method returns either a hash reference (in scalar context) or a list +or hash references (in array context) that contains information about each +of the header fields in the compressed data stream(s). +.SS tell +.IX Subsection "tell" +Usage is +.PP +.Vb 2 +\& $z\->tell() +\& tell $z +.Ve +.PP +Returns the uncompressed file offset. +.SS eof +.IX Subsection "eof" +Usage is +.PP +.Vb 2 +\& $z\->eof(); +\& eof($z); +.Ve +.PP +Returns true if the end of the compressed input stream has been reached. +.SS 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 input file/buffer. +It is a fatal error to attempt to seek backward. +.PP +Note that the implementation of \f(CW\*(C`seek\*(C'\fR in this module does not provide +true random access to a compressed file/buffer. It works by uncompressing +data from the current offset in the file/buffer until it reaches the +uncompressed offset specified in the parameters to \f(CW\*(C`seek\*(C'\fR. For very small +files this may be acceptable behaviour. For large files it may cause an +unacceptable delay. +.PP +The \f(CW$whence\fR parameter takes one the usual values, namely SEEK_SET, +SEEK_CUR or SEEK_END. +.PP +Returns 1 on success, 0 on failure. +.SS binmode +.IX Subsection "binmode" +Usage is +.PP +.Vb 2 +\& $z\->binmode +\& binmode $z ; +.Ve +.PP +This is a noop provided for completeness. +.SS opened +.IX Subsection "opened" +.Vb 1 +\& $z\->opened() +.Ve +.PP +Returns true if the object currently refers to a opened file/buffer. +.SS 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. +.SS input_line_number +.IX Subsection "input_line_number" +.Vb 2 +\& $z\->input_line_number() +\& $z\->input_line_number(EXPR) +.Ve +.PP +Returns the current uncompressed line number. If \f(CW\*(C`EXPR\*(C'\fR is present it has +the effect of setting the line number. Note that setting the line number +does not change the current position within the file/buffer being read. +.PP +The contents of \f(CW$/\fR are used to determine what constitutes a line +terminator. +.SS 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 associated with a buffer, this method will return +\&\f(CW\*(C`undef\*(C'\fR. +.SS close +.IX Subsection "close" +.Vb 2 +\& $z\->close() ; +\& close $z ; +.Ve +.PP +Closes the output file/buffer. +.PP +For most versions of Perl this method will be automatically invoked if +the IO::Uncompress::AnyInflate 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::Uncompress::AnyInflate +object was created, and the object is associated with a file, the +underlying file will also be closed. +.SS nextStream +.IX Subsection "nextStream" +Usage is +.PP +.Vb 1 +\& my $status = $z\->nextStream(); +.Ve +.PP +Skips to the next compressed data stream in the input file/buffer. If a new +compressed data stream is found, the eof marker will be cleared and \f(CW$.\fR +will be reset to 0. +.PP +Returns 1 if a new stream was found, 0 if none was found, and \-1 if an +error was encountered. +.SS trailingData +.IX Subsection "trailingData" +Usage is +.PP +.Vb 1 +\& my $data = $z\->trailingData(); +.Ve +.PP +Returns the data, if any, that is present immediately after the compressed +data stream once uncompression is complete. It only makes sense to call +this method once the end of the compressed data stream has been +encountered. +.PP +This option can be used when there is useful information immediately +following the compressed data stream, and you don't know the length of the +compressed data stream. +.PP +If the input is a buffer, \f(CW\*(C`trailingData\*(C'\fR will return everything from the +end of the compressed data stream to the end of the buffer. +.PP +If the input is a filehandle, \f(CW\*(C`trailingData\*(C'\fR will return the data that is +left in the filehandle input buffer once the end of the compressed data +stream has been reached. You can then use the filehandle to read the rest +of the input file. +.PP +Don't bother using \f(CW\*(C`trailingData\*(C'\fR if the input is a filename. +.PP +If you know the length of the compressed data stream before you start +uncompressing, you can avoid having to use \f(CW\*(C`trailingData\*(C'\fR by setting the +\&\f(CW\*(C`InputLength\*(C'\fR option in the constructor. +.SH Importing +.IX Header "Importing" +No symbolic constants are required by IO::Uncompress::AnyInflate at present. +.IP :all 5 +.IX Item ":all" +Imports \f(CW\*(C`anyinflate\*(C'\fR and \f(CW$AnyInflateError\fR. +Same as doing this +.Sp +.Vb 1 +\& use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ; +.Ve +.SH EXAMPLES +.IX Header "EXAMPLES" +.SS "Working with Net::FTP" +.IX Subsection "Working with Net::FTP" +See IO::Compress::FAQ +.SH SUPPORT +.IX Header "SUPPORT" +General feedback/questions/bug reports should be sent to +<https://github.com/pmqs/IO\-Compress/issues> (preferred) or +<https://rt.cpan.org/Public/Dist/Display.html?Name=IO\-Compress>. +.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::Lzip, IO::Uncompress::UnLzip, IO::Compress::Lzop, IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Compress::Zstd, IO::Uncompress::UnZstd, IO::Uncompress::AnyUncompress +.PP +IO::Compress::FAQ +.PP +File::GlobMapper, Archive::Zip, +Archive::Tar, +IO::Zlib +.PP +For RFC 1950, 1951 and 1952 see +<https://datatracker.ietf.org/doc/html/rfc1950>, +<https://datatracker.ietf.org/doc/html/rfc1951> and +<https://datatracker.ietf.org/doc/html/rfc1952> +.PP +The \fIzlib\fR compression library was written by Jean-loup Gailly +\&\f(CW\*(C`gzip@prep.ai.mit.edu\*(C'\fR and Mark Adler \f(CW\*(C`madler@alumni.caltech.edu\*(C'\fR. +.PP +The primary site for the \fIzlib\fR compression library is +<http://www.zlib.org>. +.PP +The primary site for the \fIzlib-ng\fR compression library is +<https://github.com/zlib\-ng/zlib\-ng>. +.PP +The primary site for gzip is <http://www.gzip.org>. +.SH AUTHOR +.IX Header "AUTHOR" +This module was written by Paul Marquess, \f(CW\*(C`pmqs@cpan.org\*(C'\fR. +.SH "MODIFICATION HISTORY" +.IX Header "MODIFICATION HISTORY" +See the Changes file. +.SH "COPYRIGHT AND LICENSE" +.IX Header "COPYRIGHT AND LICENSE" +Copyright (c) 2005\-2023 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. |