libnl 3.5.0

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