名称

archive_read_open, archive_read_open2, archive_read_open_fd, archive_read_open_FILE, archive_read_open_filename, archive_read_open_memory, — ストリーミングアーカイブを読み込むための関数

ライブラリ

ストリーミングアーカイブライブラリ (libarchive, -larchive)

書式

#include < archive.h>

int
archive_read_open( struct archive *, void *client_data, archive_open_callback *, archive_read_callback *, archive_close_callback *);

int
archive_read_open2( struct archive *, void *client_data, archive_open_callback *, archive_read_callback *, archive_skip_callback *, archive_close_callback *);

int
archive_read_open_FILE( struct archive *, FILE *file);

int
archive_read_open_fd( struct archive *, int fd, size_t block_size);

int
archive_read_open_filename( struct archive *, const char *filename, size_t block_size);

int
archive_read_open_memory( struct archive *, void *buff, size_t size);

解説

archive_read_open()

スキップコールバックが NULL であると仮定されることを除いて、 archive_read_open2() と同じです。

archive_read_open2()

設定をフリーズ (freeze) し、アーカイブをオープンし、そして、エントリを読み込む準備をします。これは、4 つのコールバック関数を受け付ける、この呼び出しの最も一般的なバージョンです。ほとんどのクライアントは、代わりに、 archive_read_open_filename(), archive_read_open_FILE(), archive_read_open_fd() または archive_read_open_memory() を使用すべきです。ライブラリは、アーカイブから生のバイトを取得するためにクライアントに提供される関数を呼び出します。

archive_read_open_FILE()

FILE * ポインタを受け付けることを除いて、 archive_read_open() に似ています。この関数は、正確な I/O ブロッキングを要求するテープドライブまたは他のデバイスで使用されるべきではありません。

archive_read_open_fd()

1 組の関数ポインタではなくファイル記述子とブロックサイズを受け付けることを除いて、 archive_read_open() に似ています。ファイル記述子は、アーカイブの終り (end-of-archive) で自動的にクローズされないことに注意してください。この関数は、テープドライブまたは他のブロックデバイスでの使用に安全です。

archive_read_open_file()

これは、廃止予定の archive_read_open_filename() と同義語です。

archive_read_open_filename()

単純なファイル名とブロックサイズを受け付けることを除いて、 archive_read_open() に似ています。 NULL ファイル名は、標準入力を表わします。この関数は、テープドライブまたは他のブロックデバイスでの使用に安全です。

archive_read_open_memory()

アーカイブデータを含んでいるメモリのブロックのポインタとサイズを受け付けることを除いて、 archive_read_open() に似ています。

libarchive(3) のための概観のマニュアルページで struct archive と struct archive_entry の完全な記述を見つけることができます。

クリアントコールバック

コールバック関数は、次のプロトタイプと一致しなければなりません:

• typedef ssize_t archive_read_callback( struct archive *, void *client_data, const void **buffer);
• typedef off_t archive_skip_callback( struct archive *, void *client_data, off_t request);
• typedef int archive_open_callback( struct archive *, void *client_data)
• typedef int archive_close_callback( struct archive *, void *client_data)

オープンコールバックは、 archive_open() によって呼び出されます。基本的なファイルまたはデータソースのオープンが成功するなら、 ARCHIVE_OK を返すべきです。オープンが失敗するなら、エラーコードとメッセージを登録するために archive_set_error() を呼び出し、 ARCHIVE_FATAL を返すべきです。

読み込みコールバックは、ライブラリがアーカイブからの生のバイトを要求するときはいつでも呼び出されます。読み込みコールバックは、バッファにデータを読み込み、 const void **buffer 引数を利用可能なデータへのポインタに設定し、利用可能なバイト数を返すべきです。ライブラリは、このデータを消費した後だけ、再び読み込みコールバックを呼び出します。ライブラリは、返されたデータブロックのサイズの制約を課しません。ファイルの終り (end-of-file) で、読み込みコールバックは、0 を返すべきです。エラーのとき、読み込みコールバックは、エラーコードとメッセージを登録するために archive_set_error() を呼び出し、-1 を返すべきです。

スキップコールバックは、ライブラリがデータブロックを無視したいとき、呼び出されます。返り値は、要求と異なるかもしれない、実際にスキップされたバイトの数です。コールバックがデータをスキップすることができないなら、0 を返すべきです。スキップコールバックが提供されないなら (関数ポインタが NULL)、ライブラリは、代わりに読み込み関数を呼び出し、単に結果を廃棄します。スキップコールバックは、素早くスキップできる、遅いディスクドライブまたは他のメディアから圧縮復元されたアーカイブを読み込むとき、著しい性能向上を提供することができます。

クローズコールバックは、アーカイブ処理が完了したとき、archive_close によって呼び出されます。コールバックは、成功すれば、 ARCHIVE_OK を返すべきです。失敗すれば、コールバックは、エラーコードとメッセージを登録するために archive_set_error() を呼び出し ARCHIVE_FATAL を返すべきです。

戻り値

これらの関数は、成功すれば、 ARCHIVE_OK を返すか、または ARCHIVE_FATAL を返します。

エラー

詳細なエラーコードとテキスト形式の記述は、 archive_errno() と archive_error_string() 関数から利用可能です。

関連項目

tar(1), libarchive(3), archive_read(3), archive_read_data(3), archive_read_filter(3), archive_read_format(3), archive_read_set_options(3), archive_util(3), tar(5)