libnl  3.2.27-rc1
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 int32_t nla_get_s32(const struct nlattr *);
107 extern int nla_put_s32(struct nl_msg *, int, int32_t);
108 extern uint32_t nla_get_u32(const struct nlattr *);
109 extern int nla_put_u32(struct nl_msg *, int, uint32_t);
110 extern uint64_t nla_get_u64(const struct nlattr *);
111 extern int nla_put_u64(struct nl_msg *, int, uint64_t);
112 
113 /* String attribute */
114 extern char * nla_get_string(const struct nlattr *);
115 extern char * nla_strdup(const struct nlattr *);
116 extern int nla_put_string(struct nl_msg *, int, const char *);
117 
118 /* Flag attribute */
119 extern int nla_get_flag(const struct nlattr *);
120 extern int nla_put_flag(struct nl_msg *, int);
121 
122 /* Msec attribute */
123 extern unsigned long nla_get_msecs(const struct nlattr *);
124 extern int nla_put_msecs(struct nl_msg *, int, unsigned long);
125 
126 /* Attribute nesting */
127 extern int nla_put_nested(struct nl_msg *, int,
128  const struct nl_msg *);
129 extern struct nlattr * nla_nest_start(struct nl_msg *, int);
130 extern int nla_nest_end(struct nl_msg *, struct nlattr *);
131 extern void nla_nest_cancel(struct nl_msg *, const struct nlattr *);
132 extern int nla_parse_nested(struct nlattr **, int, struct nlattr *,
133  struct nla_policy *);
134 extern int nla_is_nested(const struct nlattr *);
135 
136 /**
137  * @name Attribute Construction (Exception Based)
138  * @{
139  */
140 
141 /**
142  * @ingroup attr
143  * Add unspecific attribute to netlink message.
144  * @arg msg Netlink message.
145  * @arg attrtype Attribute type.
146  * @arg attrlen Length of attribute payload.
147  * @arg data Head of attribute payload.
148  */
149 #define NLA_PUT(msg, attrtype, attrlen, data) \
150  do { \
151  if (nla_put(msg, attrtype, attrlen, data) < 0) \
152  goto nla_put_failure; \
153  } while(0)
154 
155 /**
156  * @ingroup attr
157  * Add atomic type attribute to netlink message.
158  * @arg msg Netlink message.
159  * @arg type Atomic type.
160  * @arg attrtype Attribute type.
161  * @arg value Head of attribute payload.
162  */
163 #define NLA_PUT_TYPE(msg, type, attrtype, value) \
164  do { \
165  type __tmp = value; \
166  NLA_PUT(msg, attrtype, sizeof(type), &__tmp); \
167  } while(0)
168 
169 /**
170  * Add 8 bit integer attribute to netlink message.
171  * @arg msg Netlink message.
172  * @arg attrtype Attribute type.
173  * @arg value Numeric value.
174  */
175 #define NLA_PUT_U8(msg, attrtype, value) \
176  NLA_PUT_TYPE(msg, uint8_t, attrtype, value)
177 
178 /**
179  * Add 16 bit integer attribute to netlink message.
180  * @arg msg Netlink message.
181  * @arg attrtype Attribute type.
182  * @arg value Numeric value.
183  */
184 #define NLA_PUT_U16(msg, attrtype, value) \
185  NLA_PUT_TYPE(msg, uint16_t, attrtype, value)
186 
187 /**
188  * Add 32 bit integer attribute to netlink message.
189  * @arg msg Netlink message.
190  * @arg attrtype Attribute type.
191  * @arg value Numeric value.
192  */
193 #define NLA_PUT_S32(msg, attrtype, value) \
194  NLA_PUT_TYPE(msg, int32_t, attrtype, value)
195 
196 /**
197  * Add 32 bit integer attribute to netlink message.
198  * @arg msg Netlink message.
199  * @arg attrtype Attribute type.
200  * @arg value Numeric value.
201  */
202 #define NLA_PUT_U32(msg, attrtype, value) \
203  NLA_PUT_TYPE(msg, uint32_t, attrtype, value)
204 
205 /**
206  * Add 64 bit integer attribute to netlink message.
207  * @arg msg Netlink message.
208  * @arg attrtype Attribute type.
209  * @arg value Numeric value.
210  */
211 #define NLA_PUT_U64(msg, attrtype, value) \
212  NLA_PUT_TYPE(msg, uint64_t, attrtype, value)
213 
214 /**
215  * Add string attribute to netlink message.
216  * @arg msg Netlink message.
217  * @arg attrtype Attribute type.
218  * @arg value NUL terminated character string.
219  */
220 #define NLA_PUT_STRING(msg, attrtype, value) \
221  NLA_PUT(msg, attrtype, (int) strlen(value) + 1, value)
222 
223 /**
224  * Add flag attribute to netlink message.
225  * @arg msg Netlink message.
226  * @arg attrtype Attribute type.
227  */
228 #define NLA_PUT_FLAG(msg, attrtype) \
229  NLA_PUT(msg, attrtype, 0, NULL)
230 
231 /**
232  * Add msecs attribute to netlink message.
233  * @arg msg Netlink message.
234  * @arg attrtype Attribute type.
235  * @arg msecs Numeric value in micro seconds.
236  */
237 #define NLA_PUT_MSECS(msg, attrtype, msecs) \
238  NLA_PUT_U64(msg, attrtype, msecs)
239 
240 /**
241  * Add address attribute to netlink message.
242  * @arg msg Netlink message.
243  * @arg attrtype Attribute type.
244  * @arg addr Abstract address object.
245  */
246 #define NLA_PUT_ADDR(msg, attrtype, addr) \
247  NLA_PUT(msg, attrtype, nl_addr_get_len(addr), \
248  nl_addr_get_binary_addr(addr))
249 
250 /**
251  * Add abstract data attribute to netlink message.
252  * @arg msg Netlink message.
253  * @arg attrtype Attribute type.
254  * @arg data Abstract data object.
255  */
256 #define NLA_PUT_DATA(msg, attrtype, data) \
257  NLA_PUT(msg, attrtype, nl_data_get_size(data), \
258  nl_data_get(data))
259 
260 /** @} */
261 
262 /**
263  * @name Iterators
264  * @{
265  */
266 
267 /**
268  * @ingroup attr
269  * Iterate over a stream of attributes
270  * @arg pos loop counter, set to current attribute
271  * @arg head head of attribute stream
272  * @arg len length of attribute stream
273  * @arg rem initialized to len, holds bytes currently remaining in stream
274  */
275 #define nla_for_each_attr(pos, head, len, rem) \
276  for (pos = head, rem = len; \
277  nla_ok(pos, rem); \
278  pos = nla_next(pos, &(rem)))
279 
280 /**
281  * @ingroup attr
282  * Iterate over a stream of nested attributes
283  * @arg pos loop counter, set to current attribute
284  * @arg nla attribute containing the nested attributes
285  * @arg rem initialized to len, holds bytes currently remaining in stream
286  */
287 #define nla_for_each_nested(pos, nla, rem) \
288  for (pos = nla_data(nla), rem = nla_len(nla); \
289  nla_ok(pos, rem); \
290  pos = nla_next(pos, &(rem)))
291 
292 /** @} */
293 
294 #ifdef __cplusplus
295 }
296 #endif
297 
298 #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 integer attribute.
Definition: attr.c:624
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:745
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:710
uint32_t nla_get_u32(const struct nlattr *)
Return payload of 32 bit integer attribute.
Definition: attr.c:649
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
int nla_put_s32(struct nl_msg *, int, int32_t)
Add 32 bit integer attribute to netlink message.
Definition: attr.c:613
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:923
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:837
int nla_put_flag(struct nl_msg *, int)
Add flag netlink attribute to netlink message.
Definition: attr.c:734
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:911
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:762
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:663
int nla_put_nested(struct nl_msg *, int, const struct nl_msg *)
Add nested attributes to netlink message.
Definition: attr.c:797
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:773
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:885
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:638
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:674
int nla_put_string(struct nl_msg *, int, const char *)
Add string attribute to netlink message.
Definition: attr.c:699
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:815
int nla_validate(const struct nlattr *, int, int, const struct nla_policy *)
Validate a stream of attributes.
Definition: attr.c:294