日本語 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
SOCKET(9) FreeBSD カーネル開発者マニュアル SOCKET(9)
名称
socket -- カーネルソケットインタフェース
書式
#include <sys/socket.h>
#include <sys/socketvar.h>
void
soabort(struct socket *so);
int
soaccept(struct socket *so, struct sockaddr **nam);
int
socheckuid(struct socket *so, uid_t uid);
int
sobind(struct socket *so, struct sockaddr *nam, struct thread *td);
void
soclose(struct socket *so);
int
soconnect(struct socket *so, struct sockaddr *nam, struct thread *td);
int
socreate(int dom, struct socket **aso, int type, int proto,
struct ucred *cred, struct thread *td);
int
sodisconnect(struct socket *so);
struct sockaddr *
sodupsockaddr(const struct sockaddr *sa, int mflags);
void
sofree(struct socket *so);
void
sohasoutofband(struct socket *so);
int
solisten(struct socket *so, int backlog, struct thread *td);
void
solisten_proto(struct socket *so, int backlog);
int
solisten_proto_check(struct socket *so);
struct socket *
sonewconn(struct socket *head, int connstatus);
int
sopoll(struct socket *so, int events, struct ucred *active_cred,
struct thread *td);
int
sopoll_generic(struct socket *so, int events, struct ucred *active_cred,
struct thread *td);
int
soreceive(struct socket *so, struct sockaddr **psa, struct uio *uio,
struct mbuf **mp0, struct mbuf **controlp, int *flagsp);
int
soreceive_stream(struct socket *so, struct sockaddr **paddr,
struct uio *uio, struct mbuf **mp0, struct mbuf **controlp,
int *flagsp);
int
soreceive_dgram(struct socket *so, struct sockaddr **paddr,
struct uio *uio, struct mbuf **mp0, struct mbuf **controlp,
int *flagsp);
int
soreceive_generic(struct socket *so, struct sockaddr **paddr,
struct uio *uio, struct mbuf **mp0, struct mbuf **controlp,
int *flagsp);
int
soreserve(struct socket *so, u_long sndcc, u_long rcvcc);
void
sorflush(struct socket *so);
int
sosend(struct socket *so, struct sockaddr *addr, struct uio *uio,
struct mbuf *top, struct mbuf *control, int flags,
struct thread *td);
int
sosend_dgram(struct socket *so, struct sockaddr *addr, struct uio *uio,
struct mbuf *top, struct mbuf *control, int flags,
struct thread *td);
int
sosend_generic(struct socket *so, struct sockaddr *addr, struct uio *uio,
struct mbuf *top, struct mbuf *control, int flags,
struct thread *td);
int
soshutdown(struct socket *so, int how);
void
sotoxsocket(struct socket *so, struct xsocket *xso);
void
soupcall_clear(struct socket *so, int which);
void
soupcall_set(struct socket *so, int which,
int (*func)(struct socket *, void *, int), void *arg);
void
sowakeup(struct socket *so, struct sockbuf *sb);
#include <sys/sockopt.h>
int
sosetopt(struct socket *so, struct sockopt *sopt);
int
sogetopt(struct socket *so, struct sockopt *sopt);
int
sooptcopyin(struct sockopt *sopt, void *buf, size_t len, size_t minlen);
int
sooptcopyout(struct sockopt *sopt, const void *buf, size_t len);
解説
カーネル socket プログラミングインタフェースは、カーネル内の消費者が
socket(2) ユーザ API を使用して許可されたものと同様の方法でローカルとネッ
トワークソケットオブジェクトと情報をやりとりすることを許可します。これら
のインタフェースは、分散ファイルシステムと他のネットワーク意識カーネル
サービスによる使用に適しています。ユーザ API がファイル記述子で動作してい
る間に、カーネルインタフェースは、struct socket ポインタで直接動作しま
す。カーネル API のいくつかの部分は、単にユーザ API を実装するために存在
し、カーネルコードによって使用されるものとは期待されません。ソケットの消
費者によって使用されるソケット API の部分とネットワークプロトコルの実装
は、異なります。いくつかのルーチンは、単にプロトコルの実装者のために役に
立ちます。
ほかに表示されるところを除いて、socket 関数は、スリープ可能でないカーネル
ロックが保持されている間に、スリープするかもしれなくて、ithread(9) コンテ
キストで使用のためには適切ではありません。
ソケットの作成と破壊
新しいソケットは、socreate() を使用して作成されます。socket(2) と同様に、
引数は、dom, type と proto を通して、要求されたドメイン、タイプとプロトコ
ルを指定します。ソケットは、成功すれば、aso を通して返されます。さらに、
ソケットに関連している操作を承認するために使用される資格証明は、cred と
td を通して操作を実行するスレッドを通して渡されます (そして、ソケットの生
存期間のためにキャッシュされます)。警告: ソケット作成操作の承認は、(生の
ソケットのような) いくつかのプロトコルに対してスレッドの資格証明を使用し
て実行されます。
ソケットは、close(2) と同様のセマンティックがある、soclose() を使用してク
ローズされ、解放されます。
特定の状況で、接続を切断するために、待たずに、ソケットを破壊するために適
切です、それに対して soabort() が、使用されます。これは、部分的に接続され
た状態で、着信接続のために単に適切です。競合を防ぐために、その listen (接
続を受け付け) するキューからソケットを削除するスレッドによって、参照され
ないソケットで呼び出されなければなりません。それは, プロトコルのコードに
呼び出すので、ソケットのロックは、呼び出しを持続させません。soabort() の
呼び出し側、VNET コンテキストの設定に責任があります。ソケットを解放する通
常のパスは、ソケットを当てにする参照を扱う、sofree() です。参照が解放され
るときはいつでも、さらに、参照フラグがソケットまたはプロトコルのコードで
クリアされるときはいつでも、呼び出されるべきです。sofree() への呼び出し
は、ソケットの層の外側から行われるべきではありません。外側の呼び出し側
は、代わりに soclose() を使用するべきです。
接続とアドレス
sobind() 関数は、bind(2) システムコールと同等で、アドレス nam にソケット
so をバインドします。操作は、スレッド td で資格証明を使用して認定されま
す。
soconnect() 関数は、connect(2) システムコールと同等であり、ソケット so で
アドレス nam に接続を開始します。操作は、スレッド td で資格証明を使用して
承認されます。ユーザシステムコールと違って、soconnect() は、直ちに返りま
す。呼び出し側は、ソケットミューテックスを保持して、SS_ISCONNECTING フラ
グをクリアするか、または、so->so_error を 0 以外にするためにウェートして
いる間に so->so_timeo で msleep(9) します。soconnect() が失敗するなら、呼
び出し側は、手動で SS_ISCONNECTING フラグをクリアしなければなりません。
sodisconnect() への呼び出しは、それをクローズせずに、ソケットを切断しま
す。
soshutdown() 関数は、shutdown(2) システムコールと同等であり、ソケットで部
分または全ての接続を遮断します。
ソケットは、listen (接続を受け付け) しない状態から、solisten() で listen
(接続を受け付け) するように移行されます。
ソケットオプション
sogetopt() 関数は、getsockopt(2) システムコールに同等であり、ソケット so
でソケットオプションを検索します。sosetopt() 関数は、setsockopt(2) システ
ムコールに同等であり、ソケット so でソケットオプションを設定します。
sogetopt() と sosetopt() の両方の 2 番目の引数は、ソケットオプション操作
について説明する struct sopt への sopt ポインタです。呼び出し側で割り付け
られた構造は、0 にクリアされなければならなくて、次に、ソケットオプション
操作引数を指定するために初期化されたフィールドがありませす:
sopt_dir これは、操作を取得するかまたは設定するかどうかによって
SOPT_SET または SOPT_GET を設定します。
sopt_level 操作がターゲットとされるネットワークスタックでレベルを指定
します。例えば、SOL_SOCKET。
sopt_name 設定するソケットオプションの名前を指定します。
sopt_val ソケットオプションのための引数値へのカーネル空間ポインタ。
sopt_valsize バイト単位の引数値のサイズ。
ソケットの upcall
ソケットが、データを送信するか、または受信する準備ができているとき、通知
されるソケットの所有者のために、upcall は、ソケットで登録されます。upcall
は、与えられたソケットに関連したソケットのバッファが読み込みか、または書
き込みの準備ができるとき、ソケットのフレームワークによって呼び出される関
数です。soupcall_set() は、ソケットの upcall を登録するために使用されま
す。関数 func は、登録され、ポインタ arg は、それがフレームワークによって
呼び出されるとき、2 番目の引数として渡されます。それぞれ、受信と送信イベ
ントのために upcalls を登録する、SO_RCV と SO_SND のための指定できる値。
upcall 関数 func() は、upcall が返った後に、ソケットのフレームワークに
よって行われるべきである soisconnected への呼び出すかどうかに依存して、
SU_OK または SU_ISCONNECTED のいずれかを返さなければなりません。upcall
func は、ソケットのバッファのロックの順序でロックするために soisconnected
それ自体を呼び出すことはできません。SO_RCV upcall だけが SU_ISCONNECTED
を返すべきです。SO_RCV upcall が SU_ISCONNECTED を返すとき、upcall は、ソ
ケットから削除されます。
upcall は、soupcall_clear() によってそれらのソケットから削除されます。
which 引数は、送信するか、または受信する upcall が SO_RCV または SO_SND
でクリアされるかどうかを再び指定します。
ソケット I/O
soreceive() 関数は、recvmsg(2) システムコールと同等であり、ソケット so か
らバイトのデータを受信することを試み、なにも読み込む準備ができていないな
ら、オプションでデータに対してのウェートをブロックします。データは、デー
タコピーを避けて、uio 引数を通して、または mp0 を通して呼び出し側に返され
る mbuf チェーンとして、直接カーネルまたはユーザメモリで検索されます。uio
は、常に NULL 以外でなければなりません。mp0 が NULL でないなら、uio の
uio_resid だけが使用されます。呼び出し側は、NULL でない psa 引数を通して
記憶域を提供することによって、PR_ADDR ケーパビリティでプロトコルのソケッ
トアドレスをオプションで検索できます。呼び出し側は、NULL でない controlp
引数を通して制御データ mbuf をオプションで検索できます。オプションのフラ
グは、NULL でない flagsp 引数を通して soreceive() に渡され、recvmsg(2) シ
ステムコールと同じフラグの名前空間を使用します。
sosend() 関数は、sendmsg(2) システムコールと同等であり、ソケット so を通
してバイトのデータを送信することを試み、直ちにデータを送信することができ
ないなら、オプションでブロックします。データは、データコピーを避けて、uio
引数を通して、または top を通して mbuf チェーンとして、カーネルまたはユー
ザメモリから直接送信されます。uio または top ポインタの 1 つだけは、NULL
以外になります。オプションの宛先アドレスは、プロトコルによってサポートさ
れているなら、暗黙の接続となる、NULL でない addr 引数を通して指定されま
す。呼び出し側は、NULL でない control 引数を通して制御データ mbuf をオプ
ションで送信します。フラグは、flags 引数を使用して sosend() に渡され、
sendmsg(2) システムコールと同じフラグの名前空間を使用します。
ithread(9) コンテキスト、または保持されているミューテックスでで実行してい
るカーネルの呼び出し側は、ブロッキングしないソケットを使用して、これらの
関数がスリープすることを防ぐために MSG_DONTWAIT フラグを渡したくなりま
す。
sopoll() を使用して、読み込みやすさ、書き込みやすさ、帯域外のデータ、また
はエンドオブファイルについて、ソケットに問い合わせることができます。
events のための値は、<sys/poll.h> からのシンボル値 POLLIN, POLLPRI,
POLLOUT, POLLRDNORM, POLLWRNORM, POLLRDBAND と POLLINGEOF で poll(2) に指
定できます。
soaccept() への呼び出しは、着信接続を受け付けるためにプロトコルの受け付け
ルーチンに通過されます。
ソケットのユーティリティ関数
ソケットの資格証明の uid は、socheckuid() で uid と比較されます。
既存の struct sockaddr のコピーは、sodupsockaddr() を使用して行なわれま
す。
プロトコルの実装は、ソケットの層が、利用可能なデータのソケットの消費者に
通知することができるように、sohasoutofband() を使用して、帯域外のデータの
到着のソケットの層に通知します。
カーネルの構造体の変更からユーザのコードを分離するために適した、
sotoxsocket() を使用して、struct socket の ``external-format'' のバージョ
ンを作成することができます。
プロトコルの実装
プロトコルは、solisten() のための実装を供給しなければなりません。そのよう
なプロトコルの実装は、ソケットの層の listen (接続を受け付け) 状態をチェッ
クして設定するために solisten_proto_check() と solisten_proto() を使用し
て、ソケットの層へコールバックすることができます。これらのコールバック
は、プロトコルの実装が必要に応じて、ソケットの層とプロトコルのロックを順
序付けできるように、提供されています。プロトコルは、soreceive() の実装を
供給しなければなりません。関数 soreceive_stream(), soreceive_dgram() と
soreceive_generic() は、そのような実装によって使用するために供給されてい
ます。
プロトコルの実装は、ソケットを作成し、そのソケットにプロトコルの状態をア
タッチするために sonewconn() を使用することができます。これは、listen (接
続を受け付け) しているソケットで soaccept() のために利用可能な新しいソ
ケットを作成するために使用することができます。返されたソケットには、0 の
参照カウントがあります。
プロトコルは、sopoll() のために実装を供給しなければなりません。
sopoll_generic() は、プロトコルの実装によって使用のために提供されていま
す。
関数 sosend_dgram() と sosend_generic() は、sosend() のプロトコルの実装を
援助するために供給されています。
プロトコルが新しいソケットの構造体を作るとき、soreserve() を呼び出すこと
によって、そのソケットのためにソケットのバッファ空間を予約することが必要
です。この予約の荒い反対は、ソケットのフレームワークによって自動的に呼び
出される、sorflush() によって行なわれます。
プロトコルがソケットが読み込むか、または書き込む準備ができているようにな
るのを待つスレッドを起こす必要があるとき、sowakeup() の変異型が使用されま
す。sowakeup() 関数は、プロトコルのコードによって直接呼び出されるべきでは
ありません、代わりに、それぞれ、まだロックされていない対応するソケットの
バッファのロック、または既に保持されているリーダとライタ、のためのラッパ
(wrappers) sorwakeup(), sorwakeup_locked(), sowwakeup() と
sowwakeup_locked() を使用します。
関数 sooptcopyin() と sooptcopyout() は、ユーザとカーネルコードの間の
struct sockopt データを転送するために役に立ちます。
関連項目
bind(2), close(2), connect(2), getsockopt(2), recv(2), send(2),
setsockopt(2), shutdown(2), socket(2), ng_ksocket(4), ithread(9),
msleep(9), ucred(9)
歴史
socket(2) システムコールは 4.2BSD で登場しました。このマニュアルページは
FreeBSD 7.0 で導入されました。
作者
このマニュアルページは Robert Watson と
Benjamin Kaduk によって書かれました。
バグ
明白に渡された資格証明、明白に渡されたスレッドにぶら下がる資格証明、
curthread における資格証明とソケット作成時からのキャッシュされた資格証明
の使用は、矛盾していて、予期されない振る舞いを導くかもしれません。いくつ
かの td 引数は、cred 引数であるべきか、または単に全く存在していないことが
可能です。
呼び出し側は、soconnect() がエラーを返すなら、手動で SS_ISCONNECTING をク
リアする必要があります。
MSG_DONTWAIT フラグは、sosend() のために実装されないで、0 コピーソケット
が有効にされるとき、soreceive() で常に動作するとは限りません。
このマニュアルページは、ブロッキング I/O を使用しないで読み易さ/書き易さ
のために、ソケットの upcall を登録するか、またはソケットをモニタする方法
を説明していません。
soref() と sorele() 関数は、説明されていません、そして sorele() が、
soclose() の後で最後に呼び出されるとき、混乱して潜在的に不正確な相互作用
のために、多くの場合、使用するべきではありません。
FreeBSD 11.4 May 26, 2014 FreeBSD 11.4