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 拡張属性を操作するためのシス テムコール

標準 C ライブラリ (libc, −lc)

#include <sys/types.h>
#include <sys/extattr.h>
#include <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 (ヌル) 文字に よって分離された、要求された名前空間の中に存在する属性のリストを返しま す。 extattr_get_file() および extattr_list_file() 呼び出しは read(2) の 形式で data と nbytes 引数を使用します。 extattr_set_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" 関数はパス名を取ります。両方の引数 は操作されるべき拡張属性に関連付けられたファイルを、記述します。

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

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

attrname
拡張属性の名前です。

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

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

警告

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

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

関数 extattr_delete_file() は、処理が成功すると値 0 を返します。そうでな い場合、値 -1 が返され、グローバル変数 errno が設定されてエラーを示しま す。

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

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() の 呼び出しは以下のエラーのため、失敗することがあります:

[ENOATTR]
要求された属性はこのファイルのために定義されていませ ん。

[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 を使用すべきなので、このインタフェースは非推奨であり、 使用されるべきではありません。

FreeBSD 10.0 February 23, 2005 FreeBSD 10.0