.\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California. .\" All rights reserved. .\" .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) .\" 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. .\" %%%LICENSE_END .\" .\" $Id: recv.2,v 1.3 1999/05/13 11:33:38 freitag Exp $ .\" .\" Modified Sat Jul 24 00:22:20 1993 by Rik Faith .\" Modified Tue Oct 22 17:45:19 1996 by Eric S. Raymond .\" Modified 1998,1999 by Andi Kleen .\" 2001-06-19 corrected SO_EE_OFFENDER, bug report by James Hawtin .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .\" .\" Japanese Version Copyright (c) 1996 Akira Yoshiyama .\" all rights reserved. .\" Translated 1996-07-18, Akira Yoshiyama .\" Modified 1997-12-14, HANATAKA Shinya .\" Modified 1999-08-14, HANATAKA Shinya .\" Updated & Modified 2000-10-12, HAYAKAWA Hitoshi .\" and NAKANO Takeo .\" Updated & Modified 2001-02-09, NAKANO Takeo .\" Updated 2003-10-11, Kentaro Shirakata .\" Updated 2005-03-14, Akihiro MOTOKI .\" Updated 2006-04-15, Akihiro MOTOKI, Catch up to LDP v2.29 .\" Updated 2007-10-12, Akihiro MOTOKI, LDP v2.66 .\" Updated 2008-08-06, Akihiro MOTOKI, LDP v3.05 .\" Updated 2009-04-13, Akihiro MOTOKI, LDP v3.20 .\" Updated 2013-03-26, Akihiro MOTOKI .\" Updated 2013-07-22, Akihiro MOTOKI .\" .TH RECV 2 2014\-08\-19 Linux "Linux Programmer's Manual" .SH 名前 recv, recvfrom, recvmsg \- ソケットからメッセージを受け取る .SH 書式 .\" .B #include .\" .br .nf \fB#include \fP .br \fB#include \fP .sp \fBssize_t recv(int \fP\fIsockfd\fP\fB, void *\fP\fIbuf\fP\fB, size_t \fP\fIlen\fP\fB, int \fP\fIflags\fP\fB);\fP .sp \fBssize_t recvfrom(int \fP\fIsockfd\fP\fB, void *\fP\fIbuf\fP\fB, size_t \fP\fIlen\fP\fB, int \fP\fIflags\fP\fB,\fP \fB struct sockaddr *\fP\fIsrc_addr\fP\fB, socklen_t *\fP\fIaddrlen\fP\fB);\fP .sp \fBssize_t recvmsg(int \fP\fIsockfd\fP\fB, struct msghdr *\fP\fImsg\fP\fB, int \fP\fIflags\fP\fB);\fP .fi .SH 説明 \fBrecv\fP(), \fBrecvfrom\fP(), \fBrecvmsg\fP() コールは、 ソケットからメッセージを受け取るのに使用される。 これらはコネクションレス型のソケットにも接続指向 (connection\-oriened) 型のソケットにも使用できる。 このページでは、まずこれら 3 つのシステムコールすべてに共通の機能について説明し、 システムコール間の違いについて説明する。 .PP これらの三つのシステムコールはいずれも、成功した場合にはメッセージの長さを返す。 メッセージが長過ぎて指定されたバッファーに入り切らなかった場合には、 メッセージを受信したソケットの種類によっては余分のバイトが捨てられる かもしれない。 .PP ソケットに受け取るメッセージが存在しなかった場合、 受信用のコールはメッセージが到着するまで待つ。 ただし、ソケットが非停止 (nonblocking) に設定されていた場合 (\fBfcntl\fP(2) を参照) は \-1 を返し、外部変数 \fIerrno\fP に \fBEAGAIN\fP か \fBEWOULDBLOCK\fP を設定する。 これらの受信用のコールは、受信したデータのサイズが要求したサイズに 達するまで待つのではなく、何らかのデータを受信すると復帰する (受信されるデータの最大サイズは要求したサイズである)。 .PP アプリケーションは \fBselect\fP(2), \fBpoll\fP(2), \fBepoll\fP(7) を使って、ソケットにさらにデータが到着しているかを判定することができる。 .SS フラグ引き数 \fIflags\fP 引き数には、以下の値を 1つ以上、ビット単位の論理和 を取ったものを指定する: .TP \fBMSG_CMSG_CLOEXEC\fP (\fBrecvmsg\fP() のみ; Linux 2.6.23) (\fBunix\fP(7) で説明されている) \fBSCM_RIGHTS\fP 操作を使って UNIX ドメインのファイルディスクリプター経由で受信した ファイルディスクリプターについて close\-on\-exec フラグをセットする。 このフラグは、 \fBopen\fP(2) の \fBO_CLOEXEC\fP フラグと同じ理由で有用である。 .TP \fBMSG_DONTWAIT\fP (Linux 2.2 以降) 非停止 (nonblocking) 操作を有効にする。 操作が停止するような場合にエラー \fBEAGAIN\fP か \fBEWOULDBLOCK\fP で呼び出しが失敗する (\fBfcntl\fP(2) の \fBF_SETFL\fP で \fBO_NONBLOCK\fP フラグを指定することによっても有効にできる)。 .TP \fBMSG_ERRQUEUE\fP (Linux 2.2 以降) このフラグを指定すると、 キューに入れられたエラーをソケットのエラーキューから取りだせるようになる。 このエラーは補助メッセージに組み込まれて渡され、 この補助メッセージの種別はプロトコルに依存する (IPv4 の場合は \fBIP_RECVERR\fP)。 ユーザーは十分なサイズのバッファーを用意しなければならない。 補助メッセージに関するより詳細な情報は \fBcmsg\fP(3) および \fBip\fP(7) を参照のこと。 エラーの原因となったオリジナルパケットのペイロードは、 \fImsg_iovec\fP 経由で通常のデータとして渡される。 エラーを起こしたデータグラムのオリジナルの宛先アドレスは、 \fImsg_name\fP 経由で参照できる。 .IP ローカルなエラーの場合はアドレスは渡されない (これは \fIcmsghdr\fP の \fIcmsg_len\fP メンバーでチェックできる)。 受信エラーの場合は \fBMSG_ERRQUIE\fP が \fImsghdr\fP にセットされる。 エラーが渡された後には、キューに入っている次のエラーに基いて、 処理待ちのソケットエラーが再生成され、次のソケット操作の際に渡される。 このエラーは \fIsock_extended_err\fP 構造体で提供される: .in +4n .nf #define SO_EE_ORIGIN_NONE 0 #define SO_EE_ORIGIN_LOCAL 1 #define SO_EE_ORIGIN_ICMP 2 #define SO_EE_ORIGIN_ICMP6 3 struct sock_extended_err { uint32_t ee_errno; /* error number */ uint8_t ee_origin; /* where the error originated */ uint8_t ee_type; /* type */ uint8_t ee_code; /* code */ uint8_t ee_pad; /* padding */ uint32_t ee_info; /* additional information */ uint32_t ee_data; /* other data */ /* More data may follow */ }; struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *); .fi .in .IP \fIee_errno\fP にはキューに入れられたエラーの \fIerrno\fP が入っている。 \fIee_origin\fP にはエラーが発生した場所のオリジンコード (origin code) が入っている。 他のフィールドはプロトコル依存である。 \fBSO_EE_OFFENDER\fP マクロは、この補助的なメッセージを引き数に取って、 エラーの発生したネットワークオブジェクトのアドレスへのポインターを返す。 アドレスが不明の場合には、 \fIsockaddr\fP の \fIsa_family\fP メンバーが \fBAF_UNSPEC\fP になっている。 \fIsockaddr\fP の他のフィールドは不定である。 エラーの発生したパケットのペイロードは通常のデータとして渡される。 .IP ローカルなエラーの場合はアドレスは渡されない (これは \fIcmsghdr\fP の \fIcmsg_len\fP メンバーでチェックできる)。 受信エラーの場合は \fBMSG_ERRQUIE\fP が \fImsghdr\fP にセットされる。 エラーが渡された後には、キューに入っている次のエラーに基いて、 処理待ちのソケットエラーが再生成され、次のソケット操作の際に渡される。 .TP \fBMSG_OOB\fP このフラグは、通常のデータストリームでは受信できない 帯域外 (out\-of\-band) データの受信を要求する。 プロトコルによっては、 通常のデータキューの先頭に速達データを置くものがあるが、 そのようなプロトコルではこのフラグは使用できない。 .TP \fBMSG_PEEK\fP このフラグを指定すると、 受信キューの最初のデータを返すとき、キューからデータを削除しない。 したがって、この後でもう一度受信コールを呼び出すと、同じデータが返ることになる。 .TP \fBMSG_TRUNC\fP (Linux 2.2 以降) raw ソケット (\fBAF_PACKET\fP)、 Internet datagram ソケット (Linux 2.4.27/2.6.8 以降)、 netlink (Linux 2.6.22 以降) ソケット、 UNIX datagram ソケット (Linux 3.4 以降) の場合、パケットやデータグラムの長さが渡したバッファーよりも長かった場合にも、 パケットやデータグラムの実際の長さを返す。 Internet ストリームソケットでの利用については \fBtcp\fP(7) を参照。 .TP \fBMSG_WAITALL\fP (Linux 2.2 以降) .\" このフラグは、要求した量いっぱいのデータが到着するまで、 操作を停止 (block) するよう要求する。 但し、シグナルを受信したり、エラーや切断 (disconnect) が発生したり、 次に受信されるデータが異なる型だったりした場合には、 要求した量よりデータが少なくても返ることがある。 .SS recvfrom() \fBrecvfrom\fP() は受信したメッセージをバッファー \fIbuf\fP に格納する。 呼び出し元はバッファーサイズを \fIlen\fP で指定しなければならない。 .\" (Note: for datagram sockets in both the UNIX and Internet domains, .\" .I src_addr .\" is filled in. .\" .I src_addr .\" is also filled in for stream sockets in the UNIX domain, but is not .\" filled in for stream sockets in the Internet domain.) .\" [The above notes on AF_UNIX and AF_INET sockets apply as at .\" Kernel 2.4.18. (MTK, 22 Jul 02)] \fIsrc_addr\fP が NULL 以外で、下層のプロトコルからメッセージの送信元アドレスが分かる場合、 この送信元アドレスが \fIsrc_addr\fP が指すバッファーに格納される。 この場合、 \fIaddrlen\fP は入出力両用の引き数となる。 呼び出し前に、呼び出し元は \fIsrc_addr\fP に割り当てたバッファーの大きさで初期化しておくべきである。 返ってくる時には、 \fIaddrlen\fP は送信元アドレスの実際の大きさに変更される。渡されたバッファーが小さ過ぎる場合には、返されるアドレスの末尾は 切り詰められる。この場合には、 \fIaddrlen\fP では、呼び出し時に渡された値よりも大きな値が返される。 .\" 呼び出し元が送信元アドレスを必要としない場合は、 \fIsrc_addr\fP と \fIaddrlen\fP には NULL を指定すべきである。 .SS recv() \fBrecv\fP() コールは通常 \fI接続済みの (connected)\fP ソケットに対してのみ使用される (\fBconnect\fP(2) 参照)。次の呼び出しと等価である。 .\" recvfrom(fd, buf, len, flags, NULL, 0)); .SS recvmsg() \fBrecvmsg\fP() コールは、直接渡す引き数の数を減らすために \fImsghdr\fP 構造体を使用する。この構造体は \fI\fP で以下のように定義されている: .in +4n .nf struct iovec { /* Scatter/gather array items */ void *iov_base; /* Starting address */ size_t iov_len; /* Number of bytes to transfer */ }; struct msghdr { void *msg_name; /* 追加のアドレス */ socklen_t msg_namelen; /* アドレスのサイズ */ struct iovec *msg_iov; /* scatter/gather 配列 */ size_t msg_iovlen; /* msg_iov の要素数 */ void *msg_control; /* 補助データ (後述) */ size_t msg_controllen; /* 補助データバッファー長 */ int msg_flags; /* 受信メッセージのフラグ */ }; .fi .in .PP フィールド \fImsg_name\fP は、 ソケットが接続されていない場合に送信元アドレスを返すのに使用されるバッファーを指す。 このバッファーは呼び出し元が確保する。 呼び出し元は呼び出し前に \fImsg_namelen\fP にこのバッファーの大きさを設定しなければならない。 呼び出しが成功した場合、呼び出しから返って来た際には \fImsg_namelen\fP には返されるアドレスの長さが入っている。 アプリケーションが送信元アドレスを知る必要がない場合には、 \fImsg_name\fP に NULL を指定することができる。 \fImsg_iov\fP と \fImsg_iovlen\fP フィールドは scatter\-gather 用の場所を指定する。 \fBreadv\fP(2) に説明がある。 \fImsg_control\fP フィールドは \fImsg_controllen\fP の長さを持ち、他のプロトコル制御メッセージや 種々の補助データのためのバッファーへのポインターである。 \fBrecvmsg\fP() を呼ぶ際には、 \fImsg_controllen\fP に \fImsg_control\fP のバッファーの長さを入れておく必要がある。 コールが成功して返った場合、制御メッセージ列の長さが入っている。 .PP メッセージの形式は以下の通り: .in +4n .nf struct cmsghdr { socklen_t cmsg_len; /* data byte count, including hdr */ int cmsg_level; /* originating protocol */ int cmsg_type; /* protocol\-specific type */ /* followed by unsigned char cmsg_data[]; */ }; .fi .in .PP 補助データは、 \fBcmsg\fP(3) に定義されたマクロ経由でのみアクセスすべきである。 .PP 例をあげると、 Linux はこの補助データのメカニズムを、 UNIX ドメインソケット上での拡張エラーや IP オプション、 ファイルディスクリプターの受け渡しに利用している。 .PP \fImsghdr\fP の \fImsg_flags\fP フィールドは \fBrecvmsg\fP() からのリターン時に設定される。ここにはいくつかのフラグが入る。 .TP \fBMSG_EOR\fP これはレコードの終り (end\-of\-record) を示し、 返されたデータが完全なレコードであることを示す (一般的には \fBSOCK_SEQPACKET\fP 型のソケットで使用される)。 .TP \fBMSG_TRUNC\fP データグラムが与えられたバッファーより大きかったために、 データグラムのはみ出した部分が捨てられたことを示す。 .TP \fBMSG_CTRUNC\fP 補助データのためのバッファーが不足したために、 制御データの一部が捨てられたことを示す。 .TP \fBMSG_OOB\fP 速達データや帯域外データを受信したことを示す。 .TP \fBMSG_ERRQUEUE\fP データは受信しなかったが ソケットのエラーキューから拡張エラーを受信したことを示す。 .SH 返り値 これらのコールは受信したバイト数を返す。 エラーの場合は \-1 を返し、 \fIerrno\fP にエラーを示す値を設定する。 ストリームソケットの接続相手が正しくシャットダウンを実行した場合は、 返り値は 0 (昔ながらの "end\-of\-file" の戻り値) となる。 いくつかのドメインのデータグラムソケット (UNIX ドメインやインターネットドメインなど) では、長さ 0 のデータグラムが送信できる。 このようなデータグラムを受信した場合、 返り値は 0 となる。 ストリームソケットに対する受信要求バイト数が 0 だった場合も、 値 0 が返される。 .SH エラー これらはソケット層で発生する一般的なエラーである。 他のエラーが下層のプロトコルモジュールで生成され、 返されるかもしれない。 それらのマニュアルを参照すること。 .TP \fBEAGAIN\fP または \fBEWOULDBLOCK\fP .\" Actually EAGAIN on Linux ソケットが非停止 (nonblocking) に設定されていて 受信操作が停止するような状況になったか、 受信に時間切れ (timeout) が設定されていて データを受信する前に時間切れになった。 POSIX.1\-2001 は、この場合にどちらのエラーを返すことも認めており、 これら 2 つの定数が同じ値を持つことも求めていない。 したがって、移植性が必要なアプリケーションでは、両方の可能性を 確認すべきである。 .TP \fBEBADF\fP 引き数 \fIsockfd\fP が不正なディスクリプターである。 .TP \fBECONNREFUSED\fP リモートのホストでネットワーク接続が拒否された (よくある理由としては、要求したサービスが起動されていないなどがある)。 .TP \fBEFAULT\fP 受信バッファーへのポインターがプロセスのアドレス空間外を指している。 .TP \fBEINTR\fP データを受信する前に、シグナルが配送されて割り込まれた。 \fBsignal\fP(7) 参照。 .TP \fBEINVAL\fP .\" e.g., msg_namelen < 0 for recvmsg() or addrlen < 0 for recvfrom() 不正な引き数が渡された。 .TP \fBENOMEM\fP \fBrecvmsg\fP() のためのメモリーが確保できなかった。 .TP \fBENOTCONN\fP ソケットに接続指向プロトコルが割り当てられており、 まだ接続されていない (\fBconnect\fP(2) と \fBaccept\fP(2) を参照のこと)。 .TP \fBENOTSOCK\fP 引き数 \fIsockfd\fP がソケットを参照していない。 .SH 準拠 4.4BSD (これらの関数は 4.2BSD で現われた), POSIX.1\-2001。 .LP POSIX.1\-2001 では、 \fBMSG_OOB\fP, \fBMSG_PEEK\fP, \fBMSG_WAITALL\fP フラグだけが記載されている。 .SH 注意 \fIsocklen_t\fP 型は POSIX で発案された。 \fBaccept\fP(2) も参照。 .\" glibc bug raised 12 Mar 2006 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448 .\" The problem is an underlying kernel issue: the size of the .\" __kernel_size_t type used to type this field varies .\" across architectures, but socklen_t is always 32 bits. POSIX.1\-2001 では、構造体 \fImsghdr\fP のフィールド \fImsg_controllen\fP は \fIsocklen_t\fP 型であるべきだとされているが、 現在の glibc では \fIsize_t\fP 型である。 \fBrecvmmsg\fP(2) には、一度の呼び出しでの複数のデータグラムに使用できる Linux 固有の システムコールに関する情報が書かれている。 .SH 例 \fBrecvfrom\fP() の利用例が \fBgetaddrinfo\fP(3) に記載されている。 .SH 関連項目 \fBfcntl\fP(2), \fBgetsockopt\fP(2), \fBread\fP(2), \fBrecvmmsg\fP(2), \fBselect\fP(2), \fBshutdown\fP(2), \fBsocket\fP(2), \fBcmsg\fP(3), \fBsockatmark\fP(3), \fBsocket\fP(7) .SH この文書について この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man\-pages/ に書かれている。