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

名称

archive_write_open, archive_write_open_fd, archive_write_open_FILE, archive_write_open_filename, archive_write_open_memoryアーカイブを作成するための関数

ライブラリ

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

書式

#include < archive.h>

int
archive_write_open( struct archive *, void *client_data, archive_open_callback *, archive_write_callback *, archive_close_callback *);

int
archive_write_open_fd( struct archive *, int fd);

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

int
archive_write_open_filename( struct archive *, const char *filename);

int
archive_write_open_memory( struct archive *, void *buffer, size_t bufferSize, size_t *outUsed);

解説

archive_write_open()
設定を凍結し、アーカイブをオープンし、エントリを書き込む準備をします。これは、構築されるアーカイブを書き込むために圧縮レイヤ (層) によって呼び出される 3 つのコールバック関数へのポインタを受け付ける、この関数の最も一般的な形式です。
archive_write_open_fd()
ファイル記述子を受け付ける archive_write_open() の便利な形式です。 archive_write_open_fd() 関数は、テープドライブまたは他のブロック指向のデバイスで使用しても安全です。
archive_write_open_FILE()
FILE * ポインタを受け付ける archive_write_open() の便利な形式です。 archive_write_open_FILE() は、正確なブロッキングを要求するテープドライブまたは他のデバイスに書き込むことは安全ではないことに注意してください。
archive_write_open_file()
archive_write_open_filename() の廃止予定の同義語です。
archive_write_open_filename()
ファイル名を受け付ける archive_write_open() の便利な形式です。 NULL 引数は、出力が標準出力に書き込まれるべきであることを示します。“-”の引数は、その名前でファイルをオープンします。 archive_write_set_bytes_in_last_block() を呼び出さないなら、 archive_write_open_filename() は、ファイルに依存する最後のブロックのパディングを調節します。標準出力またはキャラクタデバイスまたはブロックデバイスのノードに書き込むとき、パディングを有効にし、そうでなければパディングを無効にします。 archive_write_open() を呼び出す前に archive_write_set_bytes_in_last_block() を手動で呼び出することによってこれを上書きするることができます。 archive_write_open_filename() 関数は、テープドライブまたは他のブロック指向のデバイスで使用しても安全です。
archive_write_open_memory()
アーカイブを受け取るメモリのブロックへのポインタを受け付ける archive_write_open() の便利な形式です。どのくらいのバッファが現在使用中であるかを反映するために各書き込みの後に更新される変数を指す最終の size_t * 引数。アーカイブがクローズされた後まで、この変数が割り付けられたままであることを保証するように注意するべきです。
struct archive オブジェクトとライブラリの全面的な設計に関するより多くの情報は、 libarchive(3) の要約で見つけることができます。

クライアントのコールバック

このタイブラリを使用するために、結果のアーカイブにデータを書き込むために呼び出されるコールバック関数を定義して、登録する必要があります。これらの関数は、 archive_write_open() を呼び出すことによって登録されます:
  • typedef int archive_open_callback( struct archive *, void *client_data)

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

  • typedef ssize_t archive_write_callback( struct archive *, void *client_data, const void *buffer, size_t length);

書き込みコールバックは、ライブラリがアーカイブに生のバイトを書き込む必要のあるときはいつでも呼び出されます。正確なブロッキングについては、書き込みコールバック関数への各呼び出しは、単一の write(2) システムコールに変換されるべきです。これは、テープドライブにアーカイブを書き込むとき、特に重要です。成功すれば、書き込みコールバックは、実際に書き込まれたバイトの数を返すべきです。エラーのときは、コールバックは、エラーコードとメッセージを登録するために archive_set_error() を呼び出し、-1 を返すべきです。

  • typedef int archive_close_callback( struct archive *, void *client_data)

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

クライアントに提供される書き込みコールバック関数が 0 以外の値を返すなら、 archive_write_header(), archive_write_data(), archive_write_close(), archive_write_finish() または archive_write_free() を含む、API 関数のその呼び出しの結果となるものは何でもそのエラーが呼び出し側に伝わることに注意してください。クライアントのコールバックは、 archive_errno() と archive_error_string() によって検索することができる値を提供するために archive_set_error() を呼び出すことができます。

戻り値

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

エラー

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