libnl  3.3.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, 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 void nla_nest_cancel(struct nl_msg *, const struct nlattr *);
147 extern int nla_parse_nested(struct nlattr **, int, struct nlattr *,
148  struct nla_policy *);
149 extern int nla_is_nested(const struct nlattr *);
150 
151 /**
152  * @name Attribute Construction (Exception Based)
153  * @{
154  */
155 
156 /**
157  * @ingroup attr
158  * Add unspecific attribute to netlink message.
159  * @arg msg Netlink message.
160  * @arg attrtype Attribute type.
161  * @arg attrlen Length of attribute payload.
162  * @arg data Head of attribute payload.
163  */
164 #define NLA_PUT(msg, attrtype, attrlen, data) \
165  do { \
166  if (nla_put(msg, attrtype, attrlen, data) < 0) \
167  goto nla_put_failure; \
168  } while(0)
169 
170 /**
171  * @ingroup attr
172  * Add atomic type attribute to netlink message.
173  * @arg msg Netlink message.
174  * @arg type Atomic type.
175  * @arg attrtype Attribute type.
176  * @arg value Head of attribute payload.
177  */
178 #define NLA_PUT_TYPE(msg, type, attrtype, value) \
179  do { \
180  type __tmp = value; \
181  NLA_PUT(msg, attrtype, sizeof(type), &__tmp); \
182  } while(0)
183 
184 /**
185  * Add 8 bit signed integer attribute to netlink message.
186  * @arg msg Netlink message.
187  * @arg attrtype Attribute type.
188  * @arg value Numeric value.
189  */
190 #define NLA_PUT_S8(msg, attrtype, value) \
191  NLA_PUT_TYPE(msg, int8_t, attrtype, value)
192 
193 /**
194  * Add 8 bit integer attribute to netlink message.
195  * @arg msg Netlink message.
196  * @arg attrtype Attribute type.
197  * @arg value Numeric value.
198  */
199 #define NLA_PUT_U8(msg, attrtype, value) \
200  NLA_PUT_TYPE(msg, uint8_t, attrtype, value)
201 
202 /**
203  * Add 16 bit signed integer attribute to netlink message.
204  * @arg msg Netlink message.
205  * @arg attrtype Attribute type.
206  * @arg value Numeric value.
207  */
208 #define NLA_PUT_S16(msg, attrtype, value) \
209  NLA_PUT_TYPE(msg, int16_t, attrtype, value)
210 
211 /**
212  * Add 16 bit integer attribute to netlink message.
213  * @arg msg Netlink message.
214  * @arg attrtype Attribute type.
215  * @arg value Numeric value.
216  */
217 #define NLA_PUT_U16(msg, attrtype, value) \
218  NLA_PUT_TYPE(msg, uint16_t, attrtype, value)
219 
220 /**
221  * Add 32 bit signed integer attribute to netlink message.
222  * @arg msg Netlink message.
223  * @arg attrtype Attribute type.
224  * @arg value Numeric value.
225  */
226 #define NLA_PUT_S32(msg, attrtype, value) \
227  NLA_PUT_TYPE(msg, int32_t, attrtype, value)
228 
229 /**
230  * Add 32 bit integer attribute to netlink message.
231  * @arg msg Netlink message.
232  * @arg attrtype Attribute type.
233  * @arg value Numeric value.
234  */
235 #define NLA_PUT_U32(msg, attrtype, value) \
236  NLA_PUT_TYPE(msg, uint32_t, attrtype, value)
237 
238 /**
239  * Add 64 bit signed integer attribute to netlink message.
240  * @arg msg Netlink message.
241  * @arg attrtype Attribute type.
242  * @arg value Numeric value.
243  */
244 #define NLA_PUT_S64(msg, attrtype, value) \
245  NLA_PUT_TYPE(msg, int64_t, attrtype, value)
246 
247 /**
248  * Add 64 bit integer attribute to netlink message.
249  * @arg msg Netlink message.
250  * @arg attrtype Attribute type.
251  * @arg value Numeric value.
252  */
253 #define NLA_PUT_U64(msg, attrtype, value) \
254  NLA_PUT_TYPE(msg, uint64_t, attrtype, value)
255 
256 /**
257  * Add string attribute to netlink message.
258  * @arg msg Netlink message.
259  * @arg attrtype Attribute type.
260  * @arg value NUL terminated character string.
261  */
262 #define NLA_PUT_STRING(msg, attrtype, value) \
263  NLA_PUT(msg, attrtype, (int) strlen(value) + 1, value)
264 
265 /**
266  * Add flag attribute to netlink message.
267  * @arg msg Netlink message.
268  * @arg attrtype Attribute type.
269  */
270 #define NLA_PUT_FLAG(msg, attrtype) \
271  NLA_PUT(msg, attrtype, 0, NULL)
272 
273 /**
274  * Add msecs attribute to netlink message.
275  * @arg msg Netlink message.
276  * @arg attrtype Attribute type.
277  * @arg msecs Numeric value in micro seconds.
278  */
279 #define NLA_PUT_MSECS(msg, attrtype, msecs) \
280  NLA_PUT_U64(msg, attrtype, msecs)
281 
282 /**
283  * Add address attribute to netlink message.
284  * @arg msg Netlink message.
285  * @arg attrtype Attribute type.
286  * @arg addr Abstract address object.
287  */
288 #define NLA_PUT_ADDR(msg, attrtype, addr) \
289  NLA_PUT(msg, attrtype, nl_addr_get_len(addr), \
290  nl_addr_get_binary_addr(addr))
291 
292 /**
293  * Add abstract data attribute to netlink message.
294  * @arg msg Netlink message.
295  * @arg attrtype Attribute type.
296  * @arg data Abstract data object.
297  */
298 #define NLA_PUT_DATA(msg, attrtype, data) \
299  NLA_PUT(msg, attrtype, nl_data_get_size(data), \
300  nl_data_get(data))
301 
302 /** @} */
303 
304 /**
305  * @name Iterators
306  * @{
307  */
308 
309 /**
310  * @ingroup attr
311  * Iterate over a stream of attributes
312  * @arg pos loop counter, set to current attribute
313  * @arg head head of attribute stream
314  * @arg len length of attribute stream
315  * @arg rem initialized to len, holds bytes currently remaining in stream
316  */
317 #define nla_for_each_attr(pos, head, len, rem) \
318  for (pos = head, rem = len; \
319  nla_ok(pos, rem); \
320  pos = nla_next(pos, &(rem)))
321 
322 /**
323  * @ingroup attr
324  * Iterate over a stream of nested attributes
325  * @arg pos loop counter, set to current attribute
326  * @arg nla attribute containing the nested attributes
327  * @arg rem initialized to len, holds bytes currently remaining in stream
328  */
329 #define nla_for_each_nested(pos, nla, rem) \
330  for (pos = (struct nlattr *) nla_data(nla), rem = nla_len(nla); \
331  nla_ok(pos, rem); \
332  pos = nla_next(pos, &(rem)))
333 
334 /** @} */
335 
336 #ifdef __cplusplus
337 }
338 #endif
339 
340 #endif
8 bit integer
Definition: attr.h:41
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:681
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:645
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:832
int16_t nla_get_s16(const struct nlattr *)
Return payload of 16 bit signed integer attribute.
Definition: attr.c:631
int nla_put_addr(struct nl_msg *, int, struct nl_addr *)
Add abstract address as unspecific attribute to netlink message.
Definition: attr.c:549
int nla_put_s8(struct nl_msg *, int, int8_t)
Add 8 bit signed integer attribute to netlink message.
Definition: attr.c:570
Attribute validation policy.
Definition: attr.h:69
uint8_t nla_get_u8(const struct nlattr *)
Return value of 8 bit integer attribute.
Definition: attr.c:606
Unspecified type, binary data chunk.
Definition: attr.h:40
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:797
uint32_t nla_get_u32(const struct nlattr *)
Return payload of 32 bit integer attribute.
Definition: attr.c:706
Micro seconds (64bit)
Definition: attr.h:47
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:581
int nla_put_s32(struct nl_msg *, int, int32_t)
Add 32 bit signed integer attribute to netlink message.
Definition: attr.c:670
NUL terminated character string.
Definition: attr.h:45
int nla_is_nested(const struct nlattr *)
Return true if attribute has NLA_F_NESTED flag set.
Definition: attr.c:1011
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:924
int nla_put_flag(struct nl_msg *, int)
Add flag netlink attribute to netlink message.
Definition: attr.c:821
int64_t nla_get_s64(const struct nlattr *)
Return payload of s64 attribute.
Definition: attr.c:731
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:534
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:999
int nla_type(const struct nlattr *)
Return type of the attribute.
Definition: attr.c:109
16 bit integer
Definition: attr.h:42
int nla_put_msecs(struct nl_msg *, int, unsigned long)
Add a msecs netlink attribute to a netlink message.
Definition: attr.c:849
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:750
int nla_put_nested(struct nl_msg *, int, const struct nl_msg *)
Add nested attributes to netlink message.
Definition: attr.c:884
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:77
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:860
uint16_t minlen
Minimal length of payload required.
Definition: attr.h:74
64 bit integer
Definition: attr.h:44
int nla_put_s16(struct nl_msg *, int, int16_t)
Add 16 bit signed integer attribute to netlink message.
Definition: attr.c:620
Nested attributes.
Definition: attr.h:48
void nla_nest_cancel(struct nl_msg *, const struct nlattr *)
Cancel the addition of a nested attribute.
Definition: attr.c:973
uint16_t type
Type of attribute or NLA_UNSPEC.
Definition: attr.h:71
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:656
int nla_put_u32(struct nl_msg *, int, uint32_t)
Add 32 bit integer attribute to netlink message.
Definition: attr.c:695
32 bit integer
Definition: attr.h:43
Flag.
Definition: attr.h:46
int nla_put_u8(struct nl_msg *, int, uint8_t)
Add 8 bit integer attribute to netlink message.
Definition: attr.c:595
uint64_t nla_get_u64(const struct nlattr *)
Return payload of u64 attribute.
Definition: attr.c:761
int nla_put_string(struct nl_msg *, int, const char *)
Add string attribute to netlink message.
Definition: attr.c:786
int nla_put(struct nl_msg *, int, int, const void *)
Add a unspecific attribute to netlink message.
Definition: attr.c:500
int nla_put_s64(struct nl_msg *, int, int64_t)
Add 64 bit signed integer attribute to netlink message.
Definition: attr.c:720
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:902
int nla_validate(const struct nlattr *, int, int, const struct nla_policy *)
Validate a stream of attributes.
Definition: attr.c:294