doc/ja_JP.eucJP/man/man9/sysctl_add_oid.9

.\"
.\" Copyright (c) 2000, Andrzej Bialecki <abial@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.
.\" 3. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" 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/share/man/man9/sysctl_add_oid.9,v 1.20 2004/07/03 18:29:24 ru Exp %
.\" $FreeBSD$
.\"
.Dd July 15, 2000
.Dt SYSCTL_ADD_OID 9
.Os
.Sh 名称
.Nm sysctl_add_oid ,
.Nm sysctl_move_oid ,
.Nm sysctl_remove_oid
.Nd ランタイム sysctl ツリー操作
.Sh 書式
.In sys/types.h
.In sys/sysctl.h
.Ft struct sysctl_oid *
.Fo sysctl_add_oid
.Fa "struct sysctl_ctx_list *ctx"
.Fa "struct sysctl_oid_list *parent"
.Fa "int number"
.Fa "const char *name"
.Fa "int kind"
.Fa "void *arg1"
.Fa "int arg2"
.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)"
.Fa "const char *format"
.Fa "const char *descr"
.Fc
.Ft int
.Fo sysctl_move_oid
.Fa "struct sysctl_oid *oidp"
.Fa "struct sysctl_oid_list *parent"
.Fc
.Ft int
.Fo sysctl_remove_oid
.Fa "struct sysctl_oid *oidp"
.Fa "int del"
.Fa "int recurse"
.Fc
.Ft struct sysctl_oid_list *
.Fo SYSCTL_CHILDREN
.Fa "struct sysctl_oid *oidp"
.Fc
.Ft struct sysctl_oid_list *
.Fo SYSCTL_STATIC_CHILDREN
.Fa "struct sysctl_oid_list OID_NAME"
.Fc
.Ft struct sysctl_oid *
.Fo SYSCTL_ADD_OID
.Fa "struct sysctl_ctx_list *ctx"
.Fa "struct sysctl_oid_list *parent"
.Fa "int number"
.Fa "const char *name"
.Fa "int kind"
.Fa "void *arg1"
.Fa "int arg2"
.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)"
.Fa "const char *format"
.Fa "const char *descr"
.Fc
.Ft struct sysctl_oid *
.Fo SYSCTL_ADD_NODE
.Fa "struct sysctl_ctx_list *ctx"
.Fa "struct sysctl_oid_list *parent"
.Fa "int number"
.Fa "const char *name"
.Fa "int access"
.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)"
.Fa "const char *descr"
.Fc
.Ft struct sysctl_oid *
.Fo SYSCTL_ADD_STRING
.Fa "struct sysctl_ctx_list *ctx"
.Fa "struct sysctl_oid_list *parent"
.Fa "int number"
.Fa "const char *name"
.Fa "int access"
.Fa "char *arg"
.Fa "int len"
.Fa "const char *descr"
.Fc
.Ft struct sysctl_oid *
.Fo SYSCTL_ADD_INT
.Fa "struct sysctl_ctx_list *ctx"
.Fa "struct sysctl_oid_list *parent"
.Fa "int number"
.Fa "const char *name"
.Fa "int access"
.Fa "int *arg"
.Fa "int len"
.Fa "const char *descr"
.Fc
.Ft struct sysctl_oid *
.Fo SYSCTL_ADD_UINT
.Fa "struct sysctl_ctx_list *ctx"
.Fa "struct sysctl_oid_list *parent"
.Fa "int number"
.Fa "const char *name"
.Fa "int access"
.Fa "unsigned int *arg"
.Fa "int len"
.Fa "const char *descr"
.Fc
.Ft struct sysctl_oid *
.Fo SYSCTL_ADD_LONG
.Fa "struct sysctl_ctx_list *ctx"
.Fa "struct sysctl_oid_list *parent"
.Fa "int number"
.Fa "const char *name"
.Fa "int access"
.Fa "long *arg"
.Fa "const char *descr"
.Fc
.Ft struct sysctl_oid *
.Fo SYSCTL_ADD_ULONG
.Fa "struct sysctl_ctx_list *ctx"
.Fa "struct sysctl_oid_list *parent"
.Fa "int number"
.Fa "const char *name"
.Fa "int access"
.Fa "unsigned long *arg"
.Fa "const char *descr"
.Fc
.Ft struct sysctl_oid *
.Fo SYSCTL_ADD_OPAQUE
.Fa "struct sysctl_ctx_list *ctx"
.Fa "struct sysctl_oid_list *parent"
.Fa "int number"
.Fa "const char *name"
.Fa "int access"
.Fa "void *arg"
.Fa "int len"
.Fa "const char *format"
.Fa "const char *descr"
.Fc
.Ft struct sysctl_oid *
.Fo SYSCTL_ADD_STRUCT
.Fa "struct sysctl_ctx_list *ctx"
.Fa "struct sysctl_oid_list *parent"
.Fa "int number"
.Fa "const char *name"
.Fa "int access"
.Fa "void *arg"
.Fa STRUCT_NAME
.Fa "const char *descr"
.Fc
.Ft struct sysctl_oid *
.Fo SYSCTL_ADD_PROC
.Fa "struct sysctl_ctx_list *ctx"
.Fa "struct sysctl_oid_list *parent"
.Fa "int number"
.Fa "const char *name"
.Fa "int access"
.Fa "void *arg1"
.Fa "int arg2"
.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)"
.Fa "const char *format"
.Fa "const char *descr"
.Fc
.Sh 解説
これらの関数およびマクロは sysctl oid のランタイム (例えばモジュールの
存在期間) での作成と削除のためのインタフェースを提供します。
リンカセット (詳細は
.In sys/linker_set.h
および
.\" XXX マニュアルページはソースファイルの参照を避けるべきです。
.Pa src/sys/kern/kern_sysctl.c
を参照) 
に基づく代わりの方法は、各々のモジュールのロード時およびアンロード時の
作成と削除のみを可能にします。
.Pp
型
.Dv CTLTYPE_NODE
の動的な oid は再利用可能であるため、複数のコードセクションが、
oid を作成および削除することが可能です。
実際には、参照カウントに基づいて、その割り当ておよび解放が行われます。
その結果として、2 つ以上のコードセクションが、部分的に重なり、
両者が使用できるツリーを作成可能にします。
重なる葉の作成や、同一の名前と親を持つ異なる型の子の作成は、
不可能です。
.Pp
新しく作成された oid は親のノードに接続されます。
これら全ての関数およびマクロ
.Fn ( sysctl_remove_oid
は例外) において、必須パラメータの 1 つ
.Fa parent
は、子の親リストの先頭を指します。
.Pp
殆どのトップレベルのカテゴリは静的に作成されます。
既存の静的な oid に接続するときに、このポインタは
.Fn SYSCTL_STATIC_CHILDREN
マクロによって取得することが可能で、その
.Fa OID_NAME
引数は
.Dv CTLTYPE_NODE
型の親 oid の名前 (すなわち、
.Xr sysctl 8
によって表示される名前に、
アンダスコアを前置し、全てのドットをアンダスコアで置き換えた名前) です。
.Pp
既存の動的な oid に接続するときに、このポインタは
.Fn SYSCTL_CHILDREN
マクロによって取得することが可能で、その
.Fa oidp
引数は
.Dv CTLTYPE_NODE
型の親 oid を指します。
.Pp
.Fn sysctl_add_oid
関数はあらゆる型の生の oid を作成します。
oid の作成が成功した場合には、この関数はその oid へのポインタを返します。
そうでない場合には、
.Dv NULL
を返します。
.Fn sysctl_add_oid
のための引数の多くはマクロと共通です。
引数は以下のとおりです。
.Bl -tag -width handler
.It Fa ctx
オプションの sysctl コンテキストへのポインタ、または
.Dv NULL
です。
詳細は
.Xr sysctl_ctx_init 9
を参照してください。
特別な作成および削除のシーケンスが要求されるのでなければ、
作成する動的な oid を組織するためにコンテキストを使用することを、
プログラマは強く勧告されています。
.Fa ctx
が
.Dv NULL
でない場合には、新しく作成される oid は最初のエントリとしてこのコンテキストに
追加されます。
.It Fa parent
子の親リストの先頭である
.Li struct sysctl_oid_list
へのポインタです。
.It Fa number
この oid に割り当てられる oid 番号です。
殆ど全ての場合、これは割り当て時に次の利用可能な oid 番号になる
.Dv OID_AUTO
に設定されるべきです。
.It Fa name
この oid の名前です。
新しく作成された oid は名前のコピーを含んでいます。
.It Fa kind
oid の種類で、
.In sys/sysctl.h
ヘッダファイルの中で定義される型とアクセス値のビットマスクとして明示されます。
動的に作成された oid は常に
.Dv CTLFLAG_DYN
フラグが設定されます。
アクセスフラグはこの oid が読み取り専用か読み書き可能か、および
全てのユーザによってまたはスーパユーザによってのみ修正可能かを明示します。
.It Fa arg1
oid が参照すべきあらゆるデータへのポインタ、または
.Dv NULL
です。
.It Fa arg2
.Fa arg1
の大きさ、または
.Fa arg1
が
.Dv NULL
であれば 0 です。
.It Fa handler
この oid への読み書き要求を取り扱う責任がある関数へのポインタです。
ノード、整数、文字列、および不透明なオブジェクトの操作をサポートする
幾つかの標準ハンドラが存在しています。
.Fn SYSCTL_ADD_PROC
マクロを使用して新しいハンドラを定義することも可能です。
.It Fa format
oid のフォーマットを記号的に明示する文字列へのポインタです。
このフォーマットは、表示目的のための適切なデータフォーマットを適用するために
.Xr sysctl 8
によってヒントとして使用されます。
現在使用されているフォーマット名は以下のとおりです。
.Dq N
はノード、
.Dq A
は
.Li "char *"
型、
.Dq I
は
.Li "int"
型、
.Dq IU
は
.Li "unsigned int"
型、
.Dq L
は
.Li "long"
型、
.Dq LU
は
.Li "unsigned long"
型、および
.Dq S,TYPE
は
.Li "struct TYPE"
構造体です。
.It Fa descr
この oid の解説テキストへのポインタです。
.El
.Pp
.Fn sysctl_move_oid
関数は存在している oid の親を付け変えます。
その oid は、まるで
.Fa number
に
.Dv OID_AUTO
が設定されて作成されたかの様に、新しい番号を割り当てられます。
.Pp
.Fn sysctl_remove_oid
関数は動的に作成された oid をツリーから削除し、
オプションでそのリソースを解放します。
これは以下の引数を取ります。
.Bl -tag -width recurse
.It Fa oidp
削除されるべき動的な oid へのポインタです。
oid が動的でない、またはポインタが
.Dv NULL
の場合には、この関数は
.Er EINVAL
を返します。
.It Fa del
0 でない場合には、oid の参照カウントが 0 になった時に、
.Fn sysctl_remove_oid
は oid のリソースを解放しようとします。
しかしながら
.Fa del
が 0 に設定されている場合には、このルーチンは oid のリソースの解放をせずに
ツリーから oid の登録抹消のみを行ないます。
この振舞いは、呼び出し側が後で (ひょっとすると部分的に失敗する) 多数の oid の
削除のロールバックを予期している時に、有用です。
.It Fa recurse
0 でない場合には、そのノードとその子を削除しようとします。
.Pa recurse
が 0 に設定されている場合には、あらゆる子を含むノードの削除の試みは
.Er ENOTEMPTY
エラーを発生させます。
.Em 警告 : "再帰的な削除は非常な注意を払って使用すること" !
通常、コンテキストが使用されていれば、必要とされるべきではありません。
コンテキストはツリーの利用者間の依存性の追跡に注意しています。
しかしながら、ある極端な場合には、ある他のリソースを解放するために、
それがどのように作成されたものであれ、サブツリーの一部を削除することが
必要になることがあります。
しかしながら、このことは、別のコードセクションが削除されたサブツリーを
使用し続ける場合に、システムの
.Xr panic 9
を引き起こすことがあることを知っていてください。
.El
.Pp
.\" XXX sheldonh はここまで仕上げました。
再度言いますが、殆んどの場合、作成された oid を見失わないようにするため、
および後で整然とした流儀でそれらを削除するため、
.Xr sysctl_ctx_init 9
で解説されているように、プログラマはコンテキストを使用するべきです。
.Pp
与えられた型の oid の作成を助ける定義済みのマクロセットがあります。
.Bl -tag -width SYSCTL_ADD_STRINGXX
それらを以下に示します。
.It Fn SYSCTL_ADD_OID
は生の oid を作成します。
このマクロは機能的には
.Fn sysctl_add_oid
関数と同等です。
.It Fn SYSCTL_ADD_NODE
は型
.Dv CTLTYPE_NODE
の oid を作成します。
この oid に対して、子の oid を追加可能です。
.It Fn SYSCTL_ADD_STRING
は 0 で終端された文字列を取り扱う oid を作成します。
.It Fn SYSCTL_ADD_INT
は
.Li int
変数を取り扱う oid を作成します。
.It Fn SYSCTL_ADD_UINT
は
.Li unsigned int
変数を取り扱う oid を作成します。
.It Fn SYSCTL_ADD_LONG
は
.Li long
変数を取り扱う oid を作成します。
.It Fn SYSCTL_ADD_ULONG
は
.Li unsigned long
変数を取り扱う oid を作成します。
.It Fn SYSCTL_ADD_OPAQUE
は
.Li "size_t *"
へのポインタである
.Fa len
引数によって明示された大きさのあらゆる不透明なデータのかたまりを
取り扱う oid を作成します。
.It Fn SYSCTL_ADD_STRUCT
は
.Li "struct TYPE"
構造体を取り扱う oid を作成します。
.Fa format
引数は
.Xr sysctl 8
ユーティリティへの適切なヒントを提供するために
.Dq S,TYPE
に設定されます。
.It Fn SYSCTL_ADD_PROC
は明示された
.Pa handler
ハンドラ関数を持つ oid を作成します。
ハンドラは oid に対しての読み書き要求を取り扱う責任を持ちます。
カーネルデータが簡単にアクセスできない場合、または取り出される前に処理される
必要がある場合に、この oid 型は特に有用です。
.El
.Sh 使用例
以下は、どのように新しいトップレベルのカテゴリを作成するか、および
どのように既存の静的なノードに別のサブツリーを引っ掛けるか
を示す使用例です。
この使用例はコンテキストを使用していません。
これは全ての後でそれらを解放するといった、
中間の oid の退屈な管理を結果として生じさせます。
.Bd -literal
#include <sys/sysctl.h>
 ...
/* 新しく作成したサブツリーへのポインタは、後でそれらを解放するために
 * 保存しておく必要があります。
 */
struct sysctl_oid *root1, *root2, *oidp;
int a_int;
char *string = "dynamic sysctl";
 ...

root1 = SYSCTL_ADD_NODE( NULL, SYSCTL_STATIC_CHILDREN(/* tree top */),
	OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree");
oidp = SYSCTL_ADD_INT( NULL, SYSCTL_CHILDREN(root1),
	OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf");
 ...
root2 = SYSCTL_ADD_NODE( NULL, SYSCTL_STATIC_CHILDREN(_debug),
	OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug");
oidp = SYSCTL_ADD_STRING( NULL, SYSCTL_CHILDREN(root2),
	OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf");
.Ed
.Pp
この使用例は以下のサブツリーを作成します。
.Bd -literal -offset indent
debug.newtree.newstring
newtree.newint
.Ed
.Pp
.Em "これ以上必要でなくなった全ての oid は解放されるべきであることに注意!"
.Sh 関連項目
.Xr sysctl 8 ,
.Xr sysctl_ctx_free 9 ,
.Xr sysctl_ctx_init 9
.Sh 歴史
これらの関数は
.Fx 4.2
ではじめて登場しました。
.Sh 作者
.An Andrzej Bialecki Aq abial@FreeBSD.org
.Sh バグ
多くのコードセクション間でノードを共有することは、
時々リソースをロックすることがある相互依存を引き起こします。
例えば、モジュール B によって作成された oid に対し、
モジュール A がサブツリーを引っ掛けた場合には、
モジュール B はその oid を削除できないでしょう。
これらの問題は sysctl コンテキストによって適切に取り扱われます。
.Pp
ツリー上の多くの操作はリンクリストを横切ることを必要とします。
この理由のため、oid の作成と削除は相対的にコストがかかります。