Date: Sun, 19 Aug 2018 17:42:50 +0000 (UTC) From: Mateusz Piotrowski <0mp@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r338060 - in head: lib/libc/sys share/man/man3 share/man/man4 Message-ID: <201808191742.w7JHgoDv057160@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@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@OpenBSD.org +for +.Ox 3.8 +and eventually brought to +.Fx 12.0 +by +.An Mateusz Piotrowski Aq Mt 0mp@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"
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201808191742.w7JHgoDv057160>