日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.3-RELEASE-K, 13.0-RELEASE-K から 13.2-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
SBUF(9) FreeBSD カーネル開発者マニュアル SBUF(9)
名称
sbuf, sbuf_new, sbuf_new_auto, sbuf_new_for_sysctl, sbuf_clear,
sbuf_get_flags, sbuf_set_flags, sbuf_clear_flags, sbuf_setpos, sbuf_bcat,
sbuf_bcopyin, sbuf_bcpy, sbuf_cat, sbuf_copyin, sbuf_cpy, sbuf_printf,
sbuf_vprintf, sbuf_putc, sbuf_set_drain, sbuf_trim, sbuf_error,
sbuf_finish, sbuf_data, sbuf_len, sbuf_done, sbuf_delete,
sbuf_start_section, sbuf_end_section, sbuf_hexdump, sbuf_putbuf -- 安全な
文字列の組み立て
書式
#include <sys/types.h>
#include <sys/sbuf.h>
typedef int (sbuf_drain_func) (void *arg, const char *data, int len);
struct sbuf *
sbuf_new(struct sbuf *s, char *buf, int length, int flags);
struct sbuf *
sbuf_new_auto(void);
void
sbuf_clear(struct sbuf *s);
int
sbuf_get_flags(struct sbuf *s);
void
sbuf_set_flags(struct sbuf *s, int flags);
void
sbuf_clear_flags(struct sbuf *s, int flags);
int
sbuf_setpos(struct sbuf *s, int pos);
int
sbuf_bcat(struct sbuf *s, const void *buf, 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_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);
void
sbuf_set_drain(struct sbuf *s, sbuf_drain_func *func, void *arg);
int
sbuf_trim(struct sbuf *s);
int
sbuf_error(struct sbuf *s);
int
sbuf_finish(struct sbuf *s);
char *
sbuf_data(struct sbuf *s);
ssize_t
sbuf_len(struct sbuf *s);
int
sbuf_done(struct sbuf *s);
void
sbuf_delete(struct sbuf *s);
void
sbuf_start_section(struct sbuf *s, ssize_t *old_lenp);
ssize_t
sbuf_end_section(struct sbuf *s, ssize_t old_len, size_t pad, int c);
void
sbuf_hexdump(struct sbuf *sb, void *ptr, int length, const char *hdr,
int flags);
void
sbuf_putbuf(struct sbuf *s);
#ifdef _KERNEL
#include <sys/types.h>
#include <sys/sbuf.h>
int
sbuf_bcopyin(struct sbuf *s, const void *uaddr, size_t len);
int
sbuf_copyin(struct sbuf *s, const void *uaddr, size_t len);
#include <sys/sysctl.h>
struct sbuf *
sbuf_new_for_sysctl(struct sbuf *s, char *buf, int length,
struct sysctl_req *req);
#endif /* _KERNEL */
解説
sbuf 関数ファミリは、カーネルまたはユーザ空間の文字列を安全に割り付ける、
組み立てる、そして解放することができます。
文字の配列の代わりに、これらの関数は、<sys/sbuf.h> に定義される sbufs と
呼ばれる構造体で動作します。
文字列の割り付けまたは組み立ての間に遭遇する任意のエラーは、データ構造体
でラッチされ (歯止めがかけられ)、すべてのプロセスの成否を決定するのに十分
である組み立ての終わりで単一のエラーをテストをします。
sbuf_new() 関数は、最初の引数によって指される sbuf を初期化します。そのポ
インタが NULL であるなら、sbuf_new() は、malloc(9) を使用して、struct
sbuf を割り付けます。buf 引数は、実際の文字列を格納するバッファへのポイン
タです。それが NULL であるなら、sbuf_new() は、malloc(9) を使用して、バッ
ファを割り付けます。length は、記憶域バッファの最初のサイズです。4 番目の
引数 flags は、次のフラグで構成されます:
SBUF_FIXEDLEN 記憶域のバッファは、その最初のサイズに固定されます。この
サイズを越えて sbuf を拡張する試みは、オーバフロー状態の
結果となります。
SBUF_AUTOEXTEND これは、リソースが許す限り、追加のデータを保持するため
に、記憶域のバッファが、必要に応じて拡張されることを示し
ます。
SBUF_INCLUDENUL これによって、最終的な nulterm バイトは、データの長さで
カウントされます。
buf が NULL でないなら、少なくとも length 文字の配列を指さなければならな
いことに注意してください。sbuf によって使用されている間に、その配列に直接
アクセスすることの結果は、未定義です。
sbuf_new_auto() 関数は、完全に動的な sbuf を作成するためのショートカット
(近道) です。それは、値 NULL, NULL, 0 と SBUF_AUTOEXTEND をつけて
sbuf_new() を呼び出すことと同等です。
sbuf_new_for_sysctl() 関数は、内部のバッファが満杯になるとき、
SYSCTL_OUT() を使用するために drain 関数で sbuf をセットアップします。
sbuf に追加される様々な関数がスリープ不可能なロックが保持されている間に、
使用されるなら、ユーザバッファは、sysctl_wire_old_buffer() を使用して結ば
れるべきであることに注意してください。
sbuf_delete() 関数は、sbuf をクリアし、それに割り付けられたあらゆるメモリ
を解放します。sbuf_new() への呼び出しごとに、sbuf_delete() を呼び出さなけ
ればなりません。それが削除された後に、sbuf をアクセスするあらゆる試みは、
失敗します。
sbuf_clear() 関数は、sbuf の内容を無効にし、その位置を 0 にリセットしま
す。
sbuf_get_flags() 関数は、現在のユーザフラグを返します。sbuf_set_flags()
と sbuf_get_flags() 関数は、それぞれ、1 つ以上ユーザフラグを設定するか、
またはクリアします。ユーザフラグは、sbuf_new() 関数の下で説明されます。
sbuf_setpos() 関数は、sbuf の終りの位置を 0 と記憶域バッファのサイズ未満
の間の値である pos に設定します。これは、新しい位置で sbuf を効率的に切り
詰めます。
sbuf_bcat() 関数は、バッファ buf から sbuf まで最初の len バイトを追加し
ます。
sbuf_bcopyin() 関数は、指定されたユーザランドのアドレスから sbuf に len
バイトをコピーします。
sbuf_bcpy() 関数は、sbuf の内容をバッファ buf からの最初の len バイトで置
き換えます。
sbuf_cat() 関数は、現在の位置の sbuf にヌル文字で終了する文字列 str を追
加します。
sbuf_set_drain() 関数は、sbuf のための drain 関数 func を設定し、コール
バックで drain に渡されるポインタ arg を記録します。sbuf_len が 0 以外で
ある間に、drain 関数を変更することはできません。
登録された drain 関数 sbuf_drain_func は、sbuf_set_drain() に提供された引
数 arg、sbuf の内容であるバイト文字列へのポインタ data とデータの長さの
len で呼び出されます。drain 関数が存在しているなら、sbuf の内部バッファが
満杯であるか、または sbuf_finish() の代わりに呼び出されます。drain 関数
は、一部またはすべてのデータを排出 (drain) しますが、少なくとも 1 バイト
を排出しなければなりません。drain 関数からの返り値が、正であるなら、どの
くらいのバイトを排出したかを示します。負であるなら、返り値は、これから返
される負のエラーコードまたは sbuf_finish() への遅い呼び出しを示します。返
された排出された長さは、0 のはずはありません。drain をバッファリングしな
いようにするためには、2 バイトのバッファで sbuf を初期化します。drain
は、sbuf に追加されたあらゆるバイトに対して呼び出されます。drain がある
sbuf で sbuf_bcopyin(), sbuf_copyin(), sbuf_trim() と sbuf_data() 関数を
使用することができません。
sbuf_copyin() 関数は、指定されたユーザランドのアドレスからヌル文字で終了
する文字列を sbuf にコピーします。len 引数が 0 でないなら、わずか len 文
字 (終了するヌル文字を数えずに) がコピーされます。そうでなければ、すべて
の文字列 (すなわち、sbuf にできるかぎり適合することができる) が、コピーさ
れます。
sbuf_cpy() 関数は、sbuf の内容をヌル文字で終了する文字列 str のものに置き
換えます。これは、新鮮な sbuf または位置が sbuf_clear() または
sbuf_setpos() で 0 にリセットされたもので、sbuf_cat() を呼び出すことと同
等です。
sbuf_printf() 関数は、fmt によって指される書式文字列にしたがってその引数
を書式化し、sbuf の現在位置に結果の文字列を追加します。
sbuf_vprintf() 関数は、引数が可変長引数リスト ap から取得されることを除い
て、sbuf_printf() と同様に振る舞います。
sbuf_putc() 関数は、sbuf の現在位置に文字 c を追加します。
sbuf_trim() 関数は、sbuf から後続する空白類を削除します。
sbuf_error() 関数は、ドレイン関数から、または sbuf がオーバフローしたな
ら、ENOMEM のいずれかの、sbuf が蓄積した任意のエラー値を返します。一般的
に、この関数は、必要ではありません、代わりに、sbuf_finish() からのエラー
コードは、sbuf にエラーがあったかどうかを発見するよい方法です。
sbuf_finish() 関数は、sbuf のすべてのデータがフラッシュされるまで、存在し
ているなら、アタッチされた drain 関数を呼び出します。アタッチされた drain
がないなら、sbuf_finish() は、sbuf を NUL で終了します。いずれにしても、
sbuf_clear() が sbuf をリセットするために使用されるまで、もはや
sbuf_setpos(), sbuf_cat(), sbuf_cpy(), sbuf_printf() または sbuf_putc()
を使用して変更されないことを意味する、終了しているとして sbuf をマークし
ます。
sbuf_data() 関数は、実際の文字列を返します。sbuf_data() は、終了した sbuf
でのみ動作します。sbuf_len() 関数は、文字列の長さを返します。アタッチされ
た drain がある sbuf に関して、sbuf_len() は、排出されていないデータの長
さを返します。sbuf_done() は、sbuf が終了しているなら、0 以外を返します。
sbuf_start_section() と sbuf_end_section() 関数は、自動的なセクションの整
列のために使用されます。引数 pad と c は、詰め物のために使用される詰め物
のサイズと文字を指定します。引数 old_lenp と old_len は、入れ子にされたセ
クションが使用されるとき、現在のセクションの長さを保存して復旧するための
ものです。トップレベルのセクションに対して、それぞれ、old_lenp と old_len
のために NULL と -1 を指定することができます。
sbuf_hexdump() 関数は、可能であるなら、バイトの ASCII 表現とともに、供給
された sbuf にバイトの配列を印刷 (表示) します。インタフェースに関する詳
細については、hexdump(3) マニュアルページを参照してください。
sbuf_putbuf() 関数は、ユーザランドであるなら、stdout (標準出力) に sbuf
を printf (印刷) し、カーネルであるなら、とコンソールとログに sbuf を
printf (印刷) します。それは、バッファを排出せず、あらゆるポインタを更新
しません。
注
操作が sbuf をオーバフローさせるなら、sbuf が、sbuf_finish() を使用してい
終了されるか、または sbuf_clear() 使用してリセットするか、またはその位置
が、sbuf_setpos() を使用して、その記憶域のバッファのサイズ未満の 0 と 1
の間の値にリセットされるか、または sbuf_cpy() を使用して十分に短い文字列
に再初期化されるまで、sbuf でのほとんどの続く操作は、失敗します。
ユーザ空間の drain は、示されるように常に機能するというわけではありませ
ん。drain 関数がオーバフローのときに sbuf_putc, sbuf_bcat, sbuf_cat 関数
からただちに呼び出されている間に、sbuf_printf と sbuf_vprintf は、現在、
オーバフロー起こった後まで、オーバフローがあるかを決定する方法がなく、書
式の文字列の部分的な拡張ができません。したがって、libsbuf を使用すると
き、バッファは、たとえ drain がアタッチされていても、単一の printf の呼び
出しの完了を許可するために拡張されるかもしれません、
戻り値
sbuf_new() 関数は、記憶域のバッファを割り付けることに失敗したなら、NULL
を返し、そうでなければ、新しい sbuf へのポインタを返します。
sbuf_setpos() 関数は、pos が不正であったなら、-1 を返し、そうでなければ、
0 を返します。
sbuf_cat(), sbuf_cpy(), sbuf_printf(), sbuf_putc() と sbuf_trim() 関数
は、すべて、バッファがオーバフローしたなら、-1 を返し、そうでなければ、0
を返します。
sbuf_error() 関数は、バッファがオーバフローするか、または drain エラーが
あるなら、0 以外の値を返し、そうでなければ、0 を返します。
sbuf_len() 関数は、バッファがオーバフローしたなら、-1 を返します。
sbuf_copyin() 関数は、ユーザランドから文字列をコピーすることが失敗したな
ら、-1 を返し、そうでなければ、コピーされたバイト数を返します。
sbuf_end_section() 関数は、セクションの長さを返し、バッファにエラーがある
なら、-1 を返します。
(カーネルバージョンの) sbuf_finish(9) 関数は、終わる前に、sbuf がオーバフ
ローしたなら、ENOMEM を返し、アタッチされているなら、drain からエラーコー
ドを返します。
(ユーザランドバージョンの) sbuf_finish(3) 関数は、成功すれば、0 を返し、
エラーであるなら、-1 を返し errno を設定します。
使用例
#include <sys/types.h>
#include <sys/sbuf.h>
struct sbuf *sb;
sb = sbuf_new_auto();
sbuf_cat(sb, "Customers found:\n");
TAILQ_FOREACH(foo, &foolist, list) {
sbuf_printf(sb, " %4d %s\n", foo->index, foo->name);
sbuf_printf(sb, " Address: %s\n", foo->address);
sbuf_printf(sb, " Zip: %s\n", foo->zipcode);
}
if (sbuf_finish(sb) != 0) /* ありとあらゆるエラーをチェックする */
err(1, "Could not generate message");
transmit_msg(sbuf_data(sb), sbuf_len(sb));
sbuf_delete(sb);
関連項目
hexdump(3), 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> によって追加されまし
た。drain 機能は、Matthew Fleming <mdf@FreeBSD.org> によって追加されまし
た。
このマニュアルページは、Dag-Erling Sm/rgrav <des@FreeBSD.org> によって書
かれました。
FreeBSD 11.2 April 5, 2017 FreeBSD 11.2