Debian Codegraph @

upstream/debian-unstable/man3/cmsg.3

raw
1 .\" Copyright 1999, Andi Kleen <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-1-para
5 .\"
6 .TH CMSG 3 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- access ancillary data
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <sys/socket.h>
15 .P
16 .BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh );
17 .BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh ,
18 .BR " struct cmsghdr *" cmsg );
19 .BI "size_t CMSG_ALIGN(size_t " length );
20 .BI "size_t CMSG_SPACE(size_t " length );
21 .BI "size_t CMSG_LEN(size_t " length );
22 .BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg );
23 .fi
24 .SH DESCRIPTION
25 These macros are used to create and access control messages (also called
26 ancillary data) that are not a part of the socket payload.
27 This control information may
28 include the interface the packet was received on, various rarely used header
29 fields, an extended error description, a set of file descriptors, or UNIX
30 credentials.
31 For instance, control messages can be used to send
32 additional header fields such as IP options.
33 Ancillary data is sent by calling
34 .BR sendmsg (2)
35 and received by calling
36 .BR recvmsg (2).
37 See their manual pages for more information.
38 .P
39 Ancillary data is a sequence of
40 .I cmsghdr
41 structures with appended data.
42 See the specific protocol man pages for the available control message types.
43 The maximum ancillary buffer size allowed per socket can be set using
44 .IR /proc/sys/net/core/optmem_max ;
45 see
46 .BR socket (7).
47 .P
48 The
49 .I cmsghdr
50 structure is defined as follows:
51 .P
52 .in +4n
53 .EX
54 struct cmsghdr {
55 size_t cmsg_len; /* Data byte count, including header
56 (type is socklen_t in POSIX) */
57 int cmsg_level; /* Originating protocol */
58 int cmsg_type; /* Protocol\-specific type */
59 /* followed by
60 unsigned char cmsg_data[]; */
61 };
62 .EE
63 .in
64 .P
65 The sequence of
66 .I cmsghdr
67 structures should never be accessed directly.
68 Instead, use only the following macros:
69 .TP
70 .BR CMSG_FIRSTHDR ()
71 returns a pointer to the first
72 .I cmsghdr
73 in the ancillary
74 data buffer associated with the passed
75 .IR msghdr .
76 It returns NULL if there isn't enough space for a
77 .I cmsghdr
78 in the buffer.
79 .TP
80 .BR CMSG_NXTHDR ()
81 returns the next valid
82 .I cmsghdr
83 after the passed
84 .IR cmsghdr .
85 It returns NULL when there isn't enough space left in the buffer.
86 .IP
87 When initializing a buffer that will contain a series of
88 .I cmsghdr
89 structures (e.g., to be sent with
90 .BR sendmsg (2)),
91 that buffer should first be zero-initialized
92 to ensure the correct operation of
93 .BR CMSG_NXTHDR ().
94 .TP
95 .BR CMSG_ALIGN (),
96 given a length, returns it including the required alignment.
97 This is a
98 constant expression.
99 .TP
100 .BR CMSG_SPACE ()
101 returns the number of bytes an ancillary element with payload of the
102 passed data length occupies.
103 This is a constant expression.
104 .TP
105 .BR CMSG_DATA ()
106 returns a pointer to the data portion of a
107 .IR cmsghdr .
108 The pointer returned cannot be assumed to be suitably aligned for
109 accessing arbitrary payload data types.
110 Applications should not cast it to a pointer type matching the payload,
111 but should instead use
112 .BR memcpy (3)
113 to copy data to or from a suitably declared object.
114 .TP
115 .BR CMSG_LEN ()
116 returns the value to store in the
117 .I cmsg_len
118 member of the
119 .I cmsghdr
120 structure, taking into account any necessary
121 alignment.
122 It takes the data length as an argument.
123 This is a constant
124 expression.
125 .P
126 To create ancillary data, first initialize the
127 .I msg_controllen
128 member of the
129 .I msghdr
130 with the length of the control message buffer.
131 Use
132 .BR CMSG_FIRSTHDR ()
133 on the
134 .I msghdr
135 to get the first control message and
136 .BR CMSG_NXTHDR ()
137 to get all subsequent ones.
138 In each control message, initialize
139 .I cmsg_len
140 (with
141 .BR CMSG_LEN ()),
142 the other
143 .I cmsghdr
144 header fields, and the data portion using
145 .BR CMSG_DATA ().
146 Finally, the
147 .I msg_controllen
148 field of the
149 .I msghdr
150 should be set to the sum of the
151 .BR CMSG_SPACE ()
152 of the length of
153 all control messages in the buffer.
154 For more information on the
155 .IR msghdr ,
156 see
157 .BR recvmsg (2).
158 .SH VERSIONS
159 For portability, ancillary data should be accessed using only the macros
160 described here.
161 .P
162 In Linux,
163 .BR CMSG_LEN (),
164 .BR CMSG_DATA (),
165 and
166 .BR CMSG_ALIGN ()
167 are constant expressions (assuming their argument is constant),
168 meaning that these values can be used to declare the size of global variables.
169 This may not be portable, however.
170 .SH STANDARDS
171 .TP
172 .BR CMSG_FIRSTHDR ()
173 .TQ
174 .BR CMSG_NXTHDR ()
175 .TQ
176 .BR CMSG_DATA ()
177 POSIX.1-2008.
178 .TP
179 .BR CMSG_SPACE ()
180 .TQ
181 .BR CMSG_LEN ()
182 .TQ
183 .BR CMSG_ALIGN ()
184 Linux.
185 .SH HISTORY
186 This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite,
187 the IPv6 advanced API described in RFC\ 2292 and SUSv2.
188 .P
189 .BR CMSG_SPACE ()
190 and
191 .BR CMSG_LEN ()
192 .\" https://www.austingroupbugs.net/view.php?id=978#c3242
193 will be included in the next POSIX release (Issue 8).
194 .SH EXAMPLES
195 This code looks for the
196 .B IP_TTL
197 option in a received ancillary buffer:
198 .P
199 .in +4n
200 .EX
201 struct msghdr msgh;
202 struct cmsghdr *cmsg;
203 int received_ttl;
204 \&
205 /* Receive auxiliary data in msgh */
206 \&
207 for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL;
208 cmsg = CMSG_NXTHDR(&msgh, cmsg)) {
209 if (cmsg\->cmsg_level == IPPROTO_IP
210 && cmsg\->cmsg_type == IP_TTL) {
211 memcpy(&receive_ttl, CMSG_DATA(cmsg), sizeof(received_ttl));
212 break;
213 }
214 }
215 \&
216 if (cmsg == NULL) {
217 /* Error: IP_TTL not enabled or small buffer or I/O error */
218 }
219 .EE
220 .in
221 .P
222 The code below passes an array of file descriptors over a
223 UNIX domain socket using
224 .BR SCM_RIGHTS :
225 .P
226 .in +4n
227 .EX
228 struct msghdr msg = { 0 };
229 struct cmsghdr *cmsg;
230 int myfds[NUM_FD]; /* Contains the file descriptors to pass */
231 char iobuf[1];
232 struct iovec io = {
233 .iov_base = iobuf,
234 .iov_len = sizeof(iobuf)
235 };
236 union { /* Ancillary data buffer, wrapped in a union
237 in order to ensure it is suitably aligned */
238 char buf[CMSG_SPACE(sizeof(myfds))];
239 struct cmsghdr align;
240 } u;
241 \&
242 msg.msg_iov = &io;
243 msg.msg_iovlen = 1;
244 msg.msg_control = u.buf;
245 msg.msg_controllen = sizeof(u.buf);
246 cmsg = CMSG_FIRSTHDR(&msg);
247 cmsg\->cmsg_level = SOL_SOCKET;
248 cmsg\->cmsg_type = SCM_RIGHTS;
249 cmsg\->cmsg_len = CMSG_LEN(sizeof(myfds));
250 memcpy(CMSG_DATA(cmsg), myfds, sizeof(myfds));
251 .EE
252 .in
253 .P
254 For a complete code example that shows passing of file descriptors
255 over a UNIX domain socket, see
256 .BR seccomp_unotify (2).
257 .SH SEE ALSO
258 .BR recvmsg (2),
259 .BR sendmsg (2)
260 .P
261 RFC\ 2292