sbuf_new(9)

sbuf_new, sbuf_clear, sbuf_setpos, sbuf_bcat, sbuf_bcopyin, sbuf_bcpy, sbuf_cat, sbuf_copyin, sbuf_cpy, sbuf_printf, sbuf_vprintf, sbuf_putc, sbuf_trim, sbuf_overflowed, sbuf_finish, sbuf_data, sbuf_len, sbuf_done, sbuf_delete − 安全な文字列フォーマット

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

struct sbuf *

sbuf_new(struct sbuf *s, char *buf, int length, int flags);

void

sbuf_clear(struct sbuf *s);

int

sbuf_setpos(struct sbuf *s, int pos);

int

sbuf_bcat(struct sbuf *s, const void *buf, size_t len);

int

sbuf_bcopyin(struct sbuf *s, const void *uaddr, size_t len);

int

sbuf_bcpy(struct sbuf *s, const void *buf, size_t len);

int

sbuf_cat(struct sbuf *s, const char *str);

int

sbuf_copyin(struct sbuf *s, const void *uaddr, size_t len);

int

sbuf_cpy(struct sbuf *s, const char *str);

int

sbuf_printf(struct sbuf *s, const char *fmt, ...);

int

sbuf_vprintf(struct sbuf *s, const char *fmt, va_list ap);

int

sbuf_putc(struct sbuf *s, int c);

int

sbuf_trim(struct sbuf *s);

int

sbuf_overflowed(struct sbuf *s);

void

sbuf_finish(struct sbuf *s);

char *

sbuf_data(struct sbuf *s);

int

sbuf_len(struct sbuf *s);

int

sbuf_done(struct sbuf *s);

void

sbuf_delete(struct sbuf *s);

解説

sbuf ファミリの関数は、カーネル空間内の境界のあるヌル終端文字列の、安全な 割り当て、構築、および解放を可能にします。これらの関数は、文字の配列の代 わりに、 <sys/sbuf.h> で定義される sbuf と呼ばれる構造体を操作します。

sbuf_new() 関数は最初の引数で指される sbuf を初期化します。そのポインタが NULL の場合には、 sbuf_new() は struct sbuf 構造体を malloc(9) を使用して 割り当てます。 buf 引数は実際に文字列が格納されるバッファへのポインタで、 NULL の場合には、 sbuf_new() は malloc(9) を使用してバッファを割り当てま す。 length は格納バッファの初期の大きさです。 4 番目の引数 flags は以下 のフラグから構成され得ます:

格納バッファは初期サイズで固定です。これを越えて sbuf を 拡張しようとすると、オーバフロー状態となります。

SBUF_AUTOEXTEND
これは、追加データの格納のために必要ならば、資源の許す限 りにおいて、格納バッファは拡張可能であることを示します。

buf が NULL でない場合には、少なくとも length 文字以上の配列を指さなけれ ばならないことに注意してください。 sbuf によって使用されている間に直接そ の配列にアクセスすることの結果は未定義です。

sbuf_delete() 関数は sbuf をクリアして、そのために割り当てられた全てのメ モリを開放します。全ての sbuf_new() への呼び出しのための sbuf_delete() の 呼び出しがなければなりません。削除された後の sbuf への全てのアクセスの試 みは失敗します。

sbuf_clear() 関数は sbuf の内容を無効にし、位置を 0 にリセットします。

sbuf_setpos() 関数は sbuf の終了位置を、0 と格納バッファの大きさよりも 1 小さい値の間の値である pos に設定します。結果として、新しい位置において sbuf の先端を切り捨てることになります。

sbuf_bcat() 関数はバッファ buf の最初の len バイトを sbuf に追加します。

sbuf_bcopyin() 関数は明示されたユーザ空間アドレスから sbuf に len バイト をコピーします。

sbuf_bcpy() 関数は sbuf の内容をバッファ buf の最初の len バイトで置き換 えます。

sbuf_cat() 関数は NUL 文字で終端された文字列 str を sbuf の現在位置に追加 します。

sbuf_copyin() 関数は NUL 文字で終端された文字列を明示されたユーザ空間アド レスから sbuf にコピーします。 len 引数が 0 でない場合には len 文字を越え ない文字 (終端の NUL は数えません) がコピーされ、そうでない場合には文字列 全体、または sbuf に詰め込むことが出来るだけの文字をコピーします。

sbuf_cpy() 関数は sbuf の内容を NUL 文字で終端された文字列 str で置き換え ます。これは新しい sbuf で、または sbuf_clear() か sbuf_setpos() でその位 置を 0 にリセットされている sbuf で、 sbuf_cat() を呼び出すことと等価で す。

sbuf_printf() 関数は fmt によって指されているフォーマット文字列に従ってそ の引数をフォーマットし、その結果の文字列を sbuf の現在位置に追加します。

sbuf_vprintf() 関数は sbuf_printf() と同様に振舞いますが、引数が可変長引 数リスト ap から取得されることが違います。

sbuf_putc() 関数は文字 c を sbuf の現在位置に追加します。

sbuf_trim() 関数は末尾の空白を sbuf から除去します。

sbuf_overflowed() 関数は sbuf がオーバフローしている場合に 0 以外の値を返 します。

sbuf_finish() 関数は sbuf をヌルで終端し、これ以上 sbuf_setpos(), sbuf_cat(), sbuf_cpy(), sbuf_printf() または sbuf_putc() を使用して修正さ れることが無いことを意味する完了マークを付けます。

sbuf_data() および sbuf_len() 関数はそれぞれ現在の文字列とその長さを返し ます。 sbuf_data() は完了した sbuf に対してのみ機能します。 sbuf_done() はその sbuf が終了した場合には、0 でない値を返します。

注

ある操作が sbuf をオーバフローさせた場合には、その sbuf が sbuf_finish() を使用して完了させられる、または sbuf_clear() を使用してリセットされる、 または sbuf_setpos() を使用してその位置を 0 から格納バッファの大きさより 1 小さい値までの値にリセットされる、または sbuf_cpy() を使用して十分に短 い文字列に初期化されるまでの間は、後に続くほとんどのその sbuf に対する操 作は失敗するでしょう。

sbuf_new() は格納バッファの割り当てに失敗した場合には NULL を返し、そうで ない場合には新しい sbuf へのポインタを返します。

sbuf_setpos() は pos が不正な場合には −1 を返し、そうでない場合には 0 を 返します。

sbuf_cat(), sbuf_cpy(), sbuf_printf(), sbuf_putc(), sbuf_trim() は全て バッファがオーバフローした場合には −1 を返し、そうでない場合には 0 を返し ます。

sbuf_overflowed() はバッファがオーバフローしている場合には 0 以外に値を返 し、そうでない場合には 0 を返します。

sbuf_data() および sbuf_len() はバッファがオーバフローしている場合には、 それぞれ NULL および −1 を返します。

printf(3), strcat(3), strcpy(3), copyin(9), copyinstr(9), printf(9)

sbuf ファミリの関数は FreeBSD 4.4 ではじめて登場しました。

sbuf ファミリの関数は Poul-Henning Kamp ⟨phk@FreeBSD.org⟩ が設計し、 Dag-Erling Smørgrav ⟨des@FreeBSD.org⟩ が実装しました。追加の改良は Justin T. Gibbs ⟨gibbs@FreeBSD.org⟩ が提案しました。自動拡張サポートは Kelly Yancey ⟨kbyanc@FreeBSD.org⟩ が追加しました。

このマニュアルページは Dag-Erling Smørgrav ⟨des@FreeBSD.org⟩ が書きまし た。

FreeBSD 10.0 July 9, 2004 FreeBSD 10.0