EN JA
ARCHIVE_READ_DISK(3)
ARCHIVE_READ_DISK(3) FreeBSD Library Functions Manual ARCHIVE_READ_DISK(3)

名称

archive_read_disk_new, archive_read_disk_set_symlink_logical, archive_read_disk_set_symlink_physical, archive_read_disk_set_symlink_hybrid, archive_read_disk_entry_from_file, archive_read_disk_gname, archive_read_disk_uname, archive_read_disk_set_uname_lookup, archive_read_disk_set_gname_lookup, archive_read_disk_set_standard_lookup, archive_read_close, archive_read_finish, archive_read_freeディスクからオブジェクトを読み込みのための関数

ライブラリ

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

書式

#include < archive.h>

struct archive *
archive_read_disk_new( void);

int
archive_read_disk_set_symlink_logical( struct archive *);

int
archive_read_disk_set_symlink_physical( struct archive *);

int
archive_read_disk_set_symlink_hybrid( struct archive *);

int
archive_read_disk_gname( struct archive *, gid_t);

int
archive_read_disk_uname( struct archive *, uid_t);

int
archive_read_disk_set_gname_lookup( struct archive *, void *, const char *(*lookup)(void *, gid_t), void (*cleanup)(void *));

int
archive_read_disk_set_uname_lookup( struct archive *, void *, const char *(*lookup)(void *, uid_t), void (*cleanup)(void *));

int
archive_read_disk_set_standard_lookup( struct archive *);

int
archive_read_disk_entry_from_file( struct archive *, struct archive_entry *, int fd, const struct stat *);

int
archive_read_close( struct archive *);

int
archive_read_finish( struct archive *);

int
archive_read_free( struct archive *);

解説

これらの関数は、ディスク上のオブジェクトに関する読み込み情報のための API を提供しています。特に、それらは、 struct archive_entry オブジェクトに占めるインタフェースを提供します。
archive_read_disk_new()
ディスクからオブジェクトの情報を読み込みために適切な struct archive オブジェクトを割り付けて、初期化します。
archive_read_disk_set_symlink_logical(), archive_read_disk_set_symlink_physical(), archive_read_disk_set_symlink_hybrid()
これは、シンボリックリンクを取り扱うために使用されるモードを設定します。“logical”モードは、すべてのシンボリックリンクを追跡します。“physical”モードは、どのシンボリックリンクも追跡しません。現在、“hybrid”モードは、“logical”モードと同様に振る舞います。
archive_read_disk_gname(), archive_read_disk_uname()
gid または uid 値で与えられた、ユーザ名またはグループ名を返します。デフォルトで、これらは、常に NULL 文字列を返します。
archive_read_disk_set_gname_lookup(), archive_read_disk_set_uname_lookup()
これらによって、利用者は、ユーザとグループ名を検索するために使用される関数を置き換えることができます。また、利用者は、そのデータのためのプライベートなデータ構造とクリーンアップ関数への void * ポインタを提供します。クリーンアップ関数は、 struct archive オブジェクトが破壊されるか、または新しい検索関数が登録されるとき、呼び出されます。
archive_read_disk_set_standard_lookup()
この便利関数は、ユーザ名とグループ名検索関数の標準セットをインストールします。これらの関数は、名前を検索することがができないなら NULL をデフォルトとする、 ID を名前に変換する getpwuid(3)getgrgid(3) を使用します。また、これらの関数は、 getpwuid(3)getgrgid(3) への呼び出しの数を減少させるために簡単なメモリキャッシュを実装しています。
archive_read_disk_entry_from_file()
特定のファイルに関する情報がある struct archive_entry オブジェクトに存在します。 archive_entry オブジェクトは、 archive_entry_new(3) で既に作成されていなければなりません、そして少なくともソースのパスまたはパスフィールドの 1 つは、既に設定されていなければなりません。 (両方が設定されているなら、ソースパスが使用されます。)

情報は、 struct archive_entry オブジェクトからパス名を使用してディスクから読み込まれます。ファイル記述子が提供されるなら、適切なシステムコールをサポートするプラットフォームで、いくつかの情報は、そのファイル記述子を使用して取得されます。

struct stat へのポインタが提供されるなら、その構造からの情報が必要に応じてディスクから読み込まれる代わりに使用されます。これは、 struct stat 情報が、既にある他の操作の副作用として、ディスクから読み込まれてるシナリオで性能上の利益を提供することができます。 (例えば、ディレクトリをたどるライブラリは、しばしばこの情報を提供します。)

必要ならば、ユーザ ID とグループ ID は、上記の現在登録された検索関数を使用して、ユーザ名とグループ名に変換されます。これは、 struct archive_entry オブジェクトでファイル所有権フィールドと ACL 値に影響します。

archive_read_close()
archive_read_disk ハンドルに対して何も行いません。
archive_read_finish()
これは、 archive_read_free() のための廃止予定の同義語です。
archive_read_free()
手動で呼び出されないなら、 archive_read_close() を呼び出し、次に、すべてのリソースを解放します。
struct archive オブジェクトとライブラリの総合的なデザインに関する詳しい情報を libarchive(3) 概観で見つけることができます。

使用例

次は、ディスク上の項目をアーカイブにコピーするためにどのよう使用するかを示すことによって、ライブラリの基本的な使用を説明しています。

void 
file_to_archive(struct archive *a, const char *name) 
{ 
  char buff[8192]; 
  size_t bytes_read; 
  struct archive *ard; 
  struct archive_entry *entry; 
  int fd; 
 
  ard = archive_read_disk_new(); 
  archive_read_disk_set_standard_lookup(ard); 
  entry = archive_entry_new(); 
  fd = open(name, O_RDONLY); 
  if (fd < 0) 
     return; 
  archive_entry_copy_pathname(entry, name); 
  archive_read_disk_entry_from_file(ard, entry, fd, NULL); 
  archive_write_header(a, entry); 
  while ((bytes_read = read(fd, buff, sizeof(buff))) > 0) 
    archive_write_data(a, buff, bytes_read); 
  archive_write_finish_entry(a); 
  archive_read_free(ard); 
  archive_entry_free(entry); 
}

戻り値

ほとんどの関数は、成功すれば、 ARCHIVE_OK (0) を返すか、またはエラーでは、いくつかの負のエラーコードの 1 つを返します。特定のエラーコードは、次の通りです: 再試行するなら成功するかもしれない操作に対しては、 ARCHIVE_RETRY、さらなる操作を防がない異常な状態に対しては、 ARCHIVE_WARN、と不可能な操作のままで残す重大なエラーに対しては、 ARCHIVE_FATAL です。

archive_read_disk_new() は、新しく割り付けられた struct archive オブジェクトを返すか、または何らかの理由で割り付けが失敗したなら、 NULL を返します。

archive_read_disk_gname() と archive_read_disk_uname() は、テキスト形式の名前への const char * ポインタを返すか、または何らかの理由で検索が失敗したなら、 NULL を返します。返されたポインタは、これらの関数のいずれかへの次の呼び出しで再利用される内部の記憶域を指します。呼び出し側が、それにアクセスし続ける必要があるなら、文字列をコピーするべきです。

エラー

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

歴史

libarchive ライブラリは、 FreeBSD 5.3 ではじめて登場しました。 archive_read_disk インタフェースは、 libarchive 2.6 に加えられて、 FreeBSD 8.0 ではじめて登場しました。

作者

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

バグ

getgrgid(3)getpwuid(3) は、特定のアプリケーションのためには、しばしば大き過ぎるので、“standard”ユーザ名とグループ名検索関数は、デフォルトではありません。現在のデザインによって、アプリケーション作者は、適切な場合に、よりコンパクトな実行を使用することができます。

archive_read_disk_entry_from_file() によってディスクから読み込まれたメタデータの完全なリストは、必ずしもシステム依存ではありません。

archive_read_disk_entry_from_file() 関数は、ディスクからできるだけより多くの情報を読み込みます。例えば、ACL を必要としないクライアントが、そのような情報を検索するために必要である特別の動作を避けることができるように、何らかのメソッドがこれを制限するために提供されるべきです。

この API は、ディレクトリツリーを渡り歩くための 1 組のメソッドを提供するべきです。それは、 archive_read(3) API の直列並列 (direct parallel) にするでしょう。そのようなメソッドが実装されるとき、“hybrid”シンボリックリンクモードは、意味があります。

February 2, 2012 FreeBSD