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 2008-11-20 "Linux" "Linux Programmer's Manual"
13 CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- access ancillary data
15 .B #include <sys/socket.h>
17 .BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh );
19 .BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh ", struct cmsghdr *" cmsg );
21 .BI "size_t CMSG_ALIGN(size_t " length );
23 .BI "size_t CMSG_SPACE(size_t " length );
25 .BI "size_t CMSG_LEN(size_t " length );
27 .BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg );
31 socklen_t cmsg_len; /* data byte count, including header */
32 int cmsg_level; /* originating protocol */
33 int cmsg_type; /* protocol-specific type */
34 /* followed by unsigned char cmsg_data[]; */
38 These macros are used to create and access control messages (also called
39 ancillary data) that are not a part of the socket payload.
40 This control information may
41 include the interface the packet was received on, various rarely used header
42 fields, an extended error description, a set of file descriptors or UNIX
44 For instance, control messages can be used to send
45 additional header fields such as IP options.
46 Ancillary data is sent by calling
48 and received by calling
50 See their manual pages for more information.
52 Ancillary data is a sequence of
54 structures with appended data.
55 This sequence should be accessed
56 using only the macros described in this manual page and never directly.
57 See the specific protocol man pages for the available control message types.
58 The maximum ancillary buffer size allowed per socket can be set using
59 .IR /proc/sys/net/core/optmem_max ;
64 returns a pointer to the first
67 data buffer associated with the passed
71 returns the next valid
75 It returns NULL when there isn't enough space left in the buffer.
78 given a length, returns it including the required alignment.
83 returns the number of bytes an ancillary element with payload of the
84 passed data length occupies.
85 This is a constant expression.
88 returns a pointer to the data portion of a
92 returns the value to store in the
96 structure, taking into account any necessary
98 It takes the data length as an argument.
102 To create ancillary data, first initialize the
106 with the length of the control message buffer.
111 to get the first control message and
113 to get all subsequent ones.
114 In each control message, initialize
120 header fields, and the data portion using
126 should be set to the sum of the
129 all control messages in the buffer.
130 For more information on the
135 When the control message buffer is too short to store all messages, the
142 This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite,
143 the IPv6 advanced API described in RFC\ 2292 and SUSv2.
145 is a Linux extension.
147 For portability, ancillary data should be accessed using only the macros
150 is a Linux extension and should not be used in portable programs.
157 are constant expressions (assuming their argument is constant);
158 this could be used to declare the size of global
160 This may not be portable, however.
162 This code looks for the
164 option in a received ancillary buffer:
169 struct cmsghdr *cmsg;
173 /* Receive auxiliary data in msgh */
174 for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL;
175 cmsg = CMSG_NXTHDR(&msgh,cmsg)) {
176 if (cmsg\->cmsg_level == IPPROTO_IP
177 && cmsg\->cmsg_type == IP_TTL) {
178 ttlptr = (int *) CMSG_DATA(cmsg);
179 received_ttl = *ttlptr;
185 * Error: IP_TTL not enabled or small buffer
192 The code below passes an array of file descriptors over a
193 UNIX domain socket using
198 struct msghdr msg = {0};
199 struct cmsghdr *cmsg;
200 int myfds[NUM_FD]; /* Contains the file descriptors to pass. */
201 char buf[CMSG_SPACE(sizeof myfds)]; /* ancillary data buffer */
204 msg.msg_control = buf;
205 msg.msg_controllen = sizeof buf;
206 cmsg = CMSG_FIRSTHDR(&msg);
207 cmsg\->cmsg_level = SOL_SOCKET;
208 cmsg\->cmsg_type = SCM_RIGHTS;
209 cmsg\->cmsg_len = CMSG_LEN(sizeof(int) * NUM_FD);
210 /* Initialize the payload: */
211 fdptr = (int *) CMSG_DATA(cmsg);
212 memcpy(fdptr, myfds, NUM_FD * sizeof(int));
213 /* Sum of the length of all control messages in the buffer: */
214 msg.msg_controllen = cmsg\->cmsg_len;