]>
Commit | Line | Data |
---|---|---|
fea681da MK |
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 $ | |
69962544 | 7 | .TH CMSG 3 1998-10-02 "Linux" "Linux Programmer's Manual" |
fea681da MK |
8 | .SH NAME |
9 | CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- Access ancillary data | |
10 | .SH SYNOPSIS | |
11 | .B #include <sys/socket.h> | |
cf0a9ace | 12 | .sp |
fea681da MK |
13 | .BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh ); |
14 | .br | |
15 | .BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh ", struct cmsghdr *" cmsg ); | |
16 | .br | |
17 | .BI "size_t CMSG_ALIGN(size_t " length ); | |
18 | .br | |
19 | .BI "size_t CMSG_SPACE(size_t " length ); | |
20 | .br | |
21 | .BI "size_t CMSG_LEN(size_t " length ); | |
22 | .br | |
c13182ef | 23 | .BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg ); |
fea681da MK |
24 | .sp |
25 | .nf | |
fea681da | 26 | struct cmsghdr { |
cf0a9ace MK |
27 | socklen_t cmsg_len; /* data byte count, including header */ |
28 | int cmsg_level; /* originating protocol */ | |
29 | int cmsg_type; /* protocol-specific type */ | |
30 | /* followed by unsigned char cmsg_data[]; */ | |
fea681da | 31 | }; |
fea681da MK |
32 | .fi |
33 | .SH DESCRIPTION | |
34 | These macros are used to create and access control messages (also called | |
35 | ancillary data) that are not a part of the socket payload. | |
c13182ef MK |
36 | This control information may |
37 | include the interface the packet was received on, various rarely used header | |
fea681da | 38 | fields, an extended error description, a set of file descriptors or Unix |
c13182ef MK |
39 | credentials. |
40 | For instance, control messages can be used to send | |
41 | additional header fields such as IP options. | |
42 | Ancillary data is sent by calling | |
fea681da MK |
43 | .BR sendmsg (2) |
44 | and received by calling | |
45 | .BR recvmsg (2). | |
c13182ef | 46 | See their manual pages for more information. |
fea681da | 47 | .PP |
c13182ef MK |
48 | Ancillary data is a sequence of |
49 | .I struct cmsghdr | |
50 | structures with appended data. | |
51 | This sequence should only be accessed | |
52 | using the macros described in this manual page and never directly. | |
53 | See the specific protocol man pages for the available control message types. | |
54 | The maximum ancillary buffer size allowed per socket can be set using the | |
f19a0f03 | 55 | .I net.core.optmem_max |
fea681da | 56 | sysctl; see |
c13182ef | 57 | .BR socket (7). |
fea681da | 58 | .PP |
e511ffb6 | 59 | .BR CMSG_FIRSTHDR () |
c13182ef | 60 | returns a pointer to the first |
f19a0f03 | 61 | .I cmsghdr |
fea681da | 62 | in the ancillary |
c13182ef | 63 | data buffer associated with the passed |
f19a0f03 | 64 | .IR msghdr . |
fea681da | 65 | .PP |
e511ffb6 | 66 | .BR CMSG_NXTHDR () |
c13182ef | 67 | returns the next valid |
f19a0f03 | 68 | .I cmsghdr |
c13182ef | 69 | after the passed |
f19a0f03 | 70 | .IR cmsghdr . |
8478ee02 | 71 | It returns NULL when there isn't enough space left in the buffer. |
fea681da | 72 | .PP |
e511ffb6 | 73 | .BR CMSG_ALIGN (), |
c13182ef MK |
74 | given a length, returns it including the required alignment. |
75 | This is a | |
fea681da MK |
76 | constant expression. |
77 | .PP | |
e511ffb6 | 78 | .BR CMSG_SPACE () |
c13182ef MK |
79 | returns the number of bytes an ancillary element with payload of the |
80 | passed data length occupies. | |
35478399 | 81 | This is a constant expression. |
fea681da | 82 | .PP |
e69ecf93 | 83 | .BR CMSG_DATA () |
c13182ef | 84 | returns a pointer to the data portion of a |
f19a0f03 | 85 | .IR cmsghdr . |
fea681da | 86 | .PP |
e69ecf93 | 87 | .BR CMSG_LEN () |
c13182ef | 88 | returns the value to store in the |
fea681da | 89 | .I cmsg_len |
c13182ef | 90 | member of the |
f19a0f03 | 91 | .I cmsghdr |
fea681da | 92 | structure, taking into account any necessary |
c13182ef MK |
93 | alignment. |
94 | It takes the data length as an argument. | |
95 | This is a constant | |
96 | expression. | |
fea681da | 97 | .PP |
c13182ef | 98 | To create ancillary data, first initialize the |
fea681da | 99 | .I msg_controllen |
c13182ef | 100 | member of the |
f19a0f03 | 101 | .I msghdr |
c13182ef MK |
102 | with the length of the control message buffer. |
103 | Use | |
e511ffb6 | 104 | .BR CMSG_FIRSTHDR () |
c13182ef | 105 | on the |
f19a0f03 | 106 | .I msghdr |
fea681da | 107 | to get the first control message and |
e69ecf93 | 108 | .BR CMSG_NEXTHDR () |
fea681da MK |
109 | to get all subsequent ones. |
110 | In each control message, initialize | |
111 | .I cmsg_len | |
c13182ef MK |
112 | (with |
113 | .BR CMSG_LEN ), | |
114 | the other | |
f19a0f03 | 115 | .I cmsghdr |
c13182ef | 116 | header fields, and the data portion using |
fea681da | 117 | .BR CMSG_DATA . |
c13182ef MK |
118 | Finally, the |
119 | .I msg_controllen | |
120 | field of the | |
f19a0f03 | 121 | .I msghdr |
c13182ef | 122 | should be set to the sum of the |
e511ffb6 | 123 | .BR CMSG_SPACE () |
c13182ef MK |
124 | of the length of |
125 | all control messages in the buffer. | |
126 | For more information on the | |
f19a0f03 | 127 | .IR msghdr , |
fea681da | 128 | see |
c13182ef | 129 | .BR recvmsg (2). |
fea681da MK |
130 | .PP |
131 | When the control message buffer is too short to store all messages, the | |
c13182ef MK |
132 | .B MSG_CTRUNC |
133 | flag is set in the | |
134 | .I msg_flags | |
135 | member of the | |
f19a0f03 | 136 | .IR msghdr . |
2b2581ee MK |
137 | .SH "CONFORMING TO" |
138 | This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite, | |
139 | the IPv6 advanced API described in RFC\ 2292 and the SUSv2. | |
e69ecf93 | 140 | .BR CMSG_ALIGN () |
2b2581ee MK |
141 | is a Linux extension. |
142 | .SH NOTES | |
143 | For portability, ancillary data should be accessed only using the macros | |
144 | described here. | |
145 | .BR CMSG_ALIGN () | |
146 | is a Linux extension and should be not used in portable programs. | |
147 | .PP | |
148 | In Linux, | |
e69ecf93 MK |
149 | .BR CMSG_LEN (), |
150 | .BR CMSG_DATA (), | |
2b2581ee MK |
151 | and |
152 | .BR CMSG_ALIGN () | |
153 | are constant expressions (assuming their argument is constant); | |
154 | this could be used to declare the size of global | |
155 | variables. | |
156 | This may be not portable, however. | |
fea681da | 157 | .SH EXAMPLE |
c13182ef MK |
158 | This code looks for the |
159 | .B IP_TTL | |
fea681da MK |
160 | option in a received ancillary buffer: |
161 | .PP | |
bd191423 | 162 | .in +4n |
fea681da | 163 | .nf |
c13182ef | 164 | struct msghdr msgh; |
fea681da MK |
165 | struct cmsghdr *cmsg; |
166 | int *ttlptr; | |
167 | int received_ttl; | |
168 | ||
c13182ef | 169 | /* Receive auxiliary data in msgh */ |
9584332d MK |
170 | for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL; |
171 | cmsg = CMSG_NXTHDR(&msgh,cmsg)) { | |
172 | if (cmsg\->cmsg_level == IPPROTO_IP | |
173 | && cmsg\->cmsg_type == IP_TTL) { | |
174 | ttlptr = (int *) CMSG_DATA(cmsg); | |
175 | received_ttl = *ttlptr; | |
176 | break; | |
41798314 | 177 | } |
9584332d | 178 | } |
fea681da | 179 | if (cmsg == NULL) { |
7295b7ed MK |
180 | /* |
181 | * Error: IP_TTL not enabled or small buffer | |
182 | * or I/O error. | |
c13182ef MK |
183 | */ |
184 | } | |
fea681da | 185 | .fi |
bd191423 | 186 | .in |
fea681da | 187 | .PP |
c13182ef | 188 | The code below passes an array of file descriptors over a Unix socket using |
fea681da MK |
189 | .BR SCM_RIGHTS : |
190 | .PP | |
bd191423 | 191 | .in +4n |
fea681da | 192 | .nf |
fea681da MK |
193 | struct msghdr msg = {0}; |
194 | struct cmsghdr *cmsg; | |
c13182ef | 195 | int myfds[NUM_FD]; /* Contains the file descriptors to pass. */ |
fea681da MK |
196 | char buf[CMSG_SPACE(sizeof myfds)]; /* ancillary data buffer */ |
197 | int *fdptr; | |
198 | ||
c13182ef | 199 | msg.msg_control = buf; |
fea681da | 200 | msg.msg_controllen = sizeof buf; |
c13182ef | 201 | cmsg = CMSG_FIRSTHDR(&msg); |
29059a65 MK |
202 | cmsg\->cmsg_level = SOL_SOCKET; |
203 | cmsg\->cmsg_type = SCM_RIGHTS; | |
204 | cmsg\->cmsg_len = CMSG_LEN(sizeof(int) * NUM_FD); | |
c13182ef | 205 | /* Initialize the payload: */ |
0c535394 | 206 | fdptr = (int *) CMSG_DATA(cmsg); |
c13182ef MK |
207 | memcpy(fdptr, myfds, NUM_FD * sizeof(int)); |
208 | /* Sum of the length of all control messages in the buffer: */ | |
29059a65 | 209 | msg.msg_controllen = cmsg\->cmsg_len; |
fea681da | 210 | .fi |
bd191423 | 211 | .in |
fea681da MK |
212 | .SH "SEE ALSO" |
213 | .BR recvmsg (2), | |
214 | .BR sendmsg (2) | |
215 | .PP | |
331da7c3 | 216 | RFC\ 2292 |