release/man2/recv.2

   1 .\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgement:
  15 .\"     This product includes software developed by the University of
  16 .\"     California, Berkeley and its contributors.
  17 .\" 4. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\" %%%LICENSE_END
  33 .\"
  34 .\"     $Id: recv.2,v 1.3 1999/05/13 11:33:38 freitag Exp $
  35 .\"
  36 .\" Modified Sat Jul 24 00:22:20 1993 by Rik Faith <faith@cs.unc.edu>
  37 .\" Modified Tue Oct 22 17:45:19 1996 by Eric S. Raymond <esr@thyrsus.com>
  38 .\" Modified 1998,1999 by Andi Kleen
  39 .\" 2001-06-19 corrected SO_EE_OFFENDER, bug report by James Hawtin
  40 .\"
  41 .\"*******************************************************************
  42 .\"
  43 .\" This file was generated with po4a. Translate the source file.
  44 .\"
  45 .\"*******************************************************************
  46 .\"
  47 .\" Japanese Version Copyright (c) 1996 Akira Yoshiyama
  48 .\"         all rights reserved.
  49 .\" Translated 1996-07-18, Akira Yoshiyama <yosshy@jedi.seg.kobe-u.ac.jp>
  50 .\" Modified 1997-12-14, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  51 .\" Modified 1999-08-14, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  52 .\" Updated & Modified 2000-10-12, HAYAKAWA Hitoshi <cz8cb01@linux.or.jp>
  53 .\"        and NAKANO Takeo <nakano@apm.seikei.ac.jp>
  54 .\" Updated & Modified 2001-02-09, NAKANO Takeo
  55 .\" Updated 2003-10-11, Kentaro Shirakata <argrath@ub32.org>
  56 .\" Updated 2005-03-14, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  57 .\" Updated 2006-04-15, Akihiro MOTOKI, Catch up to LDP v2.29
  58 .\" Updated 2007-10-12, Akihiro MOTOKI, LDP v2.66
  59 .\" Updated 2008-08-06, Akihiro MOTOKI, LDP v3.05
  60 .\" Updated 2009-04-13, Akihiro MOTOKI, LDP v3.20
  61 .\" Updated 2013-03-26, Akihiro MOTOKI <amotoki@gmail.com>
  62 .\" Updated 2013-07-22, Akihiro MOTOKI <amotoki@gmail.com>
  63 .\"
  64 .TH RECV 2 2014\-02\-11 Linux "Linux Programmer's Manual"
  65 .SH 名前
  66 recv, recvfrom, recvmsg \- ソケットからメッセージを受け取る
  67 .SH 書式
  68 .\" .B #include <sys/uio.h>
  69 .\" .br
  70 .nf
  71 \fB#include <sys/types.h>\fP
  72 .br
  73 \fB#include <sys/socket.h>\fP
  74 .sp
  75 \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
  76 .sp
  77 \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
  78 \fB                 struct sockaddr *\fP\fIsrc_addr\fP\fB, socklen_t *\fP\fIaddrlen\fP\fB);\fP
  79 .sp
  80 \fBssize_t recvmsg(int \fP\fIsockfd\fP\fB, struct msghdr *\fP\fImsg\fP\fB, int \fP\fIflags\fP\fB);\fP
  81 .fi
  82 .SH 説明
  83 The \fBrecv\fP(), \fBrecvfrom\fP(), and \fBrecvmsg\fP()  calls are used to receive
  84 messages from a socket.  They may be used to receive data on both
  85 connectionless and connection\-oriented sockets.  This page first describes
  86 common features of all three system calls, and then describes the
  87 differences between the calls.
  88 .PP
  89 これらの三つのシステムコールはいずれも、成功した場合にはメッセージの長さを返す。 メッセージが長過ぎて指定されたバッファに入り切らなかった場合には、
  90 メッセージを受信したソケットの種類によっては余分のバイトが捨てられる かもしれない。
  91 .PP
  92 ソケットに受け取るメッセージが存在しなかった場合、 受信用のコールはメッセージが到着するまで待つ。 ただし、ソケットが非停止 (nonblocking)
  93 に設定されていた場合 (\fBfcntl\fP(2)  を参照) は \-1 を返し、外部変数 \fIerrno\fP に \fBEAGAIN\fP か
  94 \fBEWOULDBLOCK\fP を設定する。 これらの受信用のコールは、受信したデータのサイズが要求したサイズに
  95 達するまで待つのではなく、何らかのデータを受信すると復帰する (受信されるデータの最大サイズは要求したサイズである)。
  96 .PP
  97 アプリケーションは \fBselect\fP(2), \fBpoll\fP(2), \fBepoll\fP(7)
  98 を使って、ソケットにさらにデータが到着しているかを判定することができる。
  99 .SS "The flags argument"
 100 \fIflags\fP 引き数には、以下の値を 1つ以上、ビット単位の論理和 を取ったものを指定する:
 101 .TP
 102 \fBMSG_CMSG_CLOEXEC\fP (\fBrecvmsg\fP() のみ; Linux 2.6.23)
 103 (\fBunix\fP(7)  で説明されている)  \fBSCM_RIGHTS\fP 操作を使って UNIX ドメインのファイルディスクリプタ経由で受信した
 104 ファイルディスクリプタについて close\-on\-exec フラグをセットする。 このフラグは、 \fBopen\fP(2)  の \fBO_CLOEXEC\fP
 105 フラグと同じ理由で有用である。
 106 .TP
 107 \fBMSG_DONTWAIT\fP (Linux 2.2 以降)
 108 非停止 (nonblocking) 操作を有効にする。 操作が停止するような場合にエラー \fBEAGAIN\fP か \fBEWOULDBLOCK\fP
 109 で呼び出しが失敗する (\fBfcntl\fP(2)  の \fBF_SETFL\fP で \fBO_NONBLOCK\fP
 110 フラグを指定することによっても有効にできる)。
 111 .TP
 112 \fBMSG_ERRQUEUE\fP (Linux 2.2 以降)
 113 このフラグを指定すると、 キューに入れられたエラーをソケットのエラーキューから取りだせるようになる。 このエラーは補助メッセージに組み込まれて渡され、
 114 この補助メッセージの種別はプロトコルに依存する (IPv4 の場合は \fBIP_RECVERR\fP)。
 115 ユーザは十分なサイズのバッファを用意しなければならない。 補助メッセージに関するより詳細な情報は \fBcmsg\fP(3)  および \fBip\fP(7)
 116 を参照のこと。 エラーの原因となったオリジナルパケットのペイロードは、 \fImsg_iovec\fP 経由で通常のデータとして渡される。
 117 エラーを起こしたデータグラムのオリジナルの宛先アドレスは、 \fImsg_name\fP 経由で参照できる。
 118 .IP
 119 ローカルなエラーの場合はアドレスは渡されない
 120 (これは \fIcmsghdr\fP の \fIcmsg_len\fP メンバーでチェックできる)。
 121 受信エラーの場合は \fBMSG_ERRQUIE\fP が \fImsghdr\fP にセットされる。
 122 エラーが渡された後には、キューに入っている次のエラーに基いて、
 123 処理待ちのソケット・エラーが再生成され、次のソケット操作の際に渡される。
 124
 125 このエラーは \fIsock_extended_err\fP 構造体で提供される:
 126 .in +4n
 127 .nf
 128
 129 #define SO_EE_ORIGIN_NONE    0
 130 #define SO_EE_ORIGIN_LOCAL   1
 131 #define SO_EE_ORIGIN_ICMP    2
 132 #define SO_EE_ORIGIN_ICMP6   3
 133
 134 struct sock_extended_err
 135 {
 136     uint32_t ee_errno;   /* error number */
 137     uint8_t  ee_origin;  /* where the error originated */
 138     uint8_t  ee_type;    /* type */
 139     uint8_t  ee_code;    /* code */
 140     uint8_t  ee_pad;     /* padding */
 141     uint32_t ee_info;    /* additional information */
 142     uint32_t ee_data;    /* other data */
 143     /* More data may follow */
 144 };
 145
 146 struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);
 147 .fi
 148 .in
 149 .IP
 150 \fIee_errno\fP にはキューに入れられたエラーの \fIerrno\fP が入っている。 \fIee_origin\fP
 151 にはエラーが発生した場所のオリジン・コード (origin code) が入っている。 他のフィールドはプロトコル依存である。
 152 \fBSO_EE_OFFENDER\fP マクロは、この補助的なメッセージを引き数に取って、
 153 エラーの発生したネットワークオブジェクトのアドレスへのポインタを返す。 アドレスが不明の場合には、 \fIsockaddr\fP の \fIsa_family\fP
 154 メンバーが \fBAF_UNSPEC\fP になっている。 \fIsockaddr\fP の他のフィールドは不定である。
 155 エラーの発生したパケットのペイロードは通常のデータとして渡される。
 156 .IP
 157 ローカルなエラーの場合はアドレスは渡されない
 158 (これは \fIcmsghdr\fP の \fIcmsg_len\fP メンバーでチェックできる)。
 159 受信エラーの場合は \fBMSG_ERRQUIE\fP が \fImsghdr\fP にセットされる。
 160 エラーが渡された後には、キューに入っている次のエラーに基いて、
 161 処理待ちのソケット・エラーが再生成され、次のソケット操作の際に渡される。
 162 .TP
 163 \fBMSG_OOB\fP
 164 このフラグは、通常のデータ・ストリームでは受信できない 帯域外 (out\-of\-band) データの受信を要求する。 プロトコルによっては、
 165 通常のデータ・キューの先頭に速達データを置くものがあるが、 そのようなプロトコルではこのフラグは使用できない。
 166 .TP
 167 \fBMSG_PEEK\fP
 168 このフラグを指定すると、 受信キューの最初のデータを返すとき、キューからデータを削除しない。
 169 したがって、この後でもう一度受信コールを呼び出すと、同じデータが返ることになる。
 170 .TP
 171 \fBMSG_TRUNC\fP (Linux 2.2 以降)
 172 raw ソケット (\fBAF_PACKET\fP)、 Internet datagram ソケット (Linux 2.4.27/2.6.8 以降)、
 173 netlink (Linux 2.6.22 以降) ソケット、 UNIX datagram ソケット (Linux 3.4 以降)
 174 の場合、パケットやデータグラムの長さが渡したバッファよりも長かった場合にも、 パケットやデータグラムの実際の長さを返す。
 175
 176 Internet ストリームソケットでの利用については \fBtcp\fP(7)  を参照。
 177 .TP
 178 \fBMSG_WAITALL\fP (Linux 2.2 以降)
 179 .\"
 180 このフラグは、要求した量いっぱいのデータが到着するまで、 操作を停止 (block) するよう要求する。 但し、シグナルを受信したり、エラーや切断
 181 (disconnect) が発生したり、 次に受信されるデータが異なる型だったりした場合には、 要求した量よりデータが少なくても返ることがある。
 182 .SS recvfrom()
 183 \fBrecvfrom\fP()  places the received message into the buffer \fIbuf\fP.  The
 184 caller must specify the size of the buffer in \fIlen\fP.
 185
 186 .\" (Note: for datagram sockets in both the UNIX and Internet domains,
 187 .\" .I src_addr
 188 .\" is filled in.
 189 .\" .I src_addr
 190 .\" is also filled in for stream sockets in the UNIX domain, but is not
 191 .\" filled in for stream sockets in the Internet domain.)
 192 .\" [The above notes on AF_UNIX and AF_INET sockets apply as at
 193 .\" Kernel 2.4.18. (MTK, 22 Jul 02)]
 194 If \fIsrc_addr\fP is not NULL, and the underlying protocol provides the source
 195 address of the message, that source address is placed in the buffer pointed
 196 to by \fIsrc_addr\fP.  In this case, \fIaddrlen\fP is a value\-result argument.
 197 Before the call, it should be initialized to the size of the buffer
 198 associated with \fIsrc_addr\fP.  Upon return, \fIaddrlen\fP is updated to contain
 199 the actual size of the source address.  The returned address is truncated if
 200 the buffer provided is too small; in this case, \fIaddrlen\fP will return a
 201 value greater than was supplied to the call.
 202
 203 .\"
 204 If the caller is not interested in the source address, \fIsrc_addr\fP should be
 205 specified as NULL and \fIaddrlen\fP should be specified as 0.
 206 .SS recv()
 207 \fBrecv\fP()  コールは通常 \fI接続済みの (connected)\fP ソケットに対してのみ使用される (\fBconnect\fP(2)
 208 参照)。次の呼び出しと等価である。
 209
 210 .\"
 211     recvfrom(fd, buf, len, flags, NULL, 0));
 212 .SS recvmsg()
 213 \fBrecvmsg\fP()  コールは、直接渡す引き数の数を減らすために \fImsghdr\fP 構造体を使用する。この構造体は
 214 \fI<sys/socket.h>\fP で以下のように定義されている:
 215 .in +4n
 216 .nf
 217
 218 struct iovec {                    /* Scatter/gather array items */
 219     void  *iov_base;              /* Starting address */
 220     size_t iov_len;               /* Number of bytes to transfer */
 221 };
 222
 223 struct msghdr {
 224     void         *msg_name;       /* 追加のアドレス */
 225     socklen_t     msg_namelen;    /* アドレスのサイズ */
 226     struct iovec *msg_iov;        /* scatter/gather 配列 */
 227     size_t        msg_iovlen;     /* msg_iov の要素数 */
 228     void         *msg_control;    /* 補助データ (後述) */
 229     size_t        msg_controllen; /* 補助データバッファ長 */
 230     int           msg_flags;      /* 受信メッセージのフラグ */
 231 };
 232 .fi
 233 .in
 234 .PP
 235 \fImsg_name\fP と \fImsg_namelen\fP は、ソケットが接続されていない場合に送信元のアドレスを指定する。 名前が必要ない場合には
 236 \fImsg_name\fP に NULL ポインタを指定する。 \fImsg_iov\fP と \fImsg_iovlen\fP フィールドは \fBreadv\fP(2)
 237 に記述されているような分解/結合用のベクトル (scatter\-gather locations)  を指定する。 \fImsg_control\fP
 238 フィールドは \fImsg_controllen\fP の長さを持ち、他のプロトコル制御メッセージや 種々の補助データのためのバッファへのポインタである。
 239 \fBrecvmsg\fP()  を呼ぶ際には、 \fImsg_controllen\fP に \fImsg_control\fP
 240 のバッファの長さを入れておく必要がある。 コールが成功して返った場合、制御メッセージ列の長さが入っている。
 241 .PP
 242 メッセージの形式は以下の通り:
 243 .in +4n
 244 .nf
 245
 246 struct cmsghdr {
 247     socklen_t     cmsg_len;     /* data byte count, including hdr */
 248     int           cmsg_level;   /* originating protocol */
 249     int           cmsg_type;    /* protocol\-specific type */
 250 /* followed by
 251     unsigned char cmsg_data[]; */
 252 };
 253 .fi
 254 .in
 255 .PP
 256 補助データは、 \fBcmsg\fP(3)  に定義されたマクロ経由でのみアクセスすべきである。
 257 .PP
 258 例をあげると、 Linux はこの補助データのメカニズムを、 UNIX ドメインソケット上での拡張エラーや IP オプション、
 259 ファイル・ディスクリプタの受け渡しに利用している。
 260 .PP
 261 \fImsghdr\fP の \fImsg_flags\fP フィールドは \fBrecvmsg\fP()
 262 からのリターン時に設定される。ここにはいくつかのフラグが入る。
 263 .TP
 264 \fBMSG_EOR\fP
 265 これはレコードの終り (end\-of\-record) を示し、 返されたデータが完全なレコードであることを示す (一般的には
 266 \fBSOCK_SEQPACKET\fP 型のソケットで使用される)。
 267 .TP
 268 \fBMSG_TRUNC\fP
 269 データグラムが与えられたバッファより大きかったために、 データグラムのはみ出した部分が捨てられたことを示す。
 270 .TP
 271 \fBMSG_CTRUNC\fP
 272 補助データのためのバッファが不足したために、 制御データの一部が捨てられたことを示す。
 273 .TP
 274 \fBMSG_OOB\fP
 275 速達データや帯域外データを受信したことを示す。
 276 .TP
 277 \fBMSG_ERRQUEUE\fP
 278 データは受信しなかったが ソケットのエラー・キューから拡張エラーを受信したことを示す。
 279 .SH 返り値
 280 これらのコールは受信したバイト数を返す。 エラーの場合は \-1 を返し、 \fIerrno\fP にエラーを示す値を設定する。
 281
 282 ストリームソケットの接続相手が正しくシャットダウンを実行した場合は、
 283 返り値は 0 (昔ながらの "end\-of\-file" の戻り値) となる。
 284
 285 Datagram sockets in various domains (e.g., the UNIX and Internet domains)
 286 permit zero\-length datagrams.  When such a datagram is received, the return
 287 value is 0.
 288
 289 The value 0 may also be returned if the requested number of bytes to receive
 290 from a stream socket was 0.
 291 .SH エラー
 292 これらはソケット層で発生する一般的なエラーである。 他のエラーが下層のプロトコル・モジュールで生成され、 返されるかもしれない。
 293 それらのマニュアルを参照すること。
 294 .TP
 295 \fBEAGAIN\fP または \fBEWOULDBLOCK\fP
 296 .\" Actually EAGAIN on Linux
 297 ソケットが非停止 (nonblocking) に設定されていて 受信操作が停止するような状況になったか、 受信に時間切れ (timeout)
 298 が設定されていて データを受信する前に時間切れになった。 POSIX.1\-2001 は、この場合にどちらのエラーを返すことも認めており、 これら 2
 299 つの定数が同じ値を持つことも求めていない。 したがって、移植性が必要なアプリケーションでは、両方の可能性を 確認すべきである。
 300 .TP
 301 \fBEBADF\fP
 302 引き数 \fIsockfd\fP が不正なディスクリプタである。
 303 .TP
 304 \fBECONNREFUSED\fP
 305 リモートのホストでネットワーク接続が拒否された (よくある理由としては、要求したサービスが起動されていないなどがある)。
 306 .TP
 307 \fBEFAULT\fP
 308 受信バッファへのポインタがプロセスのアドレス空間外を指している。
 309 .TP
 310 \fBEINTR\fP
 311 データを受信する前に、シグナルが配送されて割り込まれた。 \fBsignal\fP(7)  参照。
 312 .TP
 313 \fBEINVAL\fP
 314 .\" e.g., msg_namelen < 0 for recvmsg() or addrlen < 0 for recvfrom()
 315 不正な引き数が渡された。
 316 .TP
 317 \fBENOMEM\fP
 318 \fBrecvmsg\fP()  のためのメモリが確保できなかった。
 319 .TP
 320 \fBENOTCONN\fP
 321 ソケットに接続指向プロトコルが割り当てられており、 まだ接続されていない (\fBconnect\fP(2)  と \fBaccept\fP(2)
 322 を参照のこと)。
 323 .TP
 324 \fBENOTSOCK\fP
 325 引き数 \fIsockfd\fP がソケットを参照していない。
 326 .SH 準拠
 327 4.4BSD (これらの関数は 4.2BSD で現われた), POSIX.1\-2001。
 328 .LP
 329 POSIX.1\-2001 では、 \fBMSG_OOB\fP, \fBMSG_PEEK\fP, \fBMSG_WAITALL\fP フラグだけが記載されている。
 330 .SH 注意
 331 上記のプロトタイプは glibc2 にしたがっている。 Single UNIX Specification でも同様だが、 返り値の型が
 332 \fIssize_t\fP となっている (一方で 4.x BSD や libc4 や libc5 は全て \fIint\fP を使用している)。 \fIflags\fP
 333 引き数は 4.x BSD では \fIint\fP だが、libc4 と libc5 では \fIunsigned int\fP である。 \fIlen\fP 引き数は
 334 4.x BSD では \fIint\fP だが、 libc4 と libc5 では \fIsize_t\fP である。 \fIaddrlen\fP 引き数は 4.x
 335 BSD, libc4, libc5 では \fIint\ *\fP である。 現在の \fIsocklen_t\ *\fP は POSIX で発案された。
 336 \fBaccept\fP(2)  も参照すること。
 337
 338 .\" glibc bug raised 12 Mar 2006
 339 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448
 340 .\" The problem is an underlying kernel issue: the size of the
 341 .\" __kernel_size_t type used to type this field varies
 342 .\" across architectures, but socklen_t is always 32 bits.
 343 POSIX.1\-2001 では、構造体 \fImsghdr\fP のフィールド \fImsg_controllen\fP は \fIsocklen_t\fP
 344 型であるべきだとされているが、 現在の glibc では \fIsize_t\fP 型である。
 345
 346 \fBrecvmmsg\fP(2)  には、一度の呼び出しでの複数のデータグラムに使用できる Linux 固有の システムコールに関する情報が書かれている。
 347 .SH 例
 348 \fBrecvfrom\fP()  の利用例が \fBgetaddrinfo\fP(3)  に記載されている。
 349 .SH 関連項目
 350 \fBfcntl\fP(2), \fBgetsockopt\fP(2), \fBread\fP(2), \fBrecvmmsg\fP(2), \fBselect\fP(2),
 351 \fBshutdown\fP(2), \fBsocket\fP(2), \fBcmsg\fP(3), \fBsockatmark\fP(3), \fBsocket\fP(7)
 352 .SH この文書について
 353 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.63 の一部
 354 である。プロジェクトの説明とバグ報告に関する情報は
 355 http://www.kernel.org/doc/man\-pages/ に書かれている。