draft/man2/recvmmsg.2

   1 .\" Copyright (C) 2011 by Andi Kleen <andi@firstfloor.org>
   2 .\" and Copyright (c) 2011 by Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" Syscall added in following commit
  27 .\"     commit a2e2725541fad72416326798c2d7fa4dafb7d337
  28 .\"     Author: Arnaldo Carvalho de Melo <acme@redhat.com>
  29 .\"     Date:   Mon Oct 12 23:40:10 2009 -0700
  30 .\"
  31 .\"*******************************************************************
  32 .\"
  33 .\" This file was generated with po4a. Translate the source file.
  34 .\"
  35 .\"*******************************************************************
  36 .\"
  37 .\" Japanese Version Copyright (c) 2013  Akihiro MOTOKI
  38 .\"         all rights reserved.
  39 .\" Translated 2013-05-22, Akihiro MOTOKI <amotoki@gmail.com>
  40 .\"
  41 .TH RECVMMSG 2 2014\-06\-13 Linux "Linux Programmer's Manual"
  42 .SH 名前
  43 recvmmsg \- 複数のメッセージをソケットから受信する
  44 .SH 書式
  45 .nf
  46 \fB#define _GNU_SOURCE\fP         /* feature_test_macros(7) 参照 */
  47 \fB#include <sys/socket.h>\fP
  48
  49 \fBint recvmmsg(int \fP\fIsockfd\fP\fB, struct mmsghdr *\fP\fImsgvec\fP\fB, unsigned int \fP\fIvlen\fP\fB,\fP
  50 .br
  51 \fB             unsigned int \fP\fIflags\fP\fB, struct timespec *\fP\fItimeout\fP\fB);\fP
  52 .fi
  53 .SH 説明
  54 \fBrecvmmsg\fP() システムコールは \fBrecvmsg\fP(2) の拡張で、
  55 このシステムコールを使うと一度の呼び出しでソケットから複数のメッセージを受信することができる (アプリケーションによっては性能上のメリットがある)。
  56 他に \fBrecvmsg\fP(2) から拡張されている点としては、受信操作におけるタイムアウトのサポートがある。
  57
  58 \fIsockfd\fP 引き数は、データを受信するソケットのファイルディスクリプターである。
  59
  60 \fImsgvec\fP 引き数は \fImmsghdr\fP 構造体の配列である。 この配列の大きさは \fIvlen\fP で指定する。
  61
  62 \fImmsghdr\fP 構造体は \fI<sys/socket.h>\fP で次のように定義されている。
  63
  64 .in +4n
  65 .nf
  66 struct mmsghdr {
  67     struct msghdr msg_hdr;  /* メッセージヘッダー */
  68     unsigned int  msg_len;  /* このヘッダーで受信されたバイト数 */
  69 };
  70 .fi
  71 .in
  72 .PP
  73 \fImsg_hdr\fP フィールドは、 \fBrecvmsg\fP(2) で説明されている \fImsghdr\fP 構造体である。 \fImsg_len\fP
  74 フィールドは、 このエントリーで返されるメッセージのバイト数で、 このヘッダーに対して \fBrecvmsg\fP(2)
  75 を呼び出した場合の返り値と同じ値が入る。
  76
  77 \fIflags\fP 引き数には複数のフラグを論理和 (OR) で指定できる。 フラグは、 \fBrecvmsg\fP(2)
  78 で説明されているものに加えて、以下が使用できる。
  79 .TP
  80 \fBMSG_WAITFORONE\fP (Linux 2.6.34 以降)
  81 最初のメッセージを受信後に \fBMSG_DONTWAIT\fP を有効にする。
  82 .PP
  83 \fItimeout\fP 引き数は \fIstruct timespec\fP (\fBclock_gettime\fP(2) 参照) へのポインターで、
  84 この構造体で受信操作のタイムアウト (秒とナノ秒) を指定する (\fIただし、バグを参照のこと\fP)
  85 (待ち時間はシステムクロックの粒度に切り上げられ、カーネルのスケジューリング遅延により少しだけ長くなる可能性がある)。 \fItimeout\fPが NULL
  86 の場合、 受信操作は無期限に停止 (block) する。
  87
  88 停止 (blocking) モードの \fBrecvmmsg\fP() の呼び出しは、 \fIvlen\fP
  89 個のメッセージを受信するか、タイムアウトが満了するまで停止する。 非停止 (nonblocking) モードの呼び出しでは、 読み出し可能なメッセージ
  90 (最大で \fIvlen\fP 個) を読み出し、 すぐに返る。
  91
  92 \fBrecvmmsg\fP() が返った際には、 \fImsgvec\fP のうちデータが受信された要素には、受信したそれぞれのメッセージの情報が格納されている。
  93 また、 \fImsg_len\fP には受信したメッセージの大きさが入り、 \fImsg_hdr\fP の各フィールドは \fBrecvmsg\fP(2)
  94 に書かれている通りに更新される。 呼び出しの返り値は、更新された \fImsgvec\fP の要素数である。
  95 .SH 返り値
  96 成功すると、 \fBrecvmmsg\fP() は \fImsgvec\fP に受信されたメッセージ数を返す。 エラーの場合、 \-1 を返し、 \fIerrno\fP
  97 にエラーを示す値を設定する。
  98 .SH エラー
  99 エラーは \fBrecvmsg\fP(2) と同じである。 これに加えて、以下のエラーが起こる場合がある。
 100 .TP
 101 \fBEINVAL\fP
 102 \fItimeout\fP が無効である。
 103 .SH バージョン
 104 \fBrecvmmsg\fP() システムコールは Linux 2.6.33 で追加された。 glibc でのサポートはバージョン 2.12
 105 以降で利用可能である。
 106 .SH 準拠
 107 \fBrecvmmsg\fP() は Linux 固有である。
 108 .SH 例
 109 .PP
 110 以下のプログラムは、 \fBrecvmmsg\fP() を使って複数のメッセージをソケットから受信し、それらを複数のバッファーに格納する。
 111 呼び出しは、すべてのバッファーにメッセージが格納されるか、 指定したタイムアウト時間が経過すると返る。
 112
 113 以下のコマンドは、 ランダムな数字が入った UDP データグラムを定期的に生成する。
 114 .in +4n
 115 .nf
 116
 117 $\fB while true; do echo $RANDOM > /dev/udp/127.0.0.1/1234; \fP
 118 \fBsleep 0.25; done\fP
 119 .fi
 120 .in
 121
 122 生成されたデータグラムをサンプルアプリケーションが読み出し、以下のような出力が得られる。
 123 .in +4n
 124 .nf
 125
 126 $\fB ./a.out\fP
 127 5 messages received
 128 1 11782
 129 2 11345
 130 3 304
 131 4 13514
 132 5 28421
 133 .fi
 134 .in
 135 .SS プログラムのソース
 136 \&
 137 .nf
 138 #define _GNU_SOURCE
 139 #include <netinet/ip.h>
 140 #include <stdio.h>
 141 #include <stdlib.h>
 142 #include <string.h>
 143 #include <sys/socket.h>
 144
 145 int
 146 main(void)
 147 {
 148 #define VLEN 10
 149 #define BUFSIZE 200
 150 #define TIMEOUT 1
 151     int sockfd, retval, i;
 152     struct sockaddr_in sa;
 153     struct mmsghdr msgs[VLEN];
 154     struct iovec iovecs[VLEN];
 155     char bufs[VLEN][BUFSIZE+1];
 156     struct timespec timeout;
 157
 158     sockfd = socket(AF_INET, SOCK_DGRAM, 0);
 159     if (sockfd == \-1) {
 160         perror("socket()");
 161         exit(EXIT_FAILURE);
 162     }
 163
 164     sa.sin_family = AF_INET;
 165     sa.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
 166     sa.sin_port = htons(1234);
 167     if (bind(sockfd, (struct sockaddr *) &sa, sizeof(sa)) == \-1) {
 168         perror("bind()");
 169         exit(EXIT_FAILURE);
 170     }
 171
 172     memset(msgs, 0, sizeof(msgs));
 173     for (i = 0; i < VLEN; i++) {
 174         iovecs[i].iov_base         = bufs[i];
 175         iovecs[i].iov_len          = BUFSIZE;
 176         msgs[i].msg_hdr.msg_iov    = &iovecs[i];
 177         msgs[i].msg_hdr.msg_iovlen = 1;
 178     }
 179
 180     timeout.tv_sec = TIMEOUT;
 181     timeout.tv_nsec = 0;
 182
 183     retval = recvmmsg(sockfd, msgs, VLEN, 0, &timeout);
 184     if (retval == \-1) {
 185         perror("recvmmsg()");
 186         exit(EXIT_FAILURE);
 187     }
 188
 189     printf("%d messages received\en", retval);
 190     for (i = 0; i < retval; i++) {
 191         bufs[i][msgs[i].msg_len] = 0;
 192         printf("%d %s", i+1, bufs[i]);
 193     }
 194     exit(EXIT_SUCCESS);
 195 }
 196 .fi
 197 .SH バグ
 198 .\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=75371
 199 .\" http://thread.gmane.org/gmane.linux.man/5677
 200 \fItimeout\fP 引き数は意図した通りには動作しない。 タイムアウトは各データグラムの受信後にのみチェックされる。 そのため、
 201 タイムアウトが満了する前に \fIvlen\-1\fP 個のデータグラムを受信し、 その後全くデータグラムを受信しなかった場合、
 202 呼び出しはずっと停止し続けてしまう。
 203 .SH 関連項目
 204 \fBclock_gettime\fP(2), \fBrecvmsg\fP(2), \fBsendmmsg\fP(2), \fBsendmsg\fP(2),
 205 \fBsocket\fP(2), \fBsocket\fP(7)
 206 .SH この文書について
 207 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
 208 である。プロジェクトの説明とバグ報告に関する情報は
 209 http://www.kernel.org/doc/man\-pages/ に書かれている。