libnl  3.2.26
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_TYPE_MAX,
48 };
49 
50 #define NLA_TYPE_MAX (__NLA_TYPE_MAX - 1)
51 
52 /** @} */
53 
54 /**
55  * @ingroup attr
56  * Attribute validation policy.
57  *
58  * See section @core_doc{core_attr_parse,Attribute Parsing} for more details.
59  */
60 struct nla_policy {
61  /** Type of attribute or NLA_UNSPEC */
62  uint16_t type;
63 
64  /** Minimal length of payload required */
65  uint16_t minlen;
66 
67  /** Maximal length of payload allowed */
68  uint16_t maxlen;
69 };
70 
71 /* Size calculations */
72 extern int nla_attr_size(int payload);
73 extern int nla_total_size(int payload);
74 extern int nla_padlen(int payload);
75 
76 /* Attribute parsing */
77 extern int nla_type(const struct nlattr *);
78 extern void * nla_data(const struct nlattr *);
79 extern int nla_len(const struct nlattr *);
80 extern int nla_ok(const struct nlattr *, int);
81 extern struct nlattr * nla_next(const struct nlattr *, int *);
82 extern int nla_parse(struct nlattr **, int, struct nlattr *,
83  int, struct nla_policy *);
84 extern int nla_validate(const struct nlattr *, int, int,
85  const struct nla_policy *);
86 extern struct nlattr * nla_find(const struct nlattr *, int, int);
87 
88 /* Helper Functions */
89 extern int nla_memcpy(void *, const struct nlattr *, int);
90 extern size_t nla_strlcpy(char *, const struct nlattr *, size_t);
91 extern int nla_memcmp(const struct nlattr *, const void *, size_t);
92 extern int nla_strcmp(const struct nlattr *, const char *);
93 
94 /* Unspecific attribute */
95 extern struct nlattr * nla_reserve(struct nl_msg *, int, int);
96 extern int nla_put(struct nl_msg *, int, int, const void *);
97 extern int nla_put_data(struct nl_msg *, int,
98  const struct nl_data *);
99 extern int nla_put_addr(struct nl_msg *, int, struct nl_addr *);
100 
101 /* Integer attribute */
102 extern uint8_t nla_get_u8(const struct nlattr *);
103 extern int nla_put_u8(struct nl_msg *, int, uint8_t);
104 extern uint16_t nla_get_u16(const struct nlattr *);
105 extern int nla_put_u16(struct nl_msg *, int, uint16_t);
106 extern uint32_t nla_get_u32(const struct nlattr *);
107 extern int nla_put_u32(struct nl_msg *, int, uint32_t);
108 extern uint64_t nla_get_u64(const struct nlattr *);
109 extern int nla_put_u64(struct nl_msg *, int, uint64_t);
110 
111 /* String attribute */
112 extern char * nla_get_string(const struct nlattr *);
113 extern char * nla_strdup(const struct nlattr *);
114 extern int nla_put_string(struct nl_msg *, int, const char *);
115 
116 /* Flag attribute */
117 extern int nla_get_flag(const struct nlattr *);
118 extern int nla_put_flag(struct nl_msg *, int);
119 
120 /* Msec attribute */
121 extern unsigned long nla_get_msecs(const struct nlattr *);
122 extern int nla_put_msecs(struct nl_msg *, int, unsigned long);
123 
124 /* Attribute nesting */
125 extern int nla_put_nested(struct nl_msg *, int,
126  const struct nl_msg *);
127 extern struct nlattr * nla_nest_start(struct nl_msg *, int);
128 extern int nla_nest_end(struct nl_msg *, struct nlattr *);
129 extern void nla_nest_cancel(struct nl_msg *, const struct nlattr *);
130 extern int nla_parse_nested(struct nlattr **, int, struct nlattr *,
131  struct nla_policy *);
132 extern int nla_is_nested(const struct nlattr *);
133 
134 /**
135  * @name Attribute Construction (Exception Based)
136  * @{
137  */
138 
139 /**
140  * @ingroup attr
141  * Add unspecific attribute to netlink message.
142  * @arg msg Netlink message.
143  * @arg attrtype Attribute type.
144  * @arg attrlen Length of attribute payload.
145  * @arg data Head of attribute payload.
146  */
147 #define NLA_PUT(msg, attrtype, attrlen, data) \
148  do { \
149  if (nla_put(msg, attrtype, attrlen, data) < 0) \
150  goto nla_put_failure; \
151  } while(0)
152 
153 /**
154  * @ingroup attr
155  * Add atomic type attribute to netlink message.
156  * @arg msg Netlink message.
157  * @arg type Atomic type.
158  * @arg attrtype Attribute type.
159  * @arg value Head of attribute payload.
160  */
161 #define NLA_PUT_TYPE(msg, type, attrtype, value) \
162  do { \
163  type __tmp = value; \
164  NLA_PUT(msg, attrtype, sizeof(type), &__tmp); \
165  } while(0)
166 
167 /**
168  * Add 8 bit integer attribute to netlink message.
169  * @arg msg Netlink message.
170  * @arg attrtype Attribute type.
171  * @arg value Numeric value.
172  */
173 #define NLA_PUT_U8(msg, attrtype, value) \
174  NLA_PUT_TYPE(msg, uint8_t, attrtype, value)
175 
176 /**
177  * Add 16 bit integer attribute to netlink message.
178  * @arg msg Netlink message.
179  * @arg attrtype Attribute type.
180  * @arg value Numeric value.
181  */
182 #define NLA_PUT_U16(msg, attrtype, value) \
183  NLA_PUT_TYPE(msg, uint16_t, attrtype, value)
184 
185 /**
186  * Add 32 bit 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_U32(msg, attrtype, value) \
192  NLA_PUT_TYPE(msg, uint32_t, attrtype, value)
193 
194 /**
195  * Add 64 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_U64(msg, attrtype, value) \
201  NLA_PUT_TYPE(msg, uint64_t, attrtype, value)
202 
203 /**
204  * Add string attribute to netlink message.
205  * @arg msg Netlink message.
206  * @arg attrtype Attribute type.
207  * @arg value NUL terminated character string.
208  */
209 #define NLA_PUT_STRING(msg, attrtype, value) \
210  NLA_PUT(msg, attrtype, (int) strlen(value) + 1, value)
211 
212 /**
213  * Add flag attribute to netlink message.
214  * @arg msg Netlink message.
215  * @arg attrtype Attribute type.
216  */
217 #define NLA_PUT_FLAG(msg, attrtype) \
218  NLA_PUT(msg, attrtype, 0, NULL)
219 
220 /**
221  * Add msecs attribute to netlink message.
222  * @arg msg Netlink message.
223  * @arg attrtype Attribute type.
224  * @arg msecs Numeric value in micro seconds.
225  */
226 #define NLA_PUT_MSECS(msg, attrtype, msecs) \
227  NLA_PUT_U64(msg, attrtype, msecs)
228 
229 /**
230  * Add address attribute to netlink message.
231  * @arg msg Netlink message.
232  * @arg attrtype Attribute type.
233  * @arg addr Abstract address object.
234  */
235 #define NLA_PUT_ADDR(msg, attrtype, addr) \
236  NLA_PUT(msg, attrtype, nl_addr_get_len(addr), \
237  nl_addr_get_binary_addr(addr))
238 
239 /**
240  * Add abstract data attribute to netlink message.
241  * @arg msg Netlink message.
242  * @arg attrtype Attribute type.
243  * @arg data Abstract data object.
244  */
245 #define NLA_PUT_DATA(msg, attrtype, data) \
246  NLA_PUT(msg, attrtype, nl_data_get_size(data), \
247  nl_data_get(data))
248 
249 /** @} */
250 
251 /**
252  * @name Iterators
253  * @{
254  */
255 
256 /**
257  * @ingroup attr
258  * Iterate over a stream of attributes
259  * @arg pos loop counter, set to current attribute
260  * @arg head head of attribute stream
261  * @arg len length of attribute stream
262  * @arg rem initialized to len, holds bytes currently remaining in stream
263  */
264 #define nla_for_each_attr(pos, head, len, rem) \
265  for (pos = head, rem = len; \
266  nla_ok(pos, rem); \
267  pos = nla_next(pos, &(rem)))
268 
269 /**
270  * @ingroup attr
271  * Iterate over a stream of nested attributes
272  * @arg pos loop counter, set to current attribute
273  * @arg nla attribute containing the nested attributes
274  * @arg rem initialized to len, holds bytes currently remaining in stream
275  */
276 #define nla_for_each_nested(pos, nla, rem) \
277  for (pos = nla_data(nla), rem = nla_len(nla); \
278  nla_ok(pos, rem); \
279  pos = nla_next(pos, &(rem)))
280 
281 /** @} */
282 
283 #ifdef __cplusplus
284 }
285 #endif
286 
287 #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
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:588
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:720
int nla_put_addr(struct nl_msg *, int, struct nl_addr *)
Add abstract address as unspecific attribute to netlink message.
Definition: attr.c:542
Attribute validation policy.
Definition: attr.h:60
uint8_t nla_get_u8(const struct nlattr *)
Return value of 8 bit integer attribute.
Definition: attr.c:574
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:685
uint32_t nla_get_u32(const struct nlattr *)
Return payload of 32 bit integer attribute.
Definition: attr.c:624
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
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:898
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:812
int nla_put_flag(struct nl_msg *, int)
Add flag netlink attribute to netlink message.
Definition: attr.c:709
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:886
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:737
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:638
int nla_put_nested(struct nl_msg *, int, const struct nl_msg *)
Add nested attributes to netlink message.
Definition: attr.c:772
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:68
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:748
uint16_t minlen
Minimal length of payload required.
Definition: attr.h:65
64 bit integer
Definition: attr.h:42
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:860
uint16_t type
Type of attribute or NLA_UNSPEC.
Definition: attr.h:62
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:599
int nla_put_u32(struct nl_msg *, int, uint32_t)
Add 32 bit integer attribute to netlink message.
Definition: attr.c:613
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:563
uint64_t nla_get_u64(const struct nlattr *)
Return payload of u64 attribute.
Definition: attr.c:649
int nla_put_string(struct nl_msg *, int, const char *)
Add string attribute to netlink message.
Definition: attr.c:674
int nla_put(struct nl_msg *, int, int, const void *)
Add a unspecific attribute to netlink message.
Definition: attr.c:497
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:790
int nla_validate(const struct nlattr *, int, int, const struct nla_policy *)
Validate a stream of attributes.
Definition: attr.c:294