Manual Pages  — CMSG_DATA

CMSG_DATA, CMSG_FIRSTHDR, CMSG_LEN, CMSG_NXTHDR, CMSG_SPACE – socket control message routines for ancillary data access

SYNOPSIS DESCRIPTION EXAMPLES SEE ALSO STANDARDS HISTORY

#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);

The following example constructs a control message containing a file descriptor in the parent process and passes it over a pre-shared socket over the child process. Then the child process sends a "hello" string to the parent process using the received file descriptor.

#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' , 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' , buf);
                break;
        }

        return (0);
}

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

The control message API first appeared in BSD 4.2 . This manual page was originally written by Jared Yanovich <Mt jaredy@OpenBSD.org> for OpenBSD 3.8 and eventually brought to FreeBSD 12.0 by Mateusz Piotrowski <Mt 0mp@FreeBSD.org>.