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