名称

NgMkSockNode, NgNameNode, NgSendMsg, NgSendAsciiMsg, NgSendMsgReply, NgRecvMsg, NgAllocRecvMsg, NgRecvAsciiMsg, NgAllocRecvAsciiMsg, NgSendData, NgRecvData, NgAllocRecvData, NgSetDebug, NgSetErrLog — netgraph (ネットグラフ) ユーザライブラリ

ライブラリ

Netgraph User Library (libnetgraph, -lnetgraph)

書式

#include < netgraph.h>

int
NgMkSockNode( const char *name, int *csp, int *dsp);

int
NgNameNode( int cs, const char *path, const char *fmt, ...);

int
NgSendMsg( int cs, const char *path, int cookie, int cmd, const void *arg, size_t arglen);

int
NgSendAsciiMsg( int cs, const char *path, const char *fmt, ...);

int
NgSendMsgReply( int cs, const char *path, struct ng_mesg *msg, const void *arg, size_t arglen);

int
NgRecvMsg( int cs, struct ng_mesg *rep, size_t replen, char *path);

int
NgAllocRecvMsg( int cs, struct ng_mesg **rep, char *path);

int
NgRecvAsciiMsg( int cs, struct ng_mesg *rep, size_t replen, char *path);

int
NgAllocRecvAsciiMsg( int cs, struct ng_mesg **rep, char *path);

int
NgSendData( int ds, const char *hook, const u_char *buf, size_t len);

int
NgRecvData( int ds, u_char *buf, size_t len, char *hook);

int
NgAllocRecvData( int ds, u_char **buf, char *hook);

int
NgSetDebug( int level);

void
NgSetErrLog( void (*log)(const char *fmt, ...), void (*logx)(const char *fmt, ...));

解説

これらの関数は、netgraph socket ノードタイプ ( ng_socket(4) を参照) の利用によるカーネル netgraph(4) グラフベースネットワーキングシステムでのユーザモードプログラム関与を手助けします。

NgMkSockNode() 関数は関連するコントロールおよびデータソケットで新しい socket タイプ netgraph ノードを作成するために最初に呼ばれるべきです。 name が NULL でない場合、ノードはそれにグローバル名を割り当てるでしょう。 csp と dsp 引数は、ノードに関連した、新しくオープンされたコントロールおよびデータソケットに設定されるでしょう。 1 つのソケットだけが望まれる場合、 csp あるいは dsp のいずれかは、 NULL かもしれません。それがまだロードされない場合、 NgMkSockNode() 関数は、 socket ノードタイプ KLD をロードします。

NgNameNode() 関数は、 path によってアドレス付けされたノードにグローバル名を割り当てます。

NgSendMsg() 関数は、コントロールソケット cs に関連した socket ノードから path によってアドレス付けされたノードにバイナリコントロールメッセージを送ります。 cookie は、特定のコマンドを示す cmd を解釈する方法を示します。余分な引数データ (もしあれば) は、 arg と arglen によって指定されます。 cookie, cmd および引数データは、アドレス付けされているノードのタイプに対応するヘッダファイルによって定義されます。メッセージヘッダで使用するために選ばれたユニークな負でないトークン値が返されます。この値は応答を関連させるために通常使用されます。

以前に受信したコントロールメッセージに応答を送るために NgSendMsgReply() を使用します。オリジナルのメッセージヘッダは、 msg によって指されるべきです。

NgSendAsciiMsg() 関数は、 NgSendMsg() と同じ機能を実行するが、コントロールメッセージの ASCII 符号づけのサポートを加えます。 NgSendAsciiMsg() 関数はその入力を printf(3) 様式でフォーマットします、そして次に、結果の ASCII 文字列を NGM_ASCII2BINARY コントロールメッセージのノードに送ります。ノードは、ちょうど NgSendMsg() でのようにその後ノードに送り戻されるメッセージのバイナリバージョンを返します。 NgSendMsg() でのように、メッセージトークン値が返されます。 ASCII 変換がすべてのノードタイプによってサポートされないかもしれないことに注意してください。

NgRecvMsg() 関数は、コントロールソケット cs に関連したノードによって受信された次のコントロールメッセージを読み込みます。メッセージおよびどんな余分な引数データも replen バイトに入らなければなりません。 path が NULL でない場合、それは少なくとも NG_PATHSIZ バイトの、メッセージが受信されたノードへのパスで満たされる (またヌル文字で終了する) だろう、バッファを指さなければなりません。

コントロールメッセージの長さが返されます。 0 の返り値は、ソケットがクローズされていたことを示します。

NgAllocRecvMsg() 関数は、メッセージが切り詰められないことを保証するためにメッセージのためのバッファがダイナミックに割り付けられる以外は、 NgRecvMsg() のように正確に働きます。バッファのサイズはソケットの受信バッファサイズと等しい。呼び出し側は、それがもはや必要とされない時に、バッファを解放する責任があります。

NgRecvAsciiMsg() 関数は、メッセージが受け取られた後、もとの起点ノードに NGM_BINARY2ASCII リクエストを送ることにより、どんなバイナリ引数も ASCII に変換される以外は、 NgRecvMsg() のように正確に働きます。結果は、応答引数フィールドが引数 (また、応答ヘッダ引数の長さフィールドは調節されるでしょう) のヌル文字で終了した ASCII バージョンを含むことを除いて、 NgRecvMsg() と同じです。

NgAllocRecvAsciiMsg() 関数は、メッセージが切り詰められないことを保証するためにメッセージのためのバッファがダイナミックに割り付けられる以外は、 NgRecvAsciiMsg() のように正確に働きます。バッファのサイズはソケットの受信バッファサイズと等しい。呼び出し側は、それがもはや必要とされない時に、バッファを解放する責任があります。

NgSendData() 関数は、データソケット ds に対応するノードの指定されたフックにデータパケットを書き込みます。ノードは、そのフックによって他のあるノードに既に接続されなければなりません。

NgRecvData() 関数は、データソケット ds に対応するノードによって受信された次のデータパケットを ( len バイトまで) を読み込み、全パケットを保持するように十分に大きくなければならない buf にそれを格納します。 hook が NULL でない場合、それは少なくとも NG_HOOKSIZ バイトの、データが受信されたフックの名前で満たされる (またヌル文字で終了する) だろう、バッファを指さなければなりません。

パケットの長さが返されます。 0 の返り値は、ソケットがクローズされていたことを示します。

NgAllocRecvData() 関数は、データパケットが切り詰められないことを保証するためにデータパケットのためのバッファがダイナミックに割り付けられる以外は、 NgRecvData() のように正確に働きます。バッファのサイズはソケットの受信バッファサイズと等しい。呼び出し側は、それがもはや必要とされない時に、バッファを解放する責任があります。

NgSetDebug() および NgSetErrLog() 関数はデバッギングのために使用されます。 NgSetDebug() 関数はデバッグレベル (負でない場合) を設定し、古い設定を返します。より高いデバッグレベルはより多くの多弁の結果となります。デフォルトは、0 です。すべてのデバッグおよびエラーメッセージは、 NgSetErrLog() への最も最近の呼び出しで指定された関数によってログがとられます。デフォルトのログする関数は、 vwarn(3) および vwarnx(3) です。

デバッグレベル 3 で、ライブラリは、 ASCII フォーマットでのコントロールメッセージ引数を表示することを試みます。しかしながら、これは、デバッギングに干渉する送られている追加のメッセージに帰着します。同じ高いレベルでは、同じこれらの追加のメッセージは表示されるでしょう、など。

入って来るデータおよびコントロールメッセージそれぞれの存在を検知するためにデータおよびコントロールソケットで select(2) を使用することができることに注意してください。データとコントロールのパケットは常に書き込まれ、基本要素ごとに読み込まれます。つまり、in one whole piece (一つの中で、部分全体)。(訳: 意味不明)

ユーザモードプログラムは、このライブラリをリンクする -lnetgraph でリンクすべきです。

初期設定

利用者のカーネルで netgraph を利用可能にするためには、利用者のカーネルをカーネルコンフィギュレーションファイル中の options NETGRAPH でコンパイルしなければならないか、あるいは、 netgraph(4) と ng_socket(4) KLD モジュールは、 kldload(8) によってロードされなければならないかの、どちらかです。

戻り値

NgSetDebug() 関数は前のデバッグ設定を返します。

NgSetErrLog() 関数は、返り値を持っていません。

エラーがあった場合、他のすべての関数は、-1 を返し、それに応じて errno を設定します。

NgRecvMsg() または NgRecvData() からの 0 の返り値は、netgraph ソケットがクローズしていることを示します。

NgSendAsciiMsg() と NgRecvAsciiMsg() については、次の追加のエラーの可能性があります。

[ ENOSYS]

ノードタイプは、コントロールメッセージをコード化するか解読する方法を知りません。

[ ERANGE]

コード化されたあるいは解読された引数は、供給されたバッファには長すぎました。

[ ENOENT]

未知の構造体フィールドは、 ASCII コントロールメッセージで見られました。

[ EALREADY]

同じ構造体フィールドは、 ASCII コントロールメッセージの中で 2 度指定されました。

[ EINVAL]

ASCII コントロールメッセージ解析エラーあるいは不正な値です。

[ E2BIG]

ASCII コントロールメッセージ配列あるいは固定幅文字列バッファがオーバフロー。

関連項目

select(2), socket(2), warnx(3), kld(4), netgraph(4), ng_socket(4)

歴史

netgraph システムは、Whistle InterJet のためにカスタマイズされた FreeBSD 2.2 のバージョンで Whistle Communications 社で設計され最初に実装されました。

作者

Archie Cobbs <archie@FreeBSD.org>