365 lines
8 KiB
Groff
365 lines
8 KiB
Groff
.\"-
|
|
.\" Copyright (c) 2000 Poul Henning Kamp and Dag-Erling Coidan Smorgrav
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" %FreeBSD: src/share/man/man9/sbuf.9,v 1.24 2004/07/09 11:44:49 des Exp %
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd July 9, 2004
|
|
.Dt SBUF 9
|
|
.Os
|
|
.Sh 名称
|
|
.Nm sbuf_new ,
|
|
.Nm sbuf_clear ,
|
|
.Nm sbuf_setpos ,
|
|
.Nm sbuf_bcat ,
|
|
.Nm sbuf_bcopyin ,
|
|
.Nm sbuf_bcpy ,
|
|
.Nm sbuf_cat ,
|
|
.Nm sbuf_copyin ,
|
|
.Nm sbuf_cpy ,
|
|
.Nm sbuf_printf ,
|
|
.Nm sbuf_vprintf ,
|
|
.Nm sbuf_putc ,
|
|
.Nm sbuf_trim ,
|
|
.Nm sbuf_overflowed ,
|
|
.Nm sbuf_finish ,
|
|
.Nm sbuf_data ,
|
|
.Nm sbuf_len ,
|
|
.Nm sbuf_done ,
|
|
.Nm sbuf_delete
|
|
.Nd 安全な文字列フォーマット
|
|
.Sh 書式
|
|
.In sys/types.h
|
|
.In sys/sbuf.h
|
|
.Ft struct sbuf *
|
|
.Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags"
|
|
.Ft void
|
|
.Fn sbuf_clear "struct sbuf *s"
|
|
.Ft int
|
|
.Fn sbuf_setpos "struct sbuf *s" "int pos"
|
|
.Ft int
|
|
.Fn sbuf_bcat "struct sbuf *s" "const void *buf" "size_t len"
|
|
.Ft int
|
|
.Fn sbuf_bcopyin "struct sbuf *s" "const void *uaddr" "size_t len"
|
|
.Ft int
|
|
.Fn sbuf_bcpy "struct sbuf *s" "const void *buf" "size_t len"
|
|
.Ft int
|
|
.Fn sbuf_cat "struct sbuf *s" "const char *str"
|
|
.Ft int
|
|
.Fn sbuf_copyin "struct sbuf *s" "const void *uaddr" "size_t len"
|
|
.Ft int
|
|
.Fn sbuf_cpy "struct sbuf *s" "const char *str"
|
|
.Ft int
|
|
.Fn sbuf_printf "struct sbuf *s" "const char *fmt" "..."
|
|
.Ft int
|
|
.Fn sbuf_vprintf "struct sbuf *s" "const char *fmt" "va_list ap"
|
|
.Ft int
|
|
.Fn sbuf_putc "struct sbuf *s" "int c"
|
|
.Ft int
|
|
.Fn sbuf_trim "struct sbuf *s"
|
|
.Ft int
|
|
.Fn sbuf_overflowed "struct sbuf *s"
|
|
.Ft void
|
|
.Fn sbuf_finish "struct sbuf *s"
|
|
.Ft char *
|
|
.Fn sbuf_data "struct sbuf *s"
|
|
.Ft int
|
|
.Fn sbuf_len "struct sbuf *s"
|
|
.Ft int
|
|
.Fn sbuf_done "struct sbuf *s"
|
|
.Ft void
|
|
.Fn sbuf_delete "struct sbuf *s"
|
|
.Sh 解説
|
|
.Nm sbuf
|
|
ファミリの関数は、カーネル空間内の境界のあるヌル終端文字列の、
|
|
安全な割り当て、構築、および解放を可能にします。
|
|
これらの関数は、文字の配列の代わりに、
|
|
.In sys/sbuf.h
|
|
で定義される
|
|
.Fa sbuf
|
|
と呼ばれる構造体を操作します。
|
|
.Pp
|
|
.Fn sbuf_new
|
|
関数は最初の引数で指される
|
|
.Fa sbuf
|
|
を初期化します。
|
|
そのポインタが
|
|
.Dv NULL
|
|
の場合には、
|
|
.Fn sbuf_new
|
|
は
|
|
.Vt struct sbuf
|
|
構造体を
|
|
.Xr malloc 9
|
|
を使用して割り当てます。
|
|
.Fa buf
|
|
引数は実際に文字列が格納されるバッファへのポインタで、
|
|
.Dv NULL
|
|
の場合には、
|
|
.Fn sbuf_new
|
|
は
|
|
.Xr malloc 9
|
|
を使用してバッファを割り当てます。
|
|
.Fa length
|
|
は格納バッファの初期の大きさです。
|
|
4 番目の引数
|
|
.Fa flags
|
|
は以下のフラグから構成され得ます:
|
|
.Bl -tag -width ".Dv SBUF_AUTOEXTEND"
|
|
.It Dv SBUF_FIXEDLEN
|
|
格納バッファは初期サイズで固定です。
|
|
これを越えて sbuf を拡張しようとすると、オーバフロー状態となります。
|
|
.It Dv SBUF_AUTOEXTEND
|
|
これは、追加データの格納のために必要ならば、
|
|
資源の許す限りにおいて、格納バッファは拡張可能であることを示します。
|
|
.El
|
|
.Pp
|
|
.Fa buf
|
|
が
|
|
.Dv NULL
|
|
でない場合には、少なくとも
|
|
.Fa length
|
|
文字以上の配列を指さなければならないことに注意してください。
|
|
sbuf によって使用されている間に直接その配列にアクセスすることの結果は
|
|
未定義です。
|
|
.Pp
|
|
.Fn sbuf_delete
|
|
関数は
|
|
.Fa sbuf
|
|
をクリアして、そのために割り当てられた全てのメモリを開放します。
|
|
全ての
|
|
.Fn sbuf_new
|
|
への呼び出しのための
|
|
.Fn sbuf_delete
|
|
の呼び出しがなければなりません。
|
|
削除された後の sbuf への全てのアクセスの試みは失敗します。
|
|
.Pp
|
|
.Fn sbuf_clear
|
|
関数は
|
|
.Fa sbuf
|
|
の内容を無効にし、位置を 0 にリセットします。
|
|
.Pp
|
|
.Fn sbuf_setpos
|
|
関数は
|
|
.Fa sbuf
|
|
の終了位置を、0 と格納バッファの大きさよりも 1 小さい値の間の値である
|
|
.Fa pos
|
|
に設定します。
|
|
結果として、新しい位置において sbuf の先端を切り捨てることになります。
|
|
.Pp
|
|
.Fn sbuf_bcat
|
|
関数はバッファ
|
|
.Fa buf
|
|
の最初の
|
|
.Fa len
|
|
バイトを
|
|
.Fa sbuf
|
|
に追加します。
|
|
.Pp
|
|
.Fn sbuf_bcopyin
|
|
関数は明示されたユーザ空間アドレスから
|
|
.Fa sbuf
|
|
に
|
|
.Fa len
|
|
バイトをコピーします。
|
|
.Pp
|
|
.Fn sbuf_bcpy
|
|
関数は
|
|
.Fa sbuf
|
|
の内容をバッファ
|
|
.Fa buf
|
|
の最初の
|
|
.Fa len
|
|
バイトで置き換えます。
|
|
.Pp
|
|
.Fn sbuf_cat
|
|
関数は NUL 文字で終端された文字列
|
|
.Fa str
|
|
を
|
|
.Fa sbuf
|
|
の現在位置に追加します。
|
|
.Pp
|
|
.Fn sbuf_copyin
|
|
関数は NUL 文字で終端された文字列を明示されたユーザ空間アドレスから
|
|
.Fa sbuf
|
|
にコピーします。
|
|
.Fa len
|
|
引数が 0 でない場合には
|
|
.Fa len
|
|
文字を越えない文字 (終端の NUL は数えません) がコピーされ、
|
|
そうでない場合には文字列全体、または
|
|
.Fa sbuf
|
|
に詰め込むことが出来るだけの文字をコピーします。
|
|
.Pp
|
|
.Fn sbuf_cpy
|
|
関数は
|
|
.Fa sbuf
|
|
の内容を NUL 文字で終端された文字列
|
|
.Fa str
|
|
で置き換えます。
|
|
これは新しい
|
|
.Fa sbuf
|
|
で、または
|
|
.Fn sbuf_clear
|
|
か
|
|
.Fn sbuf_setpos
|
|
でその位置を 0 にリセットされている
|
|
.Fa sbuf
|
|
で、
|
|
.Fn sbuf_cat
|
|
を呼び出すことと等価です。
|
|
.Pp
|
|
.Fn sbuf_printf
|
|
関数は
|
|
.Fa fmt
|
|
によって指されているフォーマット文字列に従ってその引数をフォーマットし、
|
|
その結果の文字列を
|
|
.Fa sbuf
|
|
の現在位置に追加します。
|
|
.Pp
|
|
.Fn sbuf_vprintf
|
|
関数は
|
|
.Fn sbuf_printf
|
|
と同様に振舞いますが、引数が可変長引数リスト
|
|
.Fa ap
|
|
から取得されることが違います。
|
|
.Pp
|
|
.Fn sbuf_putc
|
|
関数は文字
|
|
.Fa c
|
|
を
|
|
.Fa sbuf
|
|
の現在位置に追加します。
|
|
.Pp
|
|
.Fn sbuf_trim
|
|
関数は末尾の空白を
|
|
.Fa sbuf
|
|
から除去します。
|
|
.Pp
|
|
.Fn sbuf_overflowed
|
|
関数は
|
|
.Fa sbuf
|
|
がオーバフローしている場合に 0 以外の値を返します。
|
|
.Pp
|
|
.Fn sbuf_finish
|
|
関数は
|
|
.Fa sbuf
|
|
をヌルで終端し、これ以上
|
|
.Fn sbuf_setpos ,
|
|
.Fn sbuf_cat ,
|
|
.Fn sbuf_cpy ,
|
|
.Fn sbuf_printf
|
|
または
|
|
.Fn sbuf_putc
|
|
を使用して修正されることが無いことを意味する完了マークを付けます。
|
|
.Pp
|
|
.Fn sbuf_data
|
|
および
|
|
.Fn sbuf_len
|
|
関数はそれぞれ現在の文字列とその長さを返します。
|
|
.Fn sbuf_data
|
|
は完了した
|
|
.Fa sbuf
|
|
に対してのみ機能します。
|
|
.Fn sbuf_done
|
|
はその sbuf が終了した場合には、0 でない値を返します。
|
|
.Sh 注
|
|
ある操作が
|
|
.Fa sbuf
|
|
をオーバフローさせた場合には、その
|
|
.Fa sbuf
|
|
が
|
|
.Fn sbuf_finish
|
|
を使用して完了させられる、または
|
|
.Fn sbuf_clear
|
|
を使用してリセットされる、または
|
|
.Fn sbuf_setpos
|
|
を使用してその位置を 0 から格納バッファの大きさより 1 小さい値までの値に
|
|
リセットされる、または
|
|
.Fn sbuf_cpy
|
|
を使用して十分に短い文字列に初期化されるまでの間は、後に続くほとんどのその
|
|
.Fa sbuf
|
|
に対する操作は失敗するでしょう。
|
|
.Sh 戻り値
|
|
.Fn sbuf_new
|
|
は格納バッファの割り当てに失敗した場合には
|
|
.Dv NULL
|
|
を返し、そうでない場合には新しい
|
|
.Fa sbuf
|
|
へのポインタを返します。
|
|
.Pp
|
|
.Fn sbuf_setpos
|
|
は
|
|
.Fa pos
|
|
が不正な場合には \-1 を返し、そうでない場合には 0 を返します。
|
|
.Pp
|
|
.Fn sbuf_cat ,
|
|
.Fn sbuf_cpy ,
|
|
.Fn sbuf_printf ,
|
|
.Fn sbuf_putc ,
|
|
.Fn sbuf_trim
|
|
は全てバッファがオーバフローした場合には \-1 を返し、
|
|
そうでない場合には 0 を返します。
|
|
.Pp
|
|
.Fn sbuf_overflowed
|
|
はバッファがオーバフローしている場合には 0 以外に値を返し、
|
|
そうでない場合には 0 を返します。
|
|
.Pp
|
|
.Fn sbuf_data
|
|
および
|
|
.Fn sbuf_len
|
|
はバッファがオーバフローしている場合には、それぞれ
|
|
.Dv NULL
|
|
および \-1 を返します。
|
|
.Sh 関連項目
|
|
.Xr printf 3 ,
|
|
.Xr strcat 3 ,
|
|
.Xr strcpy 3 ,
|
|
.Xr copyin 9 ,
|
|
.Xr copyinstr 9 ,
|
|
.Xr printf 9
|
|
.Sh 歴史
|
|
.Nm sbuf
|
|
ファミリの関数は
|
|
.Fx 4.4
|
|
ではじめて登場しました。
|
|
.Sh 作者
|
|
.An -nosplit
|
|
.Nm sbuf
|
|
ファミリの関数は
|
|
.An Poul-Henning Kamp Aq phk@FreeBSD.org
|
|
が設計し、
|
|
.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org
|
|
が実装しました。
|
|
追加の改良は
|
|
.An Justin T. Gibbs Aq gibbs@FreeBSD.org
|
|
が提案しました。
|
|
自動拡張サポートは
|
|
.An Kelly Yancey Aq kbyanc@FreeBSD.org
|
|
が追加しました。
|
|
.Pp
|
|
このマニュアルページは
|
|
.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org
|
|
が書きました。
|