libnl  3.6.0
attr.h
1 /* SPDX-License-Identifier: LGPL-2.1-only */
2 /*
3  * Copyright (c) 2003-2013 Thomas Graf <tgraf@suug.ch>
4  */
5 
6 #ifndef NETLINK_ATTR_H_
7 #define NETLINK_ATTR_H_
8 
9 #include <netlink/netlink.h>
10 #include <netlink/object.h>
11 #include <netlink/addr.h>
12 #include <netlink/data.h>
13 
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17 
18 struct nlattr;
19 
20 struct nl_msg;
21 
22 /**
23  * @name Basic Attribute Data Types
24  * @{
25  */
26 
27 /**
28  * @ingroup attr
29  * Basic attribute data types
30  *
31  * See section @core_doc{core_attr_parse,Attribute Parsing} for more details.
32  */
33 enum {
34  NLA_UNSPEC, /**< Unspecified type, binary data chunk */
35  NLA_U8, /**< 8 bit integer */
36  NLA_U16, /**< 16 bit integer */
37  NLA_U32, /**< 32 bit integer */
38  NLA_U64, /**< 64 bit integer */
39  NLA_STRING, /**< NUL terminated character string */
40  NLA_FLAG, /**< Flag */
41  NLA_MSECS, /**< Micro seconds (64bit) */
42  NLA_NESTED, /**< Nested attributes */
43  NLA_NESTED_COMPAT,
44  NLA_NUL_STRING,
45  NLA_BINARY,
46  NLA_S8,
47  NLA_S16,
48  NLA_S32,
49  NLA_S64,
50  __NLA_TYPE_MAX,
51 };
52 
53 #define NLA_TYPE_MAX (__NLA_TYPE_MAX - 1)
54 
55 /** @} */
56 
57 /**
58  * @ingroup attr
59  * Attribute validation policy.
60  *
61  * See section @core_doc{core_attr_parse,Attribute Parsing} for more details.
62  */
63 struct nla_policy {
64  /** Type of attribute or NLA_UNSPEC */
65  uint16_t type;
66 
67  /** Minimal length of payload required */
68  uint16_t minlen;
69 
70  /** Maximal length of payload allowed */
71  uint16_t maxlen;
72 };
73 
74 /* Size calculations */
75 extern int nla_attr_size(int payload);
76 extern int nla_total_size(int payload);
77 extern int nla_padlen(int payload);
78 
79 /* Attribute parsing */
80 extern int nla_type(const struct nlattr *);
81 extern void * nla_data(const struct nlattr *);
82 extern int nla_len(const struct nlattr *);
83 extern int nla_ok(const struct nlattr *, int);
84 extern struct nlattr * nla_next(const struct nlattr *, int *);
85 extern int nla_parse(struct nlattr **, int, struct nlattr *,
86  int, const struct nla_policy *);
87 extern int nla_validate(const struct nlattr *, int, int,
88  const struct nla_policy *);
89 extern struct nlattr * nla_find(const struct nlattr *, int, int);
90 
91 /* Helper Functions */
92 extern int nla_memcpy(void *, const struct nlattr *, int);
93 extern size_t nla_strlcpy(char *, const struct nlattr *, size_t);
94 extern int nla_memcmp(const struct nlattr *, const void *, size_t);
95 extern int nla_strcmp(const struct nlattr *, const char *);
96 
97 /* Unspecific attribute */
98 extern struct nlattr * nla_reserve(struct nl_msg *, int, int);
99 extern int nla_put(struct nl_msg *, int, int, const void *);
100 extern int nla_put_data(struct nl_msg *, int,
101  const struct nl_data *);
102 extern int nla_put_addr(struct nl_msg *, int, struct nl_addr *);
103 
104 /* Integer attribute */
105 extern int8_t nla_get_s8(const struct nlattr *);
106 extern int nla_put_s8(struct nl_msg *, int, int8_t);
107 extern uint8_t nla_get_u8(const struct nlattr *);
108 extern int nla_put_u8(struct nl_msg *, int, uint8_t);
109 extern int16_t nla_get_s16(const struct nlattr *);
110 extern int nla_put_s16(struct nl_msg *, int, int16_t);
111 extern uint16_t nla_get_u16(const struct nlattr *);
112 extern int nla_put_u16(struct nl_msg *, int, uint16_t);
113 extern int32_t nla_get_s32(const struct nlattr *);
114 extern int nla_put_s32(struct nl_msg *, int, int32_t);
115 extern uint32_t nla_get_u32(const struct nlattr *);
116 extern int nla_put_u32(struct nl_msg *, int, uint32_t);
117 extern int64_t nla_get_s64(const struct nlattr *);
118 extern int nla_put_s64(struct nl_msg *, int, int64_t);
119 extern uint64_t nla_get_u64(const struct nlattr *);
120 extern int nla_put_u64(struct nl_msg *, int, uint64_t);
121 
122 /* String attribute */
123 extern char * nla_get_string(const struct nlattr *);
124 extern char * nla_strdup(const struct nlattr *);
125 extern int nla_put_string(struct nl_msg *, int, const char *);
126 
127 /* Flag attribute */
128 extern int nla_get_flag(const struct nlattr *);
129 extern int nla_put_flag(struct nl_msg *, int);
130 
131 /* Msec attribute */
132 extern unsigned long nla_get_msecs(const struct nlattr *);
133 extern int nla_put_msecs(struct nl_msg *, int, unsigned long);
134 
135 /* Attribute nesting */
136 extern int nla_put_nested(struct nl_msg *, int,
137  const struct nl_msg *);
138 extern struct nlattr * nla_nest_start(struct nl_msg *, int);
139 extern int nla_nest_end(struct nl_msg *, struct nlattr *);
140 extern int nla_nest_end_keep_empty(struct nl_msg *, struct nlattr *);
141 extern void nla_nest_cancel(struct nl_msg *, const struct nlattr *);
142 extern int nla_parse_nested(struct nlattr **, int, struct nlattr *,
143  const struct nla_policy *);
144 extern int nla_is_nested(const struct nlattr *);
145 
146 /**
147  * @name Attribute Construction (Exception Based)
148  * @{
149  */
150 
151 /**
152  * @ingroup attr
153  * Add unspecific attribute to netlink message.
154  * @arg msg Netlink message.
155  * @arg attrtype Attribute type.
156  * @arg attrlen Length of attribute payload.
157  * @arg data Head of attribute payload.
158  */
159 #define NLA_PUT(msg, attrtype, attrlen, data) \
160  do { \
161  if (nla_put(msg, attrtype, attrlen, data) < 0) \
162  goto nla_put_failure; \
163  } while(0)
164 
165 /**
166  * @ingroup attr
167  * Add atomic type attribute to netlink message.
168  * @arg msg Netlink message.
169  * @arg type Atomic type.
170  * @arg attrtype Attribute type.
171  * @arg value Head of attribute payload.
172  */
173 #define NLA_PUT_TYPE(msg, type, attrtype, value) \
174  do { \
175  type __tmp = value; \
176  NLA_PUT(msg, attrtype, sizeof(type), &__tmp); \
177  } while(0)
178 
179 /**
180  * Add 8 bit signed integer attribute to netlink message.
181  * @arg msg Netlink message.
182  * @arg attrtype Attribute type.
183  * @arg value Numeric value.
184  */
185 #define NLA_PUT_S8(msg, attrtype, value) \
186  NLA_PUT_TYPE(msg, int8_t, attrtype, value)
187 
188 /**
189  * Add 8 bit integer attribute to netlink message.
190  * @arg msg Netlink message.
191  * @arg attrtype Attribute type.
192  * @arg value Numeric value.
193  */
194 #define NLA_PUT_U8(msg, attrtype, value) \
195  NLA_PUT_TYPE(msg, uint8_t, attrtype, value)
196 
197 /**
198  * Add 16 bit signed integer attribute to netlink message.
199  * @arg msg Netlink message.
200  * @arg attrtype Attribute type.
201  * @arg value Numeric value.
202  */
203 #define NLA_PUT_S16(msg, attrtype, value) \
204  NLA_PUT_TYPE(msg, int16_t, attrtype, value)
205 
206 /**
207  * Add 16 bit integer attribute to netlink message.
208  * @arg msg Netlink message.
209  * @arg attrtype Attribute type.
210  * @arg value Numeric value.
211  */
212 #define NLA_PUT_U16(msg, attrtype, value) \
213  NLA_PUT_TYPE(msg, uint16_t, attrtype, value)
214 
215 /**
216  * Add 32 bit signed integer attribute to netlink message.
217  * @arg msg Netlink message.
218  * @arg attrtype Attribute type.
219  * @arg value Numeric value.
220  */
221 #define NLA_PUT_S32(msg, attrtype, value) \
222  NLA_PUT_TYPE(msg, int32_t, attrtype, value)
223 
224 /**
225  * Add 32 bit integer attribute to netlink message.
226  * @arg msg Netlink message.
227  * @arg attrtype Attribute type.
228  * @arg value Numeric value.
229  */
230 #define NLA_PUT_U32(msg, attrtype, value) \
231  NLA_PUT_TYPE(msg, uint32_t, attrtype, value)
232 
233 /**
234  * Add 64 bit signed integer attribute to netlink message.
235  * @arg msg Netlink message.
236  * @arg attrtype Attribute type.
237  * @arg value Numeric value.
238  */
239 #define NLA_PUT_S64(msg, attrtype, value) \
240  NLA_PUT_TYPE(msg, int64_t, attrtype, value)
241 
242 /**
243  * Add 64 bit integer attribute to netlink message.
244  * @arg msg Netlink message.
245  * @arg attrtype Attribute type.
246  * @arg value Numeric value.
247  */
248 #define NLA_PUT_U64(msg, attrtype, value) \
249  NLA_PUT_TYPE(msg, uint64_t, attrtype, value)
250 
251 /**
252  * Add string attribute to netlink message.
253  * @arg msg Netlink message.
254  * @arg attrtype Attribute type.
255  * @arg value NUL terminated character string.
256  */
257 #define NLA_PUT_STRING(msg, attrtype, value) \
258  NLA_PUT(msg, attrtype, (int) strlen(value) + 1, value)
259 
260 /**
261  * Add flag attribute to netlink message.
262  * @arg msg Netlink message.
263  * @arg attrtype Attribute type.
264  */
265 #define NLA_PUT_FLAG(msg, attrtype) \
266  NLA_PUT(msg, attrtype, 0, NULL)
267 
268 /**
269  * Add msecs attribute to netlink message.
270  * @arg msg Netlink message.
271  * @arg attrtype Attribute type.
272  * @arg msecs Numeric value in micro seconds.
273  */
274 #define NLA_PUT_MSECS(msg, attrtype, msecs) \
275  NLA_PUT_U64(msg, attrtype, msecs)
276 
277 /**
278  * Add address attribute to netlink message.
279  * @arg msg Netlink message.
280  * @arg attrtype Attribute type.
281  * @arg addr Abstract address object.
282  */
283 #define NLA_PUT_ADDR(msg, attrtype, addr) \
284  NLA_PUT(msg, attrtype, nl_addr_get_len(addr), \
285  nl_addr_get_binary_addr(addr))
286 
287 /**
288  * Add abstract data attribute to netlink message.
289  * @arg msg Netlink message.
290  * @arg attrtype Attribute type.
291  * @arg data Abstract data object.
292  */
293 #define NLA_PUT_DATA(msg, attrtype, data) \
294  NLA_PUT(msg, attrtype, nl_data_get_size(data), \
295  nl_data_get(data))
296 
297 /** @} */
298 
299 /**
300  * @name Iterators
301  * @{
302  */
303 
304 /**
305  * @ingroup attr
306  * Iterate over a stream of attributes
307  * @arg pos loop counter, set to current attribute
308  * @arg head head of attribute stream
309  * @arg len length of attribute stream
310  * @arg rem initialized to len, holds bytes currently remaining in stream
311  */
312 #define nla_for_each_attr(pos, head, len, rem) \
313  for (pos = head, rem = len; \
314  nla_ok(pos, rem); \
315  pos = nla_next(pos, &(rem)))
316 
317 /**
318  * @ingroup attr
319  * Iterate over a stream of nested attributes
320  * @arg pos loop counter, set to current attribute
321  * @arg nla attribute containing the nested attributes
322  * @arg rem initialized to len, holds bytes currently remaining in stream
323  */
324 #define nla_for_each_nested(pos, nla, rem) \
325  for (pos = (struct nlattr *) nla_data(nla), rem = nla_len(nla); \
326  nla_ok(pos, rem); \
327  pos = nla_next(pos, &(rem)))
328 
329 /** @} */
330 
331 #ifdef __cplusplus
332 }
333 #endif
334 
335 #endif
int nla_validate(const struct nlattr *, int, int, const struct nla_policy *)
Validate a stream of attributes.
Definition: attr.c:287
int nla_put_s16(struct nl_msg *, int, int16_t)
Add 16 bit signed integer attribute to netlink message.
Definition: attr.c:613
uint32_t nla_get_u32(const struct nlattr *)
Return payload of 32 bit integer attribute.
Definition: attr.c:699
int nla_put_u16(struct nl_msg *, int, uint16_t)
Add 16 bit integer attribute to netlink message.
Definition: attr.c:638
uint16_t nla_get_u16(const struct nlattr *)
Return payload of 16 bit integer attribute.
Definition: attr.c:649
int nla_strcmp(const struct nlattr *, const char *)
Compare string attribute payload with string.
Definition: attr.c:416
int nla_put_data(struct nl_msg *, int, const struct nl_data *)
Add abstract data as unspecific attribute to netlink message.
Definition: attr.c:527
int nla_put_nested(struct nl_msg *, int, const struct nl_msg *)
Add nested attributes to netlink message.
Definition: attr.c:877
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
int nla_put_string(struct nl_msg *, int, const char *)
Add string attribute to netlink message.
Definition: attr.c:779
uint64_t nla_get_u64(const struct nlattr *)
Return payload of u64 attribute.
Definition: attr.c:754
int nla_get_flag(const struct nlattr *)
Return true if flag attribute is set.
Definition: attr.c:825
int nla_type(const struct nlattr *)
Return type of the attribute.
Definition: attr.c:103
int nla_put_u64(struct nl_msg *, int, uint64_t)
Add 64 bit integer attribute to netlink message.
Definition: attr.c:743
struct nlattr * nla_find(const struct nlattr *, int, int)
Find a single attribute in a stream of attributes.
Definition: attr.c:316
int nla_ok(const struct nlattr *, int)
Check if the attribute header and payload can be accessed safely.
Definition: attr.c:142
int nla_is_nested(const struct nlattr *)
Return true if attribute has NLA_F_NESTED flag set.
Definition: attr.c:1025
struct nlattr * nla_reserve(struct nl_msg *, int, int)
Reserve space for a attribute.
Definition: attr.c:449
int nla_put_u32(struct nl_msg *, int, uint32_t)
Add 32 bit integer attribute to netlink message.
Definition: attr.c:688
struct nlattr * nla_next(const struct nlattr *, int *)
Return next attribute in a stream of attributes.
Definition: attr.c:165
int nla_put_addr(struct nl_msg *, int, struct nl_addr *)
Add abstract address as unspecific attribute to netlink message.
Definition: attr.c:542
int nla_memcmp(const struct nlattr *, const void *, size_t)
Compare attribute payload with memory area.
Definition: attr.c:398
int nla_put_s64(struct nl_msg *, int, int64_t)
Add 64 bit signed integer attribute to netlink message.
Definition: attr.c:713
int nla_put_msecs(struct nl_msg *, int, unsigned long)
Add a msecs netlink attribute to a netlink message.
Definition: attr.c:842
uint8_t nla_get_u8(const struct nlattr *)
Return value of 8 bit integer attribute.
Definition: attr.c:599
int nla_attr_size(int payload)
Return size of attribute whithout padding.
Definition: attr.c:49
int16_t nla_get_s16(const struct nlattr *)
Return payload of 16 bit signed integer attribute.
Definition: attr.c:624
int64_t nla_get_s64(const struct nlattr *)
Return payload of s64 attribute.
Definition: attr.c:724
int nla_put_flag(struct nl_msg *, int)
Add flag netlink attribute to netlink message.
Definition: attr.c:814
int nla_put_s32(struct nl_msg *, int, int32_t)
Add 32 bit signed integer attribute to netlink message.
Definition: attr.c:663
int nla_memcpy(void *, const struct nlattr *, int)
Copy attribute payload to another memory area.
Definition: attr.c:346
struct nlattr * nla_nest_start(struct nl_msg *, int)
Start a new level of nested attributes.
Definition: attr.c:895
unsigned long nla_get_msecs(const struct nlattr *)
Return payload of msecs attribute.
Definition: attr.c:853
size_t nla_strlcpy(char *, const struct nlattr *, size_t)
Copy string attribute payload to a buffer.
Definition: attr.c:371
int nla_parse_nested(struct nlattr *tb[], int maxtype, struct nlattr *nla, const struct nla_policy *policy)
Create attribute index based on nested attribute.
Definition: attr.c:1013
int32_t nla_get_s32(const struct nlattr *)
Return payload of 32 bit signed integer attribute.
Definition: attr.c:674
void nla_nest_cancel(struct nl_msg *, const struct nlattr *)
Cancel the addition of a nested attribute.
Definition: attr.c:987
int nla_len(const struct nlattr *)
Return length of the payload .
Definition: attr.c:125
int nla_put_u8(struct nl_msg *, int, uint8_t)
Add 8 bit integer attribute to netlink message.
Definition: attr.c:588
int nla_nest_end(struct nl_msg *, struct nlattr *)
Finalize nesting of attributes.
Definition: attr.c:958
int nla_nest_end_keep_empty(struct nl_msg *, struct nlattr *)
Finalize nesting of attributes without stripping off empty attributes.
Definition: attr.c:973
int8_t nla_get_s8(const struct nlattr *)
Return value of 8 bit signed integer attribute.
Definition: attr.c:574
int nla_padlen(int payload)
Return length of padding at the tail of the attribute.
Definition: attr.c:85
int nla_put(struct nl_msg *, int, int, const void *)
Add a unspecific attribute to netlink message.
Definition: attr.c:493
int nla_put_s8(struct nl_msg *, int, int8_t)
Add 8 bit signed integer attribute to netlink message.
Definition: attr.c:563
void * nla_data(const struct nlattr *)
Return pointer to the payload section.
Definition: attr.c:114
char * nla_get_string(const struct nlattr *)
Return payload of string attribute.
Definition: attr.c:790
int nla_total_size(int payload)
Return size of attribute including padding.
Definition: attr.c:67
@ NLA_U64
64 bit integer
Definition: attr.h:38
@ NLA_STRING
NUL terminated character string.
Definition: attr.h:39
@ NLA_UNSPEC
Unspecified type, binary data chunk.
Definition: attr.h:34
@ NLA_MSECS
Micro seconds (64bit)
Definition: attr.h:41
@ NLA_U8
8 bit integer
Definition: attr.h:35
@ NLA_FLAG
Flag.
Definition: attr.h:40
@ NLA_U16
16 bit integer
Definition: attr.h:36
@ NLA_NESTED
Nested attributes.
Definition: attr.h:42
@ NLA_U32
32 bit integer
Definition: attr.h:37
Attribute validation policy.
Definition: attr.h:63
uint16_t maxlen
Maximal length of payload allowed.
Definition: attr.h:71
uint16_t minlen
Minimal length of payload required.
Definition: attr.h:68
uint16_t type
Type of attribute or NLA_UNSPEC.
Definition: attr.h:65