draft/man2/sendmmsg.2

   1 .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" with some material from a draft by
   3 .\" Stephan Mueller <stephan.mueller@atsec.com>
   4 .\" in turn based on Andi Kleen's recvmmsg.2 page.
   5 .\"
   6 .\" %%%LICENSE_START(VERBATIM)
   7 .\" Permission is granted to make and distribute verbatim copies of this
   8 .\" manual provided the copyright notice and this permission notice are
   9 .\" preserved on all copies.
  10 .\"
  11 .\" Permission is granted to copy and distribute modified versions of this
  12 .\" manual under the conditions for verbatim copying, provided that the
  13 .\" entire resulting derived work is distributed under the terms of a
  14 .\" permission notice identical to this one.
  15 .\"
  16 .\" Since the Linux kernel and libraries are constantly changing, this
  17 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  18 .\" responsibility for errors or omissions, or for damages resulting from
  19 .\" the use of the information contained herein.  The author(s) may not
  20 .\" have taken the same level of care in the production of this manual,
  21 .\" which is licensed free of charge, as they might when working
  22 .\" professionally.
  23 .\"
  24 .\" Formatted or processed versions of this manual, if unaccompanied by
  25 .\" the source, must acknowledge the copyright and authors of this work.
  26 .\" %%%LICENSE_END
  27 .\"
  28 .\"*******************************************************************
  29 .\"
  30 .\" This file was generated with po4a. Translate the source file.
  31 .\"
  32 .\"*******************************************************************
  33 .\"
  34 .\" Japanese Version Copyright (c) 2013  Akihiro MOTOKI
  35 .\"         all rights reserved.
  36 .\" Translated 2013-05-22, Akihiro MOTOKI <amotoki@gmail.com>
  37 .\"
  38 .TH SENDMMSG 2 2012\-12\-16 Linux "Linux Programmer's Manual"
  39 .SH 名前
  40 sendmmsg \- 複数のメッセージをソケットへ送信する
  41 .SH 書式
  42 .nf
  43 \fB#define _GNU_SOURCE\fP
  44 \fB#include <sys/socket.h>\fP
  45
  46 \fBint sendmmsg(int \fP\fIsockfd\fP\fB, struct mmsghdr *\fP\fImsgvec\fP\fB, unsigned int \fP\fIvlen\fP\fB,\fP
  47 \fB             unsigned int \fP\fIflags\fP\fB);\fP
  48 .fi
  49 .SH 説明
  50 .\" See commit 228e548e602061b08ee8e8966f567c12aa079682
  51 \fBsendmmsg\fP() システムコールは \fBsendmsg\fP(2) の拡張で、
  52 このシステムコールを使うと一度の呼び出しでソケットに複数のメッセージを送信できる (アプリケーションによっては性能上のメリットがある)。
  53
  54 \fIsockfd\fP 引き数は、 データを送信するソケットのファイルディスクリプタである。
  55
  56 \fImsgvec\fP 引き数は \fImmsghdr\fP 構造体の配列である。 この配列の大きさは \fIvlen\fP で指定する。
  57
  58 \fImmsghdr\fP 構造体は \fI<sys/socket.h>\fP で次のように定義されている。
  59
  60 .in +4n
  61 .nf
  62 struct mmsghdr {
  63     struct msghdr msg_hdr;  /* メッセージヘッダ */
  64     unsigned int  msg_len;  /* 送信されたバイト数 */
  65 };
  66 .fi
  67 .in
  68 .PP
  69 \fImsg_hdr\fP フィールドは、 \fBsendmsg\fP(2) で説明されている \fImsghdr\fP 構造体である。 \fImsg_len\fP
  70 フィールドは \fImsg_hdr\fP から送信されたメッセージのバイト数を返すのに使用される。 この値は \fBsendmsg\fP(2)
  71 をこのヘッダに対して呼び出した場合の返り値と同じである。
  72
  73 \fIflags\fP 引き数には複数のフラグを論理和 (OR) で指定できる。フラグは \fBsendmsg\fP(2) と同じである。
  74
  75 停止 (blocking) モードの \fBsendmmsg\fP() の呼び出しは、 \fIvlen\fP 個のメッセージが送信されるまで停止する。 非停止
  76 (nonblocking) モードの呼び出しでは、 送信できるだけのメッセージ (最大で \fIvlen\fP 個) を送信し、 すぐに返る。
  77
  78 \fBsendmmsg\fP() が返った際には、 \fImsgvec\fP の送信が行われた要素の \fImsg_len\fP フィールドは、対応する
  79 \fImsg_hdr\fP から送信されたバイト数が入っている。 呼び出しの返り値は、更新された \fImsgvec\fP の要素数である。
  80 .SH 返り値
  81 成功すると、 \fBsendmmsg\fP() は \fImsgvec\fP から送信されたメッセージ数を返す。 返り値が \fIvlen\fP よりも小さい場合、
  82 呼び出した側では再度 \fBsendmmsg\fP を呼び出して残りのメッセージを送信することができる。
  83
  84 エラーの場合、 \-1 を返し、 \fIerrno\fP にエラーを示す値を設定する。
  85 .SH エラー
  86 .\" commit 728ffb86f10873aaf4abd26dde691ee40ae731fe
  87 .\"     ... only return an error if no datagrams could be sent.
  88 .\"     If less than the requested number of messages were sent, the application
  89 .\"     must retry starting at the first failed one and if the problem is
  90 .\"     persistent the error will be returned.
  91 .\"
  92 .\"     This matches the behaviour of other syscalls like read/write - it
  93 .\"     is not an error if less than the requested number of elements are sent.
  94 エラーは \fBsendmsg\fP(2) と同じである。 エラーが返されるのは、 データグラムが全く送信できなかった場合のみである。
  95 .SH バージョン
  96 \fBsendmmsg\fP() システムコールは Linux 3.0 で追加された。 glibc でのサポートはバージョン 2.14 で追加された。
  97 .SH 準拠
  98 \fBsendmmsg\fP() は Linux 固有である。
  99 .SH 注意
 100 .\" commit 98382f419f32d2c12d021943b87dea555677144b
 101 .\"     net: Cap number of elements for sendmmsg
 102 .\"
 103 .\"     To limit the amount of time we can spend in sendmmsg, cap the
 104 .\"     number of elements to UIO_MAXIOV (currently 1024).
 105 .\"
 106 .\"     For error handling an application using sendmmsg needs to retry at
 107 .\"     the first unsent message, so capping is simpler and requires less
 108 .\"     application logic than returning EINVAL.
 109 \fIvlen\fP に指定できる値の最大値は \fBUIO_MAXIOV\fP (1024) である。
 110 .SH 例
 111 以下の例では、 \fBsendmmsg\fP() を使って、 一度のシステムコールで、 \fIonetwo\fP と \fIthree\fP を二つの別々の UDP
 112 データグラムで送信する。 一つ目のデータグラムの内容は、二つのバッファから取得される。
 113
 114 .nf
 115 #define _GNU_SOURCE
 116 #include <netinet/ip.h>
 117 #include <stdio.h>
 118 #include <stdlib.h>
 119 #include <string.h>
 120 #include <sys/types.h>
 121 #include <sys/socket.h>
 122
 123 int
 124 main(void)
 125 {
 126     int sockfd;
 127     struct sockaddr_in sa;
 128     struct mmsghdr msg[2];
 129     struct iovec msg1[2], msg2;
 130     int retval;
 131
 132     sockfd = socket(AF_INET, SOCK_DGRAM, 0);
 133     if (sockfd == \-1) {
 134         perror("socket()");
 135         exit(EXIT_FAILURE);
 136     }
 137
 138     sa.sin_family = AF_INET;
 139     sa.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
 140     sa.sin_port = htons(1234);
 141     if (connect(sockfd, (struct sockaddr *) &sa, sizeof(sa)) == \-1) {
 142         perror("connect()");
 143         exit(EXIT_FAILURE);
 144     }
 145
 146     memset(msg1, 0, sizeof(msg1));
 147     msg1[0].iov_base = "one";
 148     msg1[0].iov_len = 3;
 149     msg1[1].iov_base = "two";
 150     msg1[1].iov_len = 3;
 151
 152     memset(&msg2, 0, sizeof(msg2));
 153     msg2.iov_base = "three";
 154     msg2.iov_len = 5;
 155
 156     memset(msg, 0, sizeof(msg));
 157     msg[0].msg_hdr.msg_iov = msg1;
 158     msg[0].msg_hdr.msg_iovlen = 2;
 159
 160     msg[1].msg_hdr.msg_iov = &msg2;
 161     msg[1].msg_hdr.msg_iovlen = 1;
 162
 163     retval = sendmmsg(sockfd, msg, 2, 0);
 164     if (retval == \-1)
 165         perror("sendmmsg()");
 166     else
 167         printf("%d messages sent\en", retval);
 168
 169     exit(0);
 170 }
 171 .fi
 172 .SH 関連項目
 173 \fBrecvmmsg\fP(2), \fBsendmsg\fP(2), \fBsocket\fP(2), \fBsocket\fP(7)
 174 .SH この文書について
 175 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.53 の一部
 176 である。プロジェクトの説明とバグ報告に関する情報は
 177 http://www.kernel.org/doc/man\-pages/ に書かれている。