You are viewing the version of this documentation from Perl 5.20.2. View the latest version

CONTENTS

NAME

IO::Uncompress::Gunzip - Read RFC 1952 files/buffers

SYNOPSIS

use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;

my $status = gunzip $input => $output [,OPTS]
    or die "gunzip failed: $GunzipError\n";

my $z = new IO::Uncompress::Gunzip $input [OPTS] 
    or die "gunzip failed: $GunzipError\n";

$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()

$GunzipError ;

# 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)

DESCRIPTION

This module provides a Perl interface that allows the reading of files/buffers that conform to RFC 1952.

For writing RFC 1952 files/buffers, see the companion module IO::Compress::Gzip.

Functional Interface

A top-level function, gunzip, 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.

use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;

gunzip $input_filename_or_reference => $output_filename_or_reference [,OPTS] 
    or die "gunzip failed: $GunzipError\n";

The functional interface needs Perl5.005 or better.

gunzip $input_filename_or_reference => $output_filename_or_reference [, OPTS]

gunzip expects at least two parameters, $input_filename_or_reference and $output_filename_or_reference.

The $input_filename_or_reference parameter

The parameter, $input_filename_or_reference, is used to define the source of the compressed data.

It can take one of the following forms:

A filename

If the <$input_filename_or_reference> 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.

A filehandle

If the $input_filename_or_reference parameter is a filehandle, the input data will be read from it. The string '-' can be used as an alias for standard input.

A scalar reference

If $input_filename_or_reference is a scalar reference, the input data will be read from $$input_filename_or_reference.

An array reference

If $input_filename_or_reference is an array reference, each element in the array must be a filename.

The input data will be read from each file in turn.

The complete array will be walked to ensure that it only contains valid filenames before any data is uncompressed.

An Input FileGlob string

If $input_filename_or_reference is a string that is delimited by the characters "<" and ">" gunzip will assume that it is an input fileglob string. The input is the list of files that match the fileglob.

See File::GlobMapper for more details.

If the $input_filename_or_reference parameter is any other type, undef will be returned.

The $output_filename_or_reference parameter

The parameter $output_filename_or_reference is used to control the destination of the uncompressed data. This parameter can take one of these forms.

A filename

If the $output_filename_or_reference 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.

A filehandle

If the $output_filename_or_reference parameter is a filehandle, the uncompressed data will be written to it. The string '-' can be used as an alias for standard output.

A scalar reference

If $output_filename_or_reference is a scalar reference, the uncompressed data will be stored in $$output_filename_or_reference.

An Array Reference

If $output_filename_or_reference is an array reference, the uncompressed data will be pushed onto the array.

An Output FileGlob

If $output_filename_or_reference is a string that is delimited by the characters "<" and ">" gunzip will assume that it is an output fileglob string. The output is the list of files that match the fileglob.

When $output_filename_or_reference is an fileglob string, $input_filename_or_reference must also be a fileglob string. Anything else is an error.

See File::GlobMapper for more details.

If the $output_filename_or_reference parameter is any other type, undef will be returned.

Notes

When $input_filename_or_reference maps to multiple compressed files/buffers and $output_filename_or_reference is a single file/buffer, after uncompression $output_filename_or_reference will contain a concatenation of all the uncompressed data from each of the input files/buffers.

Optional Parameters

Unless specified below, the optional parameters for gunzip, OPTS, are the same as those used with the OO interface defined in the "Constructor Options" section below.

AutoClose => 0|1

This option applies to any input or output data streams to gunzip that are filehandles.

If AutoClose is specified, and the value is true, it will result in all input and/or output filehandles being closed once gunzip has completed.

This parameter defaults to 0.

BinModeOut => 0|1

When writing to a file or filehandle, set binmode before writing to the file.

Defaults to 0.

Append => 0|1

The behaviour of this option is dependent on the type of output data stream.

  • A Buffer

    If Append 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.

  • A Filename

    If Append 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.

  • A Filehandle

    If Append is enabled, the filehandle will be positioned to the end of the file via a call to seek before any uncompressed data is written to it. Otherwise the file pointer will not be moved.

When Append is specified, and set to true, it will append all uncompressed data to the output data stream.

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.

Conversely when Append is not specified, or it is present and is set to false, it will operate as follows.

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.

Defaults to 0.

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.

Defaults to 0.

TrailingData => $scalar

Returns the data, if any, that is present immediately after the compressed data stream once uncompression is complete.

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.

If the input is a buffer, trailingData will return everything from the end of the compressed data stream to the end of the buffer.

If the input is a filehandle, trailingData 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.

Don't bother using trailingData if the input is a filename.

If you know the length of the compressed data stream before you start uncompressing, you can avoid having to use trailingData by setting the InputLength option.