CMSG_DATA,
CMSG_FIRSTHDR,
CMSG_LEN,
CMSG_NXTHDR,
CMSG_SPACE —
socket control message routines
#include
<sys/socket.h>
void *
CMSG_DATA(
struct
cmsghdr *);
struct cmsghdr *
CMSG_FIRSTHDR(
struct
msghdr *);
size_t
CMSG_LEN(
size_t);
struct cmsghdr *
CMSG_NXTHDR(
struct
msghdr *,
struct
cmsghdr *);
size_t
CMSG_SPACE(
size_t);
The control message API is used to construct ancillary data objects for use in
control messages sent and received across sockets.
Control messages are passed around by the
recvmsg(2) and
sendmsg(2) system
calls. The
cmsghdr structure, described in
recvmsg(2), is used
to specify a chain of control messages.
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.
The following routines are provided:
-
-
CMSG_DATA(cmsg)- This routine accesses the data portion of the control message header
cmsg. It ensures proper alignment
constraints on the beginning of ancillary data are met.
-
-
CMSG_FIRSTHDR(mhdr)- This routine accesses the first control message attached to the message
msg. If no control messages are attached
to the message, this routine returns
NULL.
-
-
CMSG_LEN(len)- This routine determines the size in bytes of a control message, which
includes the control message header. len
specifies the length of the data held by the control message. This value
is what is normally stored in the
cmsg_len of each control message. This
routine accounts for any alignment constraints on the beginning of
ancillary data.
-
-
CMSG_NXTHDR(mhdr,
cmsg)- This routine returns the location of the control message following
cmsg in the message
mhdr. If
cmsg is the last control message in the
chain, this routine returns
NULL.
-
-
CMSG_SPACE(len)- This routine determines the size in bytes needed to hold a control message
and its contents of length len, which
includes the control message header. This value is what is normally stored
in 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.
The following example constructs a control message containing a file descriptor
and passes it over a socket:
struct msghdr msg;
struct cmsghdr *cmsg;
union {
struct cmsghdr hdr;
unsigned char buf[CMSG_SPACE(sizeof(int))];
} cmsgbuf;
memset(&msg, 0, sizeof(msg));
msg.msg_control = &cmsgbuf.buf;
msg.msg_controllen = sizeof(cmsgbuf.buf);
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");
And an example that receives and decomposes the control message:
struct msghdr msg;
struct cmsghdr *cmsg;
union {
struct cmsghdr hdr;
unsigned char buf[CMSG_SPACE(sizeof(int))];
} cmsgbuf;
memset(&msg, 0, sizeof(msg));
msg.msg_control = &cmsgbuf.buf;
msg.msg_controllen = sizeof(cmsgbuf.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. */
}
}
recvmsg(2),
sendmsg(2),
socket(2)
The control message API first appeared in
4.2BSD.
![[OpenBSD]](/openbsd.gif){kind=small}