add a manpage describing the socket control message macros.

lots of help and ok millert, ok henning, jmc

2 files changed, 140 insertions, 3 deletions

diff --git a/share/man/man3/CMSG_DATA.3 b/share/man/man3/CMSG_DATA.3
new file mode 100644
index 00000000000..1d3c3727e1c
--- /dev/null
+++ b/share/man/man3/CMSG_DATA.3
@@ -0,0 +1,135 @@
+.\"	$OpenBSD: CMSG_DATA.3,v 1.1 2005/07/04 03:03:16 jaredy Exp $
+.\" Written by Jared Yanovich <jaredy@openbsd.org>
+.\" Public domain, July 3, 2005
+.Dd July 3, 2005
+.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
+.Sh SYNOPSIS
+.In sys/socket.h
+.Ft void *
+.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 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 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 and passes it over a socket:
+.Bd -literal -offset indent
+struct msghdr	 msg;
+struct cmsghdr	*cmsg;
+unsigned char	 buf[CMSG_SPACE(sizeof(int))];
+
+memset(&msg, 0, sizeof(msg));
+msg.msg_control = buf;
+msg.msg_controllen = CMSG_LEN(sizeof(int));
+
+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) = fd;
+
+if (sendmsg(s, &msg, 0) == -1)
+	err(1, "sendmsg");
+.Ed
+.Pp
+And an example that receives and decomposes the control message:
+.Bd -literal -offset indent
+struct msghdr	 msg;
+struct cmsghdr	*cmsg;
+unsigned char	 buf[CMSG_SPACE(sizeof(int))];
+
+memset(&msg, 0, sizeof(msg));
+msg.msg_control = buf;
+msg.msg_controllen = sizeof(buf);
+
+if (recvmsg(s, &msg, 0) == -1)
+	err(1, "recvmsg");
+if ((msg.msg_flags & MSG_TRUNC) || (msg.msg_flags & MSG_CTRUNC))
+	errx(1, "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) {
+		fd = *(int *)CMSG_DATA(cmsg);
+		/* Do something with the descriptor. */
+	}
+}
+.Ed
+.Sh SEE ALSO
+.Xr recvmsg 2 ,
+.Xr sendmsg 2 ,
+.Xr socket 2
+.Sh HISTORY
+The control message API first appeared in
+.Bx 4.2 .
diff --git a/share/man/man3/Makefile b/share/man/man3/Makefile
index 4a338ee1ba6..2a64b09ee4a 100644
--- a/share/man/man3/Makefile
+++ b/share/man/man3/Makefile
@@ -1,13 +1,15 @@
-#	$OpenBSD: Makefile,v 1.17 2005/01/30 14:38:17 kettenis Exp $
+#	$OpenBSD: Makefile,v 1.18 2005/07/04 03:03:16 jaredy Exp $
 #	@(#)Makefile	8.2 (Berkeley) 12/13/93
 
-MAN=	assert.3 bitstring.3 dlfcn.3 dl_iterate_phdr.3 end.3 intro.3 queue.3 \
-	stdarg.3 sysexits.3 tree.3
+MAN=	assert.3 bitstring.3 CMSG_DATA.3 dlfcn.3 dl_iterate_phdr.3 end.3 \
+	intro.3 queue.3 stdarg.3 sysexits.3 tree.3
 MLINKS+=bitstring.3 bit_alloc.3 bitstring.3 bit_clear.3 \
 	bitstring.3 bit_decl.3 bitstring.3 bit_ffc.3 bitstring.3 bit_ffs.3 \
 	bitstring.3 bit_nclear.3 bitstring.3 bit_set.3 \
 	bitstring.3 bit_size.3  bitstring.3 bit_test.3 bitstring.3 bit_nset.3 \
 	bitstring.3 bitstr_size.3
+MLINKS+=CMSG_DATA.3 CMSG_FIRSTHDR.3 CMSG_DATA.3 CMSG_LEN.3 \
+	CMSG_DATA.3 CMSG_NXTHDR.3 CMSG_DATA.3 CMSG_SPACE.3
 MLINKS+=end.3 edata.3 end.3 etext.3
 MLINKS+=queue.3 LIST_ENTRY.3 queue.3 LIST_HEAD.3 \
 	queue.3 LIST_HEAD_INITIALIZER.3 queue.3 LIST_FIRST.3 \