libnl 3.5.0

utils.h
1 /*
2 * netlink/utils.h Utility Functions
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-2012 Thomas Graf <tgraf@suug.ch>
10 */
11
12 #ifndef NETLINK_UTILS_H_
13 #define NETLINK_UTILS_H_
14
15 #include <netlink/netlink.h>
16 #include <netlink/list.h>
17
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21
22 /**
23 * @name Probability Constants
24 * @{
25 */
26
27 /**
28 * Lower probability limit
29 * @ingroup utils
30 */
31 #define NL_PROB_MIN 0x0
32
33 /**
34 * Upper probability limit nl_dump_type
35 * @ingroup utils
36 */
37 #define NL_PROB_MAX 0xffffffff
38
39 /** @} */
40
41 enum {
42 NL_BYTE_RATE,
43 NL_BIT_RATE,
44 };
45
46 /* unit pretty-printing */
47 extern double nl_cancel_down_bytes(unsigned long long, char **);
48 extern double nl_cancel_down_bits(unsigned long long, char **);
49 extern int nl_rate2str(unsigned long long, int, char *, size_t);
50 extern double nl_cancel_down_us(uint32_t, char **);
51
52 /* generic unit translations */
53 extern long nl_size2int(const char *);
54 extern char * nl_size2str(const size_t, char *, const size_t);
55 extern long nl_prob2int(const char *);
56
57 /* time translations */
58 extern int nl_get_user_hz(void);
59 extern int nl_get_psched_hz(void);
60 extern uint32_t nl_us2ticks(uint32_t);
61 extern uint32_t nl_ticks2us(uint32_t);
62 extern int nl_str2msec(const char *, uint64_t *);
63 extern char * nl_msec2str(uint64_t, char *, size_t);
64
65 /* link layer protocol translations */
66 extern char * nl_llproto2str(int, char *, size_t);
67 extern int nl_str2llproto(const char *);
68
69 /* ethernet protocol translations */
70 extern char * nl_ether_proto2str(int, char *, size_t);
71 extern int nl_str2ether_proto(const char *);
72
73 /* IP protocol translations */
74 extern char * nl_ip_proto2str(int, char *, size_t);
75 extern int nl_str2ip_proto(const char *);
76
77 /* Dumping helpers */
78 extern void nl_new_line(struct nl_dump_params *);
79 extern void nl_dump(struct nl_dump_params *, const char *, ...);
80 extern void nl_dump_line(struct nl_dump_params *, const char *, ...);
81
82 enum {
83 NL_CAPABILITY_NONE,
84
85 /**
86 * rtnl_route_build_msg() no longer guesses the route scope
87 * if explicitly set to RT_SCOPE_NOWHERE.
88 * @ingroup utils
89 */
90 NL_CAPABILITY_ROUTE_BUILD_MSG_SET_SCOPE = 1,
91 #define NL_CAPABILITY_ROUTE_BUILD_MSG_SET_SCOPE NL_CAPABILITY_ROUTE_BUILD_MSG_SET_SCOPE
92
93 /**
94 * rtnl_link_veth_get_peer() now returns a reference that is owned by the
95 * caller and must be released by the caller with rtnl_link_put().
96 */
97 NL_CAPABILITY_ROUTE_LINK_VETH_GET_PEER_OWN_REFERENCE = 2,
98 #define NL_CAPABILITY_ROUTE_LINK_VETH_GET_PEER_OWN_REFERENCE NL_CAPABILITY_ROUTE_LINK_VETH_GET_PEER_OWN_REFERENCE
99
100 /**
101 * rtnl_u32_add_action() and rtnl_basic_add_action() now grab a reference to act
102 * caller are free to release its own
103 */
104 NL_CAPABILITY_ROUTE_LINK_CLS_ADD_ACT_OWN_REFERENCE = 3,
105 #define NL_CAPABILITY_ROUTE_LINK_CLS_ADD_ACT_OWN_REFERENCE NL_CAPABILITY_ROUTE_LINK_CLS_ADD_ACT_OWN_REFERENCE
106
107 /**
108 * Indicate that the local port is unspecified until the user accesses
109 * it (via nl_socket_get_local_port()) or until nl_connect(). More importantly,
110 * if the port is left unspecified, nl_connect() will retry generating another
111 * port when bind() fails with ADDRINUSE.
112 */
113 NL_CAPABILITY_NL_CONNECT_RETRY_GENERATE_PORT_ON_ADDRINUSE = 4,
114 #define NL_CAPABILITY_NL_CONNECT_RETRY_GENERATE_PORT_ON_ADDRINUSE NL_CAPABILITY_NL_CONNECT_RETRY_GENERATE_PORT_ON_ADDRINUSE
115
116 /**
117 * Indicate that rtnl_link_get_kernel() fails with -NLE_OPNOTSUPP in case
118 * of older kernals not supporting lookup by ifname. This changes behavior
119 * from returning -NLE_INVAL to return -NLE_OPNOTSUPP.
120 */
121 NL_CAPABILITY_ROUTE_LINK_GET_KERNEL_FAIL_OPNOTSUPP = 5,
122 #define NL_CAPABILITY_ROUTE_LINK_GET_KERNEL_FAIL_OPNOTSUPP NL_CAPABILITY_ROUTE_LINK_GET_KERNEL_FAIL_OPNOTSUPP
123
124 /**
125 * Also consider the a_cacheinfo field (ADDR_ATTR_CACHEINFO) that contains the
126 * address timestamps and expiry when comparing struct rtnl_addr objects with
127 * nl_object_diff().
128 */
129 NL_CAPABILITY_ROUTE_ADDR_COMPARE_CACHEINFO = 6,
130 #define NL_CAPABILITY_ROUTE_ADDR_COMPARE_CACHEINFO NL_CAPABILITY_ROUTE_ADDR_COMPARE_CACHEINFO
131
132 /**
133 * The library version is libnl3 3.2.26 or newer. This capability should never be backported.
134 */
135 NL_CAPABILITY_VERSION_3_2_26 = 7,
136 #define NL_CAPABILITY_VERSION_3_2_26 NL_CAPABILITY_VERSION_3_2_26
137
138 /**
139 * nl_recv() fails with NLE_MSG_TRUNC if a message got truncated
140 * with NL_MSG_PEEK disabled. Previously, the failed message was wrongly
141 * discarded and the next message received.
142 */
143 NL_CAPABILITY_NL_RECV_FAIL_TRUNC_NO_PEEK = 8,
144 #define NL_CAPABILITY_NL_RECV_FAIL_TRUNC_NO_PEEK NL_CAPABILITY_NL_RECV_FAIL_TRUNC_NO_PEEK
145
146 /**
147 * rtnl_link_build_change_request() and rtnl_link_change() would set ifi.ifi_flags but leave
148 * ifi.ifi_change at zero. This was later fixed to set ifi.ifi_change to the flags that are actually
149 * set in changes.
150 */
151 NL_CAPABILITY_LINK_BUILD_CHANGE_REQUEST_SET_CHANGE = 9,
152 #define NL_CAPABILITY_LINK_BUILD_CHANGE_REQUEST_SET_CHANGE NL_CAPABILITY_LINK_BUILD_CHANGE_REQUEST_SET_CHANGE
153
154 /**
155 * Between 3.2.14 (64fcb47a36ec12d7e7f00605f6a8952ce985dd08) and 3.2.22 (8571f58f23763d8db7365d02c9b27832ad3d7005),
156 * rtnl_neigh_get() behaved differently and only returned objects with family AF_UNSPEC.
157 * This capability indicates, that the function was fixed. The absense of the capability,
158 * doesn't indicate however which behavior the function will have. So beware. */
159 NL_CAPABILITY_RTNL_NEIGH_GET_FILTER_AF_UNSPEC_FIX = 10,
160 #define NL_CAPABILITY_RTNL_NEIGH_GET_FILTER_AF_UNSPEC_FIX NL_CAPABILITY_RTNL_NEIGH_GET_FILTER_AF_UNSPEC_FIX
161
162 /**
163 * The library version is libnl3 3.2.27 or newer. This capability should never be backported.
164 */
165 NL_CAPABILITY_VERSION_3_2_27 = 11,
166 #define NL_CAPABILITY_VERSION_3_2_27 NL_CAPABILITY_VERSION_3_2_27
167
168 /**
169 * Properly serialize vlan protocol IFLA_VLAN_PROTOCOL.
170 */
171 NL_CAPABILITY_RTNL_LINK_VLAN_PROTOCOL_SERIALZE = 12,
172 #define NL_CAPABILITY_RTNL_LINK_VLAN_PROTOCOL_SERIALZE NL_CAPABILITY_RTNL_LINK_VLAN_PROTOCOL_SERIALZE
173
174 /**
175 * Properly read gre REMOTE port.
176 */
177 NL_CAPABILITY_RTNL_LINK_PARSE_GRE_REMOTE = 13,
178 #define NL_CAPABILITY_RTNL_LINK_PARSE_GRE_REMOTE NL_CAPABILITY_RTNL_LINK_PARSE_GRE_REMOTE
179
180 /**
181 * Don't skip over vlan ingress-map entries with "to" field zero when serializing
182 * a netlink message. Previously such entires would be ignored which inhibits the
183 * user from clearing ingress map entries.
184 */
185 NL_CAPABILITY_RTNL_LINK_VLAN_INGRESS_MAP_CLEAR = 14,
186 #define NL_CAPABILITY_RTNL_LINK_VLAN_INGRESS_MAP_CLEAR NL_CAPABILITY_RTNL_LINK_VLAN_INGRESS_MAP_CLEAR
187
188 /**
189 * Consider vxlan link info for nl_object_diff().
190 */
191 NL_CAPABILITY_RTNL_LINK_VXLAN_IO_COMPARE = 15,
192 #define NL_CAPABILITY_RTNL_LINK_VXLAN_IO_COMPARE NL_CAPABILITY_RTNL_LINK_VXLAN_IO_COMPARE
193
194 /**
195 * Support 64 bit attributes for nl_object_diff().
196 */
197 NL_CAPABILITY_NL_OBJECT_DIFF64 = 16,
198 #define NL_CAPABILITY_NL_OBJECT_DIFF64 NL_CAPABILITY_NL_OBJECT_DIFF64
199
200 /**
201 * Support omitting @key argument to xfrmnl_sa_get_*_params() to check
202 * for required buffer size for key.
203 */
204 NL_CAPABILITY_XFRM_SA_KEY_SIZE = 17,
205 #define NL_CAPABILITY_XFRM_SA_KEY_SIZE NL_CAPABILITY_XFRM_SA_KEY_SIZE
206
207 /**
208 * Properly handle nl_object_identity() for AF_INET and AF_INET6 addresses
209 * and properly handle the peer/IFA_ADDRESS for IPv4 addresses.
210 */
211 NL_CAPABILITY_RTNL_ADDR_PEER_FIX = 18,
212 #define NL_CAPABILITY_RTNL_ADDR_PEER_FIX NL_CAPABILITY_RTNL_ADDR_PEER_FIX
213
214 /**
215 * The library version is libnl3 3.2.28 or newer. This capability should never be backported.
216 */
217 NL_CAPABILITY_VERSION_3_2_28 = 19,
218 #define NL_CAPABILITY_VERSION_3_2_28 NL_CAPABILITY_VERSION_3_2_28
219
220 /**
221 * After NL_CAPABILITY_RTNL_ADDR_PEER_FIX, a follow up regression to lookup
222 * IPv4 addresses in the cache was fixed (PR#105).
223 */
224 NL_CAPABILITY_RTNL_ADDR_PEER_ID_FIX = 20,
225 #define NL_CAPABILITY_RTNL_ADDR_PEER_ID_FIX NL_CAPABILITY_RTNL_ADDR_PEER_ID_FIX
226
227 /**
228 * nl_addr_fill_sockaddr() properly checks that the provided address to
229 * avoid read-out-of-bounds for invalid addresses.
230 */
231 NL_CAPABILITY_NL_ADDR_FILL_SOCKADDR = 21,
232 #define NL_CAPABILITY_NL_ADDR_FILL_SOCKADDR NL_CAPABILITY_NL_ADDR_FILL_SOCKADDR
233
234 /**
235 * Support omitting @ctx_str argument to xfrmnl_sa_get_sec_ctx() to check
236 * for required buffer size for context string.
237 */
238 NL_CAPABILITY_XFRM_SEC_CTX_LEN = 22,
239 #define NL_CAPABILITY_XFRM_SEC_CTX_LEN NL_CAPABILITY_XFRM_SEC_CTX_LEN
240
241 /**
242 * rtnl_link_build_add_request() would set ifi.ifi_flags but leave ifi.ifi_change at zero.
243 * This was later fixed to set ifi.ifi_change to the flags that are actually
244 * set
245 */
246 NL_CAPABILITY_LINK_BUILD_ADD_REQUEST_SET_CHANGE = 23,
247 #define NL_CAPABILITY_LINK_BUILD_ADD_REQUEST_SET_CHANGE NL_CAPABILITY_LINK_BUILD_ADD_REQUEST_SET_CHANGE
248
249 /* Older versions of libnl3 would not use MSG_PEEK for nl_recvmsgs() unless calling
250 * nl_socket_enable_msg_peek(). Instead, the user had to specify the buffer size via
251 * nl_socket_set_msg_buf_size(), which in turn would default to 4*getpagesize().
252 *
253 * The default value might not be large enough, so users who were not aware of the
254 * problem easily ended up using a too small receive buffer. Usually, one wants to
255 * avoid MSG_PEEK for recvmsg() because it requires an additional syscall.
256 *
257 * Now, as indicated by this capability, nl_recvmsgs() would use MSG_PEEK by default. The
258 * user still can explicitly disable MSG_PEEK by calling nl_socket_disable_msg_peek() or
259 * by setting the nl_socket_set_msg_buf_size() to a non-zero value.
260 */
261 NL_CAPABILITY_NL_RECVMSGS_PEEK_BY_DEFAULT = 24,
262 #define NL_CAPABILITY_NL_RECVMSGS_PEEK_BY_DEFAULT NL_CAPABILITY_NL_RECVMSGS_PEEK_BY_DEFAULT
263
264 /**
265 * The library version is libnl3 3.2.29 or newer. This capability should never be backported.
266 */
267 NL_CAPABILITY_VERSION_3_2_29 = 25,
268 #define NL_CAPABILITY_VERSION_3_2_29 NL_CAPABILITY_VERSION_3_2_29
269
270 /**
271 * Support omitting @ctx_str argument to xfrmnl_sp_get_sec_ctx() to check
272 * for required buffer size for context string.
273 */
274 NL_CAPABILITY_XFRM_SP_SEC_CTX_LEN = 26,
275 #define NL_CAPABILITY_XFRM_SP_SEC_CTX_LEN NL_CAPABILITY_XFRM_SP_SEC_CTX_LEN
276
277 /**
278 * The library version is libnl3 3.3.0 or newer. This capability should never be backported.
279 */
280 NL_CAPABILITY_VERSION_3_3_0 = 27,
281 #define NL_CAPABILITY_VERSION_3_3_0 NL_CAPABILITY_VERSION_3_3_0
282
283 /**
284 * The library version is libnl3 3.4.0 or newer. This capability should never be backported.
285 */
286 NL_CAPABILITY_VERSION_3_4_0 = 28,
287 #define NL_CAPABILITY_VERSION_3_4_0 NL_CAPABILITY_VERSION_3_4_0
288
289 /**
290 * Fixed memory corruption in rtnl_link_vlan_set_egress_map(). Previously, if you tried
291 * to add more then 4 mappings, a buffer overflow occured. Also fixed nl_object_clone()
292 * for VLAN links.
293 */
294 NL_CAPABILITY_ROUTE_FIX_VLAN_SET_EGRESS_MAP = 29,
295 #define NL_CAPABILITY_ROUTE_FIX_VLAN_SET_EGRESS_MAP NL_CAPABILITY_ROUTE_FIX_VLAN_SET_EGRESS_MAP
296
297 /**
298 * The library version is libnl3 3.5.0 or newer. This capability should never be backported.
299 */
300 NL_CAPABILITY_VERSION_3_5_0 = 30,
301 #define NL_CAPABILITY_VERSION_3_5_0 NL_CAPABILITY_VERSION_3_5_0
302
303 __NL_CAPABILITY_MAX,
304 NL_CAPABILITY_MAX = (__NL_CAPABILITY_MAX - 1),
305 #define NL_CAPABILITY_MAX NL_CAPABILITY_MAX
306
307 /**
308 * The range 0x7000 to 0x7FFF is reserved for private capabilities. Upstream libnl3 will
309 * not register capabilities in this range. However, instead of adding private capabilities,
310 * better register their number with upstream libnl3. */
311 #define NL_CAPABILITY_IS_USER_RESERVED(cap) ( ((cap) & ~0x0FFF) == 0x7000 )
312 };
313 int nl_has_capability (int capability);
314
315 #ifdef __cplusplus
316 }
317 #endif
318
319 #endif
nl_get_user_hz
int nl_get_user_hz(void)
Return the value of HZ.
Definition: utils.c:509
nl_new_line
void nl_new_line(struct nl_dump_params *)
Handle a new line while dumping.
Definition: utils.c:913
nl_size2int
long nl_size2int(const char *)
Convert a character string to a size.
Definition: utils.c:295
nl_cancel_down_bits
double nl_cancel_down_bits(unsigned long long, char **)
Cancel down a bit counter.
Definition: utils.c:201
nl_msec2str
char * nl_msec2str(uint64_t, char *, size_t)
Convert milliseconds to a character string.
Definition: utils.c:595
nl_size2str
char * nl_size2str(const size_t, char *, const size_t)
Convert a size toa character string.
Definition: utils.c:358
NL_CAPABILITY_ROUTE_BUILD_MSG_SET_SCOPE
rtnl_route_build_msg() no longer guesses the route scope if explicitly set to RT_SCOPE_NOWHERE.
Definition: utils.h:90
nl_cancel_down_bytes
double nl_cancel_down_bytes(unsigned long long, char **)
Cancel down a byte counter.
Definition: utils.c:170
nl_cancel_down_us
double nl_cancel_down_us(uint32_t, char **)
Cancel down a micro second value.
Definition: utils.c:258
nl_get_psched_hz
int nl_get_psched_hz(void)
Return the value of packet scheduler HZ.
Definition: utils.c:518
nl_ticks2us
uint32_t nl_ticks2us(uint32_t)
Convert ticks to micro seconds.
Definition: utils.c:541
nl_prob2int
long nl_prob2int(const char *)
Convert a character string to a probability.
Definition: utils.c:392
nl_us2ticks
uint32_t nl_us2ticks(uint32_t)
Convert micro seconds to ticks.
Definition: utils.c:529
nl_dump_params
Dumping parameters.
Definition: types.h:33
nl_dump
void nl_dump(struct nl_dump_params *, const char *,...)
Dump a formatted character string.
Definition: utils.c:962