名称

archive_read — ストリーミングアーカイブを読み込むのための関数

ライブラリ

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

書式

#include < archive.h>

解説

これらの関数は、ストリーミングアーカイブを読み込むための完全な API を提供します。一般的なプロセスは、最初に、 struct archive オブジェクトを作成して、オプションを設定し、読み込みを初期化し、アーカイブのヘッダと関連データを繰り返して、次に、アーカイブをクローズして、すべてのリソースを解放します。

アーカイブオブジェクトを作成する

archive_read_new(3) を参照してください。

アーカイブを読み込むためには、最初に archive_read_new() から初期化された struct archive オブジェクトを取得しなければなりません。

フィルタとフォーマットを有効にする

archive_read_filter(3) と archive_read_format(3) を参照してください。

次に、様々な archive_read_set_XXX() と archive_read_support_XXX() 関数で希望の操作のために、このオブジェクトを修正することができます。特に、対応する圧縮とフォーマットサポートを有効にする適切な archive_read_support_XXX() 関数を呼び出す必要があります。これらの後の関数は、2 つの異なった操作を行なうことに注意してください: それらは、利用者のプログラムに対応するサポートコードをリンクし、対応する自動検出コードを有効にします。特定の制約がないなら、ライブラリによって現在サポートされたすべてのフォーマットと圧縮タイプのための自動検出を有効とするために archive_read_support_filter_all() と archive_read_support_format_all() を通常呼び出す必要があります。

設定オプション

archive_read_set_options(3) を参照してください。

アーカイブをオープンする

archive_read_open(3) を参照してください。

いったん、 struct archive オブジェクトを準備したなら、実際にアーカイブをオープンし、読み込みのために準備するためには、 archive_read_open() を呼び出します。この関数のいくつかの変異型があります。最も基本的なものは、利用者が、アーカイブからのバイトのブロックを提供することができるいくつかの関数へのポインタを提供することを期待しています。利用者がファイル名、ファイル記述子、 FILE * オブジェクトまたはアーカイブデータを読み込むメモリのブロックを指定することができる便利な方法があります。コアライブラリは、読み込まれてブロックのサイズに関する仮定を行わないことに注意してください。コールバック関数は、ブロックサイズがメデアのための最も適切なものはなんでも読み込むために解放されます。

アーカイブを読み込む

archive_read_header(3), archive_read_data(3) と archive_read_extract(3) を参照してください。

各アーカイブエントリは、特定の量のデータが続くヘッダから成ります。利用者は、現在のアーカイブ要素に関する情報がある struct archive_entry 構造体へのポインタを返す、 archive_read_next_header() で次のヘッダを取得することができ、エントリが通常ファイルであるなら、ファイルデータがヘッダに続きます。アーカイブまたはわずかにより効率的なインタフェースを提供する archive_read_data_block() からこのデータを読み込むために ( read(2) システムコールそっくりに動作する) archive_read_data() を使用することができます。利用者は、より高いレベルの、このエントリのためにデータを読み込み廃棄する archive_read_data_skip()、提供されるファイル記述子にデータをコピーする archive_read_data_to_file() またはディスク上の指定されたエントリ再作成するか、またはアーカイブからデータをコピーする archive_read_extract() を使用するほうが良いかもしれません。特に、 archive_read_extract() は、利用者がアーカイブから今読み込まれたエントリと異なっているかもしれないものを提供する struct archive_entry 構造体を使用することに注意してください。特に、多くのアプリケーションは、パス名、ファイルパーミッションまたは所有権を上書きする必要があります。

リソースを解放する

archive_read_free(3) を参照してください。

いったん、アーカイブからのデータの読み込みを終了すると、利用者は、アーカイブをクローズするために archive_read_close() を呼び出し、次にライブラリによって割り付けられたすべてのメモリを含むすべてのリソースを解放するために archive_read_free() を呼び出すべきです。

使用例

次は、ライブラリの基本的な使用法を説明しています。この例で、コールバック関数は、標準の open(2), read(2) と close(2) システムコールを囲むような単純なラッパです。

void 
list_archive(const char *name) 
{ 
  struct mydata *mydata; 
  struct archive *a; 
  struct archive_entry *entry; 
 
  mydata = malloc(sizeof(struct mydata)); 
  a = archive_read_new(); 
  mydata->name = name; 
  archive_read_support_filter_all(a); 
  archive_read_support_format_all(a); 
  archive_read_open(a, mydata, myopen, myread, myclose); 
  while (archive_read_next_header(a, &entry) == ARCHIVE_OK) { 
    printf("%s\n",archive_entry_pathname(entry)); 
    archive_read_data_skip(a); 
  } 
  archive_read_free(a); 
  free(mydata); 
} 
 
ssize_t 
myread(struct archive *a, void *client_data, const void **buff) 
{ 
  struct mydata *mydata = client_data; 
 
  *buff = mydata->buff; 
  return (read(mydata->fd, mydata->buff, 10240)); 
} 
 
int 
myopen(struct archive *a, void *client_data) 
{ 
  struct mydata *mydata = client_data; 
 
  mydata->fd = open(mydata->name, O_RDONLY); 
  return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL); 
} 
 
int 
myclose(struct archive *a, void *client_data) 
{ 
  struct mydata *mydata = client_data; 
 
  if (mydata->fd > 0) 
    close(mydata->fd); 
  return (ARCHIVE_OK); 
}

歴史

libarchive ライブラリは、 FreeBSD 5.3 ではじめて登場しました。

作者

libarchive ライブラリは、 Tim Kientzle <kientzle@acm.org>によって書かれました。

バグ

多くの伝統的なアーカイブプログラムは、有効な空のアーカイブとして空のファイルを取り扱います。例えば、 tar(1) の多くの実装によって、利用者は、エントリを空のファイルに追加することができます。もちろん、このライブラリが特別な“empty”形式として空のファイルを取り扱うので、内容を調べることによって空のファイルの形式を決定することは不可能です。

February 2, 2012

FreeBSD

YOS OPENSONAR

名称