EN JA
SYSCTL(9)
SYSCTL(9) FreeBSD Kernel Developer's Manual SYSCTL(9)

名称

SYSCTL_DECL, SYSCTL_INT, SYSCTL_LONG, SYSCTL_NODE, SYSCTL_OPAQUE, SYSCTL_PROC, SYSCTL_QUAD, SYSCTL_STRING, SYSCTL_STRUCT, SYSCTL_UINT, SYSCTL_ULONG, SYSCTL_UQUAD静的な sysctl 宣言関数

書式

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

SYSCTL_DECL( name);

SYSCTL_INT( parent, nbr, name, access, ptr, val, descr);

SYSCTL_LONG( parent, nbr, name, access, ptr, val, descr);

SYSCTL_NODE( parent, nbr, name, access, handler, descr);

SYSCTL_OPAQUE( parent, nbr, name, access, ptr, len, fmt, descr);

SYSCTL_PROC( parent, nbr, name, access, ptr, arg, handler, fmt, descr);

SYSCTL_QUAD( parent, nbr, name, access, ptr, val, descr);

SYSCTL_STRING( parent, nbr, name, access, arg, len, descr);

SYSCTL_STRUCT( parent, nbr, name, access, ptr, type, descr);

SYSCTL_UINT( parent, nbr, name, access, ptr, val, descr);

SYSCTL_ULONG( parent, nbr, name, access, ptr, val, descr);

SYSCTL_UQUAD( parent, nbr, name, access, ptr, val, descr);

解説

SYSCTL カーネルインタフェースによって、コードは、宣言を含むカーネルモジュールが初期化されるとき、初期化される sysctl(8) MIB エントリを静的に宣言することができます。モジュールがアンロードされるとき、sysctl は、自動的に破壊されます。

sysctl ノードは、指定された C データ構造によって表現されているすべての静的なノードの状態で、階層的なツリーで作成されます。ツリーにおいて既存のノードの下に新しいノードを作成するためには、必要な親ノードを表現する構造は、 SYSCTL_DECL() を使用して現在のコンテキストで、宣言されなければなりません。

新しいノードは、 SYSCTL_INT(), SYSCTL_LONG(), SYSCTL_NODE(), SYSCTL_OPAQUE(), SYSCTL_PROC(), SYSCTL_QUAD(), SYSCTL_STRING(), SYSCTL_STRUCT(), SYSCTL_UINT(), SYSCTL_ULONG() と SYSCTL_UQUAD() の 1 つを使用して宣言されます。各マクロは、 SYSCTL_DECL()、 OID 番号、通常 OID_AUTO、ノード名、制御とアクセスフラグの 1 つの組、と記述を使用して、宣言されるような、親の名前を受け付けます。マクロによって、 MIB エントリをサポートする変数へのポインタ、サイズ、値、と MIB エントリを実装する関数ポインタも、また存在しています。

上記のマクロの大部分には、アクセスフラグの一部としてタイプを宣言することは、必要ありません—しかしながら、関数によって実装された sysctl を宣言するとき、アクセスマスクのタイプを含むことが必要です:

CTLTYPE_NODE
これは、他のノードのための親となるノードです。
CTLTYPE_INT
これは、符号付き整数です。
CTLTYPE_STRING
これは、文字配列に格納されたヌル文字で終了する文字列です。
CTLTYPE_S64
これは、64 ビットの符号付き整数です。
CTLTYPE_OPAQUE
これは、不透明な (サイズおよび形がわからない) データ構造です。
CTLTYPE_STRUCT
CTLTYPE_OPAQUE の別名。
CTLTYPE_UINT
これは、符号なし整数です。
CTLTYPE_LONG
これは、符号付き long です。
CTLTYPE_ULONG
これは、符号なし long です。
CTLTYPE_U64
これは、64 ビット符号なし整数です。

新しいノード宣言以外のすべての sysctl タイプは、sysctl の読み込み書き込み処理を示すように設定される次のフラグの 1 つを必要とします:

CTLFLAG_RD
これは、読み込み専用 sysctl です。
CTLFLAG_RDTUN
これは、システムの調整変数によって設定することができる読み込み専用の sysctl です。
CTLFLAG_WR
これは、書き込み可能な sysctl です。
CTLFLAG_RW
この sysctl は、読み込み可能で書き込み可能です。
CTLFLAG_RWTUN
この sysctl は、読み込み可能で書き込み可能で、システム調整変数によって設定することもできます。

さらに、次のオプションのフラグのいずれかも、指定されます:

CTLFLAG_ANYBODY
任意のユーザまたはプロセスは、この sysctl に書き込むことができます。
CTLFLAG_SECURE
プロセスの有効なセキュリティレベル (securelevel) が≤ 0 である場合のみ、この sysctl を書き込むことができます。
CTLFLAG_PRISON
jail(2) のプロセスによって、この sysctl を書き込むことができます。
CTLFLAG_SKIP
sysctl 名前空間を繰り返すとき、この sysctl をリストしません。
CTLFLAG_TUN
また、システム調整変数がこの変数のために存在するアドバイザリ (advisory) フラグ。

新しい sysctl を作成するとき、作成されるモニタまたは管理インタフェースのセキュリティ関係に慎重な注意が向けらるべきです。カーネルに存在するほとんどの sysctl は、スーパユーザによってのみ、読み込み専用か、または書き込み可能です。システムデータ構造と操作、特に手続きを使用して実装されたもの、において広範囲の情報をエクスポートする sysctl は、他のプロセス、ネットワーク接続などに関する情報の望まれない露出を制限するためのアクセスコントロールを実装したいでしょう。

次のトップレベルの sysctl 名前空間は、次のように一般的に使用されます:

compat
互換性の層 (レイヤ) 情報。
debug
デバッグ情報。 debug の下に様々な名前空間が存在しています。
hw
ハードウェアとデバイスドライバ情報。
kern
カーネルの振る舞いのチューニング。一般的に、より特定の名前空間を支持して推奨されません。
machdep
マシン依存の設定パラメータ。
net
ネットワークサブシステム。様々なプロトコルには、 net の下に名前空間があります。
regression
復帰テストの設定と情報。
security
セキュリティとセキュリティポリシの設定と情報。
sysctl
sysctl の実装のために予約された名前空間。
user
ユーザアプリケーションの振る舞いに関係する設定。一般的に、カーネル sysctls を使用してアプリケーションを設定することはお勧めできません。
vfs
仮想ファイルシステムの設定と情報。
vm
仮想メモリサブシステムの設定と情報。

使用例

新しいノードによって使用される security sysctl ツリーを宣言するための SYSCTL_DECL() の使用の例:

SYSCTL_DECL(_security);

整数、不透明、文字列と手続き sysctl の例は、次の通りです:

/* 
 * 定数整数値の例。制御フラグは CTLFLAG_RD、可変ポインタは NULL、 
 * そして値は宣言されることに注意してください。 
 */ 
SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, NULL, 
    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", 
    "");

SYSCTL 名前付け

sysctl 名を追加するか、変更するか、または削除するとき、これらのインタフェースがユーザ、ライブラリ、アプリケーション、または (発行された本のような) 文書によって使用され、暗黙のうちに発行されたアプリケーションインタフェースであることを承知していることは重要です。他のアプリケーションインタフェースのように、既存のアプリケーションを壊さずに、将来依存するかもしれないインタフェースの名前を変更するか、または取り除く必要性を避けるために新しい名前空間の今後の使用について考えることに注意しなければなりません。

新しい sysctl に選ばれたセマンティックは、できるだけ明確であるべきで、 sysctl の名前は、密接にそのセマンティック (意味論) を反映しなければなりません。したがって、sysctl 名は、かなり多く検討する価値があります。それは、短くて、さらに sysctl 意味を代表しているべきです。名前がいくつかの単語から成るなら、それらは、 compute_summary_at_mount のように下線文字によって分離されるべきです。下線文字は、 bootfile のように、それぞれ 4 文字より長くない、名前が 2 つ以上でない単語から成る場合にだけ、省略されます。ブール値 sysctl について、負の論理は、完全に避けられるべきです。すなわち、 no_foobar または foobar_disable のような名前を使用しません。それらは、混乱させて、設定エラーを導きます。代わりに正の論理を使用します: foobar, foobar_enable

頼りににされるべきでない一時的な sysctl ノードは、その名前を下線文字で先導するように指定されなければなりません。例えば: _dirty_hack

歴史

sysctl(8) ユーティリティは、 4.4BSD ではじめて登場しました。

作者

元々 BSD にある sysctl の実装は、MIB ノードの名前検索、名前空間の繰り返し、および動的な追加のサポートを追加するために Poul-Henning Kamp によって広範囲にわたって書き直されました。

このマニュアルページは、 Robert N. M. Watson によって書かれました。

September 12, 2013 FreeBSD