目錄

• 名稱
• 用法概要
• 描述
• 功能介面
  • gunzip $input_filename_or_reference => $output_filename_or_reference [, OPTS]
    • 參數 $input_filename_or_reference
    • 參數 $output_filename_or_reference
  • 注意事項
  • 可選參數
  • 範例
• 物件導向介面
  • 建構子
  • 建構子選項
  • 範例
• 方法
  • read
  • read
  • getline
  • getc
  • ungetc
  • inflateSync
  • getHeaderInfo
  • tell
  • eof
  • seek
  • binmode
  • opened
  • autoflush
  • input_line_number
  • fileno
  • close
  • nextStream
  • trailingData
• 匯入
• 範例
  • 與 Net::FTP 一起工作
• 支援
• 參見
• 作者
• 修改歷史
• 版權與許可

#名稱

IO::Uncompress::Gunzip - 讀取 RFC 1952 檔案/緩衝區

#用法概要

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

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

my $z = IO::Uncompress::Gunzip->new( $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)

#描述

此模組提供了一個 Perl 介面，允許讀取符合 RFC 1952 標準的文件/緩衝區。

要寫入符合 RFC 1952 的文件/緩衝區，請參見相關模組 IO::Compress::Gzip。

#功能介面

提供了一個頂層函數 gunzip，用於在緩衝區和/或文件之間進行“一次性”解壓縮。如需對解壓縮過程進行更精確的控制，請參見“OO 介面”部分。

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

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

功能介面需要 Perl5.005 或更高版本。

#gunzip $input_filename_or_reference => $output_filename_or_reference [, OPTS]

gunzip 需要至少兩個參數，$input_filename_or_reference 和 $output_filename_or_reference，以及零個或多個可選參數（參見“可選參數”）

#$input_filename_or_reference 參數

參數 $input_filename_or_reference 用於定義壓縮數據的來源。

它可以採用以下形式之一

#文件名

如果 $input_filename_or_reference 參數是一個簡單標量，則假定它是一個文件名。將打開此文件進行讀取，並從中讀取輸入數據。

#文件句柄

如果 $input_filename_or_reference 參數是一個文件句柄，則從中讀取輸入數據。字符串“-”可用作標準輸入的別名。

#標量引用

如果 $input_filename_or_reference 是一個標量引用，則從 $$input_filename_or_reference 中讀取輸入數據。

#數組引用

如果 $input_filename_or_reference 是一個數組引用，則數組中的每個元素必須是文件名。

將依次從每個文件中讀取輸入數據。

在未解壓縮任何數據之前，將完整遍歷整個數組，以確保它只包含有效的文件名。

#輸入文件全局字符串

如果 $input_filename_or_reference 是由“<”和“>”字符界定的字符串，gunzip 將假定它是一個 輸入文件全局字符串。輸入是與文件全局字符串匹配的文件列表。

有關更多詳情，請參見 File::GlobMapper。

如果 $input_filename_or_reference 参数为其他类型，则将返回 undef。

#参数 $output_filename_or_reference

参数 $output_filename_or_reference 用于控制未压缩数据的目标位置。此参数可以采用以下形式之一。

#文件名

如果 $output_filename_or_reference 参数是一个简单的标量，则假定它是一个文件名。将打开此文件进行写入，并将未压缩数据写入其中。

#文件句柄

如果 $output_filename_or_reference 参数是一个文件句柄，则未压缩数据将写入其中。字符串 '-' 可以用作标准输出的别名。

#标量引用

如果 $output_filename_or_reference 是一个标量引用，则未压缩的数据将存储在 $$output_filename_or_reference 中。

#数组引用

如果 $output_filename_or_reference 是一个数组引用，则未压缩的数据将被推送到数组中。

#输出文件通配符

如果 $output_filename_or_reference 是由字符 "<" 和 ">" 分隔的字符串，gunzip 将假定它是一个 输出文件通配符字符串。输出是与文件通配符匹配的文件列表。

当 $output_filename_or_reference 是文件通配符字符串时，$input_filename_or_reference 也必须是文件通配符字符串。否则将报错。

有關更多詳情，請參見 File::GlobMapper。

如果 $output_filename_or_reference 参数为其他类型，则将返回 undef。

#注释

当 $input_filename_or_reference 映射到多个压缩文件/缓冲区，并且 $output_filename_or_reference 是单个文件/缓冲区时，在解压缩后 $output_filename_or_reference 将包含来自每个输入文件/缓冲区的所有未压缩数据的串联。

#可选参数

一次性函数 gunzip 的可选参数（大部分）与在 "构造函数选项" 部分定义的 OO 接口相同。以下是例外情况

#AutoClose => 0|1

此選項適用於任何作為文件處理程序的 gunzip 的輸入或輸出數據流。

如果指定了 AutoClose，且值為 true，則將導致所有輸入和/或輸出文件處理程序在 gunzip 完成後被關閉。

此參數默認為 0。

#BinModeOut => 0|1

此選項現在已經不起作用。所有文件將以二進制模式寫入。

#Append => 0|1

此選項的行為取決於輸出數據流的類型。

• 緩衝區

  如果啟用了 Append，則所有未壓縮的數據將附加到輸出緩衝區的末尾。否則，在將任何未壓縮的數據寫入之前，輸出緩衝區將被清除。

• 文件名

  如果啟用了 Append，則文件將以附加模式打開。否則，在將任何未壓縮的數據寫入之前，文件的內容（如果有）將被截斷。

• 文件處理程序

  如果啟用了 Append，則在寫入任何未壓縮的數據之前，文件處理程序將通過調用 seek 定位到文件的末尾。否則，文件指針將不移動。

當指定了 Append，且設置為 true 時，將所有未壓縮的數據“附加”到輸出數據流。

因此，當輸出是文件處理程序時，它將在寫入任何未壓縮的數據之前進行尋找到文件結尾。如果輸出是文件名，它將被打開以進行附加。如果輸出是緩衝區，則所有未壓縮的數據將附加到現有的緩衝區。

相反，當未指定 Append，或者它存在且設置為 false 時，它將按以下方式操作。

當輸出是文件名時，將在寫入任何未壓縮的數據之前截斷文件的內容。如果輸出是文件處理程序，其位置將不會更改。如果輸出是緩衝區，則在輸出任何未壓縮的數據之前，它將被清除。

默認為 0。

#MultiStream => 0|1

如果輸入文件/緩衝區包含多個壓縮的數據流，此選項將將整個數據解壓縮為單個數據流。

默認為 0。

#TrailingData => $scalar

解壓縮完成後，返回存在於壓縮數據流之後的數據（如果有）。

當壓縮數據流之後立即有有用信息時，可以使用此選項，且不知道壓縮數據流的長度。

如果輸入是緩衝區，trailingData 將返回從壓縮數據流的末尾到緩衝區末尾的所有內容。

如果輸入是文件處理器，trailingData 將返回壓縮數據流的結尾到文件處理器輸入緩衝區的剩餘數據。然後您可以使用文件處理器來讀取輸入文件的其餘部分。

如果輸入是文件名，請勿使用trailingData。

如果您在開始解壓縮之前知道壓縮數據流的長度，則可以通過設置InputLength選項來避免使用trailingData。

#示例

讀取文件file1.txt.gz的內容並將未壓縮的數據寫入文件file1.txt。

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

my $input = "file1.txt.gz";
my $output = "file1.txt";
gunzip $input => $output
    or die "gunzip failed: $GunzipError\n";

從現有的Perl文件處理器$input讀取，並將未壓縮的數據寫入緩衝區$buffer。

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

my $input = IO::File->new( "<file1.txt.gz" )
    or die "Cannot open 'file1.txt.gz': $!\n" ;
my $buffer ;
gunzip $input => \$buffer
    or die "gunzip failed: $GunzipError\n";

解壓縮目錄"/my/home"中匹配 "*.txt.gz" 的所有文件並將壓縮數據存儲在相同目錄中。

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

gunzip '</my/home/*.txt.gz>' => '</my/home/#1.txt>'
    or die "gunzip failed: $GunzipError\n";

如果要逐個壓縮每個文件，則可使用以下方法。

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

for my $input ( glob "/my/home/*.txt.gz" )
{
    my $output = $input;
    $output =~ s/.gz// ;
    gunzip $input => $output
        or die "Error compressing '$input': $GunzipError\n";
}

#面向對象（OO）接口

#構造函數

IO::Uncompress::Gunzip的構造函數格式如下所示

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

成功時返回一個IO::Uncompress::Gunzip對象，失敗時返回undef。變量$GunzipError將在失敗時包含一個錯誤消息。

如果您運行的是Perl 5.005或更高版本，則從IO::Uncompress::Gunzip返回的對象$z可以像IO::File文件處理器一樣使用。這意味著可以使用$z進行所有正常的輸入文件操作。例如，要從壓縮文件/緩衝區讀取一行，可以使用以下任一形式

$line = $z->getline();
$line = <$z>;

強制參數$input用於確定壓縮數據的來源。此參數可以採用三種形式之一。

#文件名

如果$input參數是一個標量，則假定它是一個文件名。將打開此文件進行讀取，並從中讀取壓縮數據。

#文件處理器

如果$input參數是一個文件處理器，壓縮數據將從中讀取。字串'-'可以作為標準輸入的別名。

#純量引用

如果$input是一個純量引用，壓縮數據將從$$input中讀取。

#構造函數選項

下面定義的選項名稱不區分大小寫，並且可以選擇性地以'-'作為前綴。所以以下所有都是有效的

-AutoClose
-autoclose
AUTOCLOSE
autoclose

選項是以下選項的組合

#自動關閉 => 0|1

此選項僅在$input參數是文件處理器時有效。如果指定並且值為真，則將導致文件在調用close方法或IO::Uncompress::Gunzip對象被銷毀時被關閉。

此參數默認為 0。

#多流 => 0|1

允許將多個串聯的壓縮流視為單個壓縮流。解壓縮將在達到文件/緩衝區的末尾、遇到錯誤（提前eof、壓縮數據損壞）或一個流的結尾後不立即跟隨另一個流的開始時停止。

此參數默認為 0。

#預先壓縮 => $string

此選項將在處理輸入文件/緩衝區之前解壓縮$string的內容。

當壓縮數據嵌入到另一個文件/數據結構中且無法通過讀取前幾個字節來確定壓縮數據的開始位置時，此選項可能很有用。如果是這種情況，則可以使用此選項使用這些字節對解壓縮進行預先壓縮。

#透明 => 0|1

如果設置了此選項且輸入文件/緩衝區不是壓縮數據，模塊將允許仍然讀取它。

此外，如果輸入檔案/緩衝區包含壓縮資料，並且隨後立即有非壓縮資料，設置此選項將使此模塊將整個檔案/緩衝區視為單個資料流。

此選項的預設值為1。

#BlockSize => $num

在讀取壓縮輸入資料時，IO::Uncompress::Gunzip 將以 $num 字節為單位讀取。

此選項的預設值為4096。

#InputLength => $size

當存在此選項時，將限制從輸入檔案/緩衝區讀取的壓縮字節數為 $size。此選項可用於壓縮資料流後直接有有用資料的情況，並且您事先知道壓縮資料流的確切長度。

此選項在從文件處理時大多使用，此時文件指針將指向壓縮資料流之後的第一個字節。

此選項的預設值為關閉。

#Append => 0|1

此選項控制 read 方法對未壓縮資料的處理方式。

如果設置為1，則所有未壓縮資料將附加到 read 方法的輸出參數中。

如果設置為0，則 read 方法的輸出參數內容將被未壓縮資料覆蓋。

默認為 0。

#Strict => 0|1

此選項控制是否在進行解壓縮時使用下面定義的額外檢查。當啟用 Strict 時，將進行額外測試；當關閉 Strict 時，將不進行額外測試。

此選項的默認值為關閉。

1. 如果 gzip FLG 標頭位元組中設置了 FHCRC 位，則標頭中的 CRC16 字節必須與實際讀取的 gzip 標頭的 crc16 值匹配。

2. 如果 gzip 標頭包含名稱字段 (FNAME)，則它僅包含 ISO 8859-1 字元。

3. 如果 gzip 標頭包含注釋字段 (FCOMMENT)，則它僅包含 ISO 8859-1 字元和換行符。

4. 如果存在 gzip FEXTRA 標頭字段，則它必須符合 RFC 1952 中定義的子字段結構。

5. 必須存在 CRC32 和 ISIZE 尾部字段。

6. 讀取的 CRC32 字段的值必須與實際包含在 gzip 檔案中的未壓縮資料的 crc32 值匹配。

7. 讀取的 ISIZE 字段的值必須與實際從文件中讀取的未壓縮資料的長度匹配。

#ParseExtra => 0|1 如果存在 gzip FEXTRA 標頭字段並且設置了此選項，它將強制模塊檢查它是否符合 RFC 1952 中定義的子字段結構。

如果啟用 Strict，它將自動啟用此選項。

默認為 0。

#範例

待辦事項

#方法

#讀取

使用方式

$status = $z->read($buffer)

讀取壓縮資料塊（壓縮塊的大小由建構子中的 Buffer 選項決定），將其解壓縮並將任何未壓縮的資料寫入 $buffer。如果建構子中設置了 Append 參數，則未壓縮的資料將附加到 $buffer 參數。否則 $buffer 將被覆蓋。

返回寫入到 $buffer 的未壓縮位元組的數量，如果 eof 或錯誤則返回零或負數。

#讀取

使用方式

$status = $z->read($buffer, $length)
$status = $z->read($buffer, $length, $offset)

$status = read($z, $buffer, $length)
$status = read($z, $buffer, $length, $offset)

嘗試讀取 $length 個未壓縮資料位元組到 $buffer 中。

此形式的 read 方法與前一個方法的主要區別在於，此方法將嘗試返回 正好 $length 個位元組。唯一不會執行的情況是遇到文件結尾或 IO 錯誤。

返回寫入到 $buffer 的未壓縮位元組的數量，如果 eof 或錯誤則返回零或負數。

#getline

使用方式

$line = $z->getline()
$line = <$z>

讀取一行。

此方法完全支援變量 $/（或當使用 English 時為 $INPUT_RECORD_SEPARATOR 或 $RS）以確定什麼構成行尾。支援段落模式、記錄模式和文件 slurp 模式。

#getc

使用方式

$char = $z->getc()

讀取單個字符。

#ungetc

使用方式

$char = $z->ungetc($string)

#inflateSync

使用方式

$status = $z->inflateSync()

待辦事項

#getHeaderInfo

使用方式

$hdr  = $z->getHeaderInfo();
@hdrs = $z->getHeaderInfo();

此方法返回壓縮數據流中每個標頭字段的信息的哈希引用（在標量上下文中）或列表或哈希引用（在數組上下文中）。

#名稱

如果存在 Name 標頭字段，則為其內容。如果沒有名稱，則值將為 undef。請注意，這與零長度名稱不同，後者將返回空字符串。

#註釋

如果存在 Comment 標頭字段，則為其內容。如果沒有註釋，則值將為 undef。請注意，這與零長度註釋不同，後者將返回空字符串。

#tell

使用方式

$z->tell()
tell $z

返回未壓縮的文件偏移量。

#eof

使用方式

$z->eof();
eof($z);

如果已經到達壓縮輸入流的結尾，則返回 true。

#seek

$z->seek($position, $whence);
seek($z, $position, $whence);

提供seek功能的子集，限制只能在輸入文件/緩衝區中向前搜索。嘗試向後搜索會導致致命錯誤。

請注意，此模塊中seek的實現並不提供對壓縮文件/緩衝區的真正隨機訪問。它的工作方式是從文件/緩衝區中的當前偏移開始解壓縮數據，直到達到seek參數中指定的未壓縮偏移。對於非常小的文件，這可能是可以接受的行為。對於大文件，可能會導致不可接受的延遲。

$whence參數接受一個通常的值，即 SEEK_SET、SEEK_CUR 或 SEEK_END。

成功返回 1，失敗返回 0。

#binmode

使用方式

$z->binmode
binmode $z ;

這是為了完整性而提供的空操作。

#opened

$z->opened()

如果對象當前引用了一個已打開的文件/緩衝區，則返回 true。

#autoflush

my $prev = $z->autoflush()
my $prev = $z->autoflush(EXPR)

如果$z對象與文件或文件處理程序關聯，則此方法返回底層文件處理程序的當前自動刷新設置。如果EXPR存在且非零，則它將在每次寫入/打印操作後啟用刷新。

如果$z與緩衝區關聯，則此方法不起作用並始終返回undef。

請注意，特殊變量$| 不能用於設置或檢索自動刷新設置。

#input_line_number

$z->input_line_number()
$z->input_line_number(EXPR)

返回當前未壓縮的行號。如果存在EXPR，則將影響行號。請注意，設置行號不會更改正在讀取的文件/緩衝區中的當前位置。

使用$/的內容來確定什麼構成行終止符。

#fileno

$z->fileno()
fileno($z)

如果$z對象與文件或文件處理程序關聯，fileno將返回底層文件描述符。一旦調用close方法，fileno將返回undef。

如果$z對象與緩衝區關聯，則此方法將返回undef。

#close

$z->close() ;
close $z ;

關閉輸出文件/緩衝區。

對於大多數版本的 Perl，如果 IO::Uncompress::Gunzip 對象被銷毀（無論是顯式地還是由於包含對該對象引用的變量超出了作用域），則此方法將自動調用。當程序終止時，對象全局摧毀所有存活對象的異常情況是 Perl 版本 5.005 至 5.00504 和 5.8.0。在這些情況下，將自動調用close方法，但僅在程序終止時全局銷毀所有存活對象時才會這樣做。

因此，如果您希望您的脚本能够在所有版本的Perl上运行，您应该显式调用close，而不是依赖自动关闭。

成功返回true，否则返回0。

如果在创建IO::Uncompress::Gunzip对象时启用了AutoClose选项，并且对象与文件相关联，则底层文件也将被关闭。

#nextStream

使用方式

my $status = $z->nextStream();

跳至输入文件/缓冲区中的下一个压缩数据流。如果找到新的压缩数据流，则eof标记将被清除，并且$.将被重置为0。

如果找到新的流，则返回1，如果未找到，则返回0，如果遇到错误，则返回-1。

#trailingData

使用方式

my $data = $z->trailingData();

在解压缩完成后，返回紧跟在压缩数据流后的任何数据（如果存在）。只有在遇到压缩数据流的结尾后才有意义调用此方法。

當壓縮數據流之後立即有有用信息時，可以使用此選項，且不知道壓縮數據流的長度。

如果輸入是緩衝區，trailingData 將返回從壓縮數據流的末尾到緩衝區末尾的所有內容。

如果輸入是文件處理器，trailingData 將返回壓縮數據流的結尾到文件處理器輸入緩衝區的剩餘數據。然後您可以使用文件處理器來讀取輸入文件的其餘部分。

如果輸入是文件名，請勿使用trailingData。

如果您在开始解压缩之前知道压缩数据流的长度，可以通过在构造函数中设置InputLength选项来避免使用trailingData。

#Importing

IO::Uncompress::Gunzip目前不需要任何符号常量。

#:all

导入gunzip和$GunzipError。相当于执行以下操作

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

#EXAMPLES

#使用Net::FTP

请参阅IO::Compress::FAQ

#SUPPORT

一般反馈/问题/错误报告应发送至https://github.com/pmqs/IO-Compress/issues（首选）或https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress。

#另请参阅

Compress::Zlib、IO::Compress::Gzip、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

IO::Compress::FAQ

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 gzip@prep.ai.mit.edu 和 Mark Adler madler@alumni.caltech.edu 編寫。

zlib 壓縮庫的主要站點為 http://www.zlib.org。

zlib-ng 壓縮庫的主要站點為 https://github.com/zlib-ng/zlib-ng。

gzip 的主要站點為 http://www.gzip.org。

#作者

此模組由 Paul Marquess 編寫，pmqs@cpan.org。

#修改歷史

請參閱 Changes 檔案。

#版權和許可

版權所有 (c) 2005-2023 Paul Marquess。保留所有權利。

本程序是自由軟體；您可以根據 Perl 本身的相同條款重新發布或修改它。

Perldoc Browser 由 Dan Book (DBOOK) 維護。有關站點本身、搜索或文件呈現的任何問題，請通過GitHub 問題跟踪器或電子郵件與他聯繫。

Perl 文檔由 Perl 5 Porters 在 Perl 的開發中進行維護。有關文檔內容或格式的任何問題，請通過Perl 問題跟踪器、郵件列表或IRC與他們聯繫。