日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.4-RELEASE-K, 13.0-RELEASE-K から 13.3-RELEASE-K, 14.0-RELEASE-K から 14.1-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
SYSCTL(9) FreeBSD カーネル開発者マニュアル SYSCTL(9)
名称
SYSCTL_DECL, SYSCTL_ADD_BOOL, SYSCTL_ADD_COUNTER_U64,
SYSCTL_ADD_COUNTER_U64_ARRAY, SYSCTL_ADD_INT, SYSCTL_ADD_LONG,
SYSCTL_ADD_NODE, SYSCTL_ADD_NODE_WITH_LABEL, SYSCTL_ADD_OPAQUE,
SYSCTL_ADD_PROC, SYSCTL_ADD_QUAD, SYSCTL_ADD_ROOT_NODE, SYSCTL_ADD_S8,
SYSCTL_ADD_S16, SYSCTL_ADD_S32, SYSCTL_ADD_S64, SYSCTL_ADD_SBINTIME_MSEC,
SYSCTL_ADD_SBINTIME_USEC, SYSCTL_ADD_STRING, SYSCTL_ADD_CONST_STRING,
SYSCTL_ADD_STRUCT, SYSCTL_ADD_TIMEVAL_SEC, SYSCTL_ADD_U8, SYSCTL_ADD_U16,
SYSCTL_ADD_U32, SYSCTL_ADD_U64, SYSCTL_ADD_UAUTO, SYSCTL_ADD_UINT,
SYSCTL_ADD_ULONG, SYSCTL_ADD_UMA_CUR, SYSCTL_ADD_UMA_MAX,
SYSCTL_ADD_UQUAD, SYSCTL_CHILDREN, SYSCTL_STATIC_CHILDREN,
SYSCTL_NODE_CHILDREN, SYSCTL_PARENT, SYSCTL_BOOL, SYSCTL_COUNTER_U64,
SYSCTL_COUNTER_U64_ARRAY, SYSCTL_INT, SYSCTL_INT_WITH_LABEL, SYSCTL_LONG,
sysctl_msec_to_ticks, SYSCTL_NODE, SYSCTL_NODE_WITH_LABEL, SYSCTL_OPAQUE,
SYSCTL_PROC, SYSCTL_QUAD, SYSCTL_ROOT_NODE, SYSCTL_S8, SYSCTL_S16,
SYSCTL_S32, SYSCTL_S64, SYSCTL_SBINTIME_MSEC, SYSCTL_SBINTIME_USEC,
SYSCTL_STRING, SYSCTL_CONST_STRING, SYSCTL_STRUCT, SYSCTL_TIMEVAL_SEC,
SYSCTL_U8, SYSCTL_U16, SYSCTL_U32, SYSCTL_U64, SYSCTL_UINT, SYSCTL_ULONG,
SYSCTL_UMA_CUR, SYSCTL_UMA_MAX, SYSCTL_UQUAD -- 動的で静的な sysctl MIB
作成関数
書式
#include <sys/param.h>
#include <sys/sysctl.h>
SYSCTL_DECL(name);
struct sysctl_oid *
SYSCTL_ADD_BOOL(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, bool *ptr, uint8_t val, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_COUNTER_U64(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, counter_u64_t *ptr, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_COUNTER_U64_ARRAY(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, counter_u64_t *ptr, intmax_t len, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_INT(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, int *ptr, int val, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_LONG(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, long *ptr, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_NODE(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, int (*handler)(SYSCTL_HANDLER_ARGS),
const char *descr);
struct sysctl_oid *
SYSCTL_ADD_NODE_WITH_LABEL(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, int (*handler)(SYSCTL_HANDLER_ARGS), const char *descr,
const char *label);
struct sysctl_oid *
SYSCTL_ADD_OPAQUE(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, void *ptr, intptr_t len, const char *format,
const char *descr);
struct sysctl_oid *
SYSCTL_ADD_PROC(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, void *arg1, intptr_t arg2,
int (*handler) (SYSCTL_HANDLER_ARGS), const char *format,
const char *descr);
struct sysctl_oid *
SYSCTL_ADD_QUAD(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, int64_t *ptr, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_ROOT_NODE(struct sysctl_ctx_list *ctx, int number,
const char *name, int ctlflags, int (*handler)(SYSCTL_HANDLER_ARGS),
const char *descr);
struct sysctl_oid *
SYSCTL_ADD_S8(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, int8_t *ptr, int8_t val, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_S16(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, int16_t *ptr, int16_t val, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_S32(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, int32_t *ptr, int32_t val, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_S64(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, int64_t *ptr, int64_t val, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_SBINTIME_MSEC(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, sbintime_t *ptr, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_SBINTIME_USEC(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, sbintime_t *ptr, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_STRING(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, char *ptr, intptr_t len, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_CONST_STRING(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, const char *ptr, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_STRUCT(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, void *ptr, struct_type, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_TIMEVAL_SEC(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, struct timeval *ptr, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_U8(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, uint8_t *ptr, uint8_t val, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_U16(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, uint16_t *ptr, uint16_t val, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_U32(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, uint32_t *ptr, uint32_t val, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_U64(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, uint64_t *ptr, uint64_t val, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_UINT(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, unsigned int *ptr, unsigned int val,
const char *descr);
struct sysctl_oid *
SYSCTL_ADD_ULONG(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, unsigned long *ptr, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_UQUAD(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, uint64_t *ptr, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_UMA_CUR(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, uma_zone_t ptr, const char *descr);
struct sysctl_oid *
SYSCTL_ADD_UMA_MAX(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, uma_zone_t ptr, const char *descr);
const char *descr
struct sysctl_oid *
SYSCTL_ADD_UAUTO(struct sysctl_ctx_list *ctx,
struct sysctl_oid_list *parent, int number, const char *name,
int ctlflags, void *ptr, const char *descr);
struct sysctl_oid_list *
SYSCTL_CHILDREN(struct sysctl_oid *oidp);
struct sysctl_oid_list *
SYSCTL_STATIC_CHILDREN(struct sysctl_oid_list OID_NAME);
struct sysctl_oid_list *
SYSCTL_NODE_CHILDREN(parent, name);
struct sysctl_oid *
SYSCTL_PARENT(struct sysctl_oid *oid);
SYSCTL_BOOL(parent, number, name, ctlflags, ptr, val, descr);
SYSCTL_COUNTER_U64(parent, number, name, ctlflags, ptr, descr);
SYSCTL_COUNTER_U64_ARRAY(parent, number, name, ctlflags, ptr, len,
descr);
SYSCTL_INT(parent, number, name, ctlflags, ptr, val, descr);
SYSCTL_INT_WITH_LABEL(parent, number, name, ctlflags, ptr, val, descr,
label);
SYSCTL_LONG(parent, number, name, ctlflags, ptr, val, descr);
int
sysctl_msec_to_ticks(SYSCTL_HANDLER_ARGS);
SYSCTL_NODE(parent, number, name, ctlflags, handler, descr);
SYSCTL_NODE_WITH_LABEL(parent, number, name, ctlflags, handler, descr,
label);
SYSCTL_OPAQUE(parent, number, name, ctlflags, ptr, len, format, descr);
SYSCTL_PROC(parent, number, name, ctlflags, arg1, arg2, handler, format,
descr);
SYSCTL_QUAD(parent, number, name, ctlflags, ptr, val, descr);
SYSCTL_ROOT_NODE(number, name, ctlflags, handler, descr);
SYSCTL_S8(parent, number, name, ctlflags, ptr, val, descr);
SYSCTL_S16(parent, number, name, ctlflags, ptr, val, descr);
SYSCTL_S32(parent, number, name, ctlflags, ptr, val, descr);
SYSCTL_S64(parent, number, name, ctlflags, ptr, val, descr);
SYSCTL_SBINTIME_MSEC(parent, number, name, ctlflags, ptr, descr);
SYSCTL_SBINTIME_USEC(parent, number, name, ctlflags, ptr, descr);
SYSCTL_STRING(parent, number, name, ctlflags, arg, len, descr);
SYSCTL_CONST_STRING(parent, number, name, ctlflags, arg, descr);
SYSCTL_STRUCT(parent, number, name, ctlflags, ptr, struct_type, descr);
SYSCTL_TIMEVAL_SEC(parent, number, name, ctlflags, ptr, descr);
SYSCTL_U8(parent, number, name, ctlflags, ptr, val, descr);
SYSCTL_U16(parent, number, name, ctlflags, ptr, val, descr);
SYSCTL_U32(parent, number, name, ctlflags, ptr, val, descr);
SYSCTL_U64(parent, number, name, ctlflags, ptr, val, descr);
SYSCTL_UINT(parent, number, name, ctlflags, ptr, val, descr);
SYSCTL_ULONG(parent, number, name, ctlflags, ptr, val, descr);
SYSCTL_UQUAD(parent, number, name, ctlflags, ptr, val, descr);
SYSCTL_UMA_MAX(parent, number, name, ctlflags, ptr, descr);
SYSCTL_UMA_CUR(parent, number, name, ctlflags, ptr, descr);
解説
SYSCTL カーネルインタフェースは、sysctl(8) MIB エントリの動的または静的な
生成を許可します。すべての静的な sysctl は、それらが部分であるモジュール
がアンロードされるとき、自動的に破壊されます。ほとんどのトップのレベルの
カテゴリは、静的に作成され、すべてのカーネルコードとそのモジュールに利用
可能です。
引数の説明
ctx sysctl コンテキストへのポインタ、またはコンテキストがないなら、
NULL です。新しい sysctl のコンテキストを作成する方法について
は、sysctl_ctx_init(9) を参照してください。プログラマは、コンテ
キストが破壊されるとき、属している sysctl がすべて同様に破壊さ
れるので、それらが作成する動的な OID を組織化するためにコンテキ
ストを使用するように強く勧められます。これは、sysctl クリーン
アップコードをより単純にします。そうでなければ、すべての作成さ
れた OID の削除は、アンロードされるモジュールで必要とされます。
parent 子プロセスの親のリストのヘッドである、struct sysctl_oid_list へ
のポインタ。このポインタは、静的な sysctl のための
SYSCTL_STATIC_CHILDREN() マクロを、動的な sysctl のための
SYSCTL_CHILDREN() マクロを使用して検索されます。OID の親を取得
するために SYSCTL_PARENT() マクロを使用することができます。親が
ないなら、マクロは、NULL を返します。
number この OID に割り当てられる OID 番号。ほとんどすべての場合に、こ
れは、次に利用可能な OID 番号の割り当ての結果となる、OID_AUTO
に設定されるべきです。
name OID の名前。新しく作成された OID は、名前のコピーを含みます。
ctlflags sysctl 制御フラグのビットマスク。すべての制御フラグについて下記
の記述のセクションを参照してください。
arg1 手続き sysctl のための最初のコールバック引数。
arg2 手続き sysctl のための 2 番目のコールバック引数。
len ptr 引数によって指されるデータの長さ。文字列のタイプ OID につい
て、0 の長さは、OID への各アクセスで文字列の長さを取得するため
に、strlen(3) が使用されることを意味します。タイプ OID の配列た
めに、長さは、0 より大きくなければなりません。
ptr sysctl 変数または文字列データへのポインタ。sysctl 値のために、
ポインタは、OID が読み込み専用であることを意味する
SYSCTL_NULL_XXX_PTR を指定することができ、返される値は、val 引
数から取られるべきです。
val ptr 引数が SYSCTL_NULL_XXX_PTR であるなら、この OID によって返
される定数値を与えます。そうでなければ、この引数は、使用されま
せん。
struct_type
構造タイプの名前。
handler この OID への読み込みと書き込みの要求を操作するために責任がある
関数へのポインタは、ノード、整数、文字列と不透明な (サイズと形
がわからない) オブジェクトでの操作をサポートするいくつかの標準
のハンドラがあります。SYSCTL_PROC() マクロまたは
SYSCTL_ADD_PROC() 関数を使用して、カスタムハンドラを定義するこ
とは可能です、
format シンボリックな方法で OID の書式を指定する文字列へのポインタ。こ
の書式は、表示の目的のために適切なデータの書式化に適用するため
に sysctl(8) によってヒントとして使用されます。
現在の形式:
N node
A char *
I int
IK[n] ケルビン単位のの温度、10 のスケールファクタのオプ
ションの単一の数字のべき乗を乗じる: 1 (デフォル
ト) deciKelvin を与える、0 Kelvin を与える、3
milliKelvin を与える
IU unsigned int
L long
LU unsigned long
Q quad_t
QU u_quad_t
S,TYPE struct TYPE 構造体
descr OID のテキスト形式の記述へのポインタ。
label OID のこの構成要素のための集合体ラベルへのポインタ。ラベル (例
えば、Prometheus) を通して集合体をサポートする監視システムのた
めの sysctl データをエクスポートすることをより容易にするため
に、ラベル名を OID にアタッチするために、この引数を使用すること
ができます。ラベルは、この構成要素の名前がメトリック名の一部で
あるべきでないというヒントとして動作しますが、代わりにラベルと
してメトリックにアタッチされます。
ラベルは、構造的に似ている兄弟のみに適用されるべきで、同じタイ
プの値をエンコードし、そうでなければ、集合体として使用されませ
ん。
ノード値のタイプ
マクロと関数のほとんどは、タイプが、ノード値のタイプと一致する読み込み専
用の定数、または、カーネル内変数をエクスポートする sysctl ノードを作成す
るために使用されます。例えば、SYSCTL_INT() は、タイプ int の関連する変数
の生の値を報告します。しかしながら、また、ノードは、内部の表現の変換であ
る値をエクスポートします。
ミリ秒の時間の間隔をエクスポートするために、SYSCTL_PROC() または
SYSCTL_ADD_PROC() で sysctl_msec_to_ticks() ハンドラを使用することができ
ます。このハンドラを使用するとき、arg2 パラメータは、tsleep(9) のような関
数を使用するために適切なチック (tick) カウントを供給するタイプ int のカー
ネル内変数を指します。sysctl_msec_to_ticks() 関数は、ノードの値を報告する
とき、この値をミリ秒に変換します。同様に、sysctl_msec_to_ticks() は、ミリ
秒単位で新しい値を受け付け、チック (tick) 単位の同等の値を *arg2 に格納し
ます。新しいコードは、チック (tick) カウントの代わりに、タイプ sbintime_t
のカーネル変数を使用するべきであることに注意してください。
SYSCTL_ADD_SBINTIME_MSEC() と SYSCTL_ADD_SBINTIME_USEC() 関数と
SYSCTL_SBINTIME_MSEC() と SYSCTL_SBINTIME_USEC() マクロすべては、タイプ
sbintime_t のカーネル内変数をエクスポートするノードを作成します。これらの
ノードは、関連する変数の生の値をエクスポートしません。代わりに、それら
は、ミリ秒 (MSEC 変異型) またはマイクロ秒 (USEC 変異型) のいずれかのカウ
ントを含んでいる 64 ビットの整数をエクスポートします。
SYSCTL_ADD_TIMEVAL_SEC() 関数と SYSCTL_TIMEVAL_SEC() マクロは、タイプ
struct timeval のカーネル内変数をエクスポートするノードを作成します。これ
らのノードは、関連する構造の全体の値いをエクスポートしません。代わりに、
それらは、関連する変数の tv_sec フィールドに格納される簡単な整数として秒
単位のカウントをエクスポートします。この関数とマクロは、絶対的な時間では
なく、負でない間隔を格納する変数で使用されることを目的としています。結果
として、それらは、負の値を格納する試みを拒否します。
ルートノードの作成
sysctl MIB または OID は、階層的なツリーで作成されます。ツリーの下端の
ノードは、ルートノードと呼ばれ、親の OID がありません。下端のノードを作成
するために、SYSCTL_ROOT_NODE() マクロ、または SYSCTL_ADD_ROOT_NODE() 関数
が、使用される必要があります。デフォルトで、すべての静的な sysctl ノード
の OID は、グローバルで、一般的にいわゆるヘッダファイルのそれらの
SYSCTL_NODE() 定義文より前に SYSCTL_DECL() 文を必要とします。
sysctl 文字列の作成
0 で終了する文字列の sysctl は、SYSCTL_STRING() マクロまたは
SYSCTL_ADD_STRING() 関数のいずれかを使用して作成されます。len 引数が 0 で
あるなら、文字列の長さは、strlen(3) を使用して OID へのすべてのアクセスで
計算されます。定数文字列のための sysctl を追加するために、
SYSCTL_CONST_STRING() マクロまたは SYSCTL_ADD_CONST_STRING() 関数を使用し
ます。
不透明な sysctl の作成
SYSCTL_OPAQUE() または SYSCTL_STRUCT() マクロまたは SYSCTL_ADD_OPAQUE()
または SYSCTL_ADD_STRUCT() 関数は、len 引数によって指定されたサイズのデー
タのあらゆるチャンクと ptr 引数によって指されたデータを扱う、OID を作成し
ます、構造バージョンを使用するとき、タイプは、作成された sysctl の一部と
してエンコードされます。
カスタム sysctl の作成
SYSCTL_PROC() マクロと SYSCTL_ADD_PROC() 関数は、指定された handler 関数
で OID を作成します。ハンドラは、OID へのすべての読み込みと書き込み要求に
対して責任があります。この OID のタイプは、カーネルデータが容易にアクセス
可能でないか、エクスポートの前に処理される必要があるなら、特に役に立ちま
す。
静的な sysctl の作成
静的な sysctl は、SYSCTL_BOOL(), SYSCTL_COUNTER_U64(),
SYSCTL_COUNTER_U64_ARRAY(), SYSCTL_INT(), SYSCTL_INT_WITH_LABEL(),
SYSCTL_LONG(), SYSCTL_NODE(), SYSCTL_NODE_WITH_LABEL(), SYSCTL_OPAQUE(),
SYSCTL_PROC(), SYSCTL_QUAD(), SYSCTL_ROOT_NODE(), SYSCTL_S8(),
SYSCTL_S16(), SYSCTL_S32(), SYSCTL_S64(), SYSCTL_SBINTIME_MSEC(),
SYSCTL_SBINTIME_USEC(), SYSCTL_STRING(), SYSCTL_CONST_STRING(),
SYSCTL_STRUCT(), SYSCTL_TIMEVAL_SEC(), SYSCTL_U8(), SYSCTL_U16(),
SYSCTL_U32(), SYSCTL_U64(), SYSCTL_UINT(), SYSCTL_ULONG(),
SYSCTL_UQUAD(), SYSCTL_UMA_CUR() または SYSCTL_UMA_MAX() マクロの 1 つを
使用して宣言されます。
動的な sysctl の作成
動的なノードは、SYSCTL_ADD_BOOL(), SYSCTL_ADD_COUNTER_U64(),
SYSCTL_ADD_COUNTER_U64_ARRAY(), SYSCTL_ADD_INT(), SYSCTL_ADD_LONG(),
SYSCTL_ADD_NODE(), SYSCTL_ADD_NODE_WITH_LABEL(), SYSCTL_ADD_OPAQUE(),
SYSCTL_ADD_PROC(), SYSCTL_ADD_QUAD(), SYSCTL_ADD_ROOT_NODE(),
SYSCTL_ADD_S8(), SYSCTL_ADD_S16(), SYSCTL_ADD_S32(), SYSCTL_ADD_S64(),
SYSCTL_ADD_SBINTIME_MSEC(), SYSCTL_ADD_SBINTIME_USEC(),
SYSCTL_ADD_STRING(), SYSCTL_ADD_CONST_STRING(), SYSCTL_ADD_STRUCT(),
SYSCTL_ADD_TIMEVAL_SEC(), SYSCTL_ADD_U8(), SYSCTL_ADD_U16(),
SYSCTL_ADD_U32(), SYSCTL_ADD_U64(), SYSCTL_ADD_UAUTO(),
SYSCTL_ADD_UINT(), SYSCTL_ADD_ULONG(), SYSCTL_ADD_UQUAD(),
SYSCTL_ADD_UMA_CUR() または SYSCTL_ADD_UMA_MAX() 関数の 1 つを使用して作
成されます。動的に作成された OID を破壊する方法に関する詳細については、
sysctl_remove_oid(9) または sysctl_ctx_free(9) を参照してください。
制御フラグ
ほとんどの上記の関数とマクロについて、アクセスフラグの一部としてタイプを
宣言することは、必要ではありません -- しかしながら、関数によって実装され
た sysctl を宣言するとき、アクセスマスクにタイプを含むことは、必要です:
CTLTYPE_NODE これは、他のノードのための親となるノードです。
CTLTYPE_INT これは、符号付き整数です。
CTLTYPE_STRING これは、文字の配列に格納されたヌル文字で終了する文字列で
す。
CTLTYPE_S8 これは、8 ビット符号付き整数です。
CTLTYPE_S16 これは、16 ビット符号付き整数です。
CTLTYPE_S32 これは、32 ビット符号付き整数です。
CTLTYPE_S64 これは、64 ビットの符号付き整数です。
CTLTYPE_OPAQUE これは、不透明な (サイズと形がわからない) データ構造で
す。
CTLTYPE_STRUCT CTLTYPE_OPAQUE の別名。
CTLTYPE_U8 これは、8 ビット符号なし整数です。
CTLTYPE_U16 これは、16 ビット符号なし整数です。
CTLTYPE_U32 これは、32 ビット符号なし整数です。
CTLTYPE_U64 これは、64 ビット符号なし整数です。
CTLTYPE_UINT これは、符号なし整数です。
CTLTYPE_LONG これは、符号付き long です。
CTLTYPE_ULONG これは、符号なし long です。
新しいノード宣言以外のすべての sysctl タイプは、sysctl の読み込み書き込み
処理を示すように設定される次のフラグの 1 つを必要とします:
CTLFLAG_RD これは、読み込み専用 sysctl です。
CTLFLAG_RDTUN これは、モジュールのロードまたはシステムのブートの間にシ
ステムの環境からいったん取って来られることを試みられる読
み込み専用の sysctl と調整変数です。
CTLFLAG_WR これは、書き込み可能な sysctl です。
CTLFLAG_RW この sysctl は、読み込み可能で書き込み可能です。
CTLFLAG_RWTUN これは、読み込み可能または書き込み可能な sysctl でモ
ジュールがロードされるか、またはシステムのブートの間に初
期にシステム環境からいったん取って来られることを試みる調
整変数です。
CTLFLAG_NOFETCH ノードが CTLFLAG_[XX]TUN を使用する調整変数としてマーク
される場合に、このフラグは、システム環境から初期値を取っ
て来ることを防ぎます。一般的に、このフラグは、共通のドラ
イバとモジュールによってではなく、たいへん早く低レベルの
システムのセットアップのコードのためにのみ使用されるべき
です。
CTLFLAG_MPSAFE この sysctl(9) ハンドラは、MP セーフです。このハンドラへ
の呼び出しのまわりの Giant をつかみません。これは、
SYSCTL_PROC() エントリのためにのみ使用されるベきです。
さらに、次のオプションのフラグのいずれかも、指定されます:
CTLFLAG_ANYBODY あらゆるユーザまたはプロセスは、この sysctl に書き込むこ
とができます。
CTLFLAG_CAPRD ケーパビリティモードのプロセスは、この sysctl から読み込
むことができます。
CTLFLAG_CAPWR ケーパビリティモードのプロセスは、この sysctl に書き込む
ことができます。
CTLFLAG_SECURE プロセスの有効なセキュリティレベル (securelevel) が <= 0
である場合のみ、この sysctl を書き込むことができます。
CTLFLAG_PRISON jail(2) のプロセスによって、この sysctl を書き込むことが
できます。
CTLFLAG_SKIP sysctl 名前空間を繰り返すとき、この sysctl をリストしま
せん。
CTLFLAG_TUN また、システム調整変数がこの変数のために存在するアドバイ
ザリ (advisory) フラグ。初期の sysctl 値は、モジュールの
ロードまたはシステムのブートの間に初期にシステム環境から
いったん取って来ることを試みられます。
CTLFLAG_DYN 動的に作成された OID は、自動的に、このフラグの設定を取
得します。
CTLFLAG_VNET OID は、VIMAGE 有効にされた変数を参照します。
使用例
新しいノードによって使用される security sysctl ツリーを宣言するための
SYSCTL_DECL() の使用の例:
SYSCTL_DECL(_security);
整数、不透明、文字列と手続き sysctl の例は、次の通りです:
/*
* 定数整数値の例. 制御フラグは, CTLFLAG_RD で, 可変ポインタは,
* SYSCTL_NULL_INT_PTR で, そして, 値は, 宣言されることに注意
* してください.
*/
SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, SYSCTL_NULL_INT_PTR,
sizeof(struct bio), "sizeof(struct bio)");
/*
* 変数整数値の例, 制御フラグは, CTLFLAG_RW, 可変ポインタは,
* 設定され, そして, 値は, 0 であることに注意してくだい.
*/
static int doingcache = 1; /* 1 => キャッシュを有効
にする */
SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0,
"Enable name cache");
/*
* 可変文字列値の例, 制御フラグは, CTLFLAG_RW, 可変ポインタと文字列
* サイズが設定されることに注意してください, 新しい sysctl と違って,
* このより古い sysctl は, 静的な OID 番号を使用します.
*/
char kernelname[MAXPATHLEN] = "/kernel"; /* XXX bloat */
SYSCTL_STRING(_kern, KERN_BOOTFILE, bootfile, CTLFLAG_RW,
kernelname, sizeof(kernelname), "Name of kernel file booted");
/*
* sysctl によってエクスポートされた不透明なデータタイプの例.
* 可変ポインタとサイズは, sysctl(8) のための書式化文字列と
* 同様に提供されることに注意してください.
*/
static l_fp pps_freq; /* スケーリングされた周波数オフセット
(ns/s) */
SYSCTL_OPAQUE(_kern_ntp_pll, OID_AUTO, pps_freq, CTLFLAG_RD,
&pps_freq, sizeof(pps_freq), "I", "");
/*
* sysctl のエクスポートされた文字列情報に基づく手続きの例.
* データタイプが宣言され, NULL の可変ポインタと 0 サイズ,
* 関数ポインタと sysctl(8) のための書式化文字列であることに
* 注意してください.
*/
SYSCTL_PROC(_kern_timecounter, OID_AUTO, hardware, CTLTYPE_STRING |
CTLFLAG_RW, NULL, 0, sysctl_kern_timecounter_hardware, "A",
"");
下記は、新しいトップレベルのカテゴリを作成する方法、と既存の静的なノード
への別のサブツリーを取り付ける方法の例です。この例は、それらが後で解放す
る必要があるように、すべての中間の OID のつまらない管理の結果となる、コン
テキストを使用しません。
#include <sys/sysctl.h>
...
/*
* 後でそれらを解放することができるように, 新しく作成された
* サブツリーへのポインタを保存する必要はありません:
*/
static struct sysctl_oid *root1;
static struct sysctl_oid *root2;
static struct sysctl_oid *oidp;
static int a_int;
static char *string = "dynamic sysctl";
...
root1 = SYSCTL_ADD_ROOT_NODE(NULL,
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");
この例は、次のサブツリーを作成します:
debug.newtree.newstring
newtree.newint
いったん、それらがもはや必要でなければ、すべての OID を解放するために注意
するべきです!
SYSCTL の名前付け
sysctl 名を追加するか、変更するか、または削除するとき、これらのインタ
フェースがユーザ、ライブラリ、アプリケーション、または (発行された本のよ
うな) 文書によって使用され、暗黙のうちに発行されたアプリケーションインタ
フェースであることを承知していることは重要です。他のアプリケーションイン
タフェースのように、既存のアプリケーションを壊さずに、将来依存するかもし
れないインタフェースの名前を変更するか、または削除する必要性を避けるため
に新しい名前空間の今後の使用について考えることに注意しなければなりませ
ん。
新しい sysctl のために選ばれたセマンティックは、できるだけ明確であるべき
で、sysctl の名前は、密接にそのセマンティック (意味論) を反映しなければな
りません。したがって、sysctl 名は、かなり検討する価値があります。それは、
短くて、それでもやはり sysctl 意味を代表しているべきです。名前がいくつか
の単語から成るなら、それらは、compute_summary_at_mount のように下線文字に
よって区切られるべきです。下線文字は、bootfile のように、それぞれ 4 文字
より長くない、名前が 2 つ以上でない単語から成る場合にだけ、省略されます。
ブール値の sysctl について、負の論理は、完全に避けられるべきです。すなわ
ち、no_foobar または foobar_disable のような名前を使用しません。それら
は、混乱させて、設定エラーを導きます。代わりに正の論理を使用します:
foobar, foobar_enable。
頼りににされるべきでない一時的な sysctl ノードの OID は、その名前を下線文
字で先導するように指定されなければなりません。例えば: _dirty_hack。
関連項目
sysctl(3), sysctl(8), device_get_sysctl(9), sysctl_add_oid(9),
sysctl_ctx_free(9), sysctl_ctx_init(9), sysctl_remove_oid(9)
歴史
sysctl(8) ユーティリティは、4.4BSD ではじめて登場しました。
作者
最初の BSD にある sysctl の実装は、MIB ノードの名前検索、名前空間の繰り返
し、と動的な追加のサポートを追加するために Poul-Henning Kamp によって広範
囲にわたって書き直されました。
このマニュアルページは、Robert N. M. Watson によって書かれました。
セキュリティの考察
新しい sysctl を作成するとき、作成されるモニタまたは管理インタフェースの
セキュリティ関係に慎重な注意が向けらるべきです。カーネルに存在するほとん
どの sysctl は、スーパユーザによってのみ、読み込み専用か、または書き込み
可能です。システムデータ構造と操作、特に手続きを使用して実装されたもの
で、広範囲の情報をエクスポートする sysctl は、他のプロセス、ネットワーク
接続などに関する情報の望まれない公開を制限するためのアクセスコントロール
を実装したいでしょう。
次のトップレベルの sysctl の名前空間は、次のように共通に使用されます:
compat 互換性の層 (レイヤ) 情報。
debug デバッグ情報。debug の下に存在する様々な名前空間。
hw ハードウェアとデバイスドライバ情報。
kern カーネルの振る舞いのチューニング。一般的に、より特有の名前空
間を支持して推奨されません。
machdep マシン依存の設定パラメータ。
net ネットワークサブシステム。様々なプロトコルには、net の下に名
前空間があります。
regression 復帰テストの設定と情報。
security セキュリティとセキュリティポリシの設定と情報。
sysctl sysctl の実装のために予約された名前空間。
user ユーザアプリケーションの振る舞いに関係する設定。一般的に、
カーネル sysctl を使用するアプリケーションを設定することはお
勧めできません。
vfs 仮想ファイルシステムの設定と情報。
vm 仮想メモリサブシステムの設定と情報。
FreeBSD 13.2 September 1, 2020 FreeBSD 13.2