EXTATTR(2)

名称
extattr_get_fd, extattr_set_fd, extattr_delete_fd, extattr_list_fd, extattr_get_file, extattr_set_file, extattr_delete_file, extattr_list_file, extattr_get_link, extattr_set_link, extattr_delete_link, extattr_list_link - VFS 拡張属性を操作するためのシステムコール

ライブラリ
libc

書式
<sys/types.h> <sys/extattr.h> <sys/uio.h> ssize_t extattr_get_fd(int fd, int attrnamespace, const char *attrname, void *data, size_t nbytes) int extattr_set_fd(int fd, int attrnamespace, const char *attrname, const void *data, size_t nbytes) int extattr_delete_fd(int fd, int attrnamespace, const char *attrname) ssize_t extattr_list_fd(int fd, int attrnamespace, void *data, size_t nbytes) ssize_t extattr_get_file(const char *path, int attrnamespace, const char *attrname, void *data, size_t nbytes) int extattr_set_file(const char *path, int attrnamespace, const char *attrname, const void *data, size_t nbytes) int extattr_delete_file(const char *path, int attrnamespace, const char *attrname) ssize_t extattr_list_file(const char *path, int attrnamespace, void *data, size_t nbytes) ssize_t extattr_get_link(const char *path, int attrnamespace, const char *attrname, void *data, size_t nbytes) int extattr_set_link(const char *path, int attrnamespace, const char *attrname, const void *data, size_t nbytes) int extattr_delete_link(const char *path, int attrnamespace, const char *attrname) ssize_t extattr_list_link(const char *path, int attrnamespace, void *data, size_t nbytes)

解説
名前付き拡張属性は、ファイルまたはディレクトリを表現する vnode に 関連付けられたメタデータです。 これらは名前空間の集合の中に "name=value" "(名前=値") のペアとして存在します。

extattr_get_file() システムコールは、指定された拡張属性の値を大きさが nbytes の data によって指されるバッファに取り出します。 extattr_set_file() システムコールは、指定された拡張属性の値を data に記述されたデータに設定します。 extattr_delete_file() システムコールは、指定された拡張属性を削除します。 extattr_list_file() は ASCII 0 (nul) 文字によって分離された、要求された名前空間の中に存在する 属性のリストを返します。 extattr_get_file() および extattr_list_file() 呼び出しは read(2) の形式で使用します。 extattr_get_file() はこれらの引数を write(2) の形式で使用します。

extattr_get_file() の呼び出しの中で data が NULL の場合には、読み込んだ量を返すのではなく、 定義された拡張属性データの大きさを返します。 これにより、 アプリケーションが読み込みを実行せずにデータの大きさを テストすることを可能にします。 extattr_delete_link(), extattr_get_link(), extattr_set_link() システムコールは、シンボリックリンクを辿らないことを除いて、名前が "_file" のものと同じ動作をします。

extattr_get_fd(), extattr_set_fd(), extattr_delete_fd() 呼び出しは、最初の引数を除いて、名前が "_file" のものと同じ動作をします。 "_fd" 関数がファイル記述子を取るのに対し、 "_file" 関数はパス名を取ります。 両方の引数は操作されるべき拡張属性に関連付けられたファイルを、記述します。

以下に、全てのシステムコールに共通な引数を記述します:

attrnamespace
    拡張属性が属する名前空間です。 extattr(9) を参照してください。

attrname
    拡張属性の名前です。

名前付き拡張属性のセマンティクスは、 この呼び出しを実装するファイルシステムに依存し、一様ではありません。 特定の属性に対しては、全ての操作がサポートされないかもしれません。 加えて、 data に入るデータのフォーマットは、属性に特有です。

名前付き拡張属性についてのより多くの情報については、 extattr(9) を参照してください。

警告
このインタフェースは活発に開発中ですので、 アプリケーションがこのインタフェースを使うようになるのに従って、 変わるでしょう。 開発者がこれの安定を当てにすることは推奨されません。

戻り値
成功の場合には、 extattr_get_file() および extattr_set_file() の呼び出しは、各々 data から読込んだまたは書込んだバイト数を返します。 また、 data が NULL の場合には、 extattr_get_file() は読込みに利用可能なバイト数を返します。 なにか呼び出しが失敗した場合には、値 -1 が返され、グローバル変数 errno がそのエラーを示すために設定されます。

エラー
システムコール自身によって、以下のエラーが返されることがあります。 加えて、呼び出しを実装しているファイルシステムは、希望するその他の エラーを返すことがあります。

[EFAULT]
    attrnamespace および attrname 引数、または data および nbytes によって定義されるメモリ範囲が、 プロセスに割り当てられたアドレス空間の外を指しています。

[ENAMETOOLONG]
    属性の名前が EXTATTR_MAXNAMELEN より長くなっていました。

extattr_get_fd(), extattr_set_fd(), extattr_delete_fd() システムコールは、次の場合に失敗することがあります:

[EBADF]
    fd によって参照されるファイル記述子が無効です。

加えて、 extattr_get_file(), extattr_set_file(), extattr_delete_file() の呼び出しは以下のエラーのため、失敗することがあります:

[ENOTDIR]
    パス名のプレフィックスの構成要素がディレクトリではありません。

[ENAMETOOLONG]
    パス名の構成要素が 255 文字を超えている、 またはパス名全体が 1023 文字を超えています。

[ENOENT]
    存在していなければならないパス名の構成要素が、存在していません。

[EACCES]
    パス名のプレフィックスの構成要素の検索パーミッションがありません。

関連項目
extattr(3), getextattr(8), setextattr(8), extattr(9), VOP_GETEXTATTR(9), VOP_SETEXTATTR(9)

歴史
拡張属性サポートは TrustedBSD プロジェクトの一部として開発され、 FreeBSD 5.0 で導入されました。 個々のファイルまたはディレクトリに関連付けられるための追加のラベルを 要求するセキュリティ拡張をサポートするために開発されました。

バグ
この API の初期のバージョンでは、属性名として空の文字列を extattr_get_fd(), extattr_get_file() または extattr_get_link() に渡すことによって、目的のオブジェクトのために定義された属性のリストを 返しました。 明示的な list API を使用すべきなので、 このインタフェースは非推奨であり、使用されるべきではありません。