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

名称

archive_write_disk_new, archive_write_disk_set_options, archive_write_disk_set_skip_file, archive_write_disk_set_group_lookup, archive_write_disk_set_standard_lookup, archive_write_disk_set_user_lookup, archive_write_header, archive_write_data, archive_write_data_block, archive_write_finish_entry, archive_write_close, archive_write_finish archive_write_freeディスクにオブジェクトを作成するための関数

ライブラリ

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

書式

#include < archive.h>

struct archive *
archive_write_disk_new( void);

int
archive_write_disk_set_options( struct archive *, int flags);

int
archive_write_disk_set_skip_file( struct archive *, dev_t, ino_t);

int
archive_write_disk_set_group_lookup( struct archive *, void *, gid_t (*)(void *, const char *gname, gid_t gid), void (*cleanup)(void *));

int
archive_write_disk_set_standard_lookup( struct archive *);

int
archive_write_disk_set_user_lookup( struct archive *, void *, uid_t (*)(void *, const char *uname, uid_t uid), void (*cleanup)(void *));

int
archive_write_header( struct archive *, struct archive_entry *);

ssize_t
archive_write_data( struct archive *, const void *, size_t);

ssize_t
archive_write_data_block( struct archive *, const void *, size_t size, int64_t offset);

int
archive_write_finish_entry( struct archive *);

int
archive_write_close( struct archive *);

int
archive_write_finish( struct archive *);

int
archive_write_free( struct archive *);

解説

これらの関数は、 struct archive_entry 記述からディスクにオブジェクトを作成するための完全な API を提供します。それらは、 archive_read() インタフェースを使用してアーカイブからオブジェクトを抽出するとき、最も自然に使用されます。一般的なプロセスは、アーカイブから struct archive_entry オブジェクトを読み込んで、次に、 archive_write_disk() ファミリ関数を使用して作成される struct archive オブジェクトにそれらのオブジェクトを書き込みます。このインタフェースは、ストリーミングアーカイブにオブジェクトを書き込むために使用される archive_write() インタフェースと意図的によく似せています。
archive_write_disk_new()
ディスクにオブジェクト書き込むために適当な struct archive オブジェクトを割り付けて、初期化します。
archive_write_disk_set_skip_file()
上書きされるべきでないファイルのデバイスとと i ノード番号を記録します。これは、抽出のプロセスが、読み込まれているオブジェクトからアーカイブを上書きしないことを保証するために通常使用されます。このケーパビリティは、技術的に不要ですが、実際には、著しい性能の最適化が行えます。
archive_write_disk_set_options()
オプションフールドは、次の値の 1 つ以上のビット単位の論理和 (OR) で構成されます:
ARCHIVE_EXTRACT_OWNER
ユーザとグループ ID は、復元されたファイルで設定されるべきです。デフォルトで、ユーザとグループ ID は、復元されません。
ARCHIVE_EXTRACT_PERM
(SGID、SUID とスティッキビットを含んで) すべてのパーミッションは、現在の umask に従わないで指定されるように正確に復元されるべきです。ディスク上のオブジェクトのユーザとグループ ID が正しい場合にだけ、 SUID と SGID ビットを復元できることに注意してください。 ARCHIVE_EXTRACT_OWNER が指定されないなら、SUID と SGID ビットは、ディスク上に新たに作成されたオブジェクトのデフォルトユーザとグループ ID が、アーカイブエントリで指定されたものに偶然適合する場合にだけ復元されます。デフォルトでは、umask に従って、基本的なパーミッションだけが復元されます。
ARCHIVE_EXTRACT_TIME
タイムスタンプ (mtime、ctime と atime) は、復元されるべきです。デフォルトでは、それらは、無視されます。 atime の復元は、現在サポートされていないことに注意してください。
ARCHIVE_EXTRACT_NO_OVERWRITE
ディスク上に存在するファイルは、上書きされません。デフォルトでは、既存の通常のファイルは、切り詰められるか、上書きされます。既存のディレクトリは、それらの更新されたパーミッションとなります。他の以前から存在するオブジェクトは、アンリンク (削除) され、最初から再作成されます。
ARCHIVE_EXTRACT_UNLINK
ディスクに存在するファイルは、それらを作成する試みの前にアンリンク (削除) されます。ある場合には、これは、著しい性能改良となることを実証できます。デフォルトで、既存のファイルは、切り詰められ、再書き込みされますが、ファイルは、再作成されません。特に、デフォルトの振る舞いは、既存のハードリンクを切りません。
ARCHIVE_EXTRACT_ACL
ACL を復元することを試みます。デフォルトで、拡張 ACL は、無視されます。
ARCHIVE_EXTRACT_FFLAGS
拡張ファイルフラグを復元するすることを試みます。デフォルトで、ファイルフラグは、無視されます。
ARCHIVE_EXTRACT_XATTR
POSIX.1e 拡張属性を復元することを試みます。デフォルトで、それらは、無視されます。
ARCHIVE_EXTRACT_SECURE_SYMLINKS
最終的な位置がディスク上のシンボリックリンクによって変更される任意のオブジェクトを抽出することを拒否します。これは、カレントディレクトリの外にファイルを抽出する (故意にかそうでない) アーカイブによって引き起こされたさまざまな危害に対して保護することに役立つことを目的としています。デフォルトでは、このチェックを実行しません。このオプションと共に ARCHIVE_EXTRACT_UNLINK が指定されるなら、ライブラリは、見つかった中間的なシンボリックリンクを削除し、そのようなシンボリックリンクを削除することができない場合にだけ、エラーを返します。
ARCHIVE_EXTRACT_SECURE_NODOTDOT
その中のどこかに .. 要素を含むパスを抽出することを拒否します。デフォルトは、そのようなパスを拒否しません。 .. で終わるパスは、このフラグにかかわらず、常にエラーを引き起こすことに注意してください。
ARCHIVE_EXTRACT_SPARSE
NUL バイトのブロックのデータをスキャンし、ホールでそれらを再作成を試みます。アーカイブ形式がそれらをサポートするか、または使用するかどうかと無関係にこれは、スパースファイルをもたらします。
archive_write_disk_set_group_lookup(), archive_write_disk_set_user_lookup()
struct archive_entry オブジェクトは、ユーザとグループを識別するために使用することができる名前と ID の両方を含んでいます。これらの名前と ID は、ファイル自体の所有権について記述し、ACL リストの中にも現れます。デフォルトで、ライブラリは、ID を使用して、名前を無視しますが、ユーザとグループ検索関数に登録することによって、これを上書きすることができます。登録するために、利用者は、名前と ID の両方を受け付ける検索関数を提供し、適切な ID を返さなければなりません。また、利用者は、プライベートデータ構造体とそのデータのクリーンアップ関数への void * ポインタを提供します。クリーンアップ関数は、 struct archive オブジェクトが破壊されるとき、呼び出されます。
archive_write_disk_set_standard_lookup()
この便利な関数は、ユーザとグループ検索関数の標準セットをインストールします。これらの関数は、名前を検索することができないなら、 ID をデフォルトとする、名前を ID に変換するための getpwnam(3)getgrnam(3) を使用します。また、これらの関数は、 getpwnam(3)getgrnam(3) への呼び出しの数を削減するために簡単なメモリキャッシュを実装しています。
archive_write_header()
提供された struct archive_entry 構造体でデータを使用するヘッダを構築して書き込みます。 struct archive_entry オブジェクトを作成して、占有する情報については、 archive_entry(3) を参照してください。
archive_write_data()
ただ書き込まれているヘッダに対応するデータを書き込みます。書き込まれたバイト数か、またはエラーのときに -1 を返します。
archive_write_data_block()
ちょうど書き込まれるヘッダに対応する書き込みデータ。これは、データを書き込む前に指定されたオフセットまで書き込まれるファイルでシーク (seek) を行なうこと除いて、 archive_write_data() に似ています。これは、スパースファイルをサポートするアーカイブ形式からスパースファイルを復元するとき、役に立ちます。書き込まれたバイト数、またはエラーのとき、-1 を返します。 (注意: これは、現在、 archive_write_disk ハンドルに対してのみで、 archive_write ハンドルに対してサポートされていません。)
archive_write_finish_entry()
ただ書き込まれたエントリを完了します。通常、クライアントは、必要に応じて archive_write_next_header() と archive_write_close() によって自動的に呼び出されるように、決してこれを呼び出す必要がありません。しかしながら、いくつかのファイル属性は、ファイルがクローズされた後だけ、ディスクに書き込まれるので、これは、利用者がディスク上のファイルですぐに作業する必要があるなら、必要となるかもしれません。
archive_write_close()
最初の復元の間に設定されないかもしれないあらゆる属性を設定します。例えば、その後のファイルの復元で、タイムスタンプが変更されるので、ディレクトリのタイムスタンプは、始めに復元されません。同様に、書き込み可能でないディレクトリは、(それらの内容を復元することができるように) 書き込みパーミッションを付けて最初に作成されます。 archive_write_disk_new ライブラリは、すべての延期されるすべての属性のリストを保持して、この関数が呼び出されるとき、それらを設定します。
archive_write_finish()
これは、 archive_write_free() のための廃止予定の同義語です。
archive_write_free()
手動で呼び出されないなら、 archive_write_close() を呼び出し、全てのリソースを解放します。
struct archive オブジェクトとライブラリの総合的な設計に関する詳しい情報は、 libarchive(3) 概観で見つけることができます。また、これらの関数の多くは、 archive_write(3) の下で文書化されています。

戻り値

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

archive_write_disk_new() は、新しく割り付けられた struct archive オブジェクトへのポインタを返します。

archive_write_data() は、実際に書き込まれたバイト数のカウントを返し、エラーで -1 返します。

エラー

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

歴史

libarchive ライブラリは、 FreeBSD 5.3 ではじめて登場しました。 archive_write_disk インタフェースは、 libarchive 2.0 に追加され、 FreeBSD 6.3 ではじめて登場しました。

作者

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

バグ

ディレクトリは、実際には、2 つの異なったフェーズで展開されます。ディレクトリは、 archive_write_header() の間に作成されますが、最終のパーミッションは、 archive_write_close() まで設定されません。このような分離は、正しくファイルを含む書き込み不可能なディレクトリのようなきわどい事例を操作するために必要ですが、予期しなかった結果を引き起こすかもしれません。特に、ディレクトリのパーミッションは、アーカイブがクローズされるまで、完全に復元されるわけではありません。 archive_read_extract() への呼び出し、または archive_read_close() を呼び出す前にカレントディレクトリを変更するために chdir(2) を使用するなら、利用者は、パーミッションを設定する論理を混乱して、その結果として、ディレクトリのパーミッションが不正確に復元されます。

ライブラリは、フルパスの接頭辞を作成して、カレントディレクトリを変更するすることによって PATH_MAX より長いファイル名でオブジェクトを作成することを試みます。現在、この論理は、スコープ (範囲) で制限されています: 固定したパスは、そのようなオブジェクトでは、正しく動作しません、そして、シンボリックリンクセキュリティチェックオプションは、大変長いパス名のサポートを無効にします。

パス aa/../bb を復元することは、それぞれの中間的ディレクトリを作成します。特に、ディレクトリ aa は、最終的なオブジェクト bb と同様に作成されます。理論的には、単一の要求で全体のディレクトリの階層構造を作成するためにこれを利用することができます。もちろん、 ARCHIVE_EXTRACT_NODOTDOT オプションが指定されるなら、これは、動作しません。

暗黙のディレクトリは、現在の umask に従って常に作成されます。明白なオブジェクトは、現在の umask が無視される場合で、 ARCHIVE_EXTRACT_PERM が指定されない場合だけ、現在の umask に従って作成されます。

SGID と SUID ビットは、正しいユーザとグループが設定されている場合にだけ復元されます。 ARCHIVE_EXTRACT_OWNER が指定されないなら、所有権を設定することを試みを行いません。この場合は、SGID と SUID ビットは、最終的なオブジェクトのユーザとグループがたまたまエントリで指定されたものに適合する場合にだけ、復元されます。

“標準”のユーザ ID とグループ ID 検索関数は、 getgrnam(3)getpwnam(3) が特別のアプリケーションには、時々大き過ぎるので、デフォルトではありません。現在の設計によって、アプリケーションの作者は、適切なときに、よりコンパクトな実装を使用できます。

ディレクトリ階層構造を歩き回り、アーカイブエントリのオブジェクトを返す、対応する archive_read_disk インタフェースがあるべきです。

February 2, 2012 FreeBSD