.\" .\" Copyright (c) 2001 Dima Dorfman .\" Copyright (c) 2003 Robert Watson .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" %FreeBSD: src/lib/libc/sys/extattr_get_file.2,v 1.14.2.1 2005/03/01 16:16:20 csjp Exp % .\" .\" $FreeBSD$ .Dd February 23, 2005 .Dt EXTATTR 2 .Os .Sh 名称 .Nm extattr_get_fd , .Nm extattr_set_fd , .Nm extattr_delete_fd , .Nm extattr_list_fd , .Nm extattr_get_file , .Nm extattr_set_file , .Nm extattr_delete_file , .Nm extattr_list_file , .Nm extattr_get_link , .Nm extattr_set_link , .Nm extattr_delete_link , .Nm extattr_list_link .Nd VFS 拡張属性を操作するためのシステムコール .Sh ライブラリ .Lb libc .Sh 書式 .In sys/types.h .In sys/extattr.h .In sys/uio.h .Ft ssize_t .Fn extattr_get_fd "int fd" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes" .Ft int .Fn extattr_set_fd "int fd" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes" .Ft int .Fn extattr_delete_fd "int fd" "int attrnamespace" "const char *attrname" .Ft ssize_t .Fn extattr_list_fd "int fd" "int attrnamespace" "void *data" "size_t nbytes" .Ft ssize_t .Fn extattr_get_file "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes" .Ft int .Fn extattr_set_file "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes" .Ft int .Fn extattr_delete_file "const char *path" "int attrnamespace" "const char *attrname" .Ft ssize_t .Fn extattr_list_file "const char *path" "int attrnamespace" "void *data" "size_t nbytes" .Ft ssize_t .Fn extattr_get_link "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes" .Ft int .Fn extattr_set_link "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes" .Ft int .Fn extattr_delete_link "const char *path" "int attrnamespace" "const char *attrname" .Ft ssize_t .Fn extattr_list_link "const char *path" "int attrnamespace" "void *data" "size_t nbytes" .Sh 解説 名前付き拡張属性は、ファイルまたはディレクトリを表現する vnode に 関連付けられたメタデータです。 これらは名前空間の集合の中に .Qq Li name=value .Qq ( 名前=値 ) のペアとして存在します。 .Pp .Fn extattr_get_file システムコールは、指定された拡張属性の値を大きさが .Fa nbytes の .Fa data によって指されるバッファに取り出します。 .Fn extattr_set_file システムコールは、指定された拡張属性の値を .Fa data に記述されたデータに設定します。 .Fn extattr_delete_file システムコールは、指定された拡張属性を削除します。 .Fn extattr_list_file は ASCII 0 (ヌル) 文字によって分離された、要求された名前空間の中に存在する 属性のリストを返します。 .Fn extattr_get_file および .Fn extattr_list_file 呼び出しは .Xr read 2 の形式で .Fa data と .Fa nbytes 引数を使用します。 .Fn extattr_set_file は .Xr write 2 の形式でこれらの引数を使用します。 .\" 原文: .Xr write 2. は .Xr write 2<空白>. の誤り。 .Pp .Fn extattr_get_file の呼び出しの中で .Fa data が .Dv NULL の場合には、読み込んだ量を返すのではなく、 定義された拡張属性データの大きさを返します。 これにより、 アプリケーションが読み込みを実行せずにデータの大きさを テストすることを可能にします。 .Fn extattr_delete_link , .Fn extattr_get_link , .Fn extattr_set_link システムコールは、シンボリックリンクを辿らないことを除いて、名前が .Qq Li _file のものと同じ動作をします。 .Pp .Fn extattr_get_fd , .Fn extattr_set_fd , .Fn extattr_delete_fd 呼び出しは、最初の引数を除いて、名前が .Qq Li _file のものと同じ動作をします。 .Qq Li _fd 関数がファイル記述子を取るのに対し、 .Qq Li _file 関数はパス名を取ります。 両方の引数は操作されるべき拡張属性に関連付けられたファイルを、記述します。 .Pp 以下に、全てのシステムコールに共通な引数を記述します: .Bl -tag -width attrnamespace .It Fa attrnamespace 拡張属性が属する名前空間です。 .Xr extattr 9 を参照してください。 .It Fa attrname 拡張属性の名前です。 .El .Pp 名前付き拡張属性のセマンティクスは、 この呼び出しを実装するファイルシステムに依存し、一様ではありません。 特定の属性に対しては、全ての操作がサポートされないかもしれません。 加えて、 .Fa data に入るデータのフォーマットは、属性に特有です。 .Pp 名前付き拡張属性についてのより多くの情報については、 .Xr extattr 9 を参照してください。 .Sh 警告 このインタフェースは活発に開発中ですので、 アプリケーションがこのインタフェースを使うようになるのに従って、 変わるでしょう。 開発者がこれの安定を当てにすることは推奨されません。 .Sh 戻り値 成功の場合には、 .Fn extattr_get_file および .Fn extattr_set_file の呼び出しは、各々 .Fa data から読込んだまたは書込んだバイト数を返します。 また、 .Fa data が .Dv NULL の場合には、 .Fn extattr_get_file は読込みに利用可能なバイト数を返します。 なにか呼び出しが失敗した場合には、値 \-1 が返され、グローバル変数 .Va errno がそのエラーを示すために設定されます。 .Pp .Rv -std extattr_delete_file .Sh エラー システムコール自身によって、以下のエラーが返されることがあります。 加えて、呼び出しを実装しているファイルシステムは、希望するその他の エラーを返すことがあります。 .Bl -tag -width Er .It Bq Er EFAULT .Fa attrnamespace および .Fa attrname 引数、または .Fa data および .Fa nbytes によって定義されるメモリ範囲が、 プロセスに割り当てられたアドレス空間の外を指しています。 .It Bq Er ENAMETOOLONG 属性の名前が .Dv EXTATTR_MAXNAMELEN より長くなっていました。 .El .Pp .Fn extattr_get_fd , .Fn extattr_set_fd , .Fn extattr_delete_fd システムコールは、次の場合に失敗することがあります: .Bl -tag -width Er .It Bq Er EBADF .Fa fd によって参照されるファイル記述子が無効です。 .El .Pp 加えて、 .Fn extattr_get_file , .Fn extattr_set_file , .Fn extattr_delete_file の呼び出しは以下のエラーのため、失敗することがあります: .Bl -tag -width Er .It Bq Er ENOATTR 要求された属性はこのファイルのために定義されていません。 .It Bq Er ENOTDIR パス名のプレフィックスの構成要素がディレクトリではありません。 .It Bq Er ENAMETOOLONG パス名の構成要素が 255 文字を超えている、 またはパス名全体が 1023 文字を超えています。 .It Bq Er ENOENT 存在していなければならないパス名の構成要素が、存在していません。 .It Bq Er EACCES パス名のプレフィックスの構成要素の検索パーミッションがありません。 .\" XXX 何か抜けてる? .El .Sh 関連項目 .Xr extattr 3 , .Xr getextattr 8 , .Xr setextattr 8 , .Xr extattr 9 , .Xr VOP_GETEXTATTR 9 , .Xr VOP_SETEXTATTR 9 .Sh 歴史 拡張属性サポートは .Tn TrustedBSD プロジェクトの一部として開発され、 .Fx 5.0 で導入されました。 個々のファイルまたはディレクトリに関連付けられるための追加のラベルを 要求するセキュリティ拡張をサポートするために開発されました。 .Sh バグ この API の初期のバージョンでは、属性名として空の文字列を .Fn extattr_get_fd , .Fn extattr_get_file または .Fn extattr_get_link に渡すことによって、目的のオブジェクトのために定義された属性のリストを 返しました。 明示的な list API を使用すべきなので、 このインタフェースは非推奨であり、使用されるべきではありません。