日本語 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
TCP_FUNCTIONS(9) FreeBSD カーネル開発者マニュアル TCP_FUNCTIONS(9)
名称
tcp_functions -- 代替の TCP スタックフレームワーク
書式
#include <netinet/tcp.h>
#include <netinet/tcp_var.h>
int
register_tcp_functions(struct tcp_function_block *blk, int wait);
int
register_tcp_functions_as_name(struct tcp_function_block *blk,
const char *name, int wait);
register_tcp_functions_as_names(struct tcp_function_block *blk, int wait,
const char *names[], int *num_names);
int
deregister_tcp_functions(struct tcp_function_block *blk);
解説
tcp_functions フレームワークによって、カーネル開発者は、代替の TCP スタッ
クを実施することができます。カーネルにで代替のスタックをコンパイルするこ
とができるか、またはロード可能なカーネルモジュールで実装することができま
す。この関数は、TCP スタックで実験を促進し、単一のシステムの異なった TCP
接続のために代替の振る舞いを配備することを目的としています。
システム管理者は、システムのデフォルトスタックを設定することができます。
デフォルトで、すべての TCP 接続は、システムのデフォルトスタックを使用しま
す。さらに、ユーザは、基本の接続ごとに使用する特定のスタックを指定するこ
とができます。(システムのデフォルトのスタックの設定、または与えられた接続
のための特有のスタックを選択することに関する詳細については、tcp(4) を参照
してください。)
このマニュアルページは、"TCP スタック" を "関数ブロック" と同義語であると
して扱います。これは、意図的です。"TCP スタック" は、振る舞いの設定を実装
する関数の収集です。そのため、代替の "関数ブロック" は、代替の "TCP ス
タック" と定義します。
register_tcp_functions(), register_tcp_functions_as_name() と
register_tcp_functions_as_names() 関数は、システムが、指定された関数ブ
ロックを追加し、与えられた名前で使用するためにそれを登録するように要求し
ます。モジュールは、異なった名前で複数回同じ関数ブロックを登録します。し
かしながら、名前は、すべての登録された関数ブロックの間でグローバルでユ
ニークでなければなりません。また、モジュールは、モジュールが関数ブロック
を最初に成功して登録を解除するまで、それが登録された後に、(名前を含んで)
関数ブロックの内容を決して修正しません。
register_tcp_functions() 関数は、名前があるシステムレジスタの関数ブロック
が関数ブロックの tfb_tcp_block_name フィールドで定義されることを要求しま
す。これは、関数ブロックの tfb_tcp_block_name フィールドで定義された名前
を使用して関数ブロックを自動的に登録する 3 つの登録関数のただ 1 つである
ことに注意してください。モジュールが他の登録関数の 1 つを使用するなら、そ
れは、システムが、その名前を明示的に提供することによって関数ブロック
tfb_tcp_block_name フィールドで定義された名前を使用して関数ブロックを登録
することを要求します。
register_tcp_functions_as_name() 関数は、システムが name 引数で提供された
名前がある関数ブロックを要求します。
register_tcp_functions_as_names() 関数は、システムが names 引数で提供され
たすべての名前がある関数ブロックを登録することを要求します。num_names 引
数は、名前の数へのポインタを提供します。この関数は、配列のすべての名前、
または配列の名前なしの登録のいずれかで成功します。失敗で、num_names 引数
は、それがエラーに遭遇したとき、システムが処理していた names 配列のエント
リのインデックス番号で更新されます。
deregister_tcp_functions() 関数は、システムが、システムから指定された関数
ブロックを削除することを要求します。この呼び出しが成功するなら、関数ブ
ロックを登録するために使用される名前の数にかかわらず関数ブロックを完全に
登録解除します。ソケットが、まだ、指定された関数ブロックを使用しているの
で、呼び出しが失敗するなら、システムは、削除されているプロセスにあること
として関数ブロックをマークします。これは、指定された関数ブロックを使用す
ることから追加のソケットを防止します。しかしながら、それは、すでに関数ブ
ロックを使用しているソケットに影響を与えません。
tcp_functions モジュールは、初期化の間に登録関数の 1 つ以上を呼び出し、モ
ジュールがアンロードされることを許可するすることに先がけて、
deregister_tcp_functions() 関数を成功して呼び出さなければなりません。
blk 引数は、以下に説明されている (「関数ブロック構造体」を参照) struct
tcp_function_block へのポインタです。wait 引数は、malloc(9) への flags 引
数として使用され、そのマニュアルページに定義された有効な値の 1 つに設定さ
れなければなりません。
関数ブロック構造体
blk 引数は、次のメンバがある、struct tcp_function_block へのポインタです:
struct tcp_function_block {
char tfb_tcp_block_name[TCP_FUNCTION_NAME_LEN_MAX];
int (*tfb_tcp_output)(struct tcpcb *);
void (*tfb_tcp_do_segment)(struct mbuf *, struct tcphdr *,
struct socket *, struct tcpcb *,
int, int, uint8_t,
int);
int (*tfb_tcp_ctloutput)(struct socket *so,
struct sockopt *sopt,
struct inpcb *inp, struct tcpcb *tp);
/* オプションのメモリ割り付け/解放ルーチン */
void (*tfb_tcp_fb_init)(struct tcpcb *);
void (*tfb_tcp_fb_fini)(struct tcpcb *, int);
/* オプションのタイマは, 利用者がそれを定義するなら,
すべて定義しなければなりません */
int (*tfb_tcp_timer_stop_all)(struct tcpcb *);
void (*tfb_tcp_timer_activate)(struct tcpcb *,
uint32_t, u_int);
int (*tfb_tcp_timer_active)(struct tcpcb *, uint32_t);
void (*tfb_tcp_timer_stop)(struct tcpcb *, uint32_t);
/* オプションの関数 */
void (*tfb_tcp_rexmit_tmr)(struct tcpcb *);
void (*tfb_tcp_handoff_ok)(struct tcpcb *);
/* システムで使用 */
volatile uint32_t tfb_refcnt;
uint32_t tfb_flags;
};
tfb_tcp_block_name フィールドは、TCP スタックのユニークな名前を識別し、
TCP_FUNCTION_NAME_LEN_MAX-1 文字の長さより長くあるべきではありません。
tfb_tcp_output, tfb_tcp_do_segment と tfb_tcp_ctloutput フィールドは、そ
れぞれ、デフォルトの tcp_output(), tcp_do_segment() と
tcp_default_ctloutput() 関数として同等のアクションを実行する関数へのポイ
ンタです。これらの関数ポインタのそれぞれは、NULL であってはなりません。
ソケットが、最初に、TCP スタックを選択するとき、(または、ソケットが最初に
オープンされるとき)、TCP スタックが、データを初期化する必要があるなら、そ
れは、tfb_tcp_fb_init フィールドに NULL でないポインタを設定するべきで
す。同様に、ソケットが、TCP スタックの使用を停止するとき、(または、ソケッ
トがクローズされるとき) TCP スタックが、データをクリーンアップする必要が
あるなら、それは、tfb_tcp_fb_fini フィールドに NULL でないポインタを設定
するべきです。
tfb_tcp_fb_fini 引数が NULL でないなら、それが指す関数は、カーネルが TCP
制御ブロックを破壊しているとき、またはソケットが、異なる TCP スタックを使
用するために移行しているとき、呼び出されます。関数は、TCP 制御ブロックと
整数フラグの引数を付けて呼び出されます。フラグは、ソケットが別の TCP ス
タックを使用するために移行しているなら、0 となり、TCP 制御ブロックが破壊
されているなら、1 となります。
TCP スタックが追加のタイマを実施するなら、TCP スタックは、
tfb_tcp_timer_stop_all, tfb_tcp_timer_activate, tfb_tcp_timer_active と
tfb_tcp_timer_stop フィールドに NULL でないポインタを設定するべきです。こ
れらのフィールドは、すべて NULL であべきか、または関数へのポインタをすべ
て含んでいるべきです。tfb_tcp_timer_activate, tfb_tcp_timer_active と
tfb_tcp_timer_stop 関数は、それぞれ、tcp_timer_activate(),
tcp_timer_active() と tcp_timer_stop() が、標準のタイプ以外のタイマのタイ
プで呼び出されるとき、呼び出されます。TCP スタックによって定義された関数
は、それらの捕捉となる通常のタイマ関数として (引数と返り値のための両方の)
同じセマンティックスがあります。
さらに、スタックは、再送信タイマが、tfb_tcp_rexmit_tmr フィールドに NULL
でない関数ポインタを設定することによって発火するとき、取る、それ自体のア
クションを定義します。この関数は、再送信タイマを処理するプロセスでかなり
初期に呼び出されます。しかしながら、再送信タイマが再送信タイマのロジック
の残りのための有効な状態の TCP 制御ブロックを残すことを保証することに気を
つけなければなりません。
ユーザは、connect(2) または listen(2) を呼び出している前に、新しい TCP ス
タックを選択することができます。オプションで、TCP スタックは、また、ユー
ザが、NULL でない関数のポインタを tfb_tcp_handoff_ok フィールドに設定する
ことによって後の状態である接続のための TCP スタックを使用しはじめることが
できます。このフィールドが NULL でなく、ユーザが、そのソケットのために
connect(2) または listen(2) を呼び出した後にその TCP スタックを選択するこ
とを試みるなら、カーネルは、tfb_tcp_handoff_ok フィールドによって指された
関数を呼び出します。関数は、ユーザが、TCP スタックを使用するためにソケッ
トを切り替えることを許可されるなら、0 を返すべきです。そうでなければ、関
数は、ユーザに返される、エラーコードを返すべきです。tfb_tcp_handoff_ok
フィールドが NULL であり、ユーザが、そのソケットのために connect(2) また
は listen(2) を呼び出した後に TCP スタックを選択することを試みるなら、操
作は、失敗し、カーネルは、EINVAL を返します。
tfb_refcnt と tfb_flags フィールドは、カーネルの TCP コードによって使用さ
れ、TCP スタックが登録されるとき、初期化されます。
代替の TCP スタックのための要件
TCP スタックが、デフォルトの TCP 制御ブロックに格納されるものを越えるデー
タを格納する必要があるなら、TCP スタックは、それ自体の接続ごとに記憶域を
初期化することができます。struct tcpcb 制御ブロック構造体の t_fb_ptr
フィールドは、この接続ごとに記憶域へのポインタを保持するために予約されて
います。TCP スタックがこの代替の記憶域を使用するなら、それは、t_fb_ptr ポ
インタの値が NULL に初期化されないことを理解しているべきです。したがっ
て、それは、このフィールドを初期化するために、tfb_tcp_fb_init 関数を使用
するべきです。さらに、ソケットがクローズされるとき、記憶域を割り付けて解
放する tfb_tcp_fb_fini 関数を使用するべきです。
代替の TCP ソケットがデータの異なったセットを保持することを理解されていま
す。しかしながら、データが、標準化された形式でユーザとシステムの残りの両
方で利用可能であることを保証するために、代替の TCP スタックは、TCP 制御ブ
ロックのすべてのフィールドを実用的な最も大きな範囲に更新しなければなりま
せん。
戻り値
register_tcp_functions(), register_tcp_functions_as_name(),
register_tcp_functions_as_names() と deregister_tcp_functions() 関数は、
成功すると、0 を返し、失敗すると 0 以外を返します。特に、
deregister_tcp_functions() は、接続が、もはや指定された TCP スタックを使
用されなくなるまで、EBUSY を返します。deregister_tcp_functions() のモ
ジュール呼び出しは、すべての接続が、指定された TCP スタックを使用すること
を停止するまで、ウェートする準備ができていなければなりません。
エラー
register_tcp_functions() 関数は、次の場合に失敗します:
[EINVAL] blk 引数のメンバのいずれかが、間違って設定されていま
す。
[ENOMEM] 関数が、その内部のデータのためのメモリを割り付けること
ができませんでした。
[EALREADY] 関数ブロックが、すでに同じ名前で登録されています。
deregister_tcp_functions() 関数は、次の場合に失敗します:
[EPERM] blk 引数が、カーネルのコンパイルされたデフォルトの関数
ブロックを参照しています。
[EBUSY] 関数ブロックが、1 つ以上のソケットによってまだ使用され
ているか、または現在のデフォルトの関数ブロックと定義さ
れています。
[ENOENT] blk 引数が、現在登録されない関数ブロックを参照していま
す。
関連項目
connect(2), listen(2), tcp(4), malloc(9)
歴史
このフレームワークは、FreeBSD 11.0 ではじめて登場しました。
作者
tcp_functions フレームワークは、Randall Stewart <rrs@FreeBSD.org> によっ
て書かれました。
このマニュアルページは、Jonathan Looney <jtl@FreeBSD.org> によって書かれ
ました。
FreeBSD 12.2 March 10, 2017 FreeBSD 12.2