1CMSG(3)                    Linux Programmer's Manual                   CMSG(3)
2
3
4

NAME

6       CMSG_ALIGN,  CMSG_SPACE,  CMSG_NXTHDR, CMSG_FIRSTHDR - access ancillary
7       data
8

SYNOPSIS

10       #include <sys/socket.h>
11
12       struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *msgh);
13       struct cmsghdr *CMSG_NXTHDR(struct msghdr *msgh,
14                                   struct cmsghdr *cmsg);
15       size_t CMSG_ALIGN(size_t length);
16       size_t CMSG_SPACE(size_t length);
17       size_t CMSG_LEN(size_t length);
18       unsigned char *CMSG_DATA(struct cmsghdr *cmsg);
19

DESCRIPTION

21       These macros are used to  create  and  access  control  messages  (also
22       called ancillary data) that are not a part of the socket payload.  This
23       control information may include the interface the packet  was  received
24       on, various rarely used header fields, an extended error description, a
25       set of file descriptors, or UNIX credentials.   For  instance,  control
26       messages  can  be  used to send additional header fields such as IP op‐
27       tions.  Ancillary data is sent by calling sendmsg(2)  and  received  by
28       calling recvmsg(2).  See their manual pages for more information.
29
30       Ancillary  data is a sequence of cmsghdr structures with appended data.
31       See the specific protocol man pages for the available  control  message
32       types.  The maximum ancillary buffer size allowed per socket can be set
33       using /proc/sys/net/core/optmem_max; see socket(7).
34
35       The cmsghdr structure is defined as follows:
36
37           struct cmsghdr {
38               size_t cmsg_len;    /* Data byte count, including header
39                                      (type is socklen_t in POSIX) */
40               int    cmsg_level;  /* Originating protocol */
41               int    cmsg_type;   /* Protocol-specific type */
42           /* followed by
43              unsigned char cmsg_data[]; */
44           };
45
46       The sequence of cmsghdr structures should never be  accessed  directly.
47       Instead, use only the following macros:
48
49       *  CMSG_FIRSTHDR() returns a pointer to the first cmsghdr in the ancil‐
50          lary data buffer associated with the passed msghdr.  It returns NULL
51          if there isn't enough space for a cmsghdr in the buffer.
52
53       *  CMSG_NXTHDR()  returns  the next valid cmsghdr after the passed cms‐
54          ghdr.  It returns NULL when there isn't enough  space  left  in  the
55          buffer.
56
57          When  initializing  a  buffer  that will contain a series of cmsghdr
58          structures (e.g., to be sent with sendmsg(2)),  that  buffer  should
59          first  be  zero-initialized  to  ensure  the  correct  operation  of
60          CMSG_NXTHDR().
61
62       *  CMSG_ALIGN(), given a length,  returns  it  including  the  required
63          alignment.  This is a constant expression.
64
65       *  CMSG_SPACE()  returns  the number of bytes an ancillary element with
66          payload of the passed data length occupies.  This is a constant  ex‐
67          pression.
68
69       *  CMSG_DATA() returns a pointer to the data portion of a cmsghdr.  The
70          pointer returned cannot be assumed to be suitably  aligned  for  ac‐
71          cessing  arbitrary payload data types.  Applications should not cast
72          it to a pointer type matching the payload, but  should  instead  use
73          memcpy(3) to copy data to or from a suitably declared object.
74
75       *  CMSG_LEN()  returns the value to store in the cmsg_len member of the
76          cmsghdr structure, taking into account any necessary alignment.   It
77          takes  the  data  length as an argument.  This is a constant expres‐
78          sion.
79
80       To create ancillary data, first initialize the msg_controllen member of
81       the  msghdr  with  the  length  of  the  control  message  buffer.  Use
82       CMSG_FIRSTHDR() on the msghdr to get  the  first  control  message  and
83       CMSG_NXTHDR()  to  get  all  subsequent ones.  In each control message,
84       initialize cmsg_len (with CMSG_LEN()), the other cmsghdr header fields,
85       and  the  data  portion using CMSG_DATA().  Finally, the msg_controllen
86       field of the msghdr should be set to the sum of the CMSG_SPACE() of the
87       length  of all control messages in the buffer.  For more information on
88       the msghdr, see recvmsg(2).
89

CONFORMING TO

91       This ancillary data model conforms to the POSIX.1g draft,  4.4BSD-Lite,
92       the    IPv6   advanced   API   described   in   RFC 2292   and   SUSv2.
93       CMSG_FIRSTHDR(),  CMSG_NXTHDR(),  and  CMSG_DATA()  are  specified   in
94       POSIX.1-2008.  CMSG_SPACE() and CMSG_LEN() will be included in the next
95       POSIX release (Issue 8).
96
97       CMSG_ALIGN() is a Linux extension.
98

NOTES

100       For portability, ancillary data  should  be  accessed  using  only  the
101       macros  described  here.   CMSG_ALIGN() is a Linux extension and should
102       not be used in portable programs.
103
104       In Linux, CMSG_LEN(), CMSG_DATA(), and CMSG_ALIGN()  are  constant  ex‐
105       pressions  (assuming  their  argument  is constant), meaning that these
106       values can be used to declare the size of global variables.   This  may
107       not be portable, however.
108

EXAMPLES

110       This code looks for the IP_TTL option in a received ancillary buffer:
111
112           struct msghdr msgh;
113           struct cmsghdr *cmsg;
114           int received_ttl;
115
116           /* Receive auxiliary data in msgh */
117
118           for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL;
119                   cmsg = CMSG_NXTHDR(&msgh, cmsg)) {
120               if (cmsg->cmsg_level == IPPROTO_IP
121                       && cmsg->cmsg_type == IP_TTL) {
122                   memcpy(&receive_ttl, CMSG_DATA(cmsg), sizeof(received_ttl));
123                   break;
124               }
125           }
126
127           if (cmsg == NULL) {
128               /* Error: IP_TTL not enabled or small buffer or I/O error */
129           }
130
131       The  code  below passes an array of file descriptors over a UNIX domain
132       socket using SCM_RIGHTS:
133
134           struct msghdr msg = { 0 };
135           struct cmsghdr *cmsg;
136           int myfds[NUM_FD];  /* Contains the file descriptors to pass */
137           char iobuf[1];
138           struct iovec io = {
139               .iov_base = iobuf,
140               .iov_len = sizeof(iobuf)
141           };
142           union {         /* Ancillary data buffer, wrapped in a union
143                              in order to ensure it is suitably aligned */
144               char buf[CMSG_SPACE(sizeof(myfds))];
145               struct cmsghdr align;
146           } u;
147
148           msg.msg_iov = &io;
149           msg.msg_iovlen = 1;
150           msg.msg_control = u.buf;
151           msg.msg_controllen = sizeof(u.buf);
152           cmsg = CMSG_FIRSTHDR(&msg);
153           cmsg->cmsg_level = SOL_SOCKET;
154           cmsg->cmsg_type = SCM_RIGHTS;
155           cmsg->cmsg_len = CMSG_LEN(sizeof(myfds));
156           memcpy(CMSG_DATA(cmsg), myfds, sizeof(myfds));
157
158       For a complete code example that shows passing of file descriptors over
159       a UNIX domain socket, see seccomp_unotify(2).
160

SEE ALSO

162       recvmsg(2), sendmsg(2)
163
164       RFC 2292
165

COLOPHON

167       This  page  is  part of release 5.13 of the Linux man-pages project.  A
168       description of the project, information about reporting bugs,  and  the
169       latest     version     of     this    page,    can    be    found    at
170       https://www.kernel.org/doc/man-pages/.
171
172
173
174Linux                             2021-03-22                           CMSG(3)
Impressum