.\" 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.21.2.2 2005/02/28 03:32:34 brueffer Exp % .\" .\" $FreeBSD$ .Dd February 21, 1994 .Dt RECV 2 .Os .Sh 名称 .Nm recv , .Nm recvfrom , .Nm recvmsg .Nd ソケットからメッセージを受信する .Sh ライブラリ .Lb libc .Sh 書式 .In sys/types.h .In 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 * restrict buf" "size_t len" "int flags" "struct sockaddr * restrict from" "socklen_t * restrict fromlen" .Ft ssize_t .Fn recvmsg "int s" "struct msghdr *msg" "int flags" .Sh 解説 .Fn recvfrom と .Fn recvmsg システムコールは、ソケットからのメッセージを受信するのに使用されます。 ソケットが接続指向であるかどうかにかかわらず、ソケット上のデータを 受信するのに使用できます。 .Pp .Fa from が NULL ポインタでなく、ソケットが接続指向でない場合、 ここにはメッセージのソースアドレスが保存されます。 .Fa fromlen 引数は値と結果の引数であり、 .Fa from に対応するバッファのサイズに初期化され、 戻り時には保存されたアドレスの実際のサイズを示すように変更されます。 .Pp .Fn recv システムコールは、通常 .Em 接続された ソケット上だけで使用され .Pf ( Xr connect 2 を参照)、 .Fa from 引数に NULL ポインタを指定した .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 .Fn recv 関数への .Fa flags 引数は、次の値の 1 つまたは複数の論理和 .\".Em or Ap ing .Em ( or ) から成ります: .Bl -column ".Dv MSG_DONTWAIT" -offset indent .It Dv MSG_OOB Ta プロセス帯域外データ .It Dv MSG_PEEK Ta 着信メッセージの覗き見 (peek) .It Dv MSG_WAITALL Ta 要求の完全な実行、またはエラーを待つ .It Dv MSG_DONTWAIT Ta ブロックしない .El .Pp .Dv MSG_OOB フラグは帯域外データの受信を要求し、 通常のデータストリームからは受信しません。 急送データを通常のデータ待ち行列の先頭に配置するプロトコルもありますが、 このフラグはそのようなプロトコルでは使用できません。 .Dv MSG_PEEK フラグは受信待ち行列の先頭からデータを除去することなく、 そのデータを返します。 したがって、後続の受信呼び出しは同じデータを返します。 .Dv MSG_WAITALL フラグは要求が完全に満たされるまでブロックするように要求します。 しかし、シグナルが捕捉された場合、エラーまたは切断が発生した場合、 または受信する次のデータが返されたタイプと異なる 場合、呼び出しは要求されたより少ないデータを返す可能性があります。 .Dv MSG_DONTWAIT フラグは、フラグが指定されてなかったらブロックするような時に、 戻ることを要求します。 利用可能なデータが無い場合には、 .Va errno が .Er EAGAIN に設定されます。 このフラグは、厳格な .Tn ANSI または C99 のコンパイルモードでは利用できません。 .Pp .Fn recvmsg システムコールは、直接に指定される引数の数を最小にするために .Fa msghdr 構造体を使用します。 この構造体は .In sys/socket.h で定義されているように、次の形式になっています: .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 システムコールの直後に、データバッファを伴わずに .Fn 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 である必要があります。 これは次のように .In sys/socket.h 内で定義されています: .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 EMSGSIZE 接続中にオープンされている権利 (ファイル記述子) を .Fn recvmsg システムコールを使用して受信しようとしました。 しかし、受信側プログラムのにそれらを受け取るだけの 十分な空きファイル記述子スロットがありませんでした。 この場合、該当する記述子はクローズされ、保留されているデータは別の .Fn recvmsg 呼び出しで戻せます。 .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 で登場しました。