日本語 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
GETSOCKOPT(2) FreeBSD システムコールマニュアル GETSOCKOPT(2)
名称
getsockopt, setsockopt -- ソケットのオプションを取得し設定する
ライブラリ
標準 C ライブラリ (libc, -lc)
書式
#include <sys/types.h>
#include <sys/socket.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() システムコールは、ソケットに関連したオプショ
ンを操作します。オプションは、複数のプロトコルレベルで存在します。それら
は、最上の ``socket'' (ソケット) レベルで常に存在します。
ソケットのオプションを操作するとき、オプションのレベルとオプションの名前
は、指定されなければなりません。ソケットのレベルでオプションを操作するた
め、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
引数を使用します。
次のオプションは、ソケットレベルで認識されます。プロトコル特有のオプショ
ンについては、プロトコルのマニュアルページ、例えば、ip(4) または tcp(4)
を参照してください。言及されることを除いて、それぞれは、getsockopt() で調
べられ、setsockopt() で設定されます。
SO_DEBUG デバッグ情報の記録を有効にする
SO_REUSEADDR ローカルアドレスの再使用を有効にする
SO_REUSEPORT 重複したアドレスとポートのバインドを有効にする
SO_REUSEPORT_LB ロードバランシングで二重のアドレスとポートのバイ
ンディングを有効にします
SO_KEEPALIVE 接続したままとすることを有効にする
SO_DONTROUTE 発信メッセージについて経路制御のバイパスを有効に
する
SO_LINGER データが存在するなら、クローズで残存する
SO_BROADCAST ブロードキャストメッセージを送信するパーミッショ
ンを有効にする
SO_OOBINLINE 帯域内での帯域外データの受信を有効にする
SO_SNDBUF 出力のためのバッファサイズを設定する
SO_RCVBUF 入力のためのバッファサイズを設定する
SO_SNDLOWAT 出力のための最小カウントを設定する
SO_RCVLOWAT 入力のための最小カウントを設定する
SO_SNDTIMEO 出力のためのタイムアウト値を設定する
SO_RCVTIMEO 入力のためのタイムアウト値を設定する
SO_ACCEPTFILTER 接続を受け付け (listen) ソケットでの受け付けフィ
ルタを設定する
SO_NOSIGPIPE ソケットのための SIGPIPE の生成を制御する
SO_TIMESTAMP データグラムでタイムスタンプの受信を有効にする
SO_BINTIME データグラムでタイムスタンプの受信を有効にする
SO_ACCEPTCONN ソケットの接続を受け付け (listen) 状態を取得する
(取得のみ)
SO_DOMAIN ソケットのドメインを取得する (取得のみ)
SO_TYPE ソケットのタイプを取得する (取得のみ)
SO_PROTOCOL ソケットのためのプロトコル番号を取得する (取得の
み)
SO_PROTOTYPE Linux SO_PROTOCOL のための SunOS の別名 (取得の
み)
SO_ERROR ソケットでのエラーを取得してクリアする (取得の
み)
SO_SETFIB ソケットのための関連 FIB (経路表) を設定する (設
定のみ)
次のオプションは、FreeBSD で認識されます:
SO_LABEL ソケットの MAC ラベルを取得する (取得のみ)
SO_PEERLABEL ソケットの通信相手の MAC ラベルを取得する (取得
のみ)
SO_LISTENQLIMIT ソケットのバックログの制限を取得する (取得のみ)
SO_LISTENQLEN ソケットの完全なキューの長さを取得する (取得の
み)
SO_LISTENINCQLEN ソケットの不完全なキューの長さを取得する (取得
のみ)
SO_USER_COOKIE ソケットのための 'so_user_cookie' 値を設定する
(uint32_t, 設定のみ)
SO_TS_CLOCK SO_TIMESTAMP によって返されたタイムスタンプの特
有の形式を設定します
SO_MAX_PACING_RATE ソケットのためのバイト/秒単位で最大の転送レート
を設定します
SO_NO_OFFLOAD プロトコルのオフロードを無効にします
SO_NO_DDP 直接のデータの配置のオフロードを無効にします
SO_DEBUG は、基本的なプロトコルモジュールのデバッグを有効にします。
SO_REUSEADDR は、bind(2) システムコールで供給される有効化されたアドレスで
使用される規則が、ローカルなアドレスの再利用が許可されるべきであることを
示します。
SO_REUSEPORT は、複数のプロセスすべてが、ポートをバインドする前に、
SO_REUSEPORT を設定するなら、複数のプロセスによって完全に重複するバインド
を許可します。このオプションは、バインドされたポートに向かうことになって
いる UDP/IP マルチキャストまたはブロードキャスト (同報通信) データグラム
をそれぞれ受信するためにプログラムの複数のインスタンスを許可します。
SO_REUSEPORT_LB は、それらすべてがポートをバインドする前に、
SO_REUSEPORT_LB を設定するなら、複数のプロセスによって完全に二重のバイン
ディングを許可します。着信してくる TCP と UDP 接続は、ローカルポート番
号、外部 IP アドレスとポート番号のハッシュ関数に基づいて共有プロセスに分
配されます。最大 256 のプロセスが、1 つのソケットを共有することができま
す。
SO_KEEPALIVE は、接続されたソケットでメッセージの周期的な送信を有効にしま
す。接続されたパーティが、これらのメッセージに応答することに失敗するな
ら、接続は、壊れているとみなされ、ソケットを使用しているプロセスは、デー
タを送信することを試みるとき、SIGPIPE シグナルを通して通知されます。
SO_DONTROUTE は、発信メッセージが標準の経路制御機能をバイパスするべきであ
ることを示します。代わりに、メッセージは、宛先アドレスのネットワーク部分
にしたがって適切なネットワークインタフェースに向けられます。
SO_LINGER は、送信されていないメッセージがソケットのキューに入れられると
き、取られるアクションを制御し、close(2) が実行されます。ソケットが、デー
タの信頼できる配信を保証し、SO_LINGER が設定されるなら、システムは、デー
タを送信することができるまで、または、それが確信するまで、情報を配信する
ことができない、close(2) の試みでプロセスをブロックします (残存する間隔と
呼ばれる、タイムアウト期間は、SO_LINGER が要求されるとき、setsockopt() シ
ステムコールで秒単位で指定されます)。SO_LINGER が無効にされ、close(2) が
発行されるなら、システムは、できるだけ迅速に継続するプロセスを許可する方
法でクローズを処理します。
オプション SO_BROADCAST は、ソケットでブロードキャスト (同報通信) データ
グラムを送信する許可を要求します。ブロードキャスト (同報通信) は、システ
ムの初期のバージョンで特権を与えられた操作でした。
帯域外のデータをサポートするプロトコルで、SO_OOBINLINE オプションは、受信
されるように、通常のデータ入力キューに置かれる帯域外のデータを要求しま
す。次に、それは、MSG_OOB フラグなしで recv(2) または read(2) 呼び出しで
アクセス可能です。いくつかのプロトコルは、常に、あたかもこのオプションが
設定されているかのように振る舞います。
SO_SNDBUF と SO_RCVBUF は、それぞれ、出力と入力バッファのために割り付けら
れた通常のバッファサイズを調整するオプションです。バッファサイズは、大量
の接続のために増加するか、または着信データの可能なバックログを制限するた
めに減少されます。システムは、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 で返ります。
与えられたソケットのためのデフォルトの FIB (経路表) を上書きするために
SO_SETFIB を使用することができます。値は、0 から sysctl net.fibs から返さ
れた数より少なくなければなりません。
ソケットの uint32_t so_user_cookie フィールドに設定するために
SO_USER_COOKIE を使用することができます。値は、uint32_t であり、ソケット
に関連するトラフィックを操作するカーネルコードで使用することができます。
そのフィールドのためのデフォルト値は、0 です。例として、skipto ターゲット
または ipfw/dummynet のパイプ番号として、その値を使用することができます。
SO_ACCEPTFILTER は、accept(2) のために提出される前に、listen (接続を受け
付け) しているストリームのソケットで着信接続をフィルタにかける、ソケット
に accept_filter(9) 置きます。もう一度、listen(2) は、フィルタをインス
トールすることを試みる前に、ソケットで呼び出されなければなりません、そう
でなければ、setsockopt() システムコールは、失敗します。
struct accept_filter_arg {
char af_name[16];
char af_arg[256-16];
};
optval 引数は、accept_filter(9) を選択し、設定する struct
accept_filter_arg を指すべきです。af_name 引数は、アプリケーションが、
listen (接続を受け付け) しているりソケットに置くことを望む受け付けフィル
タの名前で満たされるべきです。アタッチ時間で追加の設定オプションを提供す
るために af_name によって指定された受け付けフィルタに、オプションの引数
af_arg を渡すことができます。NULL の optval を渡すことは、フィルタを削除
します。
SO_NOSIGPIPE オプションは、接続されたソケットに書き込むとき、もう一方の端
がクローズされた所でエラー EPIPE で返り、通常、送られた SIGPIPE シグナル
の生成を制御します。
SO_TIMESTAMP または SO_BINTIME オプションが SOCK_DGRAM ソケットで有効にさ
れるなら、recvmsg(2) 呼び出しは、データグラムが受信されるときに対応するタ
イムスタンプを返します。しかしながら、それは、例えば、リソース不足のため
です。msghdr 構造体の msg_control フィールドは、SO_TIMESTAMP のための
struct timeval と SO_BINTIME のための struct bintime が続く cmsghdr 構造
体を含んでいるバッファを指します。cmsghdr フィールドには、デフォルトで
TIMESTAMP に対して次の値があります:
cmsg_len = CMSG_LEN(sizeof(struct timeval));
cmsg_level = SOL_SOCKET;
cmsg_type = SCM_TIMESTAMP;
そして、SO_BINTIME のためには、次の通りです:
cmsg_len = CMSG_LEN(sizeof(struct bintime));
cmsg_level = SOL_SOCKET;
cmsg_type = SCM_BINTIME;
追加のタイムスタンプのタイプは、SO_TIMESTAMP が有効にされるとき、
SCM_TIMESTAMP の代わりに返される特有のタイムスタンプ形式を要求する
SO_TS_CLOCK で SO_TIMESTAMP に続いていることによって利用可能です。これら
の SO_TS_CLOCK 値は、FreeBSD で認識されます:
SO_TS_REALTIME_MICROリアルタイム (SCM_TIMESTAMP, struct timeval),
デフォルト
SO_TS_BINTIME リアルタイム (SCM_BINTIME, struct bintime)
SO_TS_REALTIME リアルタイム (SCM_REALTIME, struct timespec)
SO_TS_MONOTONIC単調な時間 (SCM_MONOTONIC, struct timespec)
SO_ACCEPTCONN, SO_TYPE, SO_PROTOCOL (とその別名 SO_PROTOTYPE) と SO_ERROR
は、getsockopt() でだけ使用されるオプションです。ソケットが現在接続を受け
付けるかどうかに関係なく、SO_ACCEPTCONN が返されます、すなわち、listen(2)
システムコールがそのソケットで呼び出されかどうかです。SO_TYPE は、
SOCK_STREAM のようなソケットのタイプを返します。それは、スタートアップで
ソケットを継承するサーバの役に立ちます。SO_PROTOCOL は、AF_INET と
AF_INET6 アドレスファミリに対して、ソケットのためのプロトコル番号を返しま
す。SO_ERROR は、ソケットであらゆる保留中のエラーを返し、エラー状態をクリ
アします。それは、接続されたデータグラムのソケットで非同期なエラーまたは
他の非同期なエラーをチェックするために使用されます。
SO_LABEL は、ソケットの MAC ラベルを返します。SO_PEERLABEL は、ソケットの
ピア (通信相手) の MAC ラベルを返します。利用者のカーネルは、 MAC サポー
ト付きでコンパイルされなければならないことに注意してください。詳細につい
ては、mac(3) を参照してください。
SO_LISTENQLIMIT は、listen(2) によって設定されるように、キューに入れられ
た接続の最大の数を返します。SO_LISTENQLEN は、受け付けられない完全な接続
の数を返します。SO_LISTENINCQLEN は、受け付けられない不完全な接続の数を返
します。
SO_MAX_PACING_RATE は、バイト/秒単位で与えられた符号なし 32 ビット値に転
送レートを制限するためにソケットと基本的なネットワークアダプタのレイヤを
指示します。
SO_NO_OFFLOAD は、プロトコルのオフロードのサポートを無効にします。現在の
ところ、これは、TCP オフロードエンジンを使用することから TCP ソケットを防
止します。SO_NO_DDP は、直接のデータの配置 (DDP) として知られている特有の
TCP オフロードのサポートを無効にします。DDP は、aio_read(2) を使用して、
ユーザに供給されたバッファの 0 クリアのコピーを通して受信される再構築され
た TCP データストリームを許可する Chelsio ネットワークアダプタによってサ
ポートされるオフロードです。
戻り値
成功して終了したときには値 0 を返します。そうでない場合、値 -1 が返され、
グローバル変数 errno にエラーを示す値が設定されます。
エラー
getsockopt() と setsockopt() システムコールは、次の場合を除いて成功しま
す:
[EBADF] 引数 s が、有効な記述子ではありません。
[ENOTSOCK] 引数 s が、ソケットではなく、ファイルです。
[ENOPROTOOPT] オプションが、指示されたレベルで未知です。
[EFAULT] optval によって指されたアドレスが、プロセスのアドレス
空間の有効な部分ではありません。getsockopt() につい
て、optlen がプロセスのアドレス空間の有効な部分ではな
いなら、また、このエラーが返されます。
[EINVAL] listen (接続を受け付け) していないソケットで
accept_filter(9) をインストールすることが試みられまし
た。
[ENOMEM] 要求をサービスする必要があった、メモリ割り付けが失敗し
ました。
また setsockopt() システムコールは、次のエラーを返します:
[ENOBUFS] 不十分なリソースが、操作を実行するために、システムで利
用可能でした。
関連項目
ioctl(2), listen(2), recvmsg(2), socket(2), getprotoent(3), mac(3),
sysctl(3), ip(4), ip6(4), sctp(4), tcp(4), protocols(5), sysctl(8),
accept_filter(9), bintime(9)
歴史
getsockopt() と setsockopt() システムコールは、4.2BSD で登場しました。
バグ
ソケットオプションのいくつかは、システムの低いレベルで扱われるべきです。
FreeBSD 12.2 June 03, 2020 FreeBSD 12.2