libnl  1.1
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-2006 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 Validation Policy Types
28  * @{
29  */
30 
31  /**
32  * @ingroup attr
33  * Standard attribute types to specify validation policy
34  */
35 enum {
36  NLA_UNSPEC, /**< Unspecified type */
37  NLA_U8, /**< 8bit integer */
38  NLA_U16, /**< 16bit integer */
39  NLA_U32, /**< 32bit integer */
40  NLA_U64, /**< 64bit integer */
41  NLA_STRING, /**< character string */
42  NLA_FLAG, /**< flag */
43  NLA_MSECS, /**< micro seconds (64bit) */
44  NLA_NESTED, /**< nested attributes */
45  __NLA_TYPE_MAX,
46 };
47 
48 /**
49  * @ingroup attr
50  * Maximum netlink validation policy type
51  */
52 #define NLA_TYPE_MAX (__NLA_TYPE_MAX - 1)
53 
54 /** @} */
55 
56 /**
57  * @ingroup attr
58  * attribute validation policy
59  *
60  * Policies are defined as arrays of this struct, the array must
61  * be accessible by attribute type up to the highest identifier
62  * to be expected.
63  *
64  * Example:
65  * @code
66  * static struct nla_policy my_policy[ATTR_MAX+1] __read_mostly = {
67  * [ATTR_FOO] = { .type = NLA_U16 },
68  * [ATTR_BAR] = { .type = NLA_STRING },
69  * [ATTR_BAZ] = { .minlen = sizeof(struct mystruct) },
70  * };
71  * @endcode
72  */
73 struct nla_policy {
74  /** Type of attribute or NLA_UNSPEC */
75  uint16_t type;
76 
77  /** Minimal length of payload required to be available */
78  uint16_t minlen;
79 
80  /** Maximal length of payload required to be available */
81  uint16_t maxlen;
82 };
83 
84 /* size calculations */
85 extern int nla_attr_size(int payload);
86 extern int nla_total_size(int payload);
87 extern int nla_padlen(int payload);
88 
89 /* payload access */
90 extern int nla_type(const struct nlattr *);
91 extern void * nla_data(const struct nlattr *);
92 extern int nla_len(const struct nlattr *);
93 
94 /* attribute parsing */
95 extern int nla_ok(const struct nlattr *, int);
96 extern struct nlattr * nla_next(const struct nlattr *, int *);
97 extern int nla_parse(struct nlattr **, int, struct nlattr *,
98  int, struct nla_policy *);
99 extern int nla_parse_nested(struct nlattr **, int, struct nlattr *,
100  struct nla_policy *);
101 extern int nla_validate(struct nlattr *, int, int,
102  struct nla_policy *);
103 extern struct nlattr * nla_find(struct nlattr *, int, int);
104 
105 /* utilities */
106 extern int nla_memcpy(void *, struct nlattr *, int);
107 extern size_t nla_strlcpy(char *, const struct nlattr *, size_t);
108 extern int nla_memcmp(const struct nlattr *, const void *, size_t);
109 extern int nla_strcmp(const struct nlattr *, const char *);
110 
111 /* attribute construction */
112 extern struct nlattr * nla_reserve(struct nl_msg *, int, int);
113 extern int nla_put(struct nl_msg *, int, int, const void *);
114 extern int nla_put_nested(struct nl_msg *, int, struct nl_msg *);
115 extern int nla_put_u8(struct nl_msg *, int, uint8_t);
116 extern int nla_put_u16(struct nl_msg *, int, uint16_t);
117 extern int nla_put_u32(struct nl_msg *, int, uint32_t);
118 extern int nla_put_u64(struct nl_msg *, int, uint64_t);
119 extern int nla_put_string(struct nl_msg *, int, const char *);
120 extern int nla_put_flag(struct nl_msg *, int);
121 extern int nla_put_msecs(struct nl_msg *, int, unsigned long);
122 extern int nla_put_data(struct nl_msg *, int, struct nl_data *);
123 extern int nla_put_addr(struct nl_msg *, int, struct nl_addr *);
124 
125 /* attribute nesting */
126 extern struct nlattr * nla_nest_start(struct nl_msg *, int);
127 extern int nla_nest_end(struct nl_msg *, struct nlattr *);
128 
129 /* attribute reading */
130 extern uint8_t nla_get_u8(struct nlattr *);
131 extern uint16_t nla_get_u16(struct nlattr *);
132 extern uint32_t nla_get_u32(struct nlattr *);
133 extern uint64_t nla_get_u64(struct nlattr *);
134 extern char * nla_get_string(struct nlattr *);
135 extern int nla_get_flag(struct nlattr *);
136 extern unsigned long nla_get_msecs(struct nlattr *);
137 extern struct nl_data * nla_get_data(struct nlattr *);
138 extern struct nl_addr * nla_get_addr(struct nlattr *, int);
139 
140 /**
141  * @name Attribute Construction (Exception Based)
142  *
143  * All these functions jump to nla_put_failure in case of a failure
144  * instead of returning an error code.
145  *
146  * @{
147  */
148 
149 /**
150  * @ingroup attr
151  * Add a netlink attribute to a netlink message
152  * @arg n netlink message
153  * @arg attrtype attribute type
154  * @arg attrlen length of attribute payload
155  * @arg data head of attribute payload
156  */
157 #define NLA_PUT(n, attrtype, attrlen, data) \
158  do { \
159  if (nla_put(n, attrtype, attrlen, data) < 0) \
160  goto nla_put_failure; \
161  } while(0)
162 
163 /**
164  * @ingroup attr
165  * Add a basic netlink attribute to a netlink message
166  * @arg n netlink message
167  * @arg type atomic type
168  * @arg attrtype attribute type
169  * @arg value head of attribute payload
170  */
171 #define NLA_PUT_TYPE(n, type, attrtype, value) \
172  do { \
173  type __tmp = value; \
174  NLA_PUT(n, attrtype, sizeof(type), &__tmp); \
175  } while(0)
176 
177 /**
178  * Add a u8 netlink attribute to a netlink message
179  * @arg n netlink message
180  * @arg attrtype attribute type
181  * @arg value numeric value
182  */
183 #define NLA_PUT_U8(n, attrtype, value) \
184  NLA_PUT_TYPE(n, uint8_t, attrtype, value)
185 
186 /**
187  * Add a u16 netlink attribute to a netlink message
188  * @arg n netlink message
189  * @arg attrtype attribute type
190  * @arg value numeric value
191  */
192 #define NLA_PUT_U16(n, attrtype, value) \
193  NLA_PUT_TYPE(n, uint16_t, attrtype, value)
194 
195 /**
196  * Add a u32 netlink attribute to a netlink message
197  * @arg n netlink message
198  * @arg attrtype attribute type
199  * @arg value numeric value
200  */
201 #define NLA_PUT_U32(n, attrtype, value) \
202  NLA_PUT_TYPE(n, uint32_t, attrtype, value)
203 
204 /**
205  * Add a u64 netlink attribute to a netlink message
206  * @arg n netlink message
207  * @arg attrtype attribute type
208  * @arg value numeric value
209  */
210 #define NLA_PUT_U64(n, attrtype, value) \
211  NLA_PUT_TYPE(n, uint64_t, attrtype, value)
212 
213 /**
214  * Add a character string netlink attribute to a netlink message
215  * @arg n netlink message
216  * @arg attrtype attribute type
217  * @arg value character string
218  */
219 #define NLA_PUT_STRING(n, attrtype, value) \
220  NLA_PUT(n, attrtype, strlen(value) + 1, value)
221 
222 /**
223  * Add a flag netlink attribute to a netlink message
224  * @arg n netlink message
225  * @arg attrtype attribute type
226  */
227 #define NLA_PUT_FLAG(n, attrtype) \
228  NLA_PUT(n, attrtype, 0, NULL)
229 
230 /**
231  * Add a msecs netlink attribute to a netlink message
232  * @arg n netlink message
233  * @arg attrtype attribute type
234  * @arg msecs numeric value in micro seconds
235  */
236 #define NLA_PUT_MSECS(n, attrtype, msecs) \
237  NLA_PUT_U64(n, attrtype, msecs)
238 
239 /**
240  * Add a address attribute to a netlink message
241  * @arg n netlink message
242  * @arg attrtype attribute type
243  * @arg addr abstract address object
244  */
245 #define NLA_PUT_ADDR(n, attrtype, addr) \
246  NLA_PUT(n, attrtype, nl_addr_get_len(addr), \
247  nl_addr_get_binary_addr(addr))
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