EN JA
EXTATTR(2)
EXTATTR(2) FreeBSD System Calls Manual 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_linkVFS 拡張属性を操作するためのシステムコール

ライブラリ

Standard C Library (libc, -lc)

書式

#include < sys/types.h>
#include < sys/extattr.h>

ssize_t
extattr_get_fd( int fd, int attrnamespace, const char *attrname, void *data, size_t nbytes);

ssize_t
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);

ssize_t
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);

ssize_t
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 に関連付けられたメタデータです。それらは、1 組の名前空間内に“ name=value” (名前=値) のペアとして存在します。

extattr_get_file() システムコールは、指定された拡張属性の値をサイズ nbytesdata によって指されるバッファに取り出します。 extattr_set_file() システムコールは、指定された拡張属性の値を data によって記述されたデータに設定します。 extattr_delete_file() システムコールは、指定された拡張属性を削除します。 extattr_list_file() は、要求された名前空間に存在する属性のリストを返します。各リストのエントリは、属性名の長さを含んでいる単一のバイトとそれに続く属性名から成ります。属性名は、ASCII 0 (ヌル文字) によって終了しません。 extattr_get_file() と extattr_list_file() 呼び出しは、 read(2) のスタイルで datanbytes 引数を取ります。 extattr_set_file() は、 write(2) のスタイルで、これらの引数を取ります。

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

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

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

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

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

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

警告

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

戻り値

成功するなら、 extattr_get_file(), extattr_set_file() と extattr_list_file() 呼び出しは、それぞれ data から読み込んだか、または書き込んだバイト数を返し、 dataNULL であったなら、 extattr_get_file() と extattr_list_file() は、読み込むことができるバイト数を返します。なにか呼び出しが失敗した場合には、値-1 が返され、グローバル変数 errno がそのエラーを示すために設定されます。


The extattr_delete_file() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

エラー

システムコール自身によって、以下のエラーが返されることがあります。加えて、呼び出しを実装しているファイルシステムは、希望するその他のエラーを返すことがあります。
[ EFAULT]
attrnamespaceattrname 引数、または datanbytes によって定義されるメモリ範囲が、プロセスに割り当てられたアドレス空間の外を指しています。
[ ENAMETOOLONG]
属性の名前が EXTATTR_MAXNAMELEN より長くなっていました。

extattr_get_fd(), extattr_set_fd(), extattr_delete_fd() と extattr_list_fd() システムコールは、次の場合に失敗します:

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

加えて、 extattr_get_file(), extattr_set_file() と extattr_delete_file() 呼び出しは、次のエラーのため、失敗します:

[ ENOATTR]
要求された属性はこのファイルのために定義されていません。
[ ENOTDIR]
パス名のプレフィックスの構成要素がディレクトリではありません。
[ ENAMETOOLONG]
パス名の構成要素が 255 文字を超えている、またはパス名全体が 1023 文字を超えています。
[ ENOENT]
存在していなければならないパス名の構成要素が、存在していません。
[ EACCES]
パス名のプレフィックスの構成要素の検索パーミッションがありません。

歴史

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

バグ

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