Penguin
Recent Changes
Annotated edit history of cmsg(3) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 CMSG
2 !!!CMSG
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 EXAMPLE
7 NOTES
8 CONFORMS TO
9 SEE ALSO
10 ----
11 !!NAME
12
13
14 CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR - Access ancillary data.
15 !!SYNOPSIS
16
17
18 __#include __
19
20
21 __struct cmsghdr *CMSG_FIRSTHDR(struct msghdr
22 *__''msgh''__);
23 struct cmsghdr *CMSG_NXTHDR(struct msghdr
24 *__''msgh''__, struct cmsghdr
25 *__''cmsg''__);
26 size_t CMSG_ALIGN(size_t__ ''length''__);
27 size_t CMSG_SPACE(size_t__ ''length''__);
28 size_t CMSG_LEN(size_t__ ''length''__);
29 unsigned char *CMSG_DATA(struct cmsghdr
30 *__''cmsg''__);__
31
32
33 struct cmsghdr {
34 socklen_t cmsg_len; /* data byte count, including header */
35 int cmsg_level; /* originating protocol */
36 int cmsg_type; /* protocol-specific type */
37 /* followed by unsigned char cmsg_data[[]; */
38 };
39 !!DESCRIPTION
40
41
42 These macros are used to create and access control messages
43 (also called ancillary data) that are not a part of the
44 socket payload. This control information may include the
45 interface the packet was received on, various rarely used
46 header fields, an extended error description, a set of file
47 descriptors or unix credentials. For instance, control
48 messages can be used to send additional header fields such
49 as IP options. Ancillary data is sent by calling
50 sendmsg(2) and received by calling recvmsg(2).
51 See their manual pages for more information.
52
53
54 Ancillary data is a sequence of __struct cmsghdr__
55 structures with appended data. This sequence should only be
56 accessed using the macros described in this manual page and
57 never directly. See the specific protocol man pages for the
58 available control message types. The maximum ancillary
59 buffer size allowed per socket can be set using the
60 __net.core.optmem_max__ sysctl; see
61 socket(7).
62
63
64 __CMSG_FIRSTHDR__ returns a pointer to the first
65 __cmsghdr__ in the ancillary data buffer associated with
66 the passed __msghdr__.
67
68
69 __CMSG_NXTHDR__ returns the next valid __cmsghdr__
70 after the passed __cmsghdr.__ It returns __NULL__ when
71 there isn't enough space left in the buffer.
72
73
74 __CMSG_ALIGN__, given a length, returns it including the
75 required alignment. This is a constant
76 expression.
77
78
79 __CMSG_SPACE__ returns the number of bytes an ancillary
80 element with payload of the passed data length occupies.
81 This is a constant expression.
82
83
84 __CMSG_DATA__ returns a pointer to the data portion of a
85 __cmsghdr__.
86
87
88 __CMSG_LEN__ returns the value to store in the
89 ''cmsg_len'' member of the __cmsghdr__ structure,
90 taking into account any necessary alignment. It takes the
91 data length as an argument. This is a constant
92 expression.
93
94
95 To create ancillary data, first initialize the
96 ''msg_controllen'' member of the __msghdr__ with the
97 length of the control message buffer. Use
98 __CMSG_FIRSTHDR__ on the __msghdr__ to get the first
99 control message and __CMSG_NEXTHDR__ to get all
100 subsequent ones. In each control message, initialize
101 ''cmsg_len'' (with __CMSG_LEN__), the other
102 __cmsghdr__ header fields, and the data portion using
103 __CMSG_DATA__. Finally, the ''msg_controllen'' field
104 of the __msghdr__ should be set to the sum of the
105 __CMSG_SPACE__ of the length of all control messages in
106 the buffer. For more information on the __msghdr__, see
107 recvmsg(2).
108
109
110 When the control message buffer is too short to store all
111 messages, the __MSG_CTRUNC__ flag is set in the
112 ''msg_flags'' member of the __msghdr__.
113 !!EXAMPLE
114
115
116 This code looks for the __IP_TTL__ option in a received
117 ancillary buffer:
118
119
120 struct msghdr msgh;
121 struct cmsghdr *cmsg;
122 int *ttlptr;
123 int received_ttl;
124 /* Receive auxiliary data in msgh */
125 for (cmsg = CMSG_FIRSTHDR(
126
127
128 The code below passes an array of file descriptors over a
129 Unix socket using __SCM_RIGHTS__:
130
131
132 struct msghdr msg = {0};
133 struct cmsghdr *cmsg;
134 int myfds[[NUM_FD]; /* Contains the file descriptors to pass. */
135 char buf[[CMSG_SPACE(sizeof myfds)]; /* ancillary data buffer */
136 int *fdptr;
137 msg.msg_control = buf;
138 msg.msg_controllen = sizeof buf;
139 cmsg = CMSG_FIRSTHDR(
140 !!NOTES
141
142
143 For portability, ancillary data should be accessed only
144 using the macros described here. __CMSG_ALIGN__ is a
145 Linux extension and should be not used in portable
146 programs.
147
148
149 In Linux, __CMSG_LEN__, __CMSG_DATA__, and
150 __CMSG_ALIGN__ are constant expressions (assuming their
151 argument is constant) - this could be used to declare the
152 size of global variables. This may be not portable,
153 however.
154 !!CONFORMS TO
155
156
157 This ancillary data model conforms to the POSIX.1003.1g
158 draft, 4.4BSD-Lite, the IPv6 advanced API described in
159 RFC2292 and the Single Unix specification v2.
160 __CMSG_ALIGN__ is a Linux extension.
161 !!SEE ALSO
162
163
164 sendmsg(2), recvmsg(2)
165
166
167 RFC 2292
168 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.