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

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