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