日本語 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.4-RELEASE-K, 13.0-RELEASE-K から 13.3-RELEASE-K, 14.0-RELEASE-K から 14.1-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_bcat(), 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.4 May 23, 2018 FreeBSD 11.4