名称

uni_msg_len, uni_msg_space, uni_msg_leading, uni_msg_size, uni_msg_ensure, uni_msg_append, uni_msg_extend, uni_msg_alloc, uni_msg_build, uni_msg_destroy, uni_msg_strip32, uni_msg_get32, uni_msg_append32, uni_msg_append8, uni_msg_trail32, uni_msg_dup — ATM シグナルライブラリ - メッセージバッファ

ライブラリ

Begemot ATM シグナルライブラリ (libunimsg, -lunimsg)

書式

#include < uni4/unimsg.h>

size_t
uni_msg_len( const struct uni_msg *msg);

size_t
uni_msg_space( const struct uni_msg *msg);

size_t
uni_msg_leading( const struct uni_msg *msg);

size_t
uni_msg_size( const struct uni_msg *msg);

int
uni_msg_ensure( struct uni_msg *msg, size_t bytes);

int
uni_msg_append( struct uni_msg *msg, void *buf, size_t buflen);

int
uni_msg_extend( struct uni_msg *msg, size_t bytes);

struct uni_msg *
uni_msg_alloc( size_t space);

struct uni_msg *
uni_msg_build( void *buf, ...);

void
uni_msg_destroy( struct uni_msg *msg);

u_int
uni_msg_strip32( struct uni_msg *msg);

u_int
uni_msg_get32( struct uni_msg *msg);

int
uni_msg_append32( struct uni_msg *msg, u_int value);

int
uni_msg_append8( struct uni_msg *msg, u_int byte);

u_int
uni_msg_trail32( const struct uni_msg *msg, int n);

struct uni_msg *
uni_msg_dup( const struct uni_msg *msg);

解説

これらの関数は、可変サイズのメッセージを操作するために使用されます。それらは、BSD mbufs と SysV ストリームバッファから発想を得ていますが、一般的にシグナルが少ない帯域幅のタスクであるので、いくらか簡素化されています。すべての関数は次の uni_msg データ構造体で操作します:

struct uni_msg { 
 u_char *b_wptr; /* 後尾ポインタ */ 
 u_char *b_rptr; /* 先頭ポインタ */ 
 u_char *b_buf;  /* データバッファ */ 
 u_char *b_lim;  /* データバッファの終り */ 
};

フィールド b_buf は実際のメッセージを格納するために使用されるメモリブロックを指し、フィールド b_lim はそのバッファの最後のバイトを指します。このバッファは構造体自体から分離して割り付けられ、const でない struct uni_msg の引数で上記の関数のいずれかのユーザ呼び出しはバッファが再割り付けられて、したがって、これらの関数への呼び出しにわたってバッファ中にポインタを保持しないと予想するべきです。ポインタ b_rptr はメッセージで最初に使われるバイトを指し、 b_wptr はすべての使用されたバイトの最後の未使用のバイトを指します。メッセージが空であるなら、両方のポインタは割り付けられたバッファ中のどこかの同じ場所を指します。

様々なサイズと長さを返すいくつかの関数とマクロがあります。マクロ uni_msg_len() はメッセージの実際のサイズ (使用されたバイト数) を返します。マクロ uni_msg_space() は使用された空間の後ろの未使用で残されたバイト数を返します。マクロ uni_msg_leading() は使用された空間の前の未使用のバイト数を返し、マクロ uni_msg_size() はメッセージの最大サイズ (それは割り付けられたバッファのサイズです) を返します。

2 つの関数は新しいメッセージを作成するのに使用されます: 関数 uni_msg_alloc() は、メッセージ構造体と少なくとも space バイトを保持するバッファを割り付けます (つまり、それは、2 バイト以上を割り付けます)。割り付けが失敗するなら、NULL を返します。ポインタは、バッファに先導するスペースがないようにセットアップされます。関数 uni_msg_build() は可変個のバッファからの新しいメッセージを構築します。引数は、NULL ポインタで終了する、バッファへの void * ポインタと size_t バッファサイズの複数の組です。関数は、メッセージサイズ、割り付けられたメッセージ、とメッセージにコピーしたすべてのバッファの合計を計算します。メッセージは、先導するスペースがないように構築されます。割り付けが失敗するなら、NULL を返します。

関数 uni_msg_destroy() はメッセージとメッセージ自体で指されるバッファの割り付けを解放します。それは、NULL バッファでメッセージを渡すために保存されますが、NULL メッセージではありません。

関数 uni_msg_dup() は正確に同じ先導するスペースでメッセージのコピーを返します。

多くの関数が、バイトを既存のメッセージに追加するために使用されます。関数 uni_msg_extend() は、終わりに少なくとも bytes の追加バイトの空間を持つようにメッセージバッファを拡張します。先導するスペースは変化しません。この関数はメッセージバッファを再割り付けするかもしれません。関数は成功すれば 0 を返し、再割り付けが失敗するなら ENOMEM を返します。この場合メッセージバッファは変化しません。マクロ uni_msg_ensure() は、メッセージに追加 bytes バイトの空間があるかどうかチェックします。そうでなければ、メッセージバッファをより大きくするために uni_msg_extend() を呼び出します。マクロは成功すれば 0 を返し、十分なスペースがなくて、再割り付けが失敗するなら ENOMEM を返します。この場合メッセージバッファは変化しません。関数 uni_msg_append() は buf によって指されたバッファからメッセージに buflen バイトを追加します。関数 uni_msg_append8() はメッセージに 1 バイト追加し、関数 uni_msg_append32() はネットワークバイト順で 32 ビットの値をメッセージに追加します ( b_wptr は、整列される必要はありません)。すべての 3 つの関数は、バッファの内容をメッセージに適合することを確実にするために uni_msg_ensure() を呼び出します。それらは成功すれば 0 を返し、バッファが小さ過ぎて再割り付けが失敗するなら ENOMEM を返します。この場合メッセージバッファは変化しません。

多くの関数はメッセージの部品を検索するために使用することができます。関数 uni_msg_strip32() は、32 ビットの整数がネットワークバイト順であると仮定してメッセージの最後の 4 バイトを返します。それは、メッセージからこれらの 4 バイト削除するように b_wptr を調整します。 b_wptr は整列される必要はありません。関数 uni_msg_get32() は、32 ビットの整数がネットワークバイト順であると仮定してメッセージの最初の 4 バイトを返します。それは、メッセージからこれらの 4 バイト削除するように b_rptr を調整します。 b_rptr は整列される必要はありません。関数 uni_msg_trail32() はバッファの終りから数えて n 番目の 32 ビットの整数をバッファから返します。整数はネットワークバイト順であると仮定されます。 n の値が -1 であるなら、バッファの最後の 4 バイトを返し、値が -2 であるなら、最後の 4 バイトの直前の 4 バイトを返します、等々。すべての 3 つの関数は、メッセージが十分大きいことをチェックしません。

関連項目

libunimsg(3), mbuf(9)

作者

Hartmut Brandt <harti@FreeBSD.org>