Compress::Zlib - zlib 压缩库的接口
use Compress::Zlib ;
($d, $status) = deflateInit( [OPT] ) ;
$status = $d->deflate($input, $output) ;
$status = $d->flush([$flush_type]) ;
$d->deflateParams(OPTS) ;
$d->deflateTune(OPTS) ;
$d->dict_adler() ;
$d->crc32() ;
$d->adler32() ;
$d->total_in() ;
$d->total_out() ;
$d->msg() ;
$d->get_Strategy();
$d->get_Level();
$d->get_BufSize();
($i, $status) = inflateInit( [OPT] ) ;
$status = $i->inflate($input, $output [, $eof]) ;
$status = $i->inflateSync($input) ;
$i->dict_adler() ;
$d->crc32() ;
$d->adler32() ;
$i->total_in() ;
$i->total_out() ;
$i->msg() ;
$d->get_BufSize();
$dest = compress($source) ;
$dest = uncompress($source) ;
$gz = gzopen($filename or filehandle, $mode) ;
$bytesread = $gz->gzread($buffer [,$size]) ;
$bytesread = $gz->gzreadline($line) ;
$byteswritten = $gz->gzwrite($buffer) ;
$status = $gz->gzflush($flush) ;
$offset = $gz->gztell() ;
$status = $gz->gzseek($offset, $whence) ;
$status = $gz->gzclose() ;
$status = $gz->gzeof() ;
$status = $gz->gzsetparams($level, $strategy) ;
$errstring = $gz->gzerror() ;
$gzerrno
$dest = Compress::Zlib::memGzip($buffer) ;
$dest = Compress::Zlib::memGunzip($buffer) ;
$crc = adler32($buffer [,$crc]) ;
$crc = crc32($buffer [,$crc]) ;
$crc = crc32_combine($crc1, $crc2, $len2);
$adler = adler32_combine($adler1, $adler2, $len2);
my $version = Compress::Raw::Zlib::zlib_version();Compress::Zlib 模块为 zlib 压缩库提供 Perl 接口（有关从何处获取 zlib 的详细信息，请参见 "AUTHOR"）。
Compress::Zlib 模块可分为两个通用功能区域，即 gzip 文件的简单读/写接口和低级别内存压缩/解压缩接口。
以下部分将讨论这些区域的每一个。
Compress::Zlib 版本 2.x 的主要更改是，它现在不直接与 zlib 库连接。相反，它使用 IO::Compress::Gzip 和 IO::Uncompress::Gunzip 模块来读/写 gzip 文件，并使用 Compress::Raw::Zlib 模块来进行一些低级别的 zlib 访问。
此模块的版本 2 提供的接口应与版本 1 完全向后兼容。如果您发现预期行为有所不同，请联系作者（请参见 "AUTHOR"）。请参见 "GZIP INTERFACE"
随着 IO::Compress 和 IO::Uncompress 模块的创建，Compress::Zlib 不再计划推出新功能 - 新模块执行 Compress::Zlib 执行的所有操作，并提供更多功能。对 Compress::Zlib 的开发将仅限于错误修复。
如果您正在编写新代码，您的首选应为新的 IO::Compress 或 IO::Uncompress 模块。
zlib 中提供了许多函数，用于读写符合 RFC 1952 的 gzip 文件。此模块为其中大部分函数提供了一个接口。
如果您之前使用过 Compress::Zlib 1.x，则已对 gzopen 接口进行了以下增强/更改
如果您想使用 gzopen 打开 STDIN 或 STDOUT，现在可以选择使用特殊文件名 "-" 作为 \*STDIN 和 \*STDOUT 的同义词。
在 Compress::Zlib 版本 1.x 中，gzopen 使用 zlib 库打开底层文件。当将 Perl 文件句柄传递给 gzopen 时，这会让事情变得特别棘手。在后台，必须从 Perl 文件句柄中提取数字 C 文件描述符，然后将其传递给 zlib 库。
除了无法移植到某些操作系统之外，这还使得在您想要提取/创建嵌入在较大文件中的 gzip 数据流的情况下难以使用 gzopen，而无需多次打开和关闭文件。
这也使得无法传递未与真实文件系统文件关联的 perl 文件句柄，例如 IO::String。
在 Compress::Zlib 2.x 版本中，gzopen 接口已被完全重写，以使用 IO::Compress::Gzip 来写入 gzip 文件，以及使用 IO::Uncompress::Gunzip 来读取 gzip 文件。上述限制均不适用。
添加 gzseek 以提供受限的 seek 接口。
添加 gztell。
模块 IO-Compress-Zlib 中包含一个更完整、更灵活的接口，用于读取/写入 gzip 文件/缓冲区。有关更多详细信息，请参阅 IO::Compress::Gzip 和 IO::Uncompress::Gunzip。
此函数打开 gzip 文件 $filename 以进行读取或写入，或附加到已打开的文件句柄 $filehandle。如果成功，它将返回一个对象，如果失败，则返回 undef。
在写入 gzip 文件时，此接口始终会创建尽可能小的 gzip 头（正好 10 个字节）。如果您希望更好地控制 gzip 头中存储的内容（如原始文件名或注释），请改用 IO::Compress::Gzip。同样，如果您希望读取 gzip 头的内容，请使用 IO::Uncompress::Gunzip。
第二个参数 $mode 用于指定文件是打开用于读取还是写入，以及在写入时可以选择性地指定压缩级别和压缩策略。$mode 参数的格式类似于“C”函数 fopen 的模式参数，因此“rb”用于打开以进行读取，“wb”用于写入，“ab”用于追加（在文件末尾写入）。
要在写入时指定压缩级别，请将 0 到 9 之间的数字附加到模式字符串——0 表示无压缩，9 表示最大压缩。如果未指定压缩级别，则使用 Z_DEFAULT_COMPRESSION。
要在写入时指定压缩策略，请附加“f”表示已过滤数据，“h”表示仅 Huffman 压缩，或“R”表示游程长度编码。如果未指定策略，则使用 Z_DEFAULT_STRATEGY。
因此，例如，“wb9”表示使用默认策略以最大压缩进行打开以进行写入，“wb4R”表示以压缩级别 4 和游程长度编码进行打开以进行写入。
有关 $mode 参数的确切格式，请参阅zlib 文档。
从压缩文件中读取 $size 字节到 $buffer 中。如果未指定 $size，则默认为 4096。如果标量 $buffer 不够大，它将自动扩展。
返回实际读取的字节数。在 EOF 时返回 0，在出现错误时返回 -1。
将压缩文件中的下一行读入 $line。
返回实际读取的字节数。在 EOF 时返回 0，在出现错误时返回 -1。
可以将对 gzread 和 gzreadline 的调用混合使用。
为了与该模块的 1.x 版本保持向后兼容性，gzreadline 会忽略 $/ 变量 - 它始终使用字符串 "\n" 作为行分隔符。
如果你想一次读取一个 gzip 文件的行并使其遵守 $/ 变量（或在使用 English 时为 $INPUT_RECORD_SEPARATOR 或 $RS），请参阅 IO::Uncompress::Gunzip。
将 $buffer 的内容写入压缩文件。返回实际写入的字节数，或在出现错误时返回 0。
将所有待处理的输出刷新到压缩文件中。
此方法采用一个可选参数 $flush_type，用于控制刷新方式。默认情况下，使用的 $flush_type 为 Z_FINISH。$flush_type 的其他有效值为 Z_NO_FLUSH、Z_SYNC_FLUSH、Z_FULL_FLUSH 和 Z_BLOCK。强烈建议你仅在你完全理解其含义的情况下设置 flush_type 参数 - 过度使用 flush 会严重降低达到的压缩级别。有关详细信息，请参阅 zlib 文档。
成功时返回 0。
返回未压缩的文件偏移量。
提供 seek 功能的子集，限制为仅允许在压缩文件中向前查找。尝试向后查找是致命错误。
在打开进行写入时，将向文件的空部分写入 NULL (0x00) 字节。
$whence 参数应为 SEEK_SET、SEEK_CUR 或 SEEK_END 之一。
成功时返回 1，失败时返回 0。
关闭压缩文件。在关闭文件之前，会将所有挂起的数据刷新到该文件中。
成功时返回 0。
更改 deflate 流 $gz 的设置。
有效选项的列表如下所示。未指定的选项将保持不变。
注意：此方法仅在运行 zlib 1.0.6 或更高版本时可用。
返回与 $gz 关联的上次操作的zlib 错误消息或数字。在数字上下文中使用时，返回值将是zlib 错误号；在字符串上下文中使用时，返回值将是zlib 错误消息。以下所示的zlib 错误号常量可供使用。
Z_OK
Z_STREAM_END
Z_ERRNO
Z_STREAM_ERROR
Z_DATA_ERROR
Z_MEM_ERROR
Z_BUF_ERROR$gzerrno 标量保存与最近的gzip 例程关联的错误代码。请注意，与 gzerror() 不同，该错误不与特定文件关联。
与 gzerror() 一样，它在数字上下文中返回错误号，在字符串上下文中返回错误消息。但与 gzerror() 不同，当错误与zlib 本身相关时，错误消息将对应于zlib 消息；当错误与zlib 无关时，错误消息将对应于 UNIX 错误消息（即zlib 返回 Z_ERRORNO）。
由于zlib 和 UNIX 使用的错误号之间存在重叠，因此仅应在数字上下文中使用 $gzerrno 来检查是否存在错误。使用 gzerror() 来检查特定的zlib 错误。以下gzcat 示例展示了如何安全地使用该变量。
这是一个使用该接口的示例脚本。它实现了一个gzcat 函数。
use strict ;
use warnings ;
use Compress::Zlib ;
# use stdin if no files supplied
@ARGV = '-' unless @ARGV ;
foreach my $file (@ARGV) {
my $buffer ;
my $gz = gzopen($file, "rb")
or die "Cannot open $file: $gzerrno\n" ;
print $buffer while $gz->gzread($buffer) > 0 ;
die "Error reading from $file: $gzerrno" . ($gzerrno+0) . "\n"
if $gzerrno != Z_STREAM_END ;
$gz->gzclose() ;
}以下是一个使用 gzreadline 的脚本。它实现了一个非常简单的类似grep 的脚本。
use strict ;
use warnings ;
use Compress::Zlib ;
die "Usage: gzgrep pattern [file...]\n"
unless @ARGV >= 1;
my $pattern = shift ;
# use stdin if no files supplied
@ARGV = '-' unless @ARGV ;
foreach my $file (@ARGV) {
my $gz = gzopen($file, "rb")
or die "Cannot open $file: $gzerrno\n" ;
while ($gz->gzreadline($_) > 0) {
print if /$pattern/ ;
}
die "Error reading from $file: $gzerrno\n"
if $gzerrno != Z_STREAM_END ;
$gz->gzclose() ;
}此脚本gzstream 与上述gzcat 脚本相反。它从标准输入读取内容，并向标准输出写入 gzip 数据流。
use strict ;
use warnings ;
use Compress::Zlib ;
binmode STDOUT; # gzopen only sets it on the fd
my $gz = gzopen(\*STDOUT, "wb")
or die "Cannot open stdout: $gzerrno\n" ;
while (<>) {
$gz->gzwrite($_)
or die "error writing: $gzerrno\n" ;
}
$gz->gzclose ;此函数用于创建具有最小可能 gzip 头（恰好 10 个字节）的内存中 gzip 文件。
$dest = Compress::Zlib::memGzip($buffer)
or die "Cannot compress: $gzerrno\n";如果成功，它将返回内存中 gzip 文件。否则，它将返回 undef，并且 $gzerrno 变量将存储 zlib 错误代码。
$buffer 参数可以是标量或标量引用。
请参阅 IO::Compress::Gzip，了解执行内存中 gzip 压缩的替代方法。
此函数用于解压缩内存中 gzip 文件。
$dest = Compress::Zlib::memGunzip($buffer)
or die "Cannot uncompress: $gzerrno\n";如果成功，它将返回未压缩的 gzip 文件。否则，它将返回 undef，并且 $gzerrno 变量将存储 zlib 错误代码。
$buffer 参数可以是标量或标量引用。调用此函数后，$buffer 参数的内容将被销毁。
如果 $buffer 由多个连接的 gzip 数据流组成，则仅第一个将被解压缩。如果您需要处理连接的数据流，请在 IO::Uncompress::Gunzip 模块中使用 gunzip 和 MultiStream 选项。
请参阅 IO::Uncompress::Gunzip，了解执行内存中 gzip 解压缩的替代方法。
提供了两个函数来执行 RFC 1950 数据流的内存中压缩/解压缩。它们被称为 compress 和 uncompress。
压缩 $source。如果成功，它将返回压缩后的数据。否则，它将返回 undef。
源缓冲区 $source 可以是标量或标量引用。
$level 参数定义压缩级别。有效值为 0 到 9，Z_NO_COMPRESSION、Z_BEST_SPEED、Z_BEST_COMPRESSION 和 Z_DEFAULT_COMPRESSION。如果未指定 $level，将使用 Z_DEFAULT_COMPRESSION。
解压缩 $source。如果成功，它将返回未压缩的数据。否则，它将返回 undef。
源缓冲区可以是标量或标量引用。
请注意：上面定义的两个函数不与同名 Unix 命令兼容。
请参阅此发行版中包含的 IO::Deflate 和 IO::Inflate，了解用于读/写 RFC 1950 文件/缓冲区的替代接口。
本节定义了一个接口，允许使用 zlib 提供的deflate 接口进行内存中压缩。
以下是可用接口的定义
初始化一个压缩流。
它结合了 zlib 函数 deflateInit、deflateInit2 和 deflateSetDictionary 的功能。
如果成功，它将在列表上下文中返回已初始化的压缩流 $d 和 $status（值为 Z_OK）。在标量上下文中，它仅返回压缩流 $d。
如果不成功，返回的压缩流 ($d) 将为 undef，而 $status 将保存确切的 zlib 错误代码。
该函数可以选择采用指定为 -Name=>value 对的多个命名选项。这允许定制各个选项，而无需在参数列表中指定所有选项。
为了向后兼容，也可以将参数作为对包含 name=>value 对的哈希的引用来传递。
该函数采用一个可选参数，即对哈希的引用。哈希的内容允许定制压缩接口。
以下是有效选项的列表
定义压缩级别。有效值为 0 到 9、Z_NO_COMPRESSION、Z_BEST_SPEED、Z_BEST_COMPRESSION 和 Z_DEFAULT_COMPRESSION。
默认值为 Z_DEFAULT_COMPRESSION。
定义压缩方法。目前唯一有效的值（也是默认值）是 Z_DEFLATED。
要创建 RFC 1950 数据流，请将 WindowBits 设置为正数。
要创建 RFC 1951 数据流，请将 WindowBits 设置为 -MAX_WBITS。
有关 WindowBits 的含义和有效值的完整定义，请参阅 zlib 文档中的 deflateInit2。
默认为 MAX_WBITS。
有关 MemLevel 的含义和有效值的定义，请参阅 zlib 文档中的 deflateInit2。
默认为 MAX_MEM_LEVEL。
定义用于调整压缩的策略。有效值为 Z_DEFAULT_STRATEGY、Z_FILTERED 和 Z_HUFFMAN_ONLY。
默认值为 Z_DEFAULT_STRATEGY。
当指定字典时，Compress::Zlib 会在调用 deflateInit 后自动直接调用 deflateSetDictionary。可以通过调用方法 $d->dict_adler() 获得字典的 Adler32 值。
默认情况下没有字典。
设置解压缩缓冲区的初始大小。如果必须重新分配缓冲区以增加大小，则它将以 Bufsize 的增量增长。
默认值为 4096。
以下是如何使用 deflateInit 可选参数列表覆盖默认缓冲区大小和压缩级别的示例。所有其他选项都将采用其默认值。
deflateInit( -Bufsize => 300,
-Level => Z_BEST_SPEED ) ;解压缩 $buffer 的内容。缓冲区可以是标量或标量引用。完成后，$buffer 将被完全处理（假设没有错误）。如果解压缩成功，它将返回解压缩输出 $out 和状态值 $status，即 Z_OK。
如果出错，$out 将为 undef，并且 $status 将包含 zlib 错误代码。
在标量上下文中，deflate 将仅返回 $out。
与 zlib 中的 deflate 函数一样，此方法不一定产生任何输出。因此，不要依赖于 $out 为空来进行错误测试。
通常用于完成解压缩。任何待处理的输出都将通过 $out 返回。如果成功，$status 将具有值 Z_OK。
在标量上下文中，flush 将仅返回 $out。
请注意，刷新会严重降低压缩比，因此它只应在终止解压缩（使用 Z_FINISH）或在要创建完全刷新点（使用 Z_FULL_FLUSH）时使用。
默认情况下，使用的 flush_type 是 Z_FINISH。flush_type 的其他有效值为 Z_NO_FLUSH、Z_PARTIAL_FLUSH、Z_SYNC_FLUSH 和 Z_FULL_FLUSH。强烈建议仅在完全理解其含义的情况下设置 flush_type 参数。有关详细信息，请参阅 zlib 文档。
更改解压缩流 $d 的设置。
有效选项的列表如下所示。未指定的选项将保持不变。
定义压缩级别。有效值为 0 到 9、Z_NO_COMPRESSION、Z_BEST_SPEED、Z_BEST_COMPRESSION 和 Z_DEFAULT_COMPRESSION。
定义用于调整压缩的策略。有效值为 Z_DEFAULT_STRATEGY、Z_FILTERED 和 Z_HUFFMAN_ONLY。
返回字典的 adler32 值。
返回 zlib 生成的最后一个错误消息。
返回输入到 deflate 的未压缩字节的总数。
返回从 deflate 输出的压缩字节的总数。
以下是使用 deflate 的一个简单示例。它只读取标准输入，对其进行压缩，然后将其写入标准输出。
use strict ;
use warnings ;
use Compress::Zlib ;
binmode STDIN;
binmode STDOUT;
my $x = deflateInit()
or die "Cannot create a deflation stream\n" ;
my ($output, $status) ;
while (<>)
{
($output, $status) = $x->deflate($_) ;
$status == Z_OK
or die "deflation failed\n" ;
print $output ;
}
($output, $status) = $x->flush() ;
$status == Z_OK
or die "deflation failed\n" ;
print $output ;本节定义了可用的接口，允许使用 zlib 提供的 deflate 接口进行内存解压缩。
以下是接口的定义
初始化一个膨胀流。
在列表上下文中，它返回膨胀流，$i，以及 $status 中的 zlib 状态代码。在标量上下文中，它只返回膨胀流。
如果成功，$i 将保存膨胀流，$status 将为 Z_OK。
如果不成功，$i 将为 undef，$status 将保存 zlib 错误代码。
该函数可以选择采用指定为 -Name=>value 对的多个命名选项。这允许定制各个选项，而无需在参数列表中指定所有选项。
为了向后兼容，也可以将参数作为对包含 name=>value 对的哈希的引用来传递。
该函数采用一个可选参数，即对哈希的引用。哈希的内容允许定制压缩接口。
以下是有效选项的列表
要解压缩 RFC 1950 数据流，将 WindowBits 设置为正数。
要解压缩 RFC 1951 数据流，将 WindowBits 设置为 -MAX_WBITS。
有关 WindowBits 的含义和有效值的完整定义，请参阅 zlib 文档中的 inflateInit2。
默认为 MAX_WBITS。
设置膨胀缓冲区的初始大小。如果必须重新分配缓冲区以增加大小，它将以 Bufsize 的增量增长。
默认值为 4096。
默认情况下没有字典。
以下是一个使用 inflateInit 可选参数来覆盖默认缓冲区大小的示例。
inflateInit( -Bufsize => 300 ) ;膨胀 $buffer 的全部内容。缓冲区可以是标量或标量引用。
如果成功，返回 Z_OK；如果已成功到达压缩数据的末尾，返回 Z_STREAM_END。如果不成功，$out 将为 undef，$status 将保存 zlib 错误代码。
$buffer 参数由 inflate 修改。完成时，它将包含解压后输入缓冲区中剩余的内容。这意味着当返回状态为 Z_OK 时，$buffer 将为空字符串。当返回状态为 Z_STREAM_END 时，$buffer 参数将包含解压数据流后输入缓冲区中存储的内容（如果存在）。
在处理封装压缩数据流的文件格式（例如 gzip、zip）时，此功能非常有用。
扫描 $buffer，直到达到完全刷新点或缓冲区末尾。
如果找到完全刷新点，则返回 Z_OK，并且 $buffer 将删除所有数据直至刷新点。然后可以将其传递给 deflate 方法。
任何其他返回代码都表示未找到刷新点。如果还有更多数据可用，则可以反复调用 inflateSync，提供更多压缩数据，直到找到刷新点。
返回字典的 adler32 值。
返回 zlib 生成的最后一个错误消息。
返回输入到 inflate 的压缩字节的总数。
返回从 inflate 输出的未压缩字节的总数。
以下是如何使用 inflate 的示例。
use strict ;
use warnings ;
use Compress::Zlib ;
my $x = inflateInit()
or die "Cannot create a inflation stream\n" ;
my $input = '' ;
binmode STDIN;
binmode STDOUT;
my ($output, $status) ;
while (read(STDIN, $input, 4096))
{
($output, $status) = $x->inflate(\$input) ;
print $output
if $status == Z_OK or $status == Z_STREAM_END ;
last if $status != Z_OK ;
}
die "inflation failed\n"
unless $status == Z_STREAM_END ;zlib 提供两个函数来计算校验和。对于 Perl 接口，这两个函数中两个参数的顺序已颠倒。这允许同时进行运行校验和和一次性计算。
$crc = adler32($buffer [,$crc]) ;
$crc = crc32($buffer [,$crc]) ;缓冲区参数可以是标量或标量引用。
如果 $crc 参数为 undef，则 crc 值将被重置。
如果您使用 zlib 1.2.3 或更高版本构建此模块，则可以使用另外两个与 CRC 相关的函数。
$crc = crc32_combine($crc1, $crc2, $len2);
$adler = adler32_combine($adler1, $adler2, $len2);这些函数允许合并校验和。有关更多详细信息，请参阅zlib 文档。
返回 zlib 库的版本。
当您使用 Compress::Zlib 时，所有 zlib 常量将自动导入。
一般反馈/问题/错误报告应发送至 https://github.com/pmqs/IO-Compress/issues（首选）或 https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress。
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::AnyInflate、IO::Uncompress::AnyUncompress
File::GlobMapper、Archive::Zip、Archive::Tar、IO::Zlib
有关 RFC 1950、1951 和 1952，请参阅 https://datatracker.ietf.org/doc/html/rfc1950、https://datatracker.ietf.org/doc/html/rfc1951 和 https://datatracker.ietf.org/doc/html/rfc1952
zlib 压缩库由 Jean-loup Gailly [email protected] 和 Mark Adler [email protected] 编写。
zlib 压缩库的主要网站是 http://www.zlib.org。
zlib-ng 压缩库的主要网站是 https://github.com/zlib-ng/zlib-ng。
gzip 的主要网站是 http://www.gzip.org。
此模块由 Paul Marquess 编写，[email protected]。
请参阅 Changes 文件。
版权所有 (c) 1995-2023 Paul Marquess。保留所有权利。
此程序是免费软件；您可以在与 Perl 本身相同的条款下重新分发或修改它。