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