GETSOCKOPT(2) FreeBSD システムコールマニュアル GETSOCKOPT(2)
名称
|
getsockopt, setsockopt − ソケットのオプションの取得と設定 |
ライブラリ
|
標準 C ライブラリ (libc, −lc) |
書式
|
#include <sys/types.h> int |
|
getsockopt(int s, int level, int optname, void * restrict optval, socklen_t * restrict optlen); int |
|
setsockopt(int s, int level, int optname, const void *optval, socklen_t optlen); |
|
解説 |
|
getsockopt() と setsockopt() システムコールは、ソケットに対応する オプ ションを操作します。オプションは複数のプロトコルレベルに存在する可能性が あります。これらは必ず最上位の ‘‘ソケット’’ レベルに存在します。 ソケットオプションを操作する際は、オプションが常駐するレベルおよびオプ ションの名前を指定する必要があります。ソケットレベルでオプションを操作す るには level を SOL_SOCKET として指定します。他のレベルでオプションを操作 するには、オプションを制御している適切なプロトコルのプロトコル番号を指定 します。例えば、オプションが TCP プロトコルによって解釈されることを指示す るには、 level を TCP のプロトコル番号に設定する必要があります。 getprotoent(3) を参照してください。 optval と optlen 引数は、 setsockopt() がオプション値にアクセスするために 使用されます。 getsockopt() の場合、これらは要求されたオプションの値が返 されるバッファを識別します。 getsockopt() の場合、 optlen は値と結果の引 数であり、初期には optval の指すバッファのサイズが入っており、戻り時に修 正されて返された値の実際のサイズを示すようになります。オプション値を指定 しないか、またはオプション値が返されない場合、 optval に NULL を指定して もかまいません。 optname 引数および指定のオプションは、解釈されずに、解釈用の該当プロトコ ルモジュールに渡されます。インクルードファイル <sys/socket.h> には後述す るソケットレベルオプション用の定義が入っています。他のプロトコルレベルの オプションは形式と名称がさまざまです。マニュアルのセクション 4 の該当する エントリを参照してください。 ほとんどのソケットレベルのオプションは optval 用に int 引数を使用します。 setsockopt() の場合、ブール演算を有効にするためには引数は 0 でない必要が あり、オプションを無効にする場合は 0 である必要があります。 SO_LINGER は、 <sys/socket.h> で定義された struct linger 引数を使用します。これは、 目的の状態のオプションとリンガ間隔 (後述) を指定します。 SO_SNDTIMEO と SO_RCVTIMEO は、 <sys/time.h> で定義された struct timeval 引数を使用しま す。 以降のオプションがソケットレベルで認識されます。別記した場合を除いて、各 オプションが getsockopt() で調べられ、 setsockopt() で設定されます。 |
|
SO_DEBUG デバッグ情報の記録を有効にします SO_DEBUG は下層のプロトコルモジュール内でデバッグを有効にします。 SO_REUSEADDR は、 bind(2) システムコールで指定されたアドレスを検証するの に使用する規則で、ローカルアドレスの再利用が可能であることを示します。 SO_REUSEPORT は、ポートをバインドする前の複数のプロセスがすべて SO_REUSEPORT を設定している場合に、複数のプロセスによる完全に重複したバイ ンドが可能になるようにします。このオプションは、プログラムの複数のインス タンスそれぞれが、バインドされたポートを宛先とする UDP/IP マルチキャスト またはブロードキャストのデータグラムを受信できるようにします。 SO_KEEPALIVE は接続されたソケット上でメッセージの周期的な送信を有効にしま す。接続された一方がこれらのメッセージに応答できない場合は接続が破壊され ていると考えられ、ソケットを使用しているプロセスはデータを送信しようとす るときに SIGPIPE シグナルによって通知を受けます。 SO_DONTROUTE は発信メッ セージが標準の経路設定機能をバイパスする必要があることを示します。代わり に、メッセージは、宛先アドレスのネットワーク部分に従って該当するネット ワークインタフェースに転送されます。 SO_LINGER は送信されていないメッセージがソケットの待ち行列にあり、しかも close(2) が実行される時に行われる処置を制御します。ソケットがデータの信頼 できる配信を確約し、しかも SO_LINGER が設定されている場合、データを送信で きるまで または情報を配信できない (リンガ間隔と呼ばれるタイムアウト時間 は、 SO_LINGER が要求されるときに setsockopt() システムコール内で秒単位で 指定されます) と判定するまで、システムはプロセスを close(2) 上でブロック します。 SO_LINGER が無効の状態で close(2) が起動されると、システムは、プ ロセスが可能な限り迅速に処理を継続できる方法でクローズ処理を行います。 オプション SO_BROADCAST は、ソケット上でブロードキャストデータグラムを送 信するパーミッションを要求します。ブロードキャストは、システムの初期バー ジョンでは特権操作でした。バンド外のデータをサポートするプロトコルで、 SO_OOBINLINE オプションは、バンド外のデータが受信された順番で通常のデータ 入力待ち行列に配置されることを要求します。そして、これは MSG_OOB フラグな しに recv(2) 呼び出しまたは read(2) 呼び出しでアクセスできます。常に この オプションが設定されているかのように動作するプロトコルもあります。 SO_SNDBUF と SO_RCVBUF は、それぞれ、出力および入力用に割り当てられる通常 のバッファサイズを調整するオプションです。バッファのサイズは、高ボリュー ム接続のために増加することができますし、着信データの可能なバックログを制 限するために減少させることもできます。システムはこれらの値について 1 つの 絶対最大値を設定します。この最大値は sysctl(3) MIB 変数 ‘‘kern.ipc.maxsockbuf’’ によってアクセスできます。 SO_SNDLOWAT は出力操作に最小カウントを設定するオプションです。ほとんどの 出力操作は、送信用のプロトコルにデータを配信し、フロー制御のためにブロッ クしながら呼び出しによって与えられたすべてのデータを処理します。ノンブ ロッキング出力操作は、ブロックなしのフロー制御に従って許容される限界まで データを処理しますが、フロー制御が最低基準値または要求全体のいずれか小さ い方を処理することを許容しない場合はデータを処理しません。ソケットへの書 込み能力を試験する select(2) 操作が真で返るのは、最低基準値を処理できる場 合だけです。 SO_SNDLOWAT のデフォルト値はネットワーク効率性のために適切な サイズ (多くの場合は 1024) に設定されます。 SO_RCVLOWAT は入力操作の最小 カウントを設定するオプションです。一般に、受信呼び出しは、いくらかの (0 でない) データが受信されるまでブロックしてから、利用できる量または要求さ れた量のいずれか少ない方とともに戻ります。 SO_RCVLOWAT のデフォルト値は 1 です。 SO_RCVLOWAT にもっと大きな値が設定されている場合、受信呼び出しのブ ロックは通常、最低基準値または要求された量のいずれか小さい方が受信される まで待機します。受信呼び出しは、エラーが発生したり、シグナルが捕らえられ たり、または受信待ち行列内の次のデータのタイプが返されたものと異なる場合 は、最低基準値より小さい値でも戻ることがあります。 SO_SNDTIMEO は出力操作についてタイムアウト値を設定するオプションです。こ れは、出力操作完了の待機を制限するために使用される秒数、マイクロ秒数を struct timeval 引数で指定します。送信操作が指定された時間以上ブロックされ た場合、部分的なカウントで戻るか、またはデータが送信されていない場合はエ ラー EWOULDBLOCK で戻ります。現在の実装では、このタイマは追加の各データが プロトコルに配信されるたびに再起動され、これはサイズが出力用の最低基準値 から最高基準値の範囲に至る出力部分に適用されることを意味します。 SO_RCVTIMEO は入力操作についてタイムアウト値を設定するオプションです。こ れは入力操作完了の待機を制限するために使用される秒数、マイクロ秒数を struct timeval 引数で指定します。現在の実装では、このタイマは追加のデータ がプロトコルによって受信されるたびに再起動されるので、制限は実際には休止 期間のタイマとなります。追加のデータを受信することなく受信操作がこれだけ の時間についてブロックされた場合、短いカウントで戻るか、またはデータが受 信されていない場合はエラー EWOULDBLOCK で戻ります。 SO_ACCEPTFILTER は、ソケット上に accept_filter(9) を置きます。これによ り、待ち受けしているストリームソケットに入ってくる接続が accept(2) に渡さ れる前にフィルタされることになります。念のため繰り返します。フィルタをソ ケット上にインストールする前に、ソケットに対して listen(2) 呼び出す必要が あります。そうしないと setsockopt() システムコールが失敗します。 struct accept_filter_arg {
char af_name[16];
char af_arg[256-16];
};
optval 引数は struct accept_filter_arg を指さなくてはなりません。この構造 体が accept_filter(9) を選択、設定します。 af_name 引数は、アプリケーショ ンが待ち受けソケット上に置きたいと思っている accept フィルタの名前で埋め なくてはなりません。オプションの引数 af_arg は、 af_name で指定された accept フィルタに渡すことができるものです。これにより、ソケットに置かれる 時にさらなる設定オプションを提供します。 NULL を optval 中で渡すと、フィ ルタが削除されます。 最後に、 SO_TYPE と SO_ERROR は getsockopt() でだけ使用されるオプションで す。 SO_TYPE では SOCK_STREAM のようなソケットのタイプが返ります。これは スタートアップ時にソケットを継承するようなサーバに便利です。 SO_ERROR は ソケット上で延期中のエラーを返し、エラー状態をクリアします。これは接続さ れたデータグラムソケット上の非同期的エラーをチェックしたり、その他の非同 期エラーをチェックするのに使用できます。 |
戻り値
|
成功して終了したときには値 0 を返します。そうでない場合、値 -1 が返され、 グローバル変数 errno が設定されてエラーを示します。 |
エラー
|
呼び出しは次の場合を除いて正常です: |
[EBADF]
|
引数 s が有効な記述子ではありません。 [ENOTSOCK] [ENOPROTOOPT] [EFAULT] [EINVAL] 関連項目 |
|
ioctl(2), socket(2), getprotoent(3), sysctl(3), protocols(5), sysctl(8), accept_filter(9) |
バグ
|
ソケットオプションのいくつかはシステムの低いレベルで処理される必要があり ます。 |
歴史
|
getsockopt() システムコールは 4.2BSD ではじめて登場しました。 FreeBSD 10.0 May 2, 1995 FreeBSD 10.0 |