Updated: 2025/Nov/16

Please read Privacy Policy. It's for your privacy.

CMSG_DATA(3)               Library Functions Manual               CMSG_DATA(3)

NAME
     CMSG_DATA, CMSG_FIRSTHDR, CMSG_LEN, CMSG_NXTHDR, CMSG_SPACE - socket
     control message routines

SYNOPSIS
     #include <sys/socket.h>

     unsigned char *
     CMSG_DATA(struct cmsghdr *);

     const unsigned char *
     CCMSG_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)
     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.

             If len is an integer constant expression, then CMSG_LEN(len) is
             an integer constant expression.

     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.

             If len is an integer constant expression, then CMSG_SPACE(len) is
             an integer constant expression.

EXAMPLES
     The following example constructs a control message containing a file
     descriptor and passes it over a socket:

           struct msghdr    msg;
           struct cmsghdr  *cmsg;
           /* We use a union to make sure hdr is aligned */
           union {
                   struct cmsghdr  hdr;
                   unsigned char   buf[CMSG_SPACE(sizeof(int))];
           } cmsgbuf;

           (void)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 the control message and handles all the file
     descriptors it receives:

           struct msghdr    msg;
           struct cmsghdr  *cmsg;
           union {
                   struct cmsghdr  hdr;
                   unsigned char   buf[CMSG_SPACE(sizeof(int))];
           } cmsgbuf;

           (void)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_CTRUNC)
                   warnx("control message truncated");
           for (cmsg = CMSG_FIRSTHDR(&msg); cmsg != NULL;
               cmsg = CMSG_NXTHDR(&msg, cmsg)) {
                   if (cmsg->cmsg_level == SOL_SOCKET &&
                       cmsg->cmsg_type == SCM_RIGHTS) {
                           int *fdp = (int *)CMSG_DATA(cmsg);
                           socklen_t nbytes = cmsg->cmsg_len - CMSG_LEN(0);
                           socklen_t nfds = nbytes/sizeof(fdp[0]);

                           assert(nbytes % sizeof(fdp[0]) == 0);

                           while (nfds --> 0) {
                                   int fd = *fdp++;

                                   /* Do something with the descriptor. */
                           }
                   }
           }

     Note that even if the receiver intends to size its control buffer for one
     file descriptor with CMSG_SPACE(sizeof(int)), this size may be rounded up
     for alignment to enough space for more than one file descriptor.  So if
     the sender may send more than one file descriptor at a time, the receiver
     cannot restrict itself to receiving at most one at a time, and must be
     prepared to handle all of them -- otherwise they will simply leak on the
     receiver side.

SEE ALSO
     recvmsg(2), sendmsg(2), socket(2)

HISTORY
     The control message API first appeared in 4.2BSD.

NetBSD 11.99                   January 24, 2015                   NetBSD 11.99