CMSG_DATA(3) BSD Programmer's Manual CMSG_DATA(3)NAME
CMSG_DATA, CMSG_FIRSTHDR, CMSG_LEN, CMSG_NXTHDR, CMSG_SPACE - socket con-
trol message routines
SYNOPSIS
#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);
DESCRIPTION
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) sys-
tem 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 be-
ginning 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 routine ac-
counts for any alignment constraints on the beginning of ancil-
lary data.
CMSG_NXTHDR(mhdr, cmsg)
This routine returns the location of the control message follow-
ing 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 con-
trol message and its contents of length 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.
EXAMPLES
The following example constructs a control message containing a file
descriptor and passes it over a socket:
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");
And an example that receives and decomposes the control message:
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. */
}
}
SEE ALSOrecvmsg(2), sendmsg(2), socket(2)HISTORY
The control message API first appeared in 4.2BSD.
MirOS BSD #10-current July 3, 2005 1
