1 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
2 .\" Permission is granted to distribute possibly modified copies
3 .\" of this page provided the header is included verbatim,
4 .\" and in case of nontrivial modification author and date
5 .\" of the modification is added to the header.
6 .\" $Id: cmsg.3,v 1.8 2000/12/20 18:10:31 ak Exp $
7 .TH CMSG 3 1998-10-02 "Linux Man Page" "Linux Programmer's Manual"
9 CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- Access ancillary data
11 .B #include <sys/socket.h>
14 .BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh );
16 .BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh ", struct cmsghdr *" cmsg );
18 .BI "size_t CMSG_ALIGN(size_t " length );
20 .BI "size_t CMSG_SPACE(size_t " length );
22 .BI "size_t CMSG_LEN(size_t " length );
24 .BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg );
29 socklen_t cmsg_len; /* data byte count, including header */
30 int cmsg_level; /* originating protocol */
31 int cmsg_type; /* protocol-specific type */
32 /* followed by unsigned char cmsg_data[]; */
37 These macros are used to create and access control messages (also called
38 ancillary data) that are not a part of the socket payload.
39 This control information may
40 include the interface the packet was received on, various rarely used header
41 fields, an extended error description, a set of file descriptors or Unix
42 credentials. For instance, control messages can be used to send
43 additional header fields such as IP options.
44 Ancillary data is sent by calling
46 and received by calling
48 See their manual pages for more information.
50 Ancillary data is a sequence of
52 structures with appended data. This sequence should only be accessed
53 using the macros described in this manual page and never directly.
54 See the specific protocol man pages for the available control message types.
55 The maximum ancillary buffer size allowed per socket can be set using the
56 .B net.core.optmem_max
61 returns a pointer to the first
64 data buffer associated with the passed
68 returns the next valid
74 when there isn't enough space left in the buffer.
77 given a length, returns it including the required alignment. This is a
81 returns the number of bytes an ancillary element with payload of the passed data length
82 occupies. This is a constant expression.
85 returns a pointer to the data portion of a
89 returns the value to store in the
93 structure, taking into account any necessary
94 alignment. It takes the data length as an argument. This is a constant
97 To create ancillary data, first initialize the
101 with the length of the control message buffer. Use
105 to get the first control message and
107 to get all subsequent ones.
108 In each control message, initialize
114 header fields, and the data portion using
120 should be set to the sum of the
123 all control messages in the buffer.
124 For more information on the
129 When the control message buffer is too short to store all messages, the
136 This code looks for the
138 option in a received ancillary buffer:
144 struct cmsghdr *cmsg;
148 /* Receive auxiliary data in msgh */
149 for (cmsg = CMSG_FIRSTHDR(&msgh);
151 cmsg = CMSG_NXTHDR(&msgh,cmsg)) {
152 if (cmsg->cmsg_level == SOL_IP
153 && cmsg->cmsg_type == IP_TTL) {
154 ttlptr = (int *) CMSG_DATA(cmsg);
155 received_ttl = *ttlptr;
161 * Error: IP_TTL not enabled or small buffer
169 The code below passes an array of file descriptors over a Unix socket using
175 struct msghdr msg = {0};
176 struct cmsghdr *cmsg;
177 int myfds[NUM_FD]; /* Contains the file descriptors to pass. */
178 char buf[CMSG_SPACE(sizeof myfds)]; /* ancillary data buffer */
181 msg.msg_control = buf;
182 msg.msg_controllen = sizeof buf;
183 cmsg = CMSG_FIRSTHDR(&msg);
184 cmsg->cmsg_level = SOL_SOCKET;
185 cmsg->cmsg_type = SCM_RIGHTS;
186 cmsg->cmsg_len = CMSG_LEN(sizeof(int) * NUM_FD);
187 /* Initialize the payload: */
188 fdptr = (int *)CMSG_DATA(cmsg);
189 memcpy(fdptr, myfds, NUM_FD * sizeof(int));
190 /* Sum of the length of all control messages in the buffer: */
191 msg.msg_controllen = cmsg->cmsg_len;
196 For portability, ancillary data should be accessed only using the macros
199 is a Linux extension and should be not used in portable programs.
206 are constant expressions (assuming their argument is constant);
207 this could be used to declare the size of global
208 variables. This may be not portable, however.
210 This ancillary data model conforms to the POSIX.1003.1g draft, 4.4BSD-Lite,
211 the IPv6 advanced API described in RFC2292 and the Single Unix specification v2.
214 is a Linux extension.