內容

• 名稱
• 語法
• 說明
• 函式介面
  • bzip2 $input_filename_or_reference => $output_filename_or_reference [, OPTS]
    • $input_filename_or_reference 參數
    • $output_filename_or_reference 參數
  • 注意事項
  • 選用參數
  • 範例
    • 串流
    • 從檔案系統壓縮檔案
    • 從檔案句柄讀取並寫入記憶體緩衝區
    • 壓縮多個檔案
• 物件導向介面
  • 建構函式
  • 建構函式選項
  • 範例
• 方法
  • print
  • printf
  • syswrite
  • write
  • flush
  • tell
  • eof
  • seek
  • binmode
  • opened
  • autoflush
  • input_line_number
  • fileno
  • close
  • newStream([OPTS])
• 匯入
• 範例
  • Apache::GZip 回顧
  • 使用 Net::FTP
• 支援
• 請參閱
• 作者
• 修改記錄
• 版權與授權

#名稱

IO::Compress::Bzip2 - 寫入 bzip2 檔案/緩衝區

#語法

use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;

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

my $z = IO::Compress::Bzip2->new( $output [,OPTS] )
    or die "bzip2 failed: $Bzip2Error\n";

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

$Bzip2Error ;

# IO::File mode

print $z $string;
printf $z $format, $string;
tell $z
eof $z
seek $z, $position, $whence
binmode $z
fileno $z
close $z ;

#說明

此模組提供一個 Perl 介面，允許將 bzip2 壓縮資料寫入檔案或緩衝區。

若要讀取 bzip2 檔案/緩衝區，請參閱附屬模組 IO::Uncompress::Bunzip2。

#函式介面

提供一個頂層函式 bzip2，用於在緩衝區和/或檔案之間執行「一次性」壓縮。若要更精細地控制壓縮程序，請參閱 「物件導向介面」 區段。

use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;

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

函式介面需要 Perl5.005 或更新版本。

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

bzip2 至少需要兩個參數，$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 是陣列參考，陣列中的每個元素都必須是檔案名稱。

輸入資料將依序從每個檔案讀取。

將會遍歷整個陣列，以確保在壓縮任何資料之前，它只包含有效的檔案名稱。

#輸入檔案 Glob 字串

如果 $input_filename_or_reference 是以字元「<」和「>」分隔的字串，bzip2 會假設它是一個輸入檔案 Glob 字串。輸入是與檔案 Glob 相符的檔案清單。

請參閱 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 是陣列參考，壓縮資料將推送到陣列中。

#輸出檔案 Glob

如果 $output_filename_or_reference 是以字元「<」和「>」分隔的字串，bzip2 會假設它是一個輸出檔案 Glob 字串。輸出是與檔案 Glob 相符的檔案清單。

當 $output_filename_or_reference 是檔案 Glob 字串時，$input_filename_or_reference 也必須是檔案 Glob 字串。其他任何情況都是錯誤。

請參閱 File::GlobMapper 以取得更多詳細資訊。

如果 $output_filename_or_reference 參數是任何其他類型，將會傳回 undef。

#備註

當 $input_filename_or_reference 映射到多個檔案/緩衝區，而 $output_filename_or_reference 是單一檔案/緩衝區時，輸入檔案/緩衝區將儲存在 $output_filename_or_reference 中，作為壓縮資料串流的串接系列。

#選用參數

一次性函式 bzip2 的選用參數（大部分）與在 "建構函式選項" 區段中定義的 OO 介面中使用的參數相同。例外如下所列

#自動關閉 => 0|1

此選項適用於任何輸入或輸出資料串流，而這些串流對 bzip2 來說是檔案控制代碼。

如果指定 自動關閉，且值為 true，將會在 bzip2 完成後關閉所有輸入和/或輸出檔案控制代碼。

此參數預設為 0。

#二進位模式輸入 => 0|1

此選項現在是無操作。所有檔案都將以二進位模式讀取。

#附加 => 0|1

此選項的行為取決於輸出資料串流的類型。

• 緩衝區

  如果啟用 附加，所有壓縮資料都將附加到輸出緩衝區的結尾。否則，在寫入任何壓縮資料到輸出緩衝區之前，將會清除輸出緩衝區。

• 檔案名稱

  如果啟用 Append，檔案會以附加模式開啟。否則，檔案的內容（如果有）會在寫入任何壓縮資料之前被截斷。

• 檔案控制代碼

  如果啟用 Append，檔案控制代碼會在寫入任何壓縮資料之前透過呼叫 seek 定位到檔案的結尾。否則，檔案指標不會移動。

當指定 Append 並設定為 true 時，它會將所有壓縮資料附加到輸出資料串流。

因此，當輸出為檔案控制代碼時，它會在寫入任何壓縮資料之前執行 seek 到 eof。如果輸出為檔案名稱，它會開啟以進行附加。如果輸出為緩衝區，所有壓縮資料會附加到現有的緩衝區。

相反地，當未指定 Append 或它存在且設定為 false 時，它會執行下列操作。

當輸出為檔案名稱時，它會在寫入任何壓縮資料之前截斷檔案的內容。如果輸出為檔案控制代碼，其位置不會變更。如果輸出為緩衝區，它會在輸出任何壓縮資料之前被清除。

預設為 0。

#範例

以下是一些範例，展示模組的功能。

#串流

這個非常簡單的命令列範例示範模組的串流功能。程式碼從 STDIN 讀取資料，壓縮它，並將壓縮資料寫入 STDOUT。

$ echo hello world | perl -MIO::Compress::Bzip2=bzip2 -e 'bzip2 \*STDIN => \*STDOUT' >output.bz2

特殊檔案名稱「-」可以用作 \*STDIN 和 \*STDOUT 的替身，因此上述範例可以改寫為

$ echo hello world | perl -MIO::Compress::Bzip2=bzip2 -e 'bzip2 "-" => "-"' >output.bz2

#從檔案系統壓縮檔案

要讀取檔案 file1.txt 的內容，並將壓縮資料寫入檔案 file1.txt.bz2。

use strict ;
use warnings ;
use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;

my $input = "file1.txt";
bzip2 $input => "$input.bz2"
    or die "bzip2 failed: $Bzip2Error\n";

#從檔案控制代碼讀取並寫入至記憶體中緩衝區

從現有的 Perl 檔案控制代號 $input 讀取並將壓縮資料寫入緩衝區 $buffer。

use strict ;
use warnings ;
use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
use IO::File ;

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

#壓縮多個檔案

壓縮目錄「/my/home」中符合「*.txt」的所有檔案，並將壓縮資料儲存在同一個目錄中

use strict ;
use warnings ;
use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;

bzip2 '</my/home/*.txt>' => '<*.bz2>'
    or die "bzip2 failed: $Bzip2Error\n";

如果你想要一次壓縮一個檔案，可以使用這個方法

use strict ;
use warnings ;
use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;

for my $input ( glob "/my/home/*.txt" )
{
    my $output = "$input.bz2" ;
    bzip2 $input => $output
        or die "Error compressing '$input': $Bzip2Error\n";
}

#OO 介面

#建構函式

IO::Compress::Bzip2 建構函式的格式如下所示

my $z = IO::Compress::Bzip2->new( $output [,OPTS] )
    or die "IO::Compress::Bzip2 failed: $Bzip2Error\n";

成功時會傳回 IO::Compress::Bzip2 物件，失敗時會傳回 undef。變數 $Bzip2Error 會在失敗時包含錯誤訊息。

如果你執行的是 Perl 5.005 或更新版本，從 IO::Compress::Bzip2 傳回的物件 $z 可以像 IO::File 檔案控制代號一樣使用。這表示你可以使用 $z 執行所有正常的輸出檔案操作。例如，你可以使用下列任一種格式寫入壓縮檔案/緩衝區

$z->print("hello world\n");
print $z "hello world\n";

強制參數 $output 用於控制壓縮資料的目的地。此參數可以採用下列其中一種格式。

#檔案名稱

如果 $output 參數是簡單的純量，則假設它是一個檔案名稱。這個檔案將會開啟以進行寫入，而壓縮資料將會寫入其中。

#檔案控制代號

如果 $output 參數是檔案控制代號，則壓縮資料將會寫入其中。字串「-」可以用作標準輸出的別名。

#純量參考

如果 $output 是純量參考，則壓縮資料將會儲存在 $$output 中。

如果 $output 參數是任何其他類型，則 IO::Compress::Bzip2::new 將會傳回 undef。

#建構函式選項

OPTS 是下列選項的任意組合，數量為零或多個

#自動關閉 => 0|1

此選項僅在 $output 參數是檔案控制代號時有效。如果指定，且值為 true，則表示在呼叫 close 方法或銷毀 IO::Compress::Bzip2 物件後，將會關閉 $output。

此參數預設為 0。

#附加 => 0|1

以附加模式開啟 $output。

此選項的行為取決於 $output 的類型。

• 緩衝區

  如果 $output 是緩衝區且啟用 Append，所有壓縮資料會附加到 $output 的尾端。否則，在寫入任何資料之前，會清除 $output。

• 檔案名稱

  如果 $output 是檔案名稱且啟用 Append，檔案會以附加模式開啟。否則，在寫入任何壓縮資料之前，會先清除檔案中的內容（如果有）。

• 檔案控制代碼

  如果 $output 是檔案處理，在寫入任何壓縮資料之前，會透過呼叫 seek 將檔案指標定位到檔案尾端。否則，檔案指標不會移動。

此參數預設為 0。

#BlockSize100K => number

指定 bzip2 在壓縮期間使用的 100K 區塊數。

有效值介於 1 到 9，其中 9 是最佳壓縮。

預設值為 1。

#WorkFactor => number

指定 bzip2 在採用較慢的備用壓縮演算法之前應付出的努力程度。

有效值範圍為 0 到 250，其中 0 表示使用預設值 30。

預設值為 0。

#Strict => 0|1

這是佔位符選項。

#範例

待辦事項

#方法

#列印

用法為

$z->print($data)
print $z $data

壓縮 $data 參數的內容並輸出。這與內建的 print 行為相同。

如果成功，傳回 true。

#printf

用法為

$z->printf($format, $data)
printf $z $format, $data

壓縮 $data 參數的內容並輸出。

如果成功，傳回 true。

#syswrite

用法為

$z->syswrite $data
$z->syswrite $data, $length
$z->syswrite $data, $length, $offset

壓縮 $data 參數的內容並輸出。

傳回未壓縮的寫入位元組數，或在不成功時傳回 undef。

#寫入

用法為

$z->write $data
$z->write $data, $length
$z->write $data, $length, $offset

壓縮 $data 參數的內容並輸出。

傳回未壓縮的寫入位元組數，或在不成功時傳回 undef。

#flush

用法為

$z->flush;

將任何待處理的壓縮資料沖刷至輸出檔案/緩衝區。

待辦事項

成功時傳回 true。

#tell

用法為

$z->tell()
tell $z

傳回未壓縮的檔案偏移量。

#eof

用法為

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

如果已呼叫 close 方法，則傳回 true。

#seek

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

提供 seek 功能的子集，限制僅能向前搜尋輸出檔案/緩衝區。嘗試向後搜尋會導致致命錯誤。

檔案/緩衝區的空白部分會寫入 NULL (0x00) 位元組。

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

壓縮時，此方法總是傳回 undef。

#fileno

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

如果 $z 物件與檔案或檔案控制代碼相關聯，則 fileno 會傳回底層檔案描述符。呼叫 close 方法後，fileno 會傳回 undef。

如果 $z 物件與緩衝區相關聯，則此方法會傳回 undef。

#close

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

沖刷任何待處理的壓縮資料，然後關閉輸出檔案/緩衝區。

對於大多數版本的 Perl，如果 IO::Compress::Bzip2 物件已毀損（明確或透過參照物件的變數超出範圍），則此方法會自動呼叫。例外為 Perl 版本 5.005 至 5.00504 和 5.8.0。在這些情況下，close 方法會自動呼叫，但直到程式終止時才對所有現存物件進行全域毀損。

因此，如果您希望您的腳本可以在所有版本的 Perl 上執行，則應明確呼叫 close，而不依賴自動關閉。

成功時傳回 true，否則傳回 0。

如果在建立 IO::Compress::Bzip2 物件時啟用了 AutoClose 選項，且物件與檔案相關聯，則也會關閉底層檔案。

#newStream([OPTS])

用法為

$z->newStream( [OPTS] )

關閉目前的壓縮資料串流，並開始新的串流。

OPTS 包含建立 $z 物件時可用的任何選項。

有關更多詳細資料，請參閱 "建構函式選項" 區段。

#匯入

目前 IO::Compress::Bzip2 不需要任何符號常數。

#:all

匯入 bzip2 和 $Bzip2Error。與執行下列動作相同

use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;

#範例

#Apache::GZip 再探

請參閱 IO::Compress::FAQ

#與 Net::FTP 搭配使用

請參閱 IO::Compress::FAQ

#支援

一般回饋/問題/錯誤報告應寄送至 https://github.com/pmqs/IO-Compress/issues（優先）或 https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress。

#另請參閱

Compress::Zlib、IO::Compress::Gzip、IO::Uncompress::Gunzip、IO::Compress::Deflate、IO::Uncompress::Inflate、IO::Compress::RawDeflate、IO::Uncompress::RawInflate、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

bzip2 程式的主要網站為 https://sourceware.org/bzip2/。

請參閱模組 Compress::Bzip2

#作者

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

#修改記錄

請參閱 Changes 檔案。

#版權與授權

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

本程式為自由軟體；您可以在與 Perl 相同的條款下重新散布或修改它。

Perldoc 瀏覽器由 Dan Book (DBOOK) 維護。如有任何關於網站本身、搜尋或文件呈現的問題，請透過 GitHub 問題追蹤器 或 電子郵件 與他聯繫。

Perl 文件由 Perl 5 Porters 在 Perl 開發中維護。如有任何關於文件內容或格式的問題，請透過 Perl 問題追蹤器、郵件清單 或 IRC 與他們聯繫。