Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1032 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/IO::Compress::Gzip.3pm b/upstream/mageia-cauldron/man3pm/IO::Compress::Gzip.3pm
new file mode 100644
index 00000000..c7e6ff78
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/IO::Compress::Gzip.3pm
@@ -0,0 +1,1032 @@
+.\" -*- 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::Compress::Gzip 3pm"
+.TH IO::Compress::Gzip 3pm 2023-11-28 "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::Compress::Gzip \- Write RFC 1952 files/buffers
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    use IO::Compress::Gzip qw(gzip $GzipError) ;
+\&
+\&    my $status = gzip $input => $output [,OPTS]
+\&        or die "gzip failed: $GzipError\en";
+\&
+\&    my $z = IO::Compress::Gzip\->new( $output [,OPTS] )
+\&        or die "gzip failed: $GzipError\en";
+\&
+\&    $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] );
+\&
+\&    $z\->deflateParams();
+\&
+\&    $z\->close() ;
+\&
+\&    $GzipError ;
+\&
+\&    # IO::File mode
+\&
+\&    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 RFC 1952.
+.PP
+All the gzip headers defined in RFC 1952 can be created using
+this module.
+.PP
+For reading RFC 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
+"one-shot" compression between buffers and/or files. For finer
+control over the compression process, see the "OO Interface"
+section.
+.PP
+.Vb 1
+\&    use IO::Compress::Gzip qw(gzip $GzipError) ;
+\&
+\&    gzip $input_filename_or_reference => $output_filename_or_reference [,OPTS]
+\&        or die "gzip failed: $GzipError\en";
+.Ve
+.PP
+The functional interface needs Perl5.005 or better.
+.ie n .SS "gzip $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
+.el .SS "gzip \f(CW$input_filename_or_reference\fP => \f(CW$output_filename_or_reference\fP [, OPTS]"
+.IX Subsection "gzip $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
+\&\f(CW\*(C`gzip\*(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 uncompressed 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 compressed.
+.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`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
+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
+In addition, if \f(CW$input_filename_or_reference\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 \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 compressed 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
+compressed 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
+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_filename_or_reference\fR is a scalar reference, the
+compressed 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 compressed 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`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_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 files/buffers and
+\&\f(CW$output_filename_or_reference\fR is a single
+file/buffer the input files/buffers will be stored
+in \f(CW$output_filename_or_reference\fR as a concatenated series of compressed data streams.
+.SS "Optional Parameters"
+.IX Subsection "Optional Parameters"
+The optional parameters for the one-shot function \f(CW\*(C`gzip\*(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`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"
+This option is now a no-op. All files will be read 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 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 \(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 compressed
+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 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
+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 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
+.SS Examples
+.IX Subsection "Examples"
+Here are a few example that show the capabilities of the module.
+.PP
+\fIStreaming\fR
+.IX Subsection "Streaming"
+.PP
+This very simple command line example demonstrates the streaming capabilities of the module.
+The code reads data from STDIN, compresses it, and writes the compressed data to STDOUT.
+.PP
+.Vb 1
+\&    $ echo hello world | perl \-MIO::Compress::Gzip=gzip \-e \*(Aqgzip \e*STDIN => \e*STDOUT\*(Aq >output.gz
+.Ve
+.PP
+The special filename "\-" can be used as a standin for both \f(CW\*(C`\e*STDIN\*(C'\fR and \f(CW\*(C`\e*STDOUT\*(C'\fR,
+so the above can be rewritten as
+.PP
+.Vb 1
+\&    $ echo hello world | perl \-MIO::Compress::Gzip=gzip \-e \*(Aqgzip "\-" => "\-"\*(Aq >output.gz
+.Ve
+.PP
+\fICompressing a file from the filesystem\fR
+.IX Subsection "Compressing a file from the filesystem"
+.PP
+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) ;
+\&
+\&    my $input = "file1.txt";
+\&    gzip $input => "$input.gz"
+\&        or die "gzip failed: $GzipError\en";
+.Ve
+.PP
+\fIReading from a Filehandle and writing to an in-memory buffer\fR
+.IX Subsection "Reading from a Filehandle and writing to an in-memory buffer"
+.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 ;
+\&
+\&    my $input = IO::File\->new( "<file1.txt" )
+\&        or die "Cannot open \*(Aqfile1.txt\*(Aq: $!\en" ;
+\&    my $buffer ;
+\&    gzip $input => \e$buffer
+\&        or die "gzip failed: $GzipError\en";
+.Ve
+.PP
+\fICompressing multiple files\fR
+.IX Subsection "Compressing multiple files"
+.PP
+To compress all files in the directory "/my/home" that match "*.txt"
+and store the compressed data in the same directory
+.PP
+.Vb 3
+\&    use strict ;
+\&    use warnings ;
+\&    use IO::Compress::Gzip qw(gzip $GzipError) ;
+\&
+\&    gzip \*(Aq</my/home/*.txt>\*(Aq => \*(Aq<*.gz>\*(Aq
+\&        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) ;
+\&
+\&    for my $input ( glob "/my/home/*.txt" )
+\&    {
+\&        my $output = "$input.gz" ;
+\&        gzip $input => $output
+\&            or die "Error compressing \*(Aq$input\*(Aq: $GzipError\en";
+\&    }
+.Ve
+.SH "OO Interface"
+.IX Header "OO Interface"
+.SS 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 = IO::Compress::Gzip\->new( $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.
+.SS "Constructor Options"
+.IX Subsection "Constructor Options"
+\&\f(CW\*(C`OPTS\*(C'\fR is any combination of zero or more 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 \(bu 5
+A Buffer
+.Sp
+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 \(bu 5
+A Filename
+.Sp
+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 \(bu 5
+A Filehandle
+.Sp
+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
+RFC 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
+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
+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
+RFC 1952.
+.Sp
+See the section titled "Compliance" in RFC 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 COMMENT 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 ISO
+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 NULL. If any null characters are present, the field
+will be truncated at the first NULL.
+.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 NAME header field. If
+\&\f(CW\*(C`Name\*(C'\fR is not specified, no gzip NAME field will be created.
+.Sp
+If the \f(CW\*(C`\-Strict\*(C'\fR option is enabled, \f(CW$string\fR can only consist of ISO
+8859\-1 characters.
+.Sp
+If \f(CW\*(C`\-Strict\*(C'\fR is disabled, then \f(CW$string\fR can contain any character
+except NULL. If any null characters are present, the field will be
+truncated at the first NULL.
+.ie n .IP """Time => $number""" 5
+.el .IP "\f(CWTime => $number\fR" 5
+.IX Item "Time => $number"
+Sets the MTIME 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 FLG.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 FLG.FHCRC bit to 1 in the gzip header
+and set the CRC16 header field to the CRC of the complete gzip header
+except the CRC16 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 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 OS header field. A number between 0 and 255 is
+valid.
+.Sp
+If not specified, this parameter defaults to the OS 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 RFC 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 ID's. The second byte of
+the ID 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 ID.
+.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 XFL byte in the gzip header to \f(CW$value\fR.
+.Sp
+If this option is not present, the value stored in XFL 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 XFL is set to 2.
+If \f(CW\*(C`Level => Z_BEST_COMPRESSION\*(C'\fR has been specified then XFL is set to 4.
+Otherwise XFL 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 RFC1952.
+.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 \(bu 5
+The value supplied with the \f(CW\*(C`Name\*(C'\fR option can only contain ISO 8859\-1
+characters.
+.IP \(bu 5
+The value supplied with the \f(CW\*(C`Comment\*(C'\fR option can only contain ISO 8859\-1
+characters plus line-feed.
+.IP \(bu 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 \(bu 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 RFC 1952.
+.IP \(bu 5
+If an \f(CW\*(C`ExtraField\*(C'\fR option is specified the second byte of the ID 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 \(bu 5
+The value supplied with \f(CW\*(C`\-Name\*(C'\fR option can contain
+any character except NULL.
+.IP \(bu 5
+The value supplied with \f(CW\*(C`\-Comment\*(C'\fR option can contain any character
+except NULL.
+.IP \(bu 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
+NULL.
+.IP \(bu 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 \(bu 5
+The ID header in an \f(CW\*(C`ExtraField\*(C'\fR sub-field can consist of any two bytes.
+.RE
+.RS 5
+.RE
+.SS Examples
+.IX Subsection "Examples"
+TODO
+.SH Methods
+.IX Header "Methods"
+.SS 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.
+.SS 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.
+.SS 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.
+.SS 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.
+.SS 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.
+.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 \f(CW\*(C`close\*(C'\fR method has been called.
+.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 output file/buffer.
+It is a fatal error to attempt to seek backward.
+.PP
+Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
+.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
+This method always returns \f(CW\*(C`undef\*(C'\fR when compressing.
+.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
+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.
+.SS newStream([OPTS])
+.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
+OPTS consists of any of the options that are available when creating
+the \f(CW$z\fR object.
+.PP
+See the "Constructor Options" section for more details.
+.SS deflateParams
+.IX Subsection "deflateParams"
+Usage is
+.PP
+.Vb 1
+\&    $z\->deflateParams
+.Ve
+.PP
+TODO
+.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"
+.SS "Apache::GZip Revisited"
+.IX Subsection "Apache::GZip Revisited"
+See IO::Compress::FAQ
+.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\-Copress/issues> (preferred) or
+<https://rt.cpan.org/Public/Dist/Display.html?Name=IO\-Copress>.
+.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::Lzip, IO::Uncompress::UnLzip, IO::Compress::Lzop, IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Compress::Zstd, IO::Uncompress::UnZstd, IO::Uncompress::AnyInflate, 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.