[PATCH] sendmmsg.2: Updated fixme, added example

[PATCH] sendmmsg.2: Updated fixme, added example

[Elie De Brauwer]

[-- Attachment #1: Type: text/plain, Size: 3648 bytes --]

Hello all,

A patch which updates a fixme which extends man 2 sendmmsg with an example.

The example uses sendmmsg to sends out a string "onetwo" on a first 
datagram,
where both halves originate from distinct buffers and a second datagram
contains "three", coming from a single buffer.

Tested with netcat listening:
root@ubuntu:~# nc -l -u -p 1234
onetwothree

And tcpdump peeking:
root@ubuntu:~# tcpdump -c 2 -s 0 -X -ni lo tcpdump: verbose output 
suppressed, use -v or -vv for full protocol decode
listening on lo, link-type EN10MB (Ethernet), capture size 65535 bytes
18:45:16.632134 IP 127.0.0.1.34715 > 127.0.0.1.1234: UDP, length 6
      0x0000:  4500 0022 c21c 4000 4011 7aac 7f00 0001  E.."..@.@.z.....
      0x0010:  7f00 0001 879b 04d2 000e fe21 6f6e 6574  ...........!onet
      0x0020:  776f                                     wo
18:45:16.633267 IP 127.0.0.1.34715 > 127.0.0.1.1234: UDP, length 5
      0x0000:  4500 0021 c21d 4000 4011 7aac 7f00 0001  E..!..@.@.z.....
      0x0010:  7f00 0001 879b 04d2 000d fe20 7468 7265  ............thre
      0x0020:  65                                       e
2 packets captured
4 packets received by filter
0 packets dropped by kernel

my 2 cents
E.
---
  man2/sendmmsg.2 |   69 
+++++++++++++++++++++++++++++++++++++++++++++++++++++--
  1 file changed, 67 insertions(+), 2 deletions(-)

diff --git a/man2/sendmmsg.2 b/man2/sendmmsg.2
index 12ad3ff..5027619 100644
--- a/man2/sendmmsg.2
+++ b/man2/sendmmsg.2
@@ -23,8 +23,6 @@
  .\" Formatted or processed versions of this manual, if unaccompanied by
  .\" the source, must acknowledge the copyright and authors of this work.
  .\"
-.\" FIXME Adding an example program would improve this page
-.\"
  .TH SENDMMSG 2 2012-02-27 "Linux" "Linux Programmer's Manual"
  .SH NAME
  sendmmsg \- send multiple messages on a socket
@@ -165,6 +163,73 @@ is capped to
  .\"     For error handling an application using sendmmsg needs to retry at
  .\"     the first unsent message, so capping is simpler and requires less
  .\"     application logic than returning EINVAL.
+.SH EXAMPLE
+The example below uses
+.BR sendmmsg ()
+to send
+.I onetwo
+and
+.I three
+in two distinct UDP datagrams using one system call. Where the contents
+of the first datagram originates from multiple buffers.
+
+.nf
+#define _GNU_SOURCE
+#include <netinet/ip.h> +#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+
+int main()
+{
+    int sockfd;
+    struct sockaddr_in sa;
+    struct mmsghdr msg[2];
+    struct iovec msg1[2], msg2;
+    int retval;
+
+    sockfd = socket(AF_INET, SOCK_DGRAM, 0);
+    if (sockfd == -1) {
+        perror("socket()");
+        exit(EXIT_FAILURE);
+    }
+
+    sa.sin_family = AF_INET;
+    sa.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+    sa.sin_port = htons(1234);
+    if (connect(sockfd, (struct sockaddr *)&sa, sizeof(sa))) {
+        perror("connect()");
+        exit(EXIT_FAILURE);
+    }
+
+    memset(msg1, 0, sizeof(msg1));
+    msg1[0].iov_base = "one";
+    msg1[0].iov_len = 3;
+    msg1[1].iov_base = "two";
+    msg1[1].iov_len = 3;
+
+    memset(&msg2, 0, sizeof(msg2));
+    msg2.iov_base = "three";
+    msg2.iov_len = 5;
+
+    memset(msg, 0, sizeof(msg));
+    msg[0].msg_hdr.msg_iov = msg1;
+    msg[0].msg_hdr.msg_iovlen = 2;
+
+    msg[1].msg_hdr.msg_iov = &msg2;
+    msg[1].msg_hdr.msg_iovlen = 1;
+
+    retval = sendmmsg(sockfd, msg, 2, 0);
+    if (retval == -1)
+        perror("sendmmsg()");
+    else
+        printf("%d messages sent\n", retval);
+
+    exit(0);
+}
+.fi
  .SH SEE ALSO
  .BR recvmmsg (2),
  .BR sendmsg (2),
-- 
1.7.10.4


[-- Attachment #2: Attached Message Part --]
[-- Type: text/plain, Size: 3668 bytes --]

Hello all,

A patch which updates a fixme and which extends sendmmsg with an example.

The example uses sendmmsg to sends out a string "onetwo" on a first datagram,
where both halves originate from distinct buffers and a second datagram
contains "three", coming from a single buffer. 

Tested with netcat listening:
root@ubuntu:~# nc -l -u -p 1234
onetwothree

And tcpdump peeking:
root@ubuntu:~# tcpdump -c 2 -s 0 -X -ni lo 
tcpdump: verbose output suppressed, use -v or -vv for full protocol decode
listening on lo, link-type EN10MB (Ethernet), capture size 65535 bytes
18:45:16.632134 IP 127.0.0.1.34715 > 127.0.0.1.1234: UDP, length 6
        0x0000:  4500 0022 c21c 4000 4011 7aac 7f00 0001  E.."..@.@.z.....
        0x0010:  7f00 0001 879b 04d2 000e fe21 6f6e 6574  ...........!onet
        0x0020:  776f                                     wo
18:45:16.633267 IP 127.0.0.1.34715 > 127.0.0.1.1234: UDP, length 5
        0x0000:  4500 0021 c21d 4000 4011 7aac 7f00 0001  E..!..@.@.z.....
        0x0010:  7f00 0001 879b 04d2 000d fe20 7468 7265  ............thre
        0x0020:  65                                       e
2 packets captured
4 packets received by filter
0 packets dropped by kernel

my 2 cents
E. 

---
 man2/sendmmsg.2 |   69 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 67 insertions(+), 2 deletions(-)

diff --git a/man2/sendmmsg.2 b/man2/sendmmsg.2
index 12ad3ff..5027619 100644
--- a/man2/sendmmsg.2
+++ b/man2/sendmmsg.2
@@ -23,8 +23,6 @@
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
 .\"
-.\" FIXME Adding an example program would improve this page
-.\"
 .TH SENDMMSG 2 2012-02-27 "Linux" "Linux Programmer's Manual"
 .SH NAME
 sendmmsg \- send multiple messages on a socket
@@ -165,6 +163,73 @@ is capped to
 .\"     For error handling an application using sendmmsg needs to retry at
 .\"     the first unsent message, so capping is simpler and requires less
 .\"     application logic than returning EINVAL.
+.SH EXAMPLE
+The example below uses 
+.BR sendmmsg ()
+to send  
+.I onetwo
+and 
+.I three
+in two distinct UDP datagrams using one system call. Where the contents
+of the first datagram originates from multiple buffers.
+
+.nf
+#define _GNU_SOURCE
+#include <netinet/ip.h> 
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+
+int main()
+{
+    int sockfd;
+    struct sockaddr_in sa;
+    struct mmsghdr msg[2];
+    struct iovec msg1[2], msg2;
+    int retval;
+
+    sockfd = socket(AF_INET, SOCK_DGRAM, 0);
+    if (sockfd == -1) {
+        perror("socket()");
+        exit(EXIT_FAILURE);
+    }
+
+    sa.sin_family = AF_INET;             
+    sa.sin_addr.s_addr = htonl(INADDR_LOOPBACK);  
+    sa.sin_port = htons(1234);  
+    if (connect(sockfd, (struct sockaddr *)&sa, sizeof(sa))) {
+        perror("connect()");
+        exit(EXIT_FAILURE);
+    }
+
+    memset(msg1, 0, sizeof(msg1)); 
+    msg1[0].iov_base = "one";
+    msg1[0].iov_len = 3;
+    msg1[1].iov_base = "two";
+    msg1[1].iov_len = 3;
+
+    memset(&msg2, 0, sizeof(msg2));
+    msg2.iov_base = "three";
+    msg2.iov_len = 5;
+
+    memset(msg, 0, sizeof(msg));
+    msg[0].msg_hdr.msg_iov = msg1;
+    msg[0].msg_hdr.msg_iovlen = 2;
+
+    msg[1].msg_hdr.msg_iov = &msg2;
+    msg[1].msg_hdr.msg_iovlen = 1;
+
+    retval = sendmmsg(sockfd, msg, 2, 0);
+    if (retval == -1)
+        perror("sendmmsg()");
+    else
+        printf("%d messages sent\n", retval);
+
+    exit(0);
+}
+.fi
 .SH SEE ALSO
 .BR recvmmsg (2),
 .BR sendmsg (2),
-- 
1.7.10.4

Re: [PATCH] sendmmsg.2: Updated fixme, added example

[Michael Kerrisk (man-pages)]

Hello Elie,

Thanks for this patch. See comments below.

On Fri, Dec 14, 2012 at 8:06 PM, Elie De Brauwer
<eliedebrauwer-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Hello all,
>
> A patch which updates a fixme which extends man 2 sendmmsg with an example.
>
> The example uses sendmmsg to sends out a string "onetwo" on a first
> datagram,
> where both halves originate from distinct buffers and a second datagram
> contains "three", coming from a single buffer.
>
> Tested with netcat listening:
> root@ubuntu:~# nc -l -u -p 1234
> onetwothree


Could you work something like the above into the patch, as a shell
session that demonstrates the use of the program.

> And tcpdump peeking:
> root@ubuntu:~# tcpdump -c 2 -s 0 -X -ni lo tcpdump: verbose output
> suppressed, use -v or -vv for full protocol decode
> listening on lo, link-type EN10MB (Ethernet), capture size 65535 bytes
> 18:45:16.632134 IP 127.0.0.1.34715 > 127.0.0.1.1234: UDP, length 6
>      0x0000:  4500 0022 c21c 4000 4011 7aac 7f00 0001  E.."..@.@.z.....
>      0x0010:  7f00 0001 879b 04d2 000e fe21 6f6e 6574  ...........!onet
>      0x0020:  776f                                     wo
> 18:45:16.633267 IP 127.0.0.1.34715 > 127.0.0.1.1234: UDP, length 5
>      0x0000:  4500 0021 c21d 4000 4011 7aac 7f00 0001  E..!..@.@.z.....
>      0x0010:  7f00 0001 879b 04d2 000d fe20 7468 7265  ............thre
>      0x0020:  65                                       e
> 2 packets captured
> 4 packets received by filter
> 0 packets dropped by kernel
>
> my 2 cents
> E.
> ---
>  man2/sendmmsg.2 |   69
> +++++++++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 67 insertions(+), 2 deletions(-)
>
> diff --git a/man2/sendmmsg.2 b/man2/sendmmsg.2
> index 12ad3ff..5027619 100644
> --- a/man2/sendmmsg.2
> +++ b/man2/sendmmsg.2
> @@ -23,8 +23,6 @@
>  .\" Formatted or processed versions of this manual, if unaccompanied by
>  .\" the source, must acknowledge the copyright and authors of this work.
>  .\"
> -.\" FIXME Adding an example program would improve this page
> -.\"
>  .TH SENDMMSG 2 2012-02-27 "Linux" "Linux Programmer's Manual"
>  .SH NAME
>  sendmmsg \- send multiple messages on a socket
> @@ -165,6 +163,73 @@ is capped to
>  .\"     For error handling an application using sendmmsg needs to retry at
>  .\"     the first unsent message, so capping is simpler and requires less
>  .\"     application logic than returning EINVAL.
> +.SH EXAMPLE
> +The example below uses
> +.BR sendmmsg ()
> +to send
> +.I onetwo
> +and
> +.I three
> +in two distinct UDP datagrams using one system call. Where the contents

s/Where the/The/

> +of the first datagram originates from multiple buffers.

s/multiple/a pair of/

> +
> +.nf
> +#define _GNU_SOURCE
> +#include <netinet/ip.h> +#include <stdio.h>

Broken line above.

> +#include <stdlib.h>
> +#include <string.h>
> +#include <sys/types.h>
> +#include <sys/socket.h>
> +
> +int main()

int
main()

[K&R style please.]

> +{
> +    int sockfd;
> +    struct sockaddr_in sa;
> +    struct mmsghdr msg[2];
> +    struct iovec msg1[2], msg2;
> +    int retval;
> +
> +    sockfd = socket(AF_INET, SOCK_DGRAM, 0);
> +    if (sockfd == -1) {

All instances of '-' in code should be '\-'

> +        perror("socket()");
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    sa.sin_family = AF_INET;
> +    sa.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
> +    sa.sin_port = htons(1234);
> +    if (connect(sockfd, (struct sockaddr *)&sa, sizeof(sa))) {

    if (connect(sockfd, (struct sockaddr *) &sa, sizeof(sa)) == \-1) {

(Space before '&' please.)

> +        perror("connect()");
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    memset(msg1, 0, sizeof(msg1));
> +    msg1[0].iov_base = "one";
> +    msg1[0].iov_len = 3;
> +    msg1[1].iov_base = "two";
> +    msg1[1].iov_len = 3;
> +
> +    memset(&msg2, 0, sizeof(msg2));
> +    msg2.iov_base = "three";
> +    msg2.iov_len = 5;
> +
> +    memset(msg, 0, sizeof(msg));
> +    msg[0].msg_hdr.msg_iov = msg1;
> +    msg[0].msg_hdr.msg_iovlen = 2;
> +
> +    msg[1].msg_hdr.msg_iov = &msg2;
> +    msg[1].msg_hdr.msg_iovlen = 1;
> +
> +    retval = sendmmsg(sockfd, msg, 2, 0);
> +    if (retval == -1)
> +        perror("sendmmsg()");
> +    else
> +        printf("%d messages sent\n", retval);

Make the \n into \\n

> +
> +    exit(0);
> +}
> +.fi
>  .SH SEE ALSO
>  .BR recvmmsg (2),
>  .BR sendmsg (2),

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] sendmmsg.2: Updated fixme, added example

[Elie De Brauwer]

Hello all,

Updated my patch with the comment from Michael (thanks for the feedback btw).
I however did not include the shell session using netcat for the simple
reason that the output of netcat does not illustrate that the call functions
correctly. The output of netcat would be the same no matter how much 
UDP datagrams were created in the transmission, the only reason why I showed
it in my previous e-mail was to avoid the generation of icmp port
unreachable which would break my tcpdump capture. This latter one is what I
really wanted to show, but i think that one's a bit too far fetched to be 
held in a manpage.

gr
E. 

---
 man2/sendmmsg.2 |   70 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 68 insertions(+), 2 deletions(-)

diff --git a/man2/sendmmsg.2 b/man2/sendmmsg.2
index 12ad3ff..b426b4d 100644
--- a/man2/sendmmsg.2
+++ b/man2/sendmmsg.2
@@ -23,8 +23,6 @@
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
 .\"
-.\" FIXME Adding an example program would improve this page
-.\"
 .TH SENDMMSG 2 2012-02-27 "Linux" "Linux Programmer's Manual"
 .SH NAME
 sendmmsg \- send multiple messages on a socket
@@ -165,6 +163,74 @@ is capped to
 .\"     For error handling an application using sendmmsg needs to retry at
 .\"     the first unsent message, so capping is simpler and requires less
 .\"     application logic than returning EINVAL.
+.SH EXAMPLE
+The example below uses 
+.BR sendmmsg ()
+to send  
+.I onetwo
+and 
+.I three
+in two distinct UDP datagrams using one system call. The contents
+of the first datagram originates from a pair of buffers.
+
+.nf
+#define _GNU_SOURCE
+#include <netinet/ip.h> 
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+
+int 
+main()
+{
+    int sockfd;
+    struct sockaddr_in sa;
+    struct mmsghdr msg[2];
+    struct iovec msg1[2], msg2;
+    int retval;
+
+    sockfd = socket(AF_INET, SOCK_DGRAM, 0);
+    if (sockfd == \-1) {
+        perror("socket()");
+        exit(EXIT_FAILURE);
+    }
+
+    sa.sin_family = AF_INET;             
+    sa.sin_addr.s_addr = htonl(INADDR_LOOPBACK);  
+    sa.sin_port = htons(1234);  
+    if (connect(sockfd, (struct sockaddr *) &sa, sizeof(sa))) {
+        perror("connect()");
+        exit(EXIT_FAILURE);
+    }
+
+    memset(msg1, 0, sizeof(msg1)); 
+    msg1[0].iov_base = "one";
+    msg1[0].iov_len = 3;
+    msg1[1].iov_base = "two";
+    msg1[1].iov_len = 3;
+
+    memset(&msg2, 0, sizeof(msg2));
+    msg2.iov_base = "three";
+    msg2.iov_len = 5;
+
+    memset(msg, 0, sizeof(msg));
+    msg[0].msg_hdr.msg_iov = msg1;
+    msg[0].msg_hdr.msg_iovlen = 2;
+
+    msg[1].msg_hdr.msg_iov = &msg2;
+    msg[1].msg_hdr.msg_iovlen = 1;
+
+    retval = sendmmsg(sockfd, msg, 2, 0);
+    if (retval == -1)
+        perror("sendmmsg()");
+    else
+        printf("%d messages sent\\n", retval);
+
+    exit(0);
+}
+.fi
 .SH SEE ALSO
 .BR recvmmsg (2),
 .BR sendmsg (2),
-- 
1.7.10.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] sendmmsg.2: Updated fixme, added example

[Michael Kerrisk (man-pages)]

Hello Elie,

On Sat, Dec 15, 2012 at 6:44 PM, Elie De Brauwer
<eliedebrauwer-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Hello all,
>
> Updated my patch with the comment from Michael (thanks for the feedback btw).
> I however did not include the shell session using netcat for the simple
> reason that the output of netcat does not illustrate that the call functions
> correctly. The output of netcat would be the same no matter how much
> UDP datagrams were created in the transmission, the only reason why I showed
> it in my previous e-mail was to avoid the generation of icmp port
> unreachable which would break my tcpdump capture. This latter one is what I
> really wanted to show, but i think that one's a bit too far fetched to be
> held in a manpage.

Fair enough.

I've applied this patch for 3.45.

Cheers,

Michael


> ---
>  man2/sendmmsg.2 |   70 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 68 insertions(+), 2 deletions(-)
>
> diff --git a/man2/sendmmsg.2 b/man2/sendmmsg.2
> index 12ad3ff..b426b4d 100644
> --- a/man2/sendmmsg.2
> +++ b/man2/sendmmsg.2
> @@ -23,8 +23,6 @@
>  .\" Formatted or processed versions of this manual, if unaccompanied by
>  .\" the source, must acknowledge the copyright and authors of this work.
>  .\"
> -.\" FIXME Adding an example program would improve this page
> -.\"
>  .TH SENDMMSG 2 2012-02-27 "Linux" "Linux Programmer's Manual"
>  .SH NAME
>  sendmmsg \- send multiple messages on a socket
> @@ -165,6 +163,74 @@ is capped to
>  .\"     For error handling an application using sendmmsg needs to retry at
>  .\"     the first unsent message, so capping is simpler and requires less
>  .\"     application logic than returning EINVAL.
> +.SH EXAMPLE
> +The example below uses
> +.BR sendmmsg ()
> +to send
> +.I onetwo
> +and
> +.I three
> +in two distinct UDP datagrams using one system call. The contents
> +of the first datagram originates from a pair of buffers.
> +
> +.nf
> +#define _GNU_SOURCE
> +#include <netinet/ip.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <string.h>
> +#include <sys/types.h>
> +#include <sys/socket.h>
> +
> +int
> +main()
> +{
> +    int sockfd;
> +    struct sockaddr_in sa;
> +    struct mmsghdr msg[2];
> +    struct iovec msg1[2], msg2;
> +    int retval;
> +
> +    sockfd = socket(AF_INET, SOCK_DGRAM, 0);
> +    if (sockfd == \-1) {
> +        perror("socket()");
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    sa.sin_family = AF_INET;
> +    sa.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
> +    sa.sin_port = htons(1234);
> +    if (connect(sockfd, (struct sockaddr *) &sa, sizeof(sa))) {
> +        perror("connect()");
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    memset(msg1, 0, sizeof(msg1));
> +    msg1[0].iov_base = "one";
> +    msg1[0].iov_len = 3;
> +    msg1[1].iov_base = "two";
> +    msg1[1].iov_len = 3;
> +
> +    memset(&msg2, 0, sizeof(msg2));
> +    msg2.iov_base = "three";
> +    msg2.iov_len = 5;
> +
> +    memset(msg, 0, sizeof(msg));
> +    msg[0].msg_hdr.msg_iov = msg1;
> +    msg[0].msg_hdr.msg_iovlen = 2;
> +
> +    msg[1].msg_hdr.msg_iov = &msg2;
> +    msg[1].msg_hdr.msg_iovlen = 1;
> +
> +    retval = sendmmsg(sockfd, msg, 2, 0);
> +    if (retval == -1)
> +        perror("sendmmsg()");
> +    else
> +        printf("%d messages sent\\n", retval);
> +
> +    exit(0);
> +}
> +.fi
>  .SH SEE ALSO
>  .BR recvmmsg (2),
>  .BR sendmsg (2),
> --
> 1.7.10.4
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] sendmmsg.2: Updated fixme, added example

[Elie De Brauwer]

Hello all,

Updated my patch with the comment from Michael (thanks for the feedback btw).
I however did not include the shell session using netcat for the simple
reason that the output of netcat does not illustrate that the call functions
correctly. The output of netcat would be the same no matter how much 
UDP datagrams were created in the transmission, the only reason why I showed
it in my previous e-mail was to avoid the generation of icmp port
unreachable which would break my tcpdump capture. This latter one is what I
really wanted to show, but i think that one's a bit too far fetched to be 
held in a manpage.

gr
E. 

---
 man2/sendmmsg.2 |   70 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 68 insertions(+), 2 deletions(-)

diff --git a/man2/sendmmsg.2 b/man2/sendmmsg.2
index 12ad3ff..b426b4d 100644
--- a/man2/sendmmsg.2
+++ b/man2/sendmmsg.2
@@ -23,8 +23,6 @@
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
 .\"
-.\" FIXME Adding an example program would improve this page
-.\"
 .TH SENDMMSG 2 2012-02-27 "Linux" "Linux Programmer's Manual"
 .SH NAME
 sendmmsg \- send multiple messages on a socket
@@ -165,6 +163,74 @@ is capped to
 .\"     For error handling an application using sendmmsg needs to retry at
 .\"     the first unsent message, so capping is simpler and requires less
 .\"     application logic than returning EINVAL.
+.SH EXAMPLE
+The example below uses 
+.BR sendmmsg ()
+to send  
+.I onetwo
+and 
+.I three
+in two distinct UDP datagrams using one system call. The contents
+of the first datagram originates from a pair of buffers.
+
+.nf
+#define _GNU_SOURCE
+#include <netinet/ip.h> 
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+
+int 
+main()
+{
+    int sockfd;
+    struct sockaddr_in sa;
+    struct mmsghdr msg[2];
+    struct iovec msg1[2], msg2;
+    int retval;
+
+    sockfd = socket(AF_INET, SOCK_DGRAM, 0);
+    if (sockfd == \-1) {
+        perror("socket()");
+        exit(EXIT_FAILURE);
+    }
+
+    sa.sin_family = AF_INET;             
+    sa.sin_addr.s_addr = htonl(INADDR_LOOPBACK);  
+    sa.sin_port = htons(1234);  
+    if (connect(sockfd, (struct sockaddr *) &sa, sizeof(sa))) {
+        perror("connect()");
+        exit(EXIT_FAILURE);
+    }
+
+    memset(msg1, 0, sizeof(msg1)); 
+    msg1[0].iov_base = "one";
+    msg1[0].iov_len = 3;
+    msg1[1].iov_base = "two";
+    msg1[1].iov_len = 3;
+
+    memset(&msg2, 0, sizeof(msg2));
+    msg2.iov_base = "three";
+    msg2.iov_len = 5;
+
+    memset(msg, 0, sizeof(msg));
+    msg[0].msg_hdr.msg_iov = msg1;
+    msg[0].msg_hdr.msg_iovlen = 2;
+
+    msg[1].msg_hdr.msg_iov = &msg2;
+    msg[1].msg_hdr.msg_iovlen = 1;
+
+    retval = sendmmsg(sockfd, msg, 2, 0);
+    if (retval == -1)
+        perror("sendmmsg()");
+    else
+        printf("%d messages sent\\n", retval);
+
+    exit(0);
+}
+.fi
 .SH SEE ALSO
 .BR recvmmsg (2),
 .BR sendmsg (2),
-- 
1.7.10.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] recvmmsg.2: Updated fixme, added example

[Elie De Brauwer]

Hi all,

Same patch as before but I spotted a typo I made applicatoin -> application.

my 2 cents
E.

---
 man2/recvmmsg.2 |   94 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 92 insertions(+), 2 deletions(-)

diff --git a/man2/recvmmsg.2 b/man2/recvmmsg.2
index a7b00d4..3252be7 100644
--- a/man2/recvmmsg.2
+++ b/man2/recvmmsg.2
@@ -21,8 +21,6 @@
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
 .\"
-.\" FIXME: This page could be improved with an example program.
-.\"
 .TH RECVMMSG 2 2012-05-02 "Linux" "Linux Programmer's Manual"
 .SH NAME
 recvmmsg \- receive multiple messages on a socket
@@ -165,6 +163,98 @@ Support in glibc was added in version 2.12.
 .SH CONFORMING TO
 .BR recvmmsg ()
 is Linux-specific.
+.SH EXAMPLE
+.PP
+The following program uses 
+.BR recvmmsg () 
+to receive multiple messages on a socket and stores
+them in multiple buffers. The call returns of all buffers
+are filled or if the timeout specified is expired.
+
+The following 
+.BR bash (1)
+snippet periodically generates UDP datagrams containing a 
+a random number:
+.in +4n
+.nf
+.RB "$" " while true; do echo $RANDOM > /dev/udp/127.0.0.1/1234; sleep 0.25; done"
+.fi
+.in
+
+These datagrams are read by the example application which 
+can give the following output:
+.in +4n
+.nf
+.RB "$" " ./a.out"
+5 messages received
+1 11782
+2 11345
+3 304
+4 13514
+5 28421
+.fi
+.in
+.SS Program source
+\&
+.nf
+#define _GNU_SOURCE
+#include <netinet/ip.h> 
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/socket.h>
+
+int 
+main()
+{
+#define VLEN 10
+#define BUFSIZE 200 
+#define TIMEOUT 1
+    int sockfd, retval, i;
+    struct sockaddr_in sa;
+    struct mmsghdr msgs[VLEN];
+    struct iovec iovecs[VLEN];
+    char bufs[VLEN][BUFSIZE+1];
+    struct timespec timeout;
+
+    sockfd = socket(AF_INET, SOCK_DGRAM, 0);
+    if (sockfd == \-1) {
+        perror("socket()");
+        exit(EXIT_FAILURE);
+    }
+
+    sa.sin_family = AF_INET;             
+    sa.sin_addr.s_addr = htonl(INADDR_LOOPBACK);  
+    sa.sin_port = htons(1234);  
+    if (bind(sockfd, (struct sockaddr *) &sa, sizeof(sa))) {
+        perror("bind()");
+        exit(EXIT_FAILURE);
+    }
+
+    memset(msgs, 0, sizeof(msgs));
+    for (i = 0; i < VLEN; i++) {
+        iovecs[i].iov_base         = bufs[i];
+        iovecs[i].iov_len          = BUFSIZE;
+        msgs[i].msg_hdr.msg_iov    = &iovecs[i];
+        msgs[i].msg_hdr.msg_iovlen = 1;
+    }
+
+    timeout.tv_sec = TIMEOUT;
+    timeout.tv_nsec = 0;
+
+    retval = recvmmsg(sockfd, msgs, VLEN, 0, &timeout);
+    if (retval == -1)
+        perror("recvmmsg()");
+    else {
+        printf("%d messages received\n", retval);
+        for (i = 0; i < retval; i++) {
+            bufs[i][msgs[i].msg_len] = 0;
+            printf("%d %s", i+1, bufs[i]);
+        }
+    }
+    exit(EXIT_SUCCESS);
+}
+.fi 
 .SH SEE ALSO
 .BR clock_gettime (2),
 .BR recvmsg (2),
-- 
1.7.10.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] recvmmsg.2: Updated fixme, added example

[Michael Kerrisk (man-pages)]

Hello Elie,

Can you please resubmit with fixes as below.

On Wed, Dec 19, 2012 at 10:28 PM, Elie De Brauwer
<eliedebrauwer-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Hi all,
>
> Same patch as before but I spotted a typo I made applicatoin -> application.
>
> my 2 cents
> E.
>
> ---
>  man2/recvmmsg.2 |   94 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 92 insertions(+), 2 deletions(-)
>
> diff --git a/man2/recvmmsg.2 b/man2/recvmmsg.2
> index a7b00d4..3252be7 100644
> --- a/man2/recvmmsg.2
> +++ b/man2/recvmmsg.2
> @@ -21,8 +21,6 @@
>  .\" Formatted or processed versions of this manual, if unaccompanied by
>  .\" the source, must acknowledge the copyright and authors of this work.
>  .\"
> -.\" FIXME: This page could be improved with an example program.
> -.\"
>  .TH RECVMMSG 2 2012-05-02 "Linux" "Linux Programmer's Manual"
>  .SH NAME
>  recvmmsg \- receive multiple messages on a socket
> @@ -165,6 +163,98 @@ Support in glibc was added in version 2.12.
>  .SH CONFORMING TO
>  .BR recvmmsg ()
>  is Linux-specific.
> +.SH EXAMPLE
> +.PP
> +The following program uses
> +.BR recvmmsg ()
> +to receive multiple messages on a socket and stores
> +them in multiple buffers. The call returns of all buffers

Start new sentences on new source lines.

> +are filled or if the timeout specified is expired.
> +
> +The following
> +.BR bash (1)

change to "The following shell snippet..." (We don't really care that it's bash)

> +snippet periodically generates UDP datagrams containing a
> +a random number:
> +.in +4n
> +.nf
> +.RB "$" " while true; do echo $RANDOM > /dev/udp/127.0.0.1/1234; sleep 0.25; done"
> +.fi
> +.in
> +
> +These datagrams are read by the example application which
> +can give the following output:
> +.in +4n
> +.nf
> +.RB "$" " ./a.out"
> +5 messages received
> +1 11782
> +2 11345
> +3 304
> +4 13514
> +5 28421
> +.fi
> +.in
> +.SS Program source
> +\&
> +.nf
> +#define _GNU_SOURCE
> +#include <netinet/ip.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <string.h>
> +#include <sys/socket.h>
> +
> +int
> +main()
> +{
> +#define VLEN 10
> +#define BUFSIZE 200
> +#define TIMEOUT 1
> +    int sockfd, retval, i;
> +    struct sockaddr_in sa;
> +    struct mmsghdr msgs[VLEN];
> +    struct iovec iovecs[VLEN];
> +    char bufs[VLEN][BUFSIZE+1];
> +    struct timespec timeout;
> +
> +    sockfd = socket(AF_INET, SOCK_DGRAM, 0);
> +    if (sockfd == \-1) {
> +        perror("socket()");
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    sa.sin_family = AF_INET;
> +    sa.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
> +    sa.sin_port = htons(1234);
> +    if (bind(sockfd, (struct sockaddr *) &sa, sizeof(sa))) {

Add "== \-1" here please.

> +        perror("bind()");
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    memset(msgs, 0, sizeof(msgs));
> +    for (i = 0; i < VLEN; i++) {
> +        iovecs[i].iov_base         = bufs[i];
> +        iovecs[i].iov_len          = BUFSIZE;
> +        msgs[i].msg_hdr.msg_iov    = &iovecs[i];
> +        msgs[i].msg_hdr.msg_iovlen = 1;
> +    }
> +
> +    timeout.tv_sec = TIMEOUT;
> +    timeout.tv_nsec = 0;
> +
> +    retval = recvmmsg(sockfd, msgs, VLEN, 0, &timeout);
> +    if (retval == -1)
> +        perror("recvmmsg()");
> +    else {

Make the preceding (and note the addition of the backslash).

if (retval == \-1)
    perror()
    exit(EXIT_FAILURE);
}

And then the following part does not need to sit in an 'else' branch.

> +        printf("%d messages received\n", retval);

\n should be \\n

> +        for (i = 0; i < retval; i++) {
> +            bufs[i][msgs[i].msg_len] = 0;
> +            printf("%d %s", i+1, bufs[i]);
> +        }
> +    }
> +    exit(EXIT_SUCCESS);
> +}
> +.fi
>  .SH SEE ALSO
>  .BR clock_gettime (2),
>  .BR recvmsg (2),

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] recvmmsg.2 Updated fixme, added example

[Elie De Brauwer]

Hi all,

Please find below a patch with the comments in below (including two 
other typo's I seem to have missed yesterday). 

Thanks for the comments.

E.


---
 man2/recvmmsg.2 |   94 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 92 insertions(+), 2 deletions(-)

diff --git a/man2/recvmmsg.2 b/man2/recvmmsg.2
index a7b00d4..0c6db49 100644
--- a/man2/recvmmsg.2
+++ b/man2/recvmmsg.2
@@ -21,8 +21,6 @@
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
 .\"
-.\" FIXME: This page could be improved with an example program.
-.\"
 .TH RECVMMSG 2 2012-05-02 "Linux" "Linux Programmer's Manual"
 .SH NAME
 recvmmsg \- receive multiple messages on a socket
@@ -165,6 +163,98 @@ Support in glibc was added in version 2.12.
 .SH CONFORMING TO
 .BR recvmmsg ()
 is Linux-specific.
+.SH EXAMPLE
+.PP
+The following program uses 
+.BR recvmmsg () 
+to receive multiple messages on a socket and stores
+them in multiple buffers. 
+The call returns if all buffers are filled or if the 
+timeout specified is expired.
+
+The following snippet periodically generates UDP datagrams 
+containing a random number:
+.in +4n
+.nf
+.RB "$" " while true; do echo $RANDOM > /dev/udp/127.0.0.1/1234; sleep 0.25; done"
+.fi
+.in
+
+These datagrams are read by the example application which 
+can give the following output:
+.in +4n
+.nf
+.RB "$" " ./a.out"
+5 messages received
+1 11782
+2 11345
+3 304
+4 13514
+5 28421
+.fi
+.in
+.SS Program source
+\&
+.nf
+#define _GNU_SOURCE
+#include <netinet/ip.h> 
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/socket.h>
+
+int 
+main()
+{
+#define VLEN 10
+#define BUFSIZE 200 
+#define TIMEOUT 1
+    int sockfd, retval, i;
+    struct sockaddr_in sa;
+    struct mmsghdr msgs[VLEN];
+    struct iovec iovecs[VLEN];
+    char bufs[VLEN][BUFSIZE+1];
+    struct timespec timeout;
+
+    sockfd = socket(AF_INET, SOCK_DGRAM, 0);
+    if (sockfd == \-1) {
+        perror("socket()");
+        exit(EXIT_FAILURE);
+    }
+
+    sa.sin_family = AF_INET;             
+    sa.sin_addr.s_addr = htonl(INADDR_LOOPBACK);  
+    sa.sin_port = htons(1234);  
+    if (bind(sockfd, (struct sockaddr *) &sa, sizeof(sa)) == \-1) {
+        perror("bind()");
+        exit(EXIT_FAILURE);
+    }
+
+    memset(msgs, 0, sizeof(msgs));
+    for (i = 0; i < VLEN; i++) {
+        iovecs[i].iov_base         = bufs[i];
+        iovecs[i].iov_len          = BUFSIZE;
+        msgs[i].msg_hdr.msg_iov    = &iovecs[i];
+        msgs[i].msg_hdr.msg_iovlen = 1;
+    }
+
+    timeout.tv_sec = TIMEOUT;
+    timeout.tv_nsec = 0;
+
+    retval = recvmmsg(sockfd, msgs, VLEN, 0, &timeout);
+    if (retval == \-1) {
+        perror("recvmmsg()");
+        exit(EXIT_FAILURE);
+    }
+
+    printf("%d messages received\\n", retval);
+    for (i = 0; i < retval; i++) {
+        bufs[i][msgs[i].msg_len] = 0;
+        printf("%d %s", i+1, bufs[i]);
+    }
+    exit(EXIT_SUCCESS);
+}
+.fi 
 .SH SEE ALSO
 .BR clock_gettime (2),
 .BR recvmsg (2),
-- 
1.7.10.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] recvmmsg.2 Updated fixme, added example

[Michael Kerrisk (man-pages)]

Hello Elie,

On Thu, Dec 20, 2012 at 7:47 PM, Elie De Brauwer
<eliedebrauwer-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Hi all,
>
> Please find below a patch with the comments in below (including two
> other typo's I seem to have missed yesterday).
>
> Thanks for the comments.

Thanks for the update. I've applied this for 3.46.

Cheers,

Michael


> ---
>  man2/recvmmsg.2 |   94 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 92 insertions(+), 2 deletions(-)
>
> diff --git a/man2/recvmmsg.2 b/man2/recvmmsg.2
> index a7b00d4..0c6db49 100644
> --- a/man2/recvmmsg.2
> +++ b/man2/recvmmsg.2
> @@ -21,8 +21,6 @@
>  .\" Formatted or processed versions of this manual, if unaccompanied by
>  .\" the source, must acknowledge the copyright and authors of this work.
>  .\"
> -.\" FIXME: This page could be improved with an example program.
> -.\"
>  .TH RECVMMSG 2 2012-05-02 "Linux" "Linux Programmer's Manual"
>  .SH NAME
>  recvmmsg \- receive multiple messages on a socket
> @@ -165,6 +163,98 @@ Support in glibc was added in version 2.12.
>  .SH CONFORMING TO
>  .BR recvmmsg ()
>  is Linux-specific.
> +.SH EXAMPLE
> +.PP
> +The following program uses
> +.BR recvmmsg ()
> +to receive multiple messages on a socket and stores
> +them in multiple buffers.
> +The call returns if all buffers are filled or if the
> +timeout specified is expired.
> +
> +The following snippet periodically generates UDP datagrams
> +containing a random number:
> +.in +4n
> +.nf
> +.RB "$" " while true; do echo $RANDOM > /dev/udp/127.0.0.1/1234; sleep 0.25; done"
> +.fi
> +.in
> +
> +These datagrams are read by the example application which
> +can give the following output:
> +.in +4n
> +.nf
> +.RB "$" " ./a.out"
> +5 messages received
> +1 11782
> +2 11345
> +3 304
> +4 13514
> +5 28421
> +.fi
> +.in
> +.SS Program source
> +\&
> +.nf
> +#define _GNU_SOURCE
> +#include <netinet/ip.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <string.h>
> +#include <sys/socket.h>
> +
> +int
> +main()
> +{
> +#define VLEN 10
> +#define BUFSIZE 200
> +#define TIMEOUT 1
> +    int sockfd, retval, i;
> +    struct sockaddr_in sa;
> +    struct mmsghdr msgs[VLEN];
> +    struct iovec iovecs[VLEN];
> +    char bufs[VLEN][BUFSIZE+1];
> +    struct timespec timeout;
> +
> +    sockfd = socket(AF_INET, SOCK_DGRAM, 0);
> +    if (sockfd == \-1) {
> +        perror("socket()");
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    sa.sin_family = AF_INET;
> +    sa.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
> +    sa.sin_port = htons(1234);
> +    if (bind(sockfd, (struct sockaddr *) &sa, sizeof(sa)) == \-1) {
> +        perror("bind()");
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    memset(msgs, 0, sizeof(msgs));
> +    for (i = 0; i < VLEN; i++) {
> +        iovecs[i].iov_base         = bufs[i];
> +        iovecs[i].iov_len          = BUFSIZE;
> +        msgs[i].msg_hdr.msg_iov    = &iovecs[i];
> +        msgs[i].msg_hdr.msg_iovlen = 1;
> +    }
> +
> +    timeout.tv_sec = TIMEOUT;
> +    timeout.tv_nsec = 0;
> +
> +    retval = recvmmsg(sockfd, msgs, VLEN, 0, &timeout);
> +    if (retval == \-1) {
> +        perror("recvmmsg()");
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    printf("%d messages received\\n", retval);
> +    for (i = 0; i < retval; i++) {
> +        bufs[i][msgs[i].msg_len] = 0;
> +        printf("%d %s", i+1, bufs[i]);
> +    }
> +    exit(EXIT_SUCCESS);
> +}
> +.fi
>  .SH SEE ALSO
>  .BR clock_gettime (2),
>  .BR recvmsg (2),
> --
> 1.7.10.4
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html