.\" Copyright (c) 1983, 1990, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)recv.2 8.3 (Berkeley) 2/21/94
.\" %FreeBSD: src/lib/libc/sys/recv.2,v 1.8.2.7 2001/08/17 15:42:45 ru Exp %
.\"
.\" $FreeBSD: doc/ja_JP.eucJP/man/man2/recv.2,v 1.6 2001/07/29 05:15:14 horikawa Exp $
.Dd February 21, 1994
.Dt RECV 2
.Os
.Sh 名称
.Nm recv ,
.Nm recvfrom ,
.Nm recvmsg
.Nd ソケットからメッセージを受信する
.Sh ライブラリ
.Lb libc
.Sh 書式
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft ssize_t
.Fn recv "int s" "void *buf" "size_t len" "int flags"
.Ft ssize_t
.Fn recvfrom "int s" "void *buf" "size_t len" "int flags" "struct sockaddr *from" "socklen_t *fromlen"
.Ft ssize_t
.Fn recvmsg "int s" "struct msghdr *msg" "int flags"
.Sh 解説
.Fn recvfrom
と
.Fn recvmsg
は、ソケットからのメッセージを受信するのに使用されます。
ソケットが接続指向であるかどうかにかかわらず、ソケット上のデータを
受信するのに使用できます。
.Pp
.Fa from
が nil でなく、ソケットが接続指向でない場合、
ここにはメッセージのソースアドレスが保存されます。
.Fa fromlen
は「値 - 結果」パラメータであり、
.Fa from
に対応するバッファのサイズに初期化され、
戻り時には保存されたアドレスの実際のサイズを示すように
変更されます。
.Pp
.Fn recv
呼び出しは、通常
.Em 接続された
ソケット上だけで使用され
.Pf ( Xr connect 2
を参照)、
.Fa from
パラメータに nil を指定した
.Fn recvfrom
と同一です。これは冗長なので、将来のリリースでは
サポートされない可能性があります。
.Pp
これら 3 つのルーチンは正常に完了するとメッセージの長さを返します。
メッセージが長すぎて指定のバッファに収まらない場合、
メッセージを受信したソケットのタイプによっては
超過分のバイトが破棄されることがあります
.Pf ( Xr socket 2
を参照)。
.Pp
ソケットにメッセージが無い場合は、ソケットが非ブロッキング
.Pf ( Xr fcntl 2
を参照) の場合を除き、呼び出しはメッセージが到着するのを待ちます。
ソケットが非ブロッキングの場合、値 -1 が返され、外部変数
.Va errno
が
.Er EAGAIN
に設定されます。通常、受信呼び出しは要求された量を受信するまで待たずに、
要求された量を上限として得られたデータを返します。この動作は、
.Xr getsockopt 2
で解説されているソケットレベルのオプション
.Dv SO_RCVLOWAT
および
.Dv SO_RCVTIMEO
によって影響を受けます。
.Pp
次のデータがいつ到着するかを判定するには
.Xr select 2
呼び出しを使うことができます。
.Pp
recv 呼び出しへの
.Fa flags
引数は、次の値の 1 つまたは複数の論理和
.\".Em or Ap ing
.Em ( or )
から成ります。
.Bl -column MSG_WAITALL -offset indent
.It Dv MSG_OOB Ta プロセス帯域外データ
.It Dv MSG_PEEK Ta 着信メッセージの覗き見 (peek)
.It Dv MSG_WAITALL Ta 要求の完全な実行、またはエラーを待つ
.El
.Pp
.Dv MSG_OOB
フラグは帯域外データの受信を要求し、
通常のデータストリームからは受信しません。
急送データを通常のデータ待ち行列の先頭に配置するプロトコルもありますが、
このフラグはそのようなプロトコルでは使用できません。MSG_PEEK フラグは
受信待ち行列の先頭からデータを除去することなく、そのデータを
返します。したがって、後続の受信呼び出しは同じデータ
を返します。MSG_WAITALL フラグは要求が完全に満たされるまで
ブロックするように要求します。
しかし、シグナルが捕捉された場合、エラーまたは切断が発生した場合、
または受信する次のデータが返されたタイプと異なる
場合、呼び出しは要求されたより少ないデータを返す可能性があります。
.Pp
.Fn recvmsg
呼び出しは、直接に指定されるパラメータの数を最小にするために
.Fa msghdr
構造体を使用します。この構造体は
.Ao Pa sys/socket.h Ac
で定義されているように、次の形式になっています。
.Pp
.Bd -literal
struct msghdr {
caddr_t msg_name; /* アドレス(オプション) */
u_int msg_namelen; /* アドレスのサイズ */
struct iovec *msg_iov; /* スキャッタ/ギャザー配列 */
u_int msg_iovlen; /* msg_iov の要素数 */
caddr_t msg_control; /* 補助データ、後述 */
u_int msg_controllen; /* 補助データのバッファ長 */
int msg_flags; /* 受信されたメッセージ上のフラグ */
};
.Ed
.Pp
ここで
.Fa msg_name
と
.Fa msg_namelen
は、ソケットが接続されていない場合に、宛先アドレスを指定します。
名前を要求しない場合や必要でない場合、
.Fa msg_name
は NULL ポインタとして指定できます。
.Fa msg_iov
と
.Fa msg_iovlen
は
.Xr read 2
で説明されているようにスキャッタ/ギャザーの場所を記述します。
.Fa msg_control
は、長さが
.Fa msg_controllen
の、他のプロトコル制御に関連するメッセージまたはその他の
各種補助データ用のバッファを指しています。メッセージは次の形式です。
.Bd -literal
struct cmsghdr {
u_int cmsg_len; /* データバイトカウント、hdr を含む */
int cmsg_level; /* メッセージを生成したプロトコル */
int cmsg_type; /* プロトコルに固有のタイプ */
/* u_char cmsg_data[]; が後に続く */
};
.Pp
.Ed
たとえば、これを使用して XNS/SPP において
データストリームの変化を知ることができます。また、ISO において
.Fn accept
呼び出しの直後に、データバッファを伴わずに recvmsg を要求して、
ユーザ接続要求データを得ることができるでしょう。
.Pp
オープンされたファイル記述子はこれで
.Dv AF_UNIX
ドメインソケット用の補助データとして引き渡され、その際、
.Fa cmsg_level
が
.Dv SOL_SOCKET
に設定され、
.Fa cmsg_type
が
.Dv SCM_RIGHTS
に設定されます。
.Pp
.Dv SCM_CREDS
の
.Fa cmsg_type
を使用して、プロセスの認証情報を
.Dv AF_UNIX
ドメインソケット用の補助データとして
渡すこともできます。このケースでは、
.Fa cmsg_data
は、構造体
.Fa cmsgcred
である必要があります。これは
次のように
.Ao Pa sys/socket.h Ac
内で定義されています。
.Pp
.Bd -literal
struct cmsgcred {
pid_t cmcred_pid; /* 送信プロセスの PID */
uid_t cmcred_uid; /* 送信プロセスの実 UID */
uid_t cmcred_euid; /* 送信プロセスの実効 UID */
gid_t cmcred_gid; /* 送信プロセスの実 GID */
short cmcred_ngroups; /* グループの数 */
gid_t cmcred_groups[CMGROUP_MAX]; /* グループ */
};
.Ed
.Pp
カーネルは送信プロセスの認証情報を記入し、それを受信側へ配信します。
.Pp
.Fa msg_flags
フィールドは受信済みメッセージに従って戻り時に設定されます。
.Dv MSG_EOR
は end-of-record、つまり返されたデータでレコードが
完結していることを示します (一般には、タイプ
.Dv SOCK_SEQPACKET
のソケットとともに使用されます)。
.Dv MSG_TRUNC
は、提供されたバッファよりデータグラムが大きかったので、
データグラムの後ろの部分が切り捨てられたことを示します。
.Dv MSG_CTRUNC
は、補助データ用のバッファ内の空間の不足のためにいくらかの制御データが
切り捨てられたことを示します。
.Dv MSG_OOB
は、急送または帯域外データが受信されたことを示します。
.Sh 戻り値
これらの呼び出しは受信したバイト数を返し、エラーが起きた場合は -1 を返します。
.Sh エラー
呼び出しは次の場合に失敗します。
.Bl -tag -width Er
.It Bq Er EBADF
引数
.Fa s
が有効な記述子ではありません。
.It Bq Er ENOTCONN
ソケットは接続指向プロトコルと結び付けられていますが、接続されていません
.Pf ( Xr connect 2
と
.Xr accept 2
を参照)。
.It Bq Er ENOTSOCK
引数
.Fa s
はソケットを参照していません。
.It Bq Er EAGAIN
ソケットが非ブロッキングとマークされているとき、
受信操作でブロックしました。
あるいは、受信タイムアウトが設定されていて、
データが受信される前にタイムアウトになりました。
.It Bq Er EINTR
データが受信可能になる前に、受信がシグナルによって割込まれました。
.It Bq Er EFAULT
受信バッファポインタが、プロセスに割り当てられたアドレス空間の
範囲外を指しています。
.El
.Sh 関連項目
.Xr fcntl 2 ,
.Xr getsockopt 2 ,
.Xr read 2 ,
.Xr select 2 ,
.Xr socket 2
.Sh 歴史
.Fn recv
関数は
.Bx 4.2
で登場しました。
