1CMSG(3) Library Functions Manual CMSG(3)
2
6 CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR - access ancillary
7 data
8
10 Standard C library (libc, -lc)
11
13 #include <sys/socket.h>
14 struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *msgh);
16 struct cmsghdr *CMSG_NXTHDR(struct msghdr *msgh,
17 struct cmsghdr *cmsg);
18 size_t CMSG_ALIGN(size_t length);
19 size_t CMSG_SPACE(size_t length);
20 size_t CMSG_LEN(size_t length);
21 unsigned char *CMSG_DATA(struct cmsghdr *cmsg);
22
24 These macros are used to create and access control messages (also
25 called ancillary data) that are not a part of the socket payload. This
26 control information may include the interface the packet was received
27 on, various rarely used header fields, an extended error description, a
28 set of file descriptors, or UNIX credentials. For instance, control
29 messages can be used to send additional header fields such as IP op‐
30 tions. Ancillary data is sent by calling sendmsg(2) and received by
31 calling recvmsg(2). See their manual pages for more information.
32 Ancillary data is a sequence of cmsghdr structures with appended data.
34 See the specific protocol man pages for the available control message
35 types. The maximum ancillary buffer size allowed per socket can be set
36 using /proc/sys/net/core/optmem_max; see socket(7).
37 The cmsghdr structure is defined as follows:
39 struct cmsghdr {
41 size_t cmsg_len; /* Data byte count, including header
42 (type is socklen_t in POSIX) */
43 int cmsg_level; /* Originating protocol */
44 int cmsg_type; /* Protocol-specific type */
45 /* followed by
46 unsigned char cmsg_data[]; */
47 };
48 The sequence of cmsghdr structures should never be accessed directly.
50 Instead, use only the following macros:
51 CMSG_FIRSTHDR()
53 returns a pointer to the first cmsghdr in the ancillary data
54 buffer associated with the passed msghdr. It returns NULL if
55 there isn't enough space for a cmsghdr in the buffer.
56 CMSG_NXTHDR()
58 returns the next valid cmsghdr after the passed cmsghdr. It re‐
59 turns NULL when there isn't enough space left in the buffer.
60 When initializing a buffer that will contain a series of cmsghdr
62 structures (e.g., to be sent with sendmsg(2)), that buffer
63 should first be zero-initialized to ensure the correct operation
64 of CMSG_NXTHDR().
65 CMSG_ALIGN(),
67 given a length, returns it including the required alignment.
68 This is a constant expression.
69 CMSG_SPACE()
71 returns the number of bytes an ancillary element with payload of
72 the passed data length occupies. This is a constant expression.
73 CMSG_DATA()
75 returns a pointer to the data portion of a cmsghdr. The pointer
76 returned cannot be assumed to be suitably aligned for accessing
77 arbitrary payload data types. Applications should not cast it
78 to a pointer type matching the payload, but should instead use
79 memcpy(3) to copy data to or from a suitably declared object.
80 CMSG_LEN()
82 returns the value to store in the cmsg_len member of the cmsghdr
83 structure, taking into account any necessary alignment. It
84 takes the data length as an argument. This is a constant ex‐
85 pression.
86 To create ancillary data, first initialize the msg_controllen member of
88 the msghdr with the length of the control message buffer. Use
89 CMSG_FIRSTHDR() on the msghdr to get the first control message and
90 CMSG_NXTHDR() to get all subsequent ones. In each control message,
91 initialize cmsg_len (with CMSG_LEN()), the other cmsghdr header fields,
92 and the data portion using CMSG_DATA(). Finally, the msg_controllen
93 field of the msghdr should be set to the sum of the CMSG_SPACE() of the
94 length of all control messages in the buffer. For more information on
95 the msghdr, see recvmsg(2).
96
98 For portability, ancillary data should be accessed using only the
99 macros described here.
100 In Linux, CMSG_LEN(), CMSG_DATA(), and CMSG_ALIGN() are constant ex‐
102 pressions (assuming their argument is constant), meaning that these
103 values can be used to declare the size of global variables. This may
104 not be portable, however.
105
107 CMSG_FIRSTHDR()
108 CMSG_NXTHDR()
109 CMSG_DATA()
110 POSIX.1-2008.
111 CMSG_SPACE()
113 CMSG_LEN()
114 CMSG_ALIGN()
115 Linux.
116
118 This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite,
119 the IPv6 advanced API described in RFC 2292 and SUSv2.
120 CMSG_SPACE() and CMSG_LEN() will be included in the next POSIX release
122 (Issue 8).
123
125 This code looks for the IP_TTL option in a received ancillary buffer:
126 struct msghdr msgh;
128 struct cmsghdr *cmsg;
129 int received_ttl;
130 /* Receive auxiliary data in msgh */
132 for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL;
134 cmsg = CMSG_NXTHDR(&msgh, cmsg)) {
135 if (cmsg->cmsg_level == IPPROTO_IP
136 && cmsg->cmsg_type == IP_TTL) {
137 memcpy(&receive_ttl, CMSG_DATA(cmsg), sizeof(received_ttl));
138 break;
139 }
140 }
141 if (cmsg == NULL) {
143 /* Error: IP_TTL not enabled or small buffer or I/O error */
144 }
145 The code below passes an array of file descriptors over a UNIX domain
147 socket using SCM_RIGHTS:
148 struct msghdr msg = { 0 };
150 struct cmsghdr *cmsg;
151 int myfds[NUM_FD]; /* Contains the file descriptors to pass */
152 char iobuf[1];
153 struct iovec io = {
154 .iov_base = iobuf,
155 .iov_len = sizeof(iobuf)
156 };
157 union { /* Ancillary data buffer, wrapped in a union
158 in order to ensure it is suitably aligned */
159 char buf[CMSG_SPACE(sizeof(myfds))];
160 struct cmsghdr align;
161 } u;
162 msg.msg_iov = &io;
164 msg.msg_iovlen = 1;
165 msg.msg_control = u.buf;
166 msg.msg_controllen = sizeof(u.buf);
167 cmsg = CMSG_FIRSTHDR(&msg);
168 cmsg->cmsg_level = SOL_SOCKET;
169 cmsg->cmsg_type = SCM_RIGHTS;
170 cmsg->cmsg_len = CMSG_LEN(sizeof(myfds));
171 memcpy(CMSG_DATA(cmsg), myfds, sizeof(myfds));
172 For a complete code example that shows passing of file descriptors over
174 a UNIX domain socket, see seccomp_unotify(2).
175
177 recvmsg(2), sendmsg(2)
178 RFC 2292
180Linux man-pages 6.05 2023-07-15 CMSG(3)