os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
doc/documentation/manual-pages/ja/man2/extattr_get_file.2
Sergio Carlavilla Delgado 989d921f5d Migrate doc to Hugo/AsciiDoctor 
I'm very pleased to announce the release of
our new website and documentation using
the new toolchain with Hugo and AsciiDoctor.

To get more information about the new toolchain
please read the FreeBSD Documentation Project Primer[1],
Hugo docs[2] and AsciiDoctor docs[3].

Acknowledgment:
Benedict Reuschling <bcr@>
Glen Barber <gjb@>
Hiroki Sato <hrs@>
Li-Wen Hsu <lwhsu@>
Sean Chittenden <seanc@>
The FreeBSD Foundation

[1] https://docs.FreeBSD.org/en/books/fdp-primer/
[2] https://gohugo.io/documentation/
[3] https://docs.asciidoctor.org/home/

Approved by:    doceng, core
2021-01-26 00:31:29 +01:00

264 lines
7.9 KiB
Groff
Raw Blame History

.\"
.\" Copyright (c) 2001 Dima Dorfman <dima@unixfreak.org>
.\" Copyright (c) 2003 Robert Watson <rwatson@FreeBSD.org>
.\" 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 を使用すべきなので、
このインタフェースは非推奨であり、使用されるべきではありません。
Reference in a new issue View git blame Copy permalink