tail head cat sleep
QR code linking to this page

manページ  — SBUF

名称

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_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() 関数は明示されたユーザ空間アドレスから sbuflen バイトをコピーします。

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

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

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() 関数は文字 csbuf の現在位置に追加します。

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 をオーバフローさせた場合には、その sbufsbuf_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/orgrav <des@FreeBSD.org> が実装しました。 追加の改良は Justin T. Gibbs <gibbs@FreeBSD.org> が提案しました。 自動拡張サポートは Kelly Yancey <kbyanc@FreeBSD.org> が追加しました。

このマニュアルページは Dag-Erling Sm/orgrav <des@FreeBSD.org> が書きました。


SBUF (9) July 9, 2004

tail head cat sleep
QR code linking to this page


このマニュアルページサービスについてのご意見は Ben Bullock にお知らせください。 Privacy policy.

"I liken starting one's computing career with Unix, say as an undergraduate, to being born in East Africa. It is intolerably hot, your body is covered with lice and flies, you are malnourished and you suffer from numerous curable diseases. But, as far as young East Africans can tell, this is simply the natural condition and they live within it. By the time they find out differently, it is too late. They already think that the writing of shell scripts is a natural act."
— Ken Pier, Xerox PARC