libnl  3.3.0
genl.c
1 /*
2  * lib/genl/genl.c Generic Netlink
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation version 2.1
7  * of the License.
8  *
9  * Copyright (c) 2003-2012 Thomas Graf <tgraf@suug.ch>
10  */
11 
12 /**
13  * @defgroup genl Generic Netlink Library (libnl-genl)
14  *
15  * @{
16  */
17 
18 #include <netlink-private/genl.h>
19 #include <netlink/netlink.h>
20 #include <netlink/genl/genl.h>
21 #include <netlink/utils.h>
22 
23 /**
24  * @name Generic Netlink Socket
25  * @{
26  */
27 
28 /**
29  * Connect a Generic Netlink socket
30  * @arg sk Unconnected Netlink socket
31  *
32  * This function expects a struct nl_socket object previously allocated via
33  * nl_socket_alloc(). It calls nl_connect() to create the local socket file
34  * descriptor and binds the socket to the \c NETLINK_GENERIC Netlink protocol.
35  *
36  * Using this function is equivalent to:
37  * @code
38  * nl_connect(sk, NETLINK_GENERIC);
39  * @endcode
40  *
41  * @see nl_connect()
42  *
43  * @return 0 on success or a negative error code.
44  */
45 int genl_connect(struct nl_sock *sk)
46 {
47  return nl_connect(sk, NETLINK_GENERIC);
48 }
49 
50 /** @} */
51 
52 /**
53  * @name Sending Data
54  * @{
55  */
56 
57 /**
58  * Send a Generic Netlink message consisting only of a header
59  * @arg sk Generic Netlink socket
60  * @arg family Numeric family identifier
61  * @arg cmd Numeric command identifier
62  * @arg version Interface version
63  * @arg flags Additional Netlink message flags (optional)
64  *
65  * This function is a shortcut for sending a Generic Netlink message without
66  * any message payload. The message will only consist of the Netlink and
67  * Generic Netlink headers. The header is constructed based on the specified
68  * parameters and passed on to nl_send_simple() to send it on the specified
69  * socket.
70  *
71  * @par Example:
72  * @code
73  * #include <netlink/genl/genl.h>
74  * #include <linux/genetlink.h>
75  *
76  * err = genl_send_simple(sk, GENL_ID_CTRL, CTRL_CMD_GETFAMILY, CTRL_VERSION,
77  * NLM_F_DUMP);
78  * @endcode
79  *
80  * @see nl_send_simple()
81  *
82  * @return 0 on success or a negative error code. Due to a bug, this function
83  * returns the number of bytes sent. Treat any non-negative number as success.
84  */
85 int genl_send_simple(struct nl_sock *sk, int family, int cmd,
86  int version, int flags)
87 {
88  struct genlmsghdr hdr = {
89  .cmd = cmd,
90  .version = version,
91  };
92 
93  return nl_send_simple(sk, family, flags, &hdr, sizeof(hdr));
94 }
95 
96 /** @} */
97 
98 /**
99  * @name Message Parsing
100  * @{
101  */
102 
103 /**
104  * Validate Generic Netlink message headers
105  * @arg nlh Pointer to Netlink message header
106  * @arg hdrlen Length of user header
107  *
108  * Verifies the integrity of the Netlink and Generic Netlink headers by
109  * enforcing the following requirements:
110  * - Valid Netlink message header (nlmsg_valid_hdr())
111  * - Presence of a complete Generic Netlink header
112  * - At least \c hdrlen bytes of payload included after the generic
113  * netlink header.
114  *
115  * @return A positive integer (true) if the headers are valid or
116  * 0 (false) if not.
117  */
118 int genlmsg_valid_hdr(struct nlmsghdr *nlh, int hdrlen)
119 {
120  struct genlmsghdr *ghdr;
121 
122  if (!nlmsg_valid_hdr(nlh, GENL_HDRLEN))
123  return 0;
124 
125  ghdr = nlmsg_data(nlh);
126  if (genlmsg_len(ghdr) < 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  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 = genlsmg_parse(nlmsg_nlh(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, 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 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 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 /** @} */
void * genlmsg_user_hdr(const struct genlmsghdr *gnlh)
Return pointer to user header.
Definition: genl.c:243
void * nlmsg_data(const struct nlmsghdr *nlh)
Return pointer to message payload.
Definition: msg.c:106
Attribute validation policy.
Definition: attr.h:69
int genl_connect(struct nl_sock *sk)
Connect a Generic Netlink socket.
Definition: genl.c:45
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
int genlmsg_user_datalen(const struct genlmsghdr *gnlh, const int hdrlen)
Return length of user data.
Definition: genl.c:274
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:85
int nl_connect(struct nl_sock *sk, int protocol)
Create file descriptor and bind socket.
Definition: nl.c:103
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:507
struct nlattr * genlmsg_attrdata(const struct genlmsghdr *gnlh, int hdrlen)
Return pointer to message attributes.
Definition: genl.c:288
struct genlmsghdr * genlmsg_hdr(struct nlmsghdr *nlh)
Return pointer to Generic Netlink header.
Definition: genl.c:211
int genlmsg_attrlen(const struct genlmsghdr *gnlh, int hdrlen)
Return length of message attributes.
Definition: genl.c:303
int nla_parse(struct nlattr *tb[], int maxtype, struct nlattr *head, int len, struct nla_policy *policy)
Create attribute index based on a stream of attributes.
Definition: attr.c:242
void * genlmsg_data(const struct genlmsghdr *gnlh)
Return pointer to message payload.
Definition: genl.c:386
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:580
int genlmsg_parse(struct nlmsghdr *nlh, int hdrlen, struct nlattr *tb[], int maxtype, struct nla_policy *policy)
Parse Generic Netlink message including attributes.
Definition: genl.c:192
int genlmsg_validate(struct nlmsghdr *nlh, int hdrlen, int maxtype, struct nla_policy *policy)
Validate Generic Netlink message including attributes.
Definition: genl.c:152
int genlmsg_len(const struct genlmsghdr *gnlh)
Return length of message payload including user header.
Definition: genl.c:225
int genlmsg_valid_hdr(struct nlmsghdr *nlh, int hdrlen)
Validate Generic Netlink message headers.
Definition: genl.c:118
int nla_validate(const struct nlattr *head, int len, int maxtype, const struct nla_policy *policy)
Validate a stream of attributes.
Definition: attr.c:294
void * genlmsg_user_data(const struct genlmsghdr *gnlh, const int hdrlen)
Return pointer to user data.
Definition: genl.c:260