os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
doc/documentation/manual-pages/ja/man9/sbuf.9
Sergio Carlavilla Delgado 989d921f5d Migrate doc to Hugo/AsciiDoctor 
I'm very pleased to announce the release of
our new website and documentation using
the new toolchain with Hugo and AsciiDoctor.

To get more information about the new toolchain
please read the FreeBSD Documentation Project Primer[1],
Hugo docs[2] and AsciiDoctor docs[3].

Acknowledgment:
Benedict Reuschling <bcr@>
Glen Barber <gjb@>
Hiroki Sato <hrs@>
Li-Wen Hsu <lwhsu@>
Sean Chittenden <seanc@>
The FreeBSD Foundation

[1] https://docs.FreeBSD.org/en/books/fdp-primer/
[2] https://gohugo.io/documentation/
[3] https://docs.asciidoctor.org/home/

Approved by:    doceng, core
2021-01-26 00:31:29 +01:00

365 lines
8 KiB
Groff
Raw Blame History

.\"-
.\" 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
が書きました。
Reference in a new issue View git blame Copy permalink