svn commit: r338060 - in head: lib/libc/sys share/man/man3 share/man/man4
Mateusz Piotrowski
0mp at FreeBSD.org
Sun Aug 19 17:42:52 UTC 2018
Author: 0mp (ports committer)
Date: Sun Aug 19 17:42:49 2018
New Revision: 338060
URL: https://svnweb.freebsd.org/changeset/base/338060
Log:
Document socket control message routines for ancillary data access (CMSG_DATA).
PR: 227777
Reviewed by: bcr, eadler
Approved by: mat (mentor), manpages (bcr)
Obtained from: OpenBSD
Differential Revision: https://reviews.freebsd.org/D15215
Added:
head/share/man/man3/CMSG_DATA.3 (contents, props changed)
Modified:
head/lib/libc/sys/recv.2
head/lib/libc/sys/send.2
head/lib/libc/sys/socket.2
head/share/man/man3/Makefile
head/share/man/man4/ip.4
head/share/man/man4/ip6.4
head/share/man/man4/unix.4
Modified: head/lib/libc/sys/recv.2
==============================================================================
--- head/lib/libc/sys/recv.2 Sun Aug 19 17:40:50 2018 (r338059)
+++ head/lib/libc/sys/recv.2 Sun Aug 19 17:42:49 2018 (r338060)
@@ -28,7 +28,7 @@
.\" @(#)recv.2 8.3 (Berkeley) 2/21/94
.\" $FreeBSD$
.\"
-.Dd May 20, 2018
+.Dd August 19, 2018
.Dt RECV 2
.Os
.Sh NAME
@@ -366,6 +366,7 @@ address space.
.Xr read 2 ,
.Xr select 2 ,
.Xr socket 2 ,
+.Xr CMSG_DATA 3 ,
.Xr unix 4
.Sh HISTORY
The
Modified: head/lib/libc/sys/send.2
==============================================================================
--- head/lib/libc/sys/send.2 Sun Aug 19 17:40:50 2018 (r338059)
+++ head/lib/libc/sys/send.2 Sun Aug 19 17:42:49 2018 (r338060)
@@ -28,7 +28,7 @@
.\" From: @(#)send.2 8.2 (Berkeley) 2/21/94
.\" $FreeBSD$
.\"
-.Dd August 18, 2016
+.Dd August 19, 2018
.Dt SEND 2
.Os
.Sh NAME
@@ -242,7 +242,8 @@ is not connected.
.Xr recv 2 ,
.Xr select 2 ,
.Xr socket 2 ,
-.Xr write 2
+.Xr write 2 ,
+.Xr CMSG_DATA 3
.Sh HISTORY
The
.Fn send
Modified: head/lib/libc/sys/socket.2
==============================================================================
--- head/lib/libc/sys/socket.2 Sun Aug 19 17:40:50 2018 (r338059)
+++ head/lib/libc/sys/socket.2 Sun Aug 19 17:42:49 2018 (r338060)
@@ -28,7 +28,7 @@
.\" From: @(#)socket.2 8.1 (Berkeley) 6/4/93
.\" $FreeBSD$
.\"
-.Dd June 10, 2017
+.Dd August 19, 2018
.Dt SOCKET 2
.Os
.Sh NAME
@@ -299,6 +299,7 @@ The socket type is not supported by the protocol.
.Xr shutdown 2 ,
.Xr socketpair 2 ,
.Xr write 2 ,
+.Xr CMSG_DATA 3 ,
.Xr getprotoent 3 ,
.Xr netgraph 4 ,
.Xr protocols 5
Added: head/share/man/man3/CMSG_DATA.3
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/share/man/man3/CMSG_DATA.3 Sun Aug 19 17:42:49 2018 (r338060)
@@ -0,0 +1,214 @@
+.\" Written by Jared Yanovich <jaredy at openbsd.org>
+.\" Public domain, July 3, 2005
+.\"
+.\" $FreeBSD$
+.Dd August 19, 2018
+.Dt CMSG_DATA 3
+.Os
+.Sh NAME
+.Nm CMSG_DATA ,
+.Nm CMSG_FIRSTHDR ,
+.Nm CMSG_LEN ,
+.Nm CMSG_NXTHDR ,
+.Nm CMSG_SPACE
+.Nd socket control message routines for ancillary data access
+.Sh SYNOPSIS
+.In sys/socket.h
+.Ft unsigned char *
+.Fn CMSG_DATA "struct cmsghdr *"
+.Ft struct cmsghdr *
+.Fn CMSG_FIRSTHDR "struct msghdr *"
+.Ft size_t
+.Fn CMSG_LEN "size_t"
+.Ft struct cmsghdr *
+.Fn CMSG_NXTHDR "struct msghdr *" "struct cmsghdr *"
+.Ft size_t
+.Fn CMSG_SPACE "size_t"
+.Sh DESCRIPTION
+The control message API is used to construct ancillary data objects for
+use in control messages sent and received across sockets.
+.Pp
+Control messages are passed around by the
+.Xr recvmsg 2
+and
+.Xr sendmsg 2
+system calls.
+The
+.Vt cmsghdr
+structure, described in
+.Xr recvmsg 2 ,
+is used to specify a chain of control messages.
+.Pp
+These routines should be used instead of directly accessing the control
+message header members and data buffers as they ensure that necessary
+alignment constraints are met.
+.Pp
+The following routines are provided:
+.Bl -tag -width Ds
+.It Fn CMSG_DATA cmsg
+This routine accesses the data portion of the control message header
+.Fa cmsg .
+It ensures proper alignment constraints on the beginning of ancillary
+data are met.
+.It Fn CMSG_FIRSTHDR mhdr
+This routine accesses the first control message attached to the
+message
+.Fa msg .
+If no control messages are attached to the message, this routine
+returns
+.Dv NULL .
+.It Fn CMSG_LEN len
+This routine determines the size in bytes of a control message,
+which includes the control message header.
+.Fa len
+specifies the length of the data held by the control message.
+This value is what is normally stored in the
+.Fa cmsg_len
+of each control message.
+This routine accounts for any alignment constraints on the beginning of
+ancillary data.
+.It Fn CMSG_NXTHDR mhdr cmsg
+This routine returns the location of the control message following
+.Fa cmsg
+in the message
+.Fa mhdr .
+If
+.Fa cmsg
+is the last control message in the chain, this routine returns
+.Dv NULL .
+.It Fn CMSG_SPACE len
+This routine determines the size in bytes needed to hold a control
+message and its contents of length
+.Fa len ,
+which includes the control message header.
+This value is what is normally stored in
+.Fa msg_msgcontrollen .
+This routine accounts for any alignment constraints on the beginning of
+ancillary data as well as any needed to pad the next control message.
+.El
+.Sh EXAMPLES
+The following example constructs a control message containing a file descriptor
+in the parent process and passes it over a pre-shared socket over the child
+process.
+Then the child process sends a "hello" string to the parent process using the
+received file descriptor.
+.Bd -literal
+#include <sys/socket.h>
+
+#include <err.h>
+#include <stdio.h>
+#include <string.h>
+#include <sysexits.h>
+#include <unistd.h>
+
+#define HELLOLEN sizeof("hello")
+
+int
+main()
+{
+ struct msghdr msg;
+ union {
+ struct cmsghdr hdr;
+ unsigned char buf[CMSG_SPACE(sizeof(int))];
+ } cmsgbuf;
+ char buf[HELLOLEN];
+ int hellofd[2];
+ int presharedfd[2];
+ struct cmsghdr *cmsg;
+
+ if (socketpair(PF_LOCAL, SOCK_STREAM, 0, presharedfd) == -1)
+ err(EX_OSERR, "failed to create a pre-shared socket pair");
+
+ memset(&msg, 0, sizeof(msg));
+ msg.msg_control = &cmsgbuf.buf;
+ msg.msg_controllen = sizeof(cmsgbuf.buf);
+ msg.msg_iov = NULL;
+ msg.msg_iovlen = 0;
+
+ switch (fork()) {
+ case -1:
+ err(EX_OSERR, "fork");
+ case 0:
+ close(presharedfd[0]);
+ strlcpy(buf, "hello", HELLOLEN);
+
+ if (recvmsg(presharedfd[1], &msg, 0) == -1)
+ err(EX_IOERR, "failed to receive a message");
+ if (msg.msg_flags & (MSG_CTRUNC | MSG_TRUNC))
+ errx(EX_IOERR, "control message truncated");
+ for (cmsg = CMSG_FIRSTHDR(&msg); cmsg != NULL;
+ cmsg = CMSG_NXTHDR(&msg, cmsg)) {
+ if (cmsg->cmsg_len == CMSG_LEN(sizeof(int)) &&
+ cmsg->cmsg_level == SOL_SOCKET &&
+ cmsg->cmsg_type == SCM_RIGHTS) {
+ hellofd[1] = *(int *)CMSG_DATA(cmsg);
+ printf("child: sending '%s'\n", buf);
+ if (write(hellofd[1], buf, HELLOLEN) == -1)
+ err(EX_IOERR, "failed to send 'hello'");
+ }
+ }
+ break;
+ default:
+ close(presharedfd[1]);
+
+ if (socketpair(PF_LOCAL, SOCK_STREAM, 0, hellofd) == -1)
+ err(EX_OSERR, "failed to create a 'hello' socket pair");
+
+ cmsg = CMSG_FIRSTHDR(&msg);
+ cmsg->cmsg_len = CMSG_LEN(sizeof(int));
+ cmsg->cmsg_level = SOL_SOCKET;
+ cmsg->cmsg_type = SCM_RIGHTS;
+ *(int *)CMSG_DATA(cmsg) = hellofd[1];
+
+ if (sendmsg(presharedfd[0], &msg, 0) == -1)
+ err(EX_IOERR, "sendmsg");
+ close(hellofd[1]);
+
+ if (read(hellofd[0], buf, HELLOLEN) == -1)
+ err(EX_IOERR, "faild to receive 'hello'");
+ printf("parent: received '%s'\n", buf);
+ break;
+ }
+
+ return (0);
+}
+.Ed
+.Sh SEE ALSO
+.Xr recvmsg 2 ,
+.Xr sendmsg 2 ,
+.Xr socket 2 ,
+.Xr ip 4 ,
+.Xr ip6 4 ,
+.Xr unix 4
+.Sh STANDARDS
+.Bl -item
+.It
+.Rs
+.%A W. Stevens
+.%A M. Thomas
+.%T "Advanced Sockets API for IPv6"
+.%R RFC 2292
+.%D February 1998
+.Re
+.It
+.Rs
+.%A W. Stevens
+.%A M. Thomas
+.%A E. Nordmark
+.%A T. Jinmei
+.%T "Advanced Sockets Application Program Interface (API) for IPv6"
+.%R RFC 3542
+.%D May 2003
+.Re
+.El
+.Sh HISTORY
+The control message API first appeared in
+.Bx 4.2 .
+This manual page was originally written by
+.An Jared Yanovich Aq Mt jaredy at OpenBSD.org
+for
+.Ox 3.8
+and eventually brought to
+.Fx 12.0
+by
+.An Mateusz Piotrowski Aq Mt 0mp at FreeBSD.org .
Modified: head/share/man/man3/Makefile
==============================================================================
--- head/share/man/man3/Makefile Sun Aug 19 17:40:50 2018 (r338059)
+++ head/share/man/man3/Makefile Sun Aug 19 17:42:49 2018 (r338060)
@@ -8,6 +8,7 @@ PACKAGE=runtime-manuals
MAN= assert.3 \
ATOMIC_VAR_INIT.3 \
bitstring.3 \
+ CMSG_DATA.3 \
end.3 \
fpgetround.3 \
intro.3 \
@@ -57,6 +58,10 @@ MLINKS+= bitstring.3 bit_alloc.3 \
bitstring.3 bit_set.3 \
bitstring.3 bitstr_size.3 \
bitstring.3 bit_test.3
+MLINKS+= CMSG_DATA.3 CMSG_FIRSTHDR.3 \
+ CMSG_DATA.3 CMSG_LEN.3 \
+ CMSG_DATA.3 CMSG_NEXTHDR.3 \
+ CMSG_DATA.3 CMSG_SPACE.3
MLINKS+= end.3 edata.3 \
end.3 etext.3
MLINKS+= fpgetround.3 fpgetmask.3 \
Modified: head/share/man/man4/ip.4
==============================================================================
--- head/share/man/man4/ip.4 Sun Aug 19 17:40:50 2018 (r338059)
+++ head/share/man/man4/ip.4 Sun Aug 19 17:42:49 2018 (r338060)
@@ -28,7 +28,7 @@
.\" @(#)ip.4 8.2 (Berkeley) 11/30/93
.\" $FreeBSD$
.\"
-.Dd September 1, 2014
+.Dd August 19, 2018
.Dt IP 4
.Os
.Sh NAME
@@ -888,6 +888,7 @@ field was not equal to the length of the datagram writ
.Xr recv 2 ,
.Xr send 2 ,
.Xr byteorder 3 ,
+.Xr CMSG_DATA 3 ,
.Xr sourcefilter 3 ,
.Xr icmp 4 ,
.Xr igmp 4 ,
Modified: head/share/man/man4/ip6.4
==============================================================================
--- head/share/man/man4/ip6.4 Sun Aug 19 17:40:50 2018 (r338059)
+++ head/share/man/man4/ip6.4 Sun Aug 19 17:42:49 2018 (r338060)
@@ -30,7 +30,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd March 13, 2011
+.Dd August 19, 2018
.Dt IP6 4
.Os
.Sh NAME
@@ -651,6 +651,7 @@ An ancillary data object was improperly formed.
.Xr send 2 ,
.Xr setsockopt 2 ,
.Xr socket 2 ,
+.Xr CMSG_DATA 3 ,
.\" .Xr inet6_option_space 3 ,
.\" .Xr inet6_rthdr_space 3 ,
.Xr if_nametoindex 3 ,
Modified: head/share/man/man4/unix.4
==============================================================================
--- head/share/man/man4/unix.4 Sun Aug 19 17:40:50 2018 (r338059)
+++ head/share/man/man4/unix.4 Sun Aug 19 17:42:49 2018 (r338060)
@@ -28,7 +28,7 @@
.\" @(#)unix.4 8.1 (Berkeley) 6/9/93
.\" $FreeBSD$
.\"
-.Dd February 3, 2017
+.Dd August 19, 2018
.Dt UNIX 4
.Os
.Sh NAME
@@ -350,6 +350,7 @@ socket option.
.Xr sendto 2 ,
.Xr setsockopt 2 ,
.Xr socket 2 ,
+.Xr CMSG_DATA 3 ,
.Xr intro 4
.Rs
.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
More information about the svn-src-all
mailing list