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(3), sysctl(8), sysctl_add_oid(9), sysctl_ctx_free(9), sysctl_ctx_init(9), sysctl_remove_oid(9)作者
元々 BSD にある sysctl の実装は、MIB ノードの名前検索、名前空間の繰り返し、および動的な追加のサポートを追加するために によって広範囲にわたって書き直されました。このマニュアルページは、
によって書かれました。September 12, 2013 | FreeBSD |