GETSOCKOPT(2)

名前
getsockopt, setsockopt - ソケットのオプションの設定と取得を行なう

書式
#include <sys/types.h>
#include <sys/socket.h>

int getsockopt(int s, int level, int optname, void *optval, int *optlen);

int setsockopt(int s, int level, int optname, const void *optval, int optlen);

説明
getsockopt と setsockopt はソケットに関連する options を操作する。オプションは複数のプロトコル層(level)に存在するかもしれないが、 これらは常に最上位の socket 層へと設定される。 ソケット・オプションを操作する際には、オプションの層(level)とオプションの 名前を指定しなければならない。ソケット層でオプションを操作する為には、 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 で、二値(boolean)オプションを有効(enable)にするにはゼロ以外を指定し、 無効(disable)にするにはゼロを指定する。 SO_LINGER はパラメーターとして <linux/socket.h> で定義された linger 構造体 を使用する。この構造体にはこのオプションの望のましい状態と 遅延時間(linger interval)(下記参照)を指定する。 SO_SNDTIMEO と SO_RCVTIMEO は <sys/time.h> に定義された timeval 構造体 をパラメーターとして使用する。 以下のオプションはソケット層で認識される。 特に注記されてなければ、getsockopt で調べ setsockopt で設定できる。

SO_DEBUG
    デバッグ情報の記録を有効にする

SO_REUSEADDR
    ローカル・アドレスの再利用を可能にする

SO_KEEPALIVE
    接続を生きている(alive)状態に保つ

SO_DONTROUTE
    外向きの通信のルーティングの迂回を有効にする

SO_LINGER
    データが存在する時にクローズ(close)を遅延させる

SO_BROADCAST
    ブロードキャスト通信を送信する許可を与える

SO_OOBINLINE
    帯域外(out-of-band)データの帯域内での受信を有効にする

SO_SNDBUF
    送信用のバッファー・サイズを設定する

SO_RCVBUF
    受信用のバッファー・サイズを設定する

SO_SNDLOWAT
    送信の最小値を設定する

SO_RCVLOWAT
    受信の最小値を設定する

SO_SNDTIMEO
    送信の時間切れ(timeout)値を取得する (取得のみ可能)

SO_RCVTIMEO
    受信の時間切れ(timeout)値を取得する (取得のみ可能)

SO_TYPE
    ソケットの型を取得する (取得のみ可能)

SO_ERROR
    ソケットのエラー状態を取し、それをクリアする (取得のみ可能)

SO_DEBUG は下層のプロトコル・モジュールのデバッグも有効にする。 SO_REUSEADDR は bind(2) コールで与えられた有効なアドレスを使用するための規則が ローカル・アドレスの再使用を許すことを指示する。 SO_KEEPALIVE は接続されたソケットに定期的にメッセージを送るようにする。 接続相手がこれらのメッセージへの応答に失敗した場合、 接続が切れたとみなされ、ソケットを使用しているプロセスが データを送信しようと試みた時に SIGPIPE シグナルで通知される。 SO_DONTROUTE は外向きの通信が標準のルーティング機能を迂回することを指示する。 代りに、通信は目的アドレスのネットワーク部分を参照して適切な ネットワーク・インターフェースへと直接送られる。 SO_LINGER は未配送のメッセージがソケット上のキューに入っている状態で close(2) が実行された場合にとられる行動を制御する。 ソケットがデータの確実な転送を保証していて、 SO_LINGER が設定されている場合、システムはデータの転送が可能になるか、 情報の転送が不可能であると決定されるまで、システムは close の処理を停止(block)する。(時間切れ(time out)期間は SO_LINGER を要求した時に setsockopt
コールで指定した遅延時間(linger    interval)となる。)
SO_LINGER が無効で close が実行された場合、システムはすぐに close 処理を行ない できるだけ早く処理を継続できるようにする。 linger 構造体は <linux/socket.h> で以下のように定義されている:

    struct linger {
            int  l_onoff;   /* Linger active */
            int  l_linger;  /* How long to linger for */
    };
l_onoff は遅延を行なうかどうかを指示する。これを 1 に設定すると l_linger にプロセスが close を行なうまでにどれだけの時間を待つかが百分の一秒単位で 含まれているとみなす。 l_onoff にゼロを設定した場合、プロセスはシステム・コールからすぐに返ってくる。 SO_BROADCAST オプションはソケットにデータグラムをブロードキャストすることを 許可する。 ブロードキャストは初期のバージョンのシステムでは特権操作だった。 帯域外データをサポートしたプロトコルで、 SO_OOBINLINE オプションは帯域外データを通常の入力キューに受信データとして置く ことを要求する; これは MSG_OOB フラグを使用しなくてもも、 recv や read でアクセスすることができる。いくつかのプロトコルは常に このオプションが設定されているかのように作動する。 SO_SNDBUF と SO_RCVBUF はそれぞれ送信、受信バッファーに割り当てられたバッファーのサイズを 変更する。大容量の接続のためにバッファーのサイズを増加させたり、 受信データの蓄積を制限するためにバッファーを減少させたりできる。 SO_SNDLOWAT オプションは送信操作のための最低量を設定する。ほんどの出力操作では そのコールによって与えられたデータを全て処理し、送信のためにプロトコル にデータを配送したり、フロー制御のために必要ならば停止(block) したりする。非停止(non-blocking)出力操作では、停止することなしに フロー制御できれば可能な限りのデータを処理する。しかしフロー制御が 最低量の小量データを許していなかったり、一度に全てを 処理することを要求していた場合にはデータは全く処理されない。 ソケットへの書き込みを試す select(2) 操作は、最低量が処理できる場合にのみ真となる。 SO_SNDLOWAT のデフォルト値はネットワーク効率の良い値に設定されており、 たいていは 1024 である。 SO_RCVLOWAT オプションは受信操作の最低量を設定する。一般に、受信用のコールは なんらかのデータを受信するまで停止する。そして要求された量か、 それより小さい可能な限りの量を返す。 SO_RCVLOWAT のデフォルトは 1である。もし SO_RCVLOWAT が大きな値に設定された場合、その最低量か要求された量のデータを 受信するまで停止する。この場合でも受信コールは エラーが発生したり、シグナルを受けたり、 受信キューの次のデータの型が返すべきものと異なっていた 場合には少ない量データを返すかもしれない。 SO_SNDTIMEO オプションは送信操作の時間切れ(timeout)の時間を取得する。 (これは getsockopt でのみ使用できる)。 これは送信操作を完了するまでの待ち時間の限界の秒とマイクロ秒を struct timeval パラメーターを使用して返す。もし送信操作がこの時間だけ停止すると、 部分的に送信できた値か、全く送信できなかった場合には EWOULDBLOCK エラーを返す。現在の実装において、このタイマーは追加のデータが プロトコルに渡されるごとに再起動され、この制限が送信の最低量から 最高量までのサイズの範囲の出力部分に適用されることを意味している。 SO_RCVTIMEO オプションは受信操作の時間切れ(timeout)の時間を取得する。 (これは getsockopt でのみ使用できる)。 これは受信操作を完了するまでの待ち時間の限界の秒とマイクロ秒を struct timeval パラメーターを使用して返す。現在の実装において、このタイマーは プロトコルより新たなデータを受信するごとに再起動される。 それでこれは動かないタイマーのようになる。 もし受信操作が追加のデータを受信できずに、この時間だけ停止した場合には、 受信したより少ないデータか、全くデータを受信できなかった場合には EWOULDBLOCK エラーを返す。 最後に SO_TYPE と SO_ERROR オプションも getsockopt でのみ使用される。 SO_TYPE は SOCK_STREAM のようなソケットの型を返す; これは起動時のソケットを受け継ぐサーバーに便利である。 SO_ERROR は未受信のソケットのエラーを返し、エラー状態をクリアする。 データグラム接続のソケットにおける非同期(asynchronous)エラーや、 その他の非同期エラーのチェックに使用できる。

返り値
成功した場合にはゼロを返す。エラー時には -1 が返され、 errno が適切に設定される。

エラー

EBADF
    引き数 s が有効なディスクリプターでない。

ENOTSOCK
    引き数 s はファイルであり、ソケットでない。

ENOPROTOOPT
    指定された層(level)にはこのオプションは存在しない。

EFAULT
    optval で指定されたアドレスがプロセスのアドレス空間の有効な部分ではない。 getsockopt の場合、 optlen がプロセスのアドレス空間の有効な部分でない場合にもこのエラーが返される。

準拠
SVr4, 4.4BSD (これらのシステム・コールは 4.2BSD で最初に現われた)。 SVr4 には他に ENOMEM と ENOSR エラー・コードについても記述されている。 しかし、 SO_SNDLOWAT, SO_RCVLOWAT, SO_SNDTIMEO, SO_RCVTIMEO オプションに関する記述はない。

バグ
ソケットのオプションのいくつかはシステムのより低い層で 処理されるべきである。

関連項目
ioctl(2), socket(2), getprotoent(3), protocols(5)