CMSG_DATA(3)

💅 CMSG_DATA(3) — socket control message routines for ancillary data access

okay bestie, so this is page 3 of the Library Functions Manual — the manual name is literally right there in the corner, no cap — and today we're doing the socket control message girlies. Ancillary data access. Yes it sounds scary. No it's not, come sit with me 🫶

CMSG_DATA, CMSG_FIRSTHDR, CMSG_LEN, CMSG_NXTHDR, CMSG_SPACE — socket control message routines for ancillary data access. That's the whole friend group ✨

---

✨ SYNOPSIS ✨

#include <sys/socket.h>

unsigned char *
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 🦋

So the control message API is the thing you use to construct ancillary data objects for control messages that get sent and received across sockets. It's giving backstage-pass energy 🎟️

Control messages get passed around by the recvmsg(2) and sendmsg(2) system calls. The cmsghdr structure — which is described over in recvmsg(2), go read it, iykyk — is what you use to specify a chain of control messages.

Use these routines, bestie. Do not go poking at the control message header members and data buffers directly — these routines are the ones that make sure the necessary alignment constraints are met. Trust the process 💅

The following routines are provided:

• CMSG_DATA(cmsg) — this one accesses the data portion of the control message header cmsg. And the way it ensures proper alignment constraints on the beginning of ancillary data are met? iconic. you literally could not do that yourself.
• CMSG_FIRSTHDR(msghdr) — accesses the first control message attached to the message msghdr. And if there are no control messages attached? It returns NULL. empty. barren. no messages. 😭
• CMSG_LEN(len) — figures out the size in bytes of a control message, and yes that includes the control message header. len is the length of the data held by the control message. This value is what's normally stored in the cmsg_len of each control message. It also accounts for any alignment constraints on the beginning of ancillary data — she's thorough 💖
• CMSG_NXTHDR(msghdr, cmsg) — returns the location of the control message following cmsg in the message msghdr. And if cmsg is the last one in the chain? NULL. end of the line. that's the last one, periodt.
• CMSG_SPACE(len) — determines the size in bytes needed to hold a control message and its contents of length len, and yeah it includes the control message header too. This value is what's normally stored in msg_msgcontrollen. It accounts for any alignment constraints on the beginning of ancillary data as well as any needed to pad the next control message. she does it all. multi-talented. 👑

---

🎀 EXAMPLES 🎀

okay so the example: it constructs a control message containing a file descriptor in the parent process, passes it over a pre-shared socket to the child process, and then the child sends a "hello" string back to the parent using the received file descriptor. full circle communication. we love a reciprocal relationship 🫶

#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, "failed to receive 'hello'");
                printf("parent: received '%s'\n", buf);
                break;
        }

        return (0);
}

---

🌈 SEE ALSO 🌈

recvmsg(2), sendmsg(2), socket(2), ip(4), ip6(4), unix(4)

go read those too, they're all linked, it's a whole ecosystem bestie 🦋

---

⭐ STANDARDS ⭐

• W. Stevens and M. Thomas, Advanced Sockets API for IPv6, RFC 2292, February 1998.
• W. Stevens, M. Thomas, E. Nordmark, and T. Jinmei, Advanced Sockets Application Program Interface (API) for IPv6, RFC 3542, May 2003.

two RFCs. practically vintage. 📜

---

🧚 HISTORY 🧚

The control message API first appeared in 4.2BSD. and this manual page itself? originally written by Jared Yanovich <jaredy@OpenBSD.org> for OpenBSD 3.8, and eventually brought to FreeBSD 12.0 by Mateusz Piotrowski <0mp@FreeBSD.org>. a whole journey. a whole lore arc. we stan a documented migration 💜

---

aaaand that's the page, bestie 🎀 sign-off time: this one's from Debian, dated March 13, 2020 — CMSG_DATA(3), that's a wrap. slay 💅✨