Solaris Bandwidth Manager 1.6 の開発

第 3 章 C Statistics API の使用

C Statistics API は、Solaris Bandwidth Manager のローカル設定情報、およびこの設定によって定義されるネットワークトラフィックのクラス統計を取得するために使用されます。

C Statistics API は、次のオペレーションに使用する関数を提供します。

デバイスの処理
インタフェースの処理
クラスの処理
統計情報の処理
イベントの処理
エラーの処理
メモリーの処理

共有ライブラリとのリンク

C Statistics API は、次の共有ライブラリとして実装されています。

/opt/SUNWconn/lib/libba_stat.so.1

作成するソースコードには、次の行を含める必要があります。

#include <netinet/ba_stat.h>

アプリケーションをコンパイルするには、次のスイッチを指定して cc(1B) コマンドを実行します。

-I/opt/SUNWconn/include

共有ライブラリをアプリケーションにリンクするには、次のスイッチを指定して ld(1) コマンドを実行します。

-L/opt/SUNWconn/lib -R/opt/SUNWconn/lib -lba_stat

例:

$ ld -o myexe myobj -L/opt/SUNWconn/lib -R/opt/SUNWconn/lib -lba_stat

Makefile を使用してアプリケーションをリンクする方法については、コード例の Makefile /opt/SUNWconn/ba/examples/Makefile を参照してください。

マルチスレッド化

C Statistics API は、マルチスレッドモードで安全に使用できます。ただし、次の制限があります。

すべてのスレッドで同じファイル記述子が共有されます。したがって、すべてのスレッドが同じイベントマスクを共有します。つまり、2 つのスレッドが ba_get_next_event() を同時に呼び出す場合、どのスレッドがイベント通知を受けるか制御できません。
thr_sigsetmak() または pthread_sigmak() ライブラリ関数を使用してシグナルマスクが正しく定義されていないかぎり、ba_enable_signal() 関数をマルチスレッドモードで使用しないでください。
各スレッドには変数 ba_errno が 1 つ存在します。したがって、API を呼び出したスレッド内でこの変数の値を常にチェックする必要があります。

デバイスの処理

カーネルモジュールは、ユーザープロセスにはストリームドライバ (/dev/ipqos) として見え、IP スタックにはストリームモジュール (ipqos) として見えます。/dev/ipqos ファイルは、C Statistics API を通した最初の関数呼び出しによって自動的に開かれます。このファイルのファイル記述子は、ipqos モジュールへのアクセスに使用されます。

C Statistics API は、/dev/ipqos ファイルを直接制御する次の 2 つの関数を提供しています。

ba_open() は、/dev/ipqos ファイルを開き、ファイル記述子を返します。
ba_close() は、/dev/ipqos ファイルを閉じます。

インタフェースの処理

C Statistics API は、インタフェースを処理する次の関数を提供しています。

ba_encode_ifname() は、インタフェースの物理的な名前と通信方向から Solaris Bandwidth Manager のインタフェース名を生成します。
ba_decode_ifname() は、Solaris Bandwidth Manager のインタフェース名からインタフェースの物理的な名前と通信方向を取得します。
ba_get_num_interfaces() は、Solaris Bandwidth Manager によって管理されているインタフェース数を返します。
ba_list_interfaces() は、Solaris Bandwidth Manager によって管理されているインタフェース名のリストを返します。
ba_get_interface_config() は、指定されたインタフェースの設定情報を返します。
ba_list_interface_config() は、Solaris Bandwidth Manager によって管理されているすべてのインタフェースの設定情報を返します。

クラスの処理

C Statistics API は、クラスを処理する次の関数を提供します。

ba_get_num_classes() は、指定されたインタフェースに定義されているクラス数を返します。
ba_list_class_names() は、指定されたインタフェースに定義されているクラスのリストをそれらの親クラスと共に返します。
ba_list_classes() は、指定されたインスタンスの親クラスと子クラスのリストを返します。

統計情報の処理

C Statistics API は、統計情報を処理する次の関数を提供しています。

ba_get_class_stats() は、指定されたインタフェースのネットワークトラフィックについて、指定されたクラスの統計情報を返します。返される情報は次のとおりです。
- 送信されたパケット数
- 送信されたバイト数
- 帯域幅の借用が試みられた回数
- ドロップされたパケット数
- ドロップされたバイト数
ba_reset_class_stats() は、指定されたクラスとそのすべての子の統計情報をリセットするために使用します。ba_reset_class_stats() を呼び出すプロセスは特権化されていなければなりません。
ba_get_flow_stats() は、指定されたクラスのフローレベルの統計情報を返します。

イベントの処理

C Statistics API を使用して ipqos モジュールレベルで特定のイベントの発生を検出し、発生したイベントについての情報を返すことができます。イベントの発生は、次の 3 つの方法で検出できます。

poll(2) または select(3C) を使用してファイル記述子を調べる
ユーザープロセスにシグナルを直接送信するデバイスの機能を有効にする
関数 ba_get_next_event() を呼び出して次のイベントを検査する

注 -

イベントはバッファーに入るため、poll(2) または select(3C) を使用する場合は、非ブロックモードで ba_get_next_event() を繰り返し呼び出し、未処理のイベントが存在しないかを確認する必要があります。これは、次の poll(2) を正しく動作させるためです。

イベントの発生を (たとえば poll(2) を使用して) 検出した時点で、ba_get_next_event() 関数を呼び出してそのイベントについての情報を取り出します。

C Statistics API は、イベントを処理する次の関数を提供しています。

ba_set_event_mask() は、表 3-1 に挙げられたイベントのどれを報告するかを示すイベントマスクを設定します。
ba_get_event_mask() は、現在のイベントマスクを取得します。
ba_get_next_event() は、発生した最新のイベントについての情報を取得します。
ba_enable_signal() は、シグナル機構を有効にして、ipqos モジュールがユーザープロセスにシグナルを直接送信できるようにします。
ba_disable_signal() は、シグナル機構を無効にします。

表 3-1 は、ユーザープロセスに報告されるイベントタイプを示しています。

表 3-1 イベントタイプ


イベントタイプ	説明
`BA_EVENT_CONFIG_STARTING`	Solaris Bandwidth Manager のポリシーエージェントが新しい設定の読み取りを開始する時に生成される
`BA_EVENT_CONFIG_ENDING`	Solaris Bandwidth Manager のポリシーエージェントが新しい設定の読み取りを終了する時に生成される
`BA_EVENT_DAEMON_ENDING`	Solaris Bandwidth Manager のポリシーエージェントが終了する場合または強制的に終了させられる場合に生成される
`BA_EVENT_FLOW_ACCOUNTING`	フローがタイムアウトしたか、フローの TOS フィールドが変化した場合に生成される
`BA_EVENT_STATS_RESET`	クラスがリセットまたは削除された場合に生成される

バッファーが保持できるイベント数を制限するには、/etc/default/ba_info ファイル内の環境変数 BA_EVENTBUFSIZE を編集します。この値を 0 に設定すると、イベントを無制限にバッファリングできます。ただしこの場合、すべてのイベントを取得しないと、カーネルメモリーが使い果たされることに注意してください。

エラーの処理

C Statistics API 呼び出しの際にエラーが発生すると、その関数は値 -1 を返し、変数 ba_errno にそのエラー状況を示すエラーコードが設定されます。ba_errno のエラーコードについては、表 4-2 を参照してください。

C Statistics API は、エラーを処理する次の関数を提供します。

ba_strerror() は、ba_errno に入っているエラーコードに関連付けられたエラーメッセージを返します。この関数は strerror(3C) に同等です。

ba_perror() は、標準出力にエラーコードと、ba_strerror() が返すエラーメッセージを出力します。この関数は perror(3C) に同等です。

注 -

関数呼び出しが適切に行われた場合、Solaris Bandwidth Manager は ba_errno をリセットしません。つまり、ba_errno の値は、関数がエラー状況を示す -1 を返す場合だけ有効です。

メモリーの処理

C Statistics API では、配列にメモリーを割り当てるために 2 つのメソッドを使用します。

ba_list_interfaces() と ba_list_class_names() 関数を使用する場合は、必ずバッファーにクラス数に応じた十分なメモリーを割り当てる必要があります。ba_list_interfaces() の使用例を次に示します。

nintface = ba_get_num_interfaces();
if (nintface > 0) {
    interfaces = (ba_name_t *) calloc(nintface, sizeof ba_name_t);
    if (ba_list_interfaces(interfaces) != -1) {
    /* process interfaces .. */
} else {
    /* error handling */
}
    free(interfaces);
}

ba_list_interface_config()、ba_list_classes()、および ba_get_flow_stats() 関数を使用する場合、メモリーは自動的に割り当てられます。ただし、あとで ba_free() 関数を呼び出して、このメモリーを解放する必要があります。

コード例

Solaris Bandwidth Manager には、次のコード例が含まれています。

ba_classes.c は、指定されたインタフェースに設定されているクラスのリストを返します。このプログラムでは、クラス処理関数の使用例を示します。
ba_events.c は、プログラムが CTRL-C キーで停止されるまで、イベントの発生時にイベント情報を出力します。このプログラムでは、イベント処理関数の使用例を示します。
ba_get_stats.c は、指定されたクラスの統計情報を返します。このプログラムでは、ba_get_class_stats() 関数の使用例を示します。
ba_interfaces.c は、設定されたインタフェースのリストを返します。このプログラムでは、インタフェース処理関数の使用例を示します。
ba_reset_stats.c は、指定されたクラスの統計情報をリセットします。このプログラムでは、ba_reset_class_stats() 関数の使用例を示します。
ba_signals.c は、プログラムが CTRL-C キーで停止されるまで、イベントの発生時にイベント情報を出力します。このプログラムでは、イベント処理関数の使用例とシグナル機構を示します。
ba_get_flows.c は、特定のクラスに関連付けられたすべてのフローについての情報を出力します。

これらのコード例は、/opt/SUNWconn/ba/examples ディレクトリに入っています。このディレクトリには、これらの例の Makefile である Makefile も入っています。