日本語 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
RECV(2) FreeBSD システムコールマニュアル RECV(2)
名称
recv, recvfrom, recvmsg, recvmmsg -- ソケットから (複数の) メッセージを受
信する
ライブラリ
標準 C ライブラリ (libc, -lc)
書式
#include <sys/socket.h>
ssize_t
recv(int s, void *buf, size_t len, int flags);
ssize_t
recvfrom(int s, void *buf, size_t len, int flags,
struct sockaddr * restrict from, socklen_t * restrict fromlen);
ssize_t
recvmsg(int s, struct msghdr *msg, int flags);
ssize_t
recvmmsg(int s, struct mmsghdr * restrict msgvec, size_t vlen, int flags,
const struct timespec * restrict timeout);
解説
recvfrom(), recvmsg() と recvmmsg() システムコールは、ソケットからメッ
セージを受信するために使用され、接続指向であるかどうかにかかわらず、ソ
ケットでデータを受信するために使用されます。
from が NULL ポインタでなく、ソケットが接続指向でないなら、メッセージの
ソースアドレスが、書き込まれます。fromlen 引数は、値結果 (value-result)
引数で、from に関連するバッファのサイズに初期化され、そこに格納されるアド
レスの実サイズを示すように返り時に修正されます。
recv() 関数は、通常接続されたソケット (connect(2) 参照) でのみ使用され、
from 引数として渡された NULL ポインタを付けた recvfrom() と同一です。
recvmmsg() 関数は、呼び出しで複数のメッセージを受信するために使用されま
す。それらの番号は、vlen によって供給されます。メッセージは、受信の後に
msgvec ベクトルによって記述されたバッファに置かれます。各受信されたメッ
セージのサイズは、ベクトルの各要素の msg_len フィールドに置かれます。
timeout が NULL であるなら、データが、供給されたメッセージバッファごとに
利用可能であるまで、呼び出しは、ブロックします。そうでなければ、時間の指
定された量のためのデータをウェートします。タイムアウトが期限切れとなり、
受信されたデータがないなら、値 0 が、返されます。ppoll(2) システムコール
は、最初の受信が実行される前に、タイムアウトのメカニズムを実装するために
使用されます。
recvmmsg() が、受信されたメッセージの数を返すのに対して、recv(),
recvfrom() と recvmsg() は、成功して完了するとメッセージの長さを返しま
す。メッセージが供給されたバッファに適合するには長すぎるなら、メッセージ
が受信されたソケットのタイプに依存して、超過するバイトは、廃棄されるかも
しれません (socket(2) を参照)。
メッセージがソケットで利用可能でないなら、受信呼び出しは、メッセージが到
着するのを待ち、ソケットが非ブロッキング (fcntl(2) を参照) でないなら、そ
の場合に、値 -1 が返され、グローバル変数 errno は、EAGAIN に設定されま
す。recvmmsg() を除いた受信呼び出しは、通常、要求された全体の量の受信を待
つのではなく、要求された量まで、利用可能なあらゆるデータを返します。この
振る舞いは、getsockopt(2) に記述されているソケットレベルのオプション
SO_RCVLOWAT と SO_RCVTIMEO によって影響を受けます。recvmmsg() 関数は、ベ
クトルのメッセージごとのこの振る舞いを実装します。
select(2) システムコールは、より多くのデータが到着するとき、決定するため
に使用されます。
recv() 関数への flags 引数は、次の 1 つ以上の値を論理和 (OR) して形成され
ます:
MSG_OOB プロセスの帯域外のデータ
MSG_PEEK 着信メッセージをのぞき見る (peek)
MSG_WAITALL 完全な要求またはエラーを待つ
MSG_DONTWAIT ブロックしない
MSG_CMSG_CLOEXEC 受信された fds close-on-exec を設定する
MSG_WAITFORONE 最初のメッセージを受信した後にブロックしません
(recvmmsg() のためだけに)
MSG_OOB フラグは、通常のデータストリームで受信されない、帯域外のデータの
受信を要求します。いくつかのプロトコルは、通常のデータキューの先頭に促進
されたデータを置き、そのため、このフラグは、そのようなプロトコルと共に使
用することができません。MSG_PEEK フラグは、受信操作が、キューからそのデー
タを削除せずに、受信キューの始めからデータを返します。したがって、続く受
信呼び出しは、同じデータを返します。MSG_WAITALL フラグは、要求が完全に満
たされるまで、操作がブロックされることを要求します。しかしながら、呼び出
しは、シグナルが捕獲されるか、エラーまたは切断が生じるか、または、受信さ
れる次のデータが、返されたものと異なっているタイプであるなら、要求された
ものより少ないデータをまだ返すかもしれません。MSG_DONTWAIT フラグは、そう
でなければブロックするとき、返るための呼び出しを要求します。データが利用
可能でないなら、errno は、EAGAIN に設定されます。このフラグは、ANSI
X3.159-1999 (``ANSI C89'') または ISO/IEC 9899:1999 (``ISO C99'') コンパ
イルモードで利用可能ではありません。MSG_WAITFORONE フラグは、最初のメッ
セージが受信された後に、MSG_DONTWAIT を設定します。このフラグは、
recvmmsg() のために関連しているだけです。
recvmsg() システムコールは、直接供給された引数の数を最小化するために
msghdr 構造体を使用します。この構造体には、<sys/socket.h> で定義されるよ
うに、次の形式があります:
struct msghdr {
void *msg_name; /* オプションのアドレス */
socklen_t msg_namelen; /* アドレスのサイズ */
struct iovec *msg_iov; /* 分散/集中配列 */
int msg_iovlen; /* msg_iov の要素数 */
void *msg_control; /* 補助データ, 下記参照 */
socklen_t msg_controllen;/* 補助データのバッファ長 */
int msg_flags; /* 受信されたメッセージのフラグ */
};
ここで、msg_name と msg_namelen は、ソケットが接続されていないなら、発信
元アドレスを指定します。msg_name は、名前が望まれないかまたは必要でないな
ら、NULL ポインタとして与えられます。msg_iov と msg_iovlen 引数は、
read(2) で議論されているように、スキャッタ (scatter) ギャザ (gather) 位置
を記述しています。長さ msg_controllen がある msg_control 引数は、他のプロ
トコル制御に関連するメッセージまたは他の様々な補助データのためのバッファ
を指します。メッセージは、次の形式です:
struct cmsghdr {
socklen_t cmsg_len; /* データバイトカウント, hdr を含む */
int cmsg_level; /* 起源のプロトコル */
int cmsg_type; /* プロトコル特有のタイプ */
/* 次が続く
u_char cmsg_data[]; */
};
例として、accept() システムコールの直後に提供されたデータバッファなしで
recvmsg() を要求することによってユーザー接続要求データ得る、XNS/SPP また
は ISO のデータストリームの変更を学ためにこれを使用できます。
AF_UNIX ドメインソケットで、補助データは、ファイル記述子とプロセス資格証
明を渡すために使用することができます。詳細については、unix(4) を参照して
ください。
msg_flags フィールドは、受信されたメッセージにしたがって返り時に設定され
ます。MSG_EOR は、レコードの終りで、全部のレコード (一般的にタイプ
SOCK_SEQPACKET のソケットと共に使用された) が返されたデータを示します。
MSG_TRUNC は、データグラムが供給されたバッファより大きかったので、データ
グラムの後続する部分が廃棄されたことを示します。MSG_CTRUNC は、いくつかの
制御データが、補助データのためのバッファの空間の不足のために廃棄されたこ
とを示します。MSG_OOB は、促進されたデータまたは帯域外のデータが受信され
たことを示すために返されます。
recvmmsg() システムコールは、<sys/socket.h> ヘッダで次のように定義される
mmsghdr 構造体を使用します:
struct mmsghdr {
struct msghdr msg_hdr; /* メッセージのヘッダ */
ssize_t msg_len; /* メッセージの長さ */
};
データの受信で、msg_len フィールドは、受信されたメッセージの長さに更新さ
れます。
戻り値
recvmmsg() を除いて、これらの呼び出しは、受信されたバイト数を返します。
recvmmsg() は、受信されたメッセージの数を返します。エラーが起きたなら、-1
の値が返されます。
エラー
呼び出しは、次の場合に失敗します:
[EBADF] 引数 s が不正な記述子です。
[ECONNRESET] リモートのソケットの終りが強制的にクローズされました。
[ENOTCONN] ソケットが、接続指向のプロトコルと関連付けられ、接続さ
れていません (connect(2) と accept(2) を参照)。
[ENOTSOCK] 引数 s が、ソケットを参照していません。
[EMSGSIZE] 接続中にオープンされている権利 (ファイル記述子) を
recvmsg() システムコールを使用して受信しようとしまし
た。しかし、受信側プログラムのにそれらを受け取るだけの
十分な空きファイル記述子スロットがありませんでした。こ
の場合、該当する記述子は、クローズされ、保留されている
データは、別の recvmsg() 呼び出しで戻せます。
[EAGAIN] ソケットが、非ブロッキングとマークされ、受信操作が、ブ
ロックするか、または受信のタイムアウトが、設定されて、
タイムアウトが、データが受信される前に、期限が切れまし
た。
[EINTR] あらゆるデータが利用可能になる前に、受信がシグナルの配
信によって割り込まれました。
[EFAULT] (複数の) 受信バッファポインタが、プロセスのアドレス空
間の外側を指しています。
関連項目
fcntl(2), getsockopt(2), read(2), select(2), socket(2), CMSG_DATA(3),
unix(4)
歴史
recv() 関数は、4.2BSD で登場しました。recvmmsg() 関数は、FreeBSD 11.0 で
登場しました。
FreeBSD 12.2 August 19, 2018 FreeBSD 12.2