SBUF(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 - 安全な文字列フォーマット

書式
<sys/types.h> <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_FIXEDLEN
    格納バッファは初期サイズで固定です。 これを越えて 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 ではじめて登場しました。

作者
-nosplit 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> が書きました。