1 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
3 .\" %%%LICENSE_START(VERBATIM_ONE_PARA)
4 .\" Permission is granted to distribute possibly modified copies
5 .\" of this page provided the header is included verbatim,
6 .\" and in case of nontrivial modification author and date
7 .\" of the modification is added to the header.
10 .\" $Id: cmsg.3,v 1.8 2000/12/20 18:10:31 ak Exp $
11 .TH CMSG 3 2017-09-15 "Linux" "Linux Programmer's Manual"
13 CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- access ancillary data
16 .B #include <sys/socket.h>
17 .BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh );
18 .BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh " ,
19 .BR " struct cmsghdr *" cmsg );
20 .BI "size_t CMSG_ALIGN(size_t " length );
21 .BI "size_t CMSG_SPACE(size_t " length );
22 .BI "size_t CMSG_LEN(size_t " length );
23 .BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg );
26 These macros are used to create and access control messages (also called
27 ancillary data) that are not a part of the socket payload.
28 This control information may
29 include the interface the packet was received on, various rarely used header
30 fields, an extended error description, a set of file descriptors, or UNIX
32 For instance, control messages can be used to send
33 additional header fields such as IP options.
34 Ancillary data is sent by calling
36 and received by calling
38 See their manual pages for more information.
40 Ancillary data is a sequence of
42 structures with appended data.
43 See the specific protocol man pages for the available control message types.
44 The maximum ancillary buffer size allowed per socket can be set using
45 .IR /proc/sys/net/core/optmem_max ;
51 structure is defined as follows:
56 size_t cmsg_len; /* Data byte count, including header
57 (type is socklen_t in POSIX) */
58 int cmsg_level; /* Originating protocol */
59 int cmsg_type; /* Protocol-specific type */
61 unsigned char cmsg_data[]; */
68 structures should never be accessed directly.
69 Instead, use only the following macros:
72 returns a pointer to the first
75 data buffer associated with the passed
77 It returns NULL if there isn't enough space for a
82 returns the next valid
86 It returns NULL when there isn't enough space left in the buffer.
88 When initializing a buffer that will contain a series of
90 structures (e.g., to be sent with
92 that buffer should first be zero-initialized
93 to ensure the correct operation of
97 given a length, returns it including the required alignment.
102 returns the number of bytes an ancillary element with payload of the
103 passed data length occupies.
104 This is a constant expression.
107 returns a pointer to the data portion of a
111 returns the value to store in the
115 structure, taking into account any necessary
117 It takes the data length as an argument.
121 To create ancillary data, first initialize the
125 with the length of the control message buffer.
130 to get the first control message and
132 to get all subsequent ones.
133 In each control message, initialize
139 header fields, and the data portion using
145 should be set to the sum of the
148 all control messages in the buffer.
149 For more information on the
154 This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite,
155 the IPv6 advanced API described in RFC\ 2292 and SUSv2.
157 is a Linux extension.
159 For portability, ancillary data should be accessed using only the macros
162 is a Linux extension and should not be used in portable programs.
169 are constant expressions (assuming their argument is constant),
170 meaning that these values can be used to declare the size of global variables.
171 This may not be portable, however.
173 This code looks for the
175 option in a received ancillary buffer:
180 struct cmsghdr *cmsg;
184 /* Receive auxiliary data in msgh */
186 for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL;
187 cmsg = CMSG_NXTHDR(&msgh, cmsg)) {
188 if (cmsg\->cmsg_level == IPPROTO_IP
189 && cmsg\->cmsg_type == IP_TTL) {
190 ttlptr = (int *) CMSG_DATA(cmsg);
191 received_ttl = *ttlptr;
197 /* Error: IP_TTL not enabled or small buffer or I/O error */
202 The code below passes an array of file descriptors over a
203 UNIX domain socket using
208 struct msghdr msg = { 0 };
209 struct cmsghdr *cmsg;
210 int myfds[NUM_FD]; /* Contains the file descriptors to pass */
214 .iov_len = sizeof(iobuf)
216 union { /* Ancillary data buffer, wrapped in a union
217 in order to ensure it is suitably aligned */
218 char buf[CMSG_SPACE(sizeof(myfds))];
219 struct cmsghdr align;
224 msg.msg_control = u.buf;
225 msg.msg_controllen = sizeof(u.buf);
226 cmsg = CMSG_FIRSTHDR(&msg);
227 cmsg\->cmsg_level = SOL_SOCKET;
228 cmsg\->cmsg_type = SCM_RIGHTS;
229 cmsg\->cmsg_len = CMSG_LEN(sizeof(int) * NUM_FD);
230 memcpy(CMSG_DATA(cmsg), myfds, NUM_FD * sizeof(int));