libnl: /data/src/libnl3/lib/genl/genl.c Source File

libnl 3.7.0

genl.c
1 /* SPDX-License-Identifier: LGPL-2.1-only */
2 /*
3 * Copyright (c) 2003-2012 Thomas Graf <tgraf@suug.ch>
4 */
5
6 /**
7 * @defgroup genl Generic Netlink Library (libnl-genl)
8 *
9 * @{
10 */
11
12 #include <netlink-private/genl.h>
13 #include <netlink/netlink.h>
14 #include <netlink/genl/genl.h>
15 #include <netlink/utils.h>
16
17 /**
18 * @name Generic Netlink Socket
19 * @{
20 */
21
22 /**
23 * Connect a Generic Netlink socket
24 * @arg sk Unconnected Netlink socket
25 *
26 * This function expects a struct nl_socket object previously allocated via
27 * nl_socket_alloc(). It calls nl_connect() to create the local socket file
28 * descriptor and binds the socket to the \c NETLINK_GENERIC Netlink protocol.
29 *
30 * Using this function is equivalent to:
31 * @code
32 * nl_connect(sk, NETLINK_GENERIC);
33 * @endcode
34 *
35 * @see nl_connect()
36 *
37 * @return 0 on success or a negative error code.
38 */
39 int genl_connect(struct nl_sock *sk)
40 {
41 return nl_connect(sk, NETLINK_GENERIC);
42 }
43
44 /** @} */
45
46 /**
47 * @name Sending Data
48 * @{
49 */
50
51 /**
52 * Send a Generic Netlink message consisting only of a header
53 * @arg sk Generic Netlink socket
54 * @arg family Numeric family identifier
55 * @arg cmd Numeric command identifier
56 * @arg version Interface version
57 * @arg flags Additional Netlink message flags (optional)
58 *
59 * This function is a shortcut for sending a Generic Netlink message without
60 * any message payload. The message will only consist of the Netlink and
61 * Generic Netlink headers. The header is constructed based on the specified
62 * parameters and passed on to nl_send_simple() to send it on the specified
63 * socket.
64 *
65 * @par Example:
66 * @code
67 * #include <netlink/genl/genl.h>
68 * #include <linux/genetlink.h>
69 *
70 * err = genl_send_simple(sk, GENL_ID_CTRL, CTRL_CMD_GETFAMILY, CTRL_VERSION,
71 * NLM_F_DUMP);
72 * @endcode
73 *
74 * @see nl_send_simple()
75 *
76 * @return 0 on success or a negative error code. Due to a bug, this function
77 * returns the number of bytes sent. Treat any non-negative number as success.
78 */
79 int genl_send_simple(struct nl_sock *sk, int family, int cmd,
80 int version, int flags)
81 {
82 struct genlmsghdr hdr = {
83 .cmd = cmd,
84 .version = version,
85 };
86
87 return nl_send_simple(sk, family, flags, &hdr, sizeof(hdr));
88 }
89
90 /** @} */
91
92 /**
93 * @name Message Parsing
94 * @{
95 */
96
97 /**
98 * Validate Generic Netlink message headers
99 * @arg nlh Pointer to Netlink message header
100 * @arg hdrlen Length of user header
101 *
102 * Verifies the integrity of the Netlink and Generic Netlink headers by
103 * enforcing the following requirements:
104 * - Valid Netlink message header (nlmsg_valid_hdr())
105 * - Presence of a complete Generic Netlink header
106 * - At least \c hdrlen bytes of payload included after the generic
107 * netlink header.
108 *
109 * @return A positive integer (true) if the headers are valid or
110 * 0 (false) if not.
111 */
112 int genlmsg_valid_hdr(struct nlmsghdr *nlh, int hdrlen)
113 {
114 struct genlmsghdr *ghdr;
115
116 if (!nlmsg_valid_hdr(nlh, GENL_HDRLEN))
117 return 0;
118
119 ghdr = nlmsg_data(nlh);
120 if (genlmsg_len(ghdr) < NLMSG_ALIGN(hdrlen))
121 return 0;
122
123 return 1;
124 }
125
126 /**
127 * Validate Generic Netlink message including attributes
128 * @arg nlh Pointer to Netlink message header
129 * @arg hdrlen Length of user header
130 * @arg maxtype Maximum attribtue id expected
131 * @arg policy Attribute validation policy
132 *
133 * Verifies the validity of the Netlink and Generic Netlink headers using
134 * genlmsg_valid_hdr() and calls nla_validate() on the message payload to
135 * verify the integrity of eventual attributes.
136 *
137 * @note You may call genlmsg_parse() directly to perform validation and
138 * parsing in a single step.
139 *
140 * @see genlmsg_valid_hdr()
141 * @see nla_validate()
142 * @see genlmsg_parse()
143 *
144 * @return 0 on success or a negative error code.
145 */
146 int genlmsg_validate(struct nlmsghdr *nlh, int hdrlen, int maxtype,
147 const struct nla_policy *policy)
148 {
149 struct genlmsghdr *ghdr;
150
151 if (!genlmsg_valid_hdr(nlh, hdrlen))
152 return -NLE_MSG_TOOSHORT;
153
154 ghdr = nlmsg_data(nlh);
155 return nla_validate(genlmsg_attrdata(ghdr, hdrlen),
156 genlmsg_attrlen(ghdr, hdrlen), maxtype, policy);
157 }
158
159 /**
160 * Parse Generic Netlink message including attributes
161 * @arg nlh Pointer to Netlink message header
162 * @arg hdrlen Length of user header
163 * @arg tb Array to store parsed attributes
164 * @arg maxtype Maximum attribute id expected
165 * @arg policy Attribute validation policy
166 *
167 * Verifies the validity of the Netlink and Generic Netlink headers using
168 * genlmsg_valid_hdr() and calls nla_parse() on the message payload to
169 * parse eventual attributes.
170 *
171 * @par Example:
172 * @code
173 * struct nlattr *attrs[MY_TYPE_MAX+1];
174 *
175 * if ((err = genlmsg_parse(nlmsg_hdr(msg), sizeof(struct my_hdr), attrs,
176 * MY_TYPE_MAX, attr_policy)) < 0)
177 * // ERROR
178 * @endcode
179 *
180 * @see genlmsg_valid_hdr()
181 * @see genlmsg_validate()
182 * @see nla_parse()
183 *
184 * @return 0 on success or a negative error code.
185 */
186 int genlmsg_parse(struct nlmsghdr *nlh, int hdrlen, struct nlattr *tb[],
187 int maxtype, const struct nla_policy *policy)
188 {
189 struct genlmsghdr *ghdr;
190
191 if (!genlmsg_valid_hdr(nlh, hdrlen))
192 return -NLE_MSG_TOOSHORT;
193
194 ghdr = nlmsg_data(nlh);
195 return nla_parse(tb, maxtype, genlmsg_attrdata(ghdr, hdrlen),
196 genlmsg_attrlen(ghdr, hdrlen), policy);
197 }
198
199 /**
200 * Return pointer to Generic Netlink header
201 * @arg nlh Netlink message header
202 *
203 * @return Pointer to Generic Netlink message header
204 */
205 struct genlmsghdr *genlmsg_hdr(struct nlmsghdr *nlh)
206 {
207 return nlmsg_data(nlh);
208 }
209
210 /**
211 * Return length of message payload including user header
212 * @arg gnlh Generic Netlink message header
213 *
214 * @see genlmsg_data()
215 *
216 * @return Length of user payload including an eventual user header in
217 * number of bytes.
218 */
219 int genlmsg_len(const struct genlmsghdr *gnlh)
220 {
221 const struct nlmsghdr *nlh;
222
223 nlh = (const struct nlmsghdr *)((const unsigned char *) gnlh - NLMSG_HDRLEN);
224 return (nlh->nlmsg_len - GENL_HDRLEN - NLMSG_HDRLEN);
225 }
226
227
228 /**
229 * Return pointer to user header
230 * @arg gnlh Generic Netlink message header
231 *
232 * Calculates the pointer to the user header based on the pointer to
233 * the Generic Netlink message header.
234 *
235 * @return Pointer to the user header
236 */
237 void *genlmsg_user_hdr(const struct genlmsghdr *gnlh)
238 {
239 return genlmsg_data(gnlh);
240 }
241
242 /**
243 * Return pointer to user data
244 * @arg gnlh Generic netlink message header
245 * @arg hdrlen Length of user header
246 *
247 * Calculates the pointer to the user data based on the pointer to
248 * the Generic Netlink message header.
249 *
250 * @see genlmsg_user_datalen()
251 *
252 * @return Pointer to the user data
253 */
254 void *genlmsg_user_data(const struct genlmsghdr *gnlh, const int hdrlen)
255 {
256 return (char *) genlmsg_user_hdr(gnlh) + NLMSG_ALIGN(hdrlen);
257 }
258
259 /**
260 * Return length of user data
261 * @arg gnlh Generic Netlink message header
262 * @arg hdrlen Length of user header
263 *
264 * @see genlmsg_user_data()
265 *
266 * @return Length of user data in bytes
267 */
268 int genlmsg_user_datalen(const struct genlmsghdr *gnlh, const int hdrlen)
269 {
270 return genlmsg_len(gnlh) - NLMSG_ALIGN(hdrlen);
271 }
272
273 /**
274 * Return pointer to message attributes
275 * @arg gnlh Generic Netlink message header
276 * @arg hdrlen Length of user header
277 *
278 * @see genlmsg_attrlen()
279 *
280 * @return Pointer to the start of the message's attributes section.
281 */
282 struct nlattr *genlmsg_attrdata(const struct genlmsghdr *gnlh, int hdrlen)
283 {
284 return genlmsg_user_data(gnlh, hdrlen);
285 }
286
287 /**
288 * Return length of message attributes
289 * @arg gnlh Generic Netlink message header
290 * @arg hdrlen Length of user header
291 *
292 * @see genlmsg_attrdata()
293 *
294 * @return Length of the message section containing attributes in number
295 * of bytes.
296 */
297 int genlmsg_attrlen(const struct genlmsghdr *gnlh, int hdrlen)
298 {
299 return genlmsg_len(gnlh) - NLMSG_ALIGN(hdrlen);
300 }
301
302 /** @} */
303
304 /**
305 * @name Message Construction
306 * @{
307 */
308
309 /**
310 * Add Generic Netlink headers to Netlink message
311 * @arg msg Netlink message object
312 * @arg port Netlink port or NL_AUTO_PORT
313 * @arg seq Sequence number of message or NL_AUTO_SEQ
314 * @arg family Numeric family identifier
315 * @arg hdrlen Length of user header
316 * @arg flags Additional Netlink message flags (optional)
317 * @arg cmd Numeric command identifier
318 * @arg version Interface version
319 *
320 * Calls nlmsg_put() on the specified message object to reserve space for
321 * the Netlink header, the Generic Netlink header, and a user header of
322 * specified length. Fills out the header fields with the specified
323 * parameters.
324 *
325 * @par Example:
326 * @code
327 * struct nl_msg *msg;
328 * struct my_hdr *user_hdr;
329 *
330 * if (!(msg = nlmsg_alloc()))
331 * // ERROR
332 *
333 * user_hdr = genlmsg_put(msg, NL_AUTO_PORT, NL_AUTO_SEQ, family_id,
334 * sizeof(struct my_hdr), 0, MY_CMD_FOO, 0);
335 * if (!user_hdr)
336 * // ERROR
337 * @endcode
338 *
339 * @see nlmsg_put()
340 *
341 * Returns Pointer to user header or NULL if an error occurred.
342 */
343 void *genlmsg_put(struct nl_msg *msg, uint32_t port, uint32_t seq, int family,
344 int hdrlen, int flags, uint8_t cmd, uint8_t version)
345 {
346 struct nlmsghdr *nlh;
347 struct genlmsghdr hdr = {
348 .cmd = cmd,
349 .version = version,
350 };
351
352 nlh = nlmsg_put(msg, port, seq, family, GENL_HDRLEN + hdrlen, flags);
353 if (nlh == NULL)
354 return NULL;
355
356 memcpy(nlmsg_data(nlh), &hdr, sizeof(hdr));
357 NL_DBG(2, "msg %p: Added generic netlink header cmd=%d version=%d\n",
358 msg, cmd, version);
359
360 return (char *) nlmsg_data(nlh) + GENL_HDRLEN;
361 }
362
363 /** @} */
364
365 /**
366 * @name Deprecated
367 * @{
368 */
369
370 /**
371 * Return pointer to message payload
372 * @arg gnlh Generic Netlink message header
373 *
374 * @deprecated This function has been deprecated due to inability to specify
375 * the length of the user header. Use genlmsg_user_hdr()
376 * respectively genlmsg_user_data().
377 *
378 * @return Pointer to payload section
379 */
380 void *genlmsg_data(const struct genlmsghdr *gnlh)
381 {
382 return ((unsigned char *) gnlh + GENL_HDRLEN);
383 }
384
385 /** @} */
386 /** @} */
nla_validate
int nla_validate(const struct nlattr *head, int len, int maxtype, const struct nla_policy *policy)
Validate a stream of attributes.
Definition: attr.c:287
nla_parse
int nla_parse(struct nlattr *tb[], int maxtype, struct nlattr *head, int len, const struct nla_policy *policy)
Create attribute index based on a stream of attributes.
Definition: attr.c:236
genlmsg_validate
int genlmsg_validate(struct nlmsghdr *nlh, int hdrlen, int maxtype, const struct nla_policy *policy)
Validate Generic Netlink message including attributes.
Definition: genl.c:146
genlmsg_user_data
void * genlmsg_user_data(const struct genlmsghdr *gnlh, const int hdrlen)
Return pointer to user data.
Definition: genl.c:254
genlmsg_len
int genlmsg_len(const struct genlmsghdr *gnlh)
Return length of message payload including user header.
Definition: genl.c:219
genlmsg_user_datalen
int genlmsg_user_datalen(const struct genlmsghdr *gnlh, const int hdrlen)
Return length of user data.
Definition: genl.c:268
genl_send_simple
int genl_send_simple(struct nl_sock *sk, int family, int cmd, int version, int flags)
Send a Generic Netlink message consisting only of a header.
Definition: genl.c:79
genlmsg_attrdata
struct nlattr * genlmsg_attrdata(const struct genlmsghdr *gnlh, int hdrlen)
Return pointer to message attributes.
Definition: genl.c:282
genlmsg_data
void * genlmsg_data(const struct genlmsghdr *gnlh)
Return pointer to message payload.
Definition: genl.c:380
genlmsg_parse
int genlmsg_parse(struct nlmsghdr *nlh, int hdrlen, struct nlattr *tb[], int maxtype, const struct nla_policy *policy)
Parse Generic Netlink message including attributes.
Definition: genl.c:186
genlmsg_put
void * genlmsg_put(struct nl_msg *msg, uint32_t port, uint32_t seq, int family, int hdrlen, int flags, uint8_t cmd, uint8_t version)
Add Generic Netlink headers to Netlink message.
Definition: genl.c:343
genl_connect
int genl_connect(struct nl_sock *sk)
Connect a Generic Netlink socket.
Definition: genl.c:39
genlmsg_attrlen
int genlmsg_attrlen(const struct genlmsghdr *gnlh, int hdrlen)
Return length of message attributes.
Definition: genl.c:297
genlmsg_hdr
struct genlmsghdr * genlmsg_hdr(struct nlmsghdr *nlh)
Return pointer to Generic Netlink header.
Definition: genl.c:205
genlmsg_user_hdr
void * genlmsg_user_hdr(const struct genlmsghdr *gnlh)
Return pointer to user header.
Definition: genl.c:237
genlmsg_valid_hdr
int genlmsg_valid_hdr(struct nlmsghdr *nlh, int hdrlen)
Validate Generic Netlink message headers.
Definition: genl.c:112
nlmsg_put
struct nlmsghdr * nlmsg_put(struct nl_msg *n, uint32_t pid, uint32_t seq, int type, int payload, int flags)
Add a netlink message header to a netlink message.
Definition: msg.c:503
nlmsg_data
void * nlmsg_data(const struct nlmsghdr *nlh)
Return pointer to message payload.
Definition: msg.c:100
nl_connect
int nl_connect(struct nl_sock *sk, int protocol)
Create file descriptor and bind socket.
Definition: nl.c:97
nl_send_simple
int nl_send_simple(struct nl_sock *sk, int type, int flags, void *buf, size_t size)
Construct and transmit a Netlink message.
Definition: nl.c:574
nla_policy
Attribute validation policy.
Definition: attr.h:63