libnl 3.7.0

Macros

#define NL_CACHE_AF_ITER   0x0001
 Explicitely iterate over all address families when updating the cache. More...
 

Access Functions

int nl_cache_nitems (struct nl_cache *cache)
 Return the number of items in the cache. More...
 
int nl_cache_nitems_filter (struct nl_cache *cache, struct nl_object *filter)
 Return the number of items matching a filter in the cache. More...
 
int nl_cache_is_empty (struct nl_cache *cache)
 Returns true if the cache is empty. More...
 
struct nl_cache_ops * nl_cache_get_ops (struct nl_cache *cache)
 Return the operations set of the cache. More...
 
struct nl_object * nl_cache_get_first (struct nl_cache *cache)
 Return the first element in the cache. More...
 
struct nl_object * nl_cache_get_last (struct nl_cache *cache)
 Return the last element in the cache. More...
 
struct nl_object * nl_cache_get_next (struct nl_object *obj)
 Return the next element in the cache. More...
 
struct nl_object * nl_cache_get_prev (struct nl_object *obj)
 Return the previous element in the cache. More...
 

Cache Allocation/Deletion

struct nl_cache * nl_cache_alloc (struct nl_cache_ops *ops)
 Allocate new cache. More...
 
int nl_cache_alloc_and_fill (struct nl_cache_ops *ops, struct nl_sock *sock, struct nl_cache **result)
 Allocate new cache and fill it. More...
 
int nl_cache_alloc_name (const char *kind, struct nl_cache **result)
 Allocate new cache based on type name. More...
 
struct nl_cache * nl_cache_subset (struct nl_cache *orig, struct nl_object *filter)
 Allocate new cache containing a subset of an existing cache. More...
 
struct nl_cache * nl_cache_clone (struct nl_cache *cache)
 Allocate new cache and copy the contents of an existing cache. More...
 
void nl_cache_clear (struct nl_cache *cache)
 Remove all objects of a cache. More...
 
void nl_cache_get (struct nl_cache *cache)
 Increase reference counter of cache. More...
 
void nl_cache_free (struct nl_cache *cache)
 Free a cache. More...
 
void nl_cache_put (struct nl_cache *cache)
 

Cache Modifications

int nl_cache_add (struct nl_cache *cache, struct nl_object *obj)
 Add object to cache. More...
 
int nl_cache_move (struct nl_cache *cache, struct nl_object *obj)
 Move object from one cache to another. More...
 
void nl_cache_remove (struct nl_object *obj)
 Remove object from cache. More...
 

Synchronization

void nl_cache_set_arg1 (struct nl_cache *cache, int arg)
 Set synchronization arg1 of cache. More...
 
void nl_cache_set_arg2 (struct nl_cache *cache, int arg)
 Set synchronization arg2 of cache. More...
 
void nl_cache_set_flags (struct nl_cache *cache, unsigned int flags)
 Set cache flags. More...
 
int nl_cache_pickup_checkdup (struct nl_sock *sk, struct nl_cache *cache)
 Pickup a netlink dump response and put it into a cache. More...
 
int nl_cache_pickup (struct nl_sock *sk, struct nl_cache *cache)
 Pickup a netlink dump response and put it into a cache. More...
 
int nl_cache_include (struct nl_cache *cache, struct nl_object *obj, change_func_t change_cb, void *data)
 
int nl_cache_include_v2 (struct nl_cache *cache, struct nl_object *obj, change_func_v2_t change_cb, void *data)
 
int nl_cache_resync (struct nl_sock *sk, struct nl_cache *cache, change_func_t change_cb, void *data)
 

Parsing

int nl_cache_parse_and_add (struct nl_cache *cache, struct nl_msg *msg)
 Parse a netlink message and add it to the cache. More...
 
int nl_cache_refill (struct nl_sock *sk, struct nl_cache *cache)
 (Re)fill a cache with the contents in the kernel. More...
 

Utillities

struct nl_object * nl_cache_search (struct nl_cache *cache, struct nl_object *needle)
 Search object in cache. More...
 
struct nl_object * nl_cache_find (struct nl_cache *cache, struct nl_object *filter)
 Find object in cache. More...
 
void nl_cache_mark_all (struct nl_cache *cache)
 Mark all objects of a cache. More...
 

Dumping

void nl_cache_dump (struct nl_cache *cache, struct nl_dump_params *params)
 Dump all elements of a cache. More...
 
void nl_cache_dump_filter (struct nl_cache *cache, struct nl_dump_params *params, struct nl_object *filter)
 Dump all elements of a cache (filtered). More...
 

Iterators

void nl_cache_foreach (struct nl_cache *cache, void(*cb)(struct nl_object *, void *), void *arg)
 Call a callback on each element of the cache. More...
 
void nl_cache_foreach_filter (struct nl_cache *cache, struct nl_object *filter, void(*cb)(struct nl_object *, void *), void *arg)
 Call a callback on each element of the cache (filtered). More...
 

Detailed Description

Cache Management | | Type Specific Cache Operations
| | +----------------+ +------------+
| request update | | msg_parser |
| | +----------------+ +------------+
+- - - - -^- - - - - - - -^- -|- - - -
nl_cache_update: | | | |
1) --------- co_request_update ------+ | |
| | |
2) destroy old cache +----------- pp_cb ---------|---+
| | |
3) ---------- nl_recvmsgs ----------+ +- cb_valid -+
+--------------+ | | | |
| nl_cache_add |<-----+ + - - -v- -|- - - - - - - - - - -
+--------------+ | | +-------------+
| | +-----|-^-----+
+---v-|---+
| | | nl_recv |
+---------+
| | Core Netlink
int nl_cache_add(struct nl_cache *cache, struct nl_object *obj)
Add object to cache.
Definition: cache.c:474
int nl_recv(struct nl_sock *sk, struct sockaddr_nl *nla, unsigned char **buf, struct ucred **creds)
Receive data from netlink socket.
Definition: nl.c:652
int nl_recvmsgs(struct nl_sock *sk, struct nl_cb *cb)
Receive a set of messages from a netlink socket.
Definition: nl.c:1071

Related sections in the development guide:

Header

#include <netlink/cache.h>

Macro Definition Documentation

◆ NL_CACHE_AF_ITER

#define NL_CACHE_AF_ITER   0x0001

Explicitely iterate over all address families when updating the cache.

Definition at line 39 of file cache.h.

Function Documentation

◆ nl_cache_nitems()

int nl_cache_nitems ( struct nl_cache *  cache)

Return the number of items in the cache.

Parameters
cachecache handle

Definition at line 63 of file cache.c.

Referenced by nl_cache_mngr_info().

+ Here is the caller graph for this function:

◆ nl_cache_nitems_filter()

int nl_cache_nitems_filter ( struct nl_cache *  cache,
struct nl_object *  filter 
)

Return the number of items matching a filter in the cache.

Parameters
cacheCache object.
filterFilter object.

Definition at line 73 of file cache.c.

References nl_object_match_filter().

+ Here is the call graph for this function:

◆ nl_cache_is_empty()

int nl_cache_is_empty ( struct nl_cache *  cache)

Returns true if the cache is empty.

Parameters
cacheCache to check
Returns
true if the cache is empty, otherwise false is returned.

Definition at line 96 of file cache.c.

◆ nl_cache_get_ops()

struct nl_cache_ops * nl_cache_get_ops ( struct nl_cache *  cache)

Return the operations set of the cache.

Parameters
cachecache handle

Definition at line 105 of file cache.c.

Referenced by nl_cache_clone().

+ Here is the caller graph for this function:

◆ nl_cache_get_first()

struct nl_object * nl_cache_get_first ( struct nl_cache *  cache)

Return the first element in the cache.

Parameters
cachecache handle

Definition at line 114 of file cache.c.

◆ nl_cache_get_last()

struct nl_object * nl_cache_get_last ( struct nl_cache *  cache)

Return the last element in the cache.

Parameters
cachecache handle

Definition at line 127 of file cache.c.

◆ nl_cache_get_next()

struct nl_object * nl_cache_get_next ( struct nl_object *  obj)

Return the next element in the cache.

Parameters
objcurrent object

Definition at line 140 of file cache.c.

◆ nl_cache_get_prev()

struct nl_object * nl_cache_get_prev ( struct nl_object *  obj)

Return the previous element in the cache.

Parameters
objcurrent object

Definition at line 153 of file cache.c.

◆ nl_cache_alloc()

struct nl_cache * nl_cache_alloc ( struct nl_cache_ops *  ops)

Allocate new cache.

Parameters
opsCache operations

Allocate and initialize a new cache based on the cache operations provided.

Returns
Allocated cache or NULL if allocation failed.

Definition at line 178 of file cache.c.

References nl_hash_table_alloc().

Referenced by flnl_result_alloc_cache(), idiagnl_msg_alloc_cache(), nl_cache_alloc_and_fill(), nl_cache_alloc_name(), nl_cache_clone(), nl_cache_mngr_add(), nl_cache_subset(), rtnl_class_alloc_cache(), rtnl_cls_alloc_cache(), rtnl_link_alloc_cache_flags(), rtnl_neigh_alloc_cache_flags(), rtnl_route_alloc_cache(), and rtnl_rule_alloc_cache().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ nl_cache_alloc_and_fill()

int nl_cache_alloc_and_fill ( struct nl_cache_ops *  ops,
struct nl_sock *  sock,
struct nl_cache **  result 
)

Allocate new cache and fill it.

Parameters
opsCache operations
sockNetlink socket
resultResult pointer

Allocate new cache and fill it. Equivalent to calling:

cache = nl_cache_alloc(ops);
nl_cache_refill(sock, cache);
int nl_cache_refill(struct nl_sock *sk, struct nl_cache *cache)
(Re)fill a cache with the contents in the kernel.
Definition: cache.c:1035
struct nl_cache * nl_cache_alloc(struct nl_cache_ops *ops)
Allocate new cache.
Definition: cache.c:178
See also
nl_cache_alloc
Returns
0 on success or a negative error code.

Definition at line 228 of file cache.c.

References nl_cache_alloc(), nl_cache_free(), and nl_cache_refill().

Referenced by genl_ctrl_alloc_cache(), nfnl_ct_alloc_cache(), nfnl_exp_alloc_cache(), rtnl_neigh_alloc_cache(), rtnl_neightbl_alloc_cache(), and rtnl_qdisc_alloc_cache().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ nl_cache_alloc_name()

int nl_cache_alloc_name ( const char *  kind,
struct nl_cache **  result 
)

Allocate new cache based on type name.

Parameters
kindName of cache type
resultResult pointer

Lookup cache ops via nl_cache_ops_lookup() and allocate the cache by calling nl_cache_alloc(). Stores the allocated cache in the result pointer provided.

See also
nl_cache_alloc
Returns
0 on success or a negative error code.

Definition at line 259 of file cache.c.

References nl_cache_alloc(), nl_cache_ops_lookup_safe(), and nl_cache_ops_put().

+ Here is the call graph for this function:

◆ nl_cache_subset()

struct nl_cache * nl_cache_subset ( struct nl_cache *  orig,
struct nl_object *  filter 
)

Allocate new cache containing a subset of an existing cache.

Parameters
origOriginal cache to base new cache on
filterFilter defining the subset to be filled into the new cache

Allocates a new cache matching the type of the cache specified by orig. Iterates over the orig cache applying the specified filter and copies all objects that match to the new cache.

The copied objects are clones but do not contain a reference to each other. Later modifications to objects in the original cache will not affect objects in the new cache.

Returns
A newly allocated cache or NULL.

Definition at line 292 of file cache.c.

References nl_cache_add(), nl_cache_alloc(), and nl_object_match_filter().

+ Here is the call graph for this function:

◆ nl_cache_clone()

struct nl_cache * nl_cache_clone ( struct nl_cache *  cache)

Allocate new cache and copy the contents of an existing cache.

Parameters
cacheOriginal cache to base new cache on

Allocates a new cache matching the type of the cache specified by cache. Iterates over the cache cache and copies all objects to the new cache.

The copied objects are clones but do not contain a reference to each other. Later modifications to objects in the original cache will not affect objects in the new cache.

Returns
A newly allocated cache or NULL.

Definition at line 332 of file cache.c.

References nl_cache_add(), nl_cache_alloc(), and nl_cache_get_ops().

+ Here is the call graph for this function:

◆ nl_cache_clear()

void nl_cache_clear ( struct nl_cache *  cache)

Remove all objects of a cache.

Parameters
cacheCache to clear

The objects are unliked/removed from the cache by calling nl_cache_remove() on each object in the cache. If any of the objects to not contain any further references to them, those objects will be freed.

Unlike with nl_cache_free(), the cache is not freed just emptied.

Definition at line 361 of file cache.c.

References nl_cache_remove().

Referenced by nl_cache_refill().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ nl_cache_get()

void nl_cache_get ( struct nl_cache *  cache)

Increase reference counter of cache.

Parameters
cacheCache

Definition at line 386 of file cache.c.

Referenced by nl_cache_mngt_provide(), and nl_cache_mngt_require_safe().

+ Here is the caller graph for this function:

◆ nl_cache_free()

void nl_cache_free ( struct nl_cache *  cache)

Free a cache.

Parameters
cacheCache to free.

Calls nl_cache_clear() to remove all objects associated with the cache and frees the cache afterwards.

See also
nl_cache_clear()

Definition at line 403 of file cache.c.

Referenced by genl_mngt_resolve(), genl_ops_resolve(), nl_cache_alloc_and_fill(), nl_cache_mngr_add(), nl_cache_mngr_free(), nl_cache_mngt_unprovide(), rtnl_class_alloc_cache(), rtnl_cls_alloc_cache(), rtnl_link_alloc_cache_flags(), and rtnl_neigh_alloc_cache_flags().

+ Here is the caller graph for this function:

◆ nl_cache_put()

void nl_cache_put ( struct nl_cache *  cache)

Definition at line 417 of file cache.c.

◆ nl_cache_add()

int nl_cache_add ( struct nl_cache *  cache,
struct nl_object *  obj 
)

Add object to cache.

Parameters
cacheCache
objObject to be added to the cache

Adds the object obj to the specified cache. In case the object is already associated with another cache, the object is cloned before adding it to the cache. In this case, the sole reference to the object will be the one of the cache. Therefore clearing/freeing the cache will result in the object being freed again.

If the object has not been associated with a cache yet, the reference counter of the object is incremented to account for the additional reference.

The type of the object and cache must match, otherwise an error is returned (-NLE_OBJ_MISMATCH).

See also
nl_cache_move()
Returns
0 or a negative error code.

Definition at line 474 of file cache.c.

References nl_object_clone(), nl_object_get(), and nl_object_put().

Referenced by nl_cache_clone(), and nl_cache_subset().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ nl_cache_move()

int nl_cache_move ( struct nl_cache *  cache,
struct nl_object *  obj 
)

Move object from one cache to another.

Parameters
cacheCache to move object to.
objObject subject to be moved

Removes the the specified object obj from its associated cache and moves it to another cache.

If the object is not associated with a cache, the function behaves just like nl_cache_add().

The type of the object and cache must match, otherwise an error is returned (-NLE_OBJ_MISMATCH).

See also
nl_cache_add()
Returns
0 on success or a negative error code.

Definition at line 518 of file cache.c.

References nl_cache_remove(), and nl_object_get().

+ Here is the call graph for this function:

◆ nl_cache_remove()

void nl_cache_remove ( struct nl_object *  obj)

Remove object from cache.

Parameters
objObject to remove from cache

Removes the object obj from the cache it is associated with. The reference counter of the object will be decremented. If the reference to the object was the only one remaining, the object will be freed.

If no cache is associated with the object, this function is a NOP.

Definition at line 546 of file cache.c.

References nl_hash_table_del(), and nl_object_put().

Referenced by nl_cache_clear(), nl_cache_move(), and nl_object_free().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ nl_cache_set_arg1()

void nl_cache_set_arg1 ( struct nl_cache *  cache,
int  arg 
)

Set synchronization arg1 of cache.

Parameters
cacheCache
argargument

Synchronization arguments are used to specify filters when requesting dumps from the kernel.

Definition at line 585 of file cache.c.

Referenced by nl_cache_refill().

+ Here is the caller graph for this function:

◆ nl_cache_set_arg2()

void nl_cache_set_arg2 ( struct nl_cache *  cache,
int  arg 
)

Set synchronization arg2 of cache.

Parameters
cacheCache
argargument

Synchronization arguments are used to specify filters when requesting dumps from the kernel.

Definition at line 598 of file cache.c.

◆ nl_cache_set_flags()

void nl_cache_set_flags ( struct nl_cache *  cache,
unsigned int  flags 
)

Set cache flags.

Parameters
cacheCache
flagsFlags

Definition at line 608 of file cache.c.

Referenced by rtnl_link_alloc_cache_flags(), and rtnl_neigh_alloc_cache_flags().

+ Here is the caller graph for this function:

◆ nl_cache_pickup_checkdup()

int nl_cache_pickup_checkdup ( struct nl_sock *  sk,
struct nl_cache *  cache 
)

Pickup a netlink dump response and put it into a cache.

Parameters
skNetlink socket.
cacheCache to put items into.

Waits for netlink messages to arrive, parses them and puts them into the specified cache. If an old object with same key attributes is present in the cache, it is replaced with the new object. If the old object type supports an update operation, an update is attempted before a replace.

Returns
0 on success or a negative error code.

Definition at line 761 of file cache.c.

Referenced by flnl_lookup().

+ Here is the caller graph for this function:

◆ nl_cache_pickup()

int nl_cache_pickup ( struct nl_sock *  sk,
struct nl_cache *  cache 
)

Pickup a netlink dump response and put it into a cache.

Parameters
skNetlink socket.
cacheCache to put items into.

Waits for netlink messages to arrive, parses them and puts them into the specified cache.

Returns
0 on success or a negative error code.

Definition at line 776 of file cache.c.

Referenced by nl_cache_refill().

+ Here is the caller graph for this function:

◆ nl_cache_include()

int nl_cache_include ( struct nl_cache *  cache,
struct nl_object *  obj,
change_func_t  change_cb,
void *  data 
)

Definition at line 856 of file cache.c.

◆ nl_cache_include_v2()

int nl_cache_include_v2 ( struct nl_cache *  cache,
struct nl_object *  obj,
change_func_v2_t  change_cb,
void *  data 
)

Definition at line 876 of file cache.c.

◆ nl_cache_resync()

int nl_cache_resync ( struct nl_sock *  sk,
struct nl_cache *  cache,
change_func_t  change_cb,
void *  data 
)

Definition at line 908 of file cache.c.

◆ nl_cache_parse_and_add()

int nl_cache_parse_and_add ( struct nl_cache *  cache,
struct nl_msg *  msg 
)

Parse a netlink message and add it to the cache.

Parameters
cachecache to add element to
msgnetlink message

Parses a netlink message by calling the cache specific message parser and adds the new element to the cache. If an old object with same key attributes is present in the cache, it is replaced with the new object. If the old object type supports an update operation, an update is attempted before a replace.

Returns
0 or a negative error code.

Definition at line 1015 of file cache.c.

References nlmsg_hdr().

+ Here is the call graph for this function:

◆ nl_cache_refill()

int nl_cache_refill ( struct nl_sock *  sk,
struct nl_cache *  cache 
)

(Re)fill a cache with the contents in the kernel.

Parameters
skNetlink socket.
cachecache to update

Clears the specified cache and fills it with the current state in the kernel.

Returns
0 or a negative error code.

Definition at line 1035 of file cache.c.

References NL_CACHE_AF_ITER, nl_cache_clear(), nl_cache_pickup(), and nl_cache_set_arg1().

Referenced by idiagnl_msg_alloc_cache(), nl_cache_alloc_and_fill(), nl_cache_mngr_add_cache(), rtnl_class_alloc_cache(), rtnl_cls_alloc_cache(), rtnl_link_alloc_cache_flags(), rtnl_neigh_alloc_cache_flags(), rtnl_route_alloc_cache(), and rtnl_rule_alloc_cache().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ nl_cache_search()

struct nl_object * nl_cache_search ( struct nl_cache *  cache,
struct nl_object *  needle 
)

Search object in cache.

Parameters
cacheCache
needleObject to look for.

Searches the cache for an object which matches the object needle. The function nl_object_identical() is used to determine if the objects match. If a matching object is found, the reference counter is incremented and the object is returned.

Therefore, if an object is returned, the reference to the object must be returned by calling nl_object_put() after usage.

Returns
Reference to object or NULL if not found.

Definition at line 1108 of file cache.c.

References nl_object_get(), and nl_object_identical().

+ Here is the call graph for this function:

◆ nl_cache_find()

struct nl_object * nl_cache_find ( struct nl_cache *  cache,
struct nl_object *  filter 
)

Find object in cache.

Parameters
cacheCache
filterobject acting as a filter

Searches the cache for an object which matches the object filter. If the filter attributes matches the object type id attributes, and the cache supports hash lookups, a faster hashtable lookup is used to return the object. Else, function nl_object_match_filter() is used to determine if the objects match. If a matching object is found, the reference counter is incremented and the object is returned.

Therefore, if an object is returned, the reference to the object must be returned by calling nl_object_put() after usage.

Returns
Reference to object or NULL if not found.

Definition at line 1143 of file cache.c.

References nl_object_get(), nl_object_get_id_attrs(), and nl_object_match_filter().

+ Here is the call graph for this function:

◆ nl_cache_mark_all()

void nl_cache_mark_all ( struct nl_cache *  cache)

Mark all objects of a cache.

Parameters
cacheCache

Marks all objects of a cache by calling nl_object_mark() on each object associated with the cache.

Definition at line 1172 of file cache.c.

References nl_object_mark().

+ Here is the call graph for this function:

◆ nl_cache_dump()

void nl_cache_dump ( struct nl_cache *  cache,
struct nl_dump_params params 
)

Dump all elements of a cache.

Parameters
cachecache to dump
paramsdumping parameters

Dumps all elements of the cache to the file descriptor fd.

Definition at line 1197 of file cache.c.

References nl_cache_dump_filter().

Referenced by nl_cache_mngr_info().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ nl_cache_dump_filter()

void nl_cache_dump_filter ( struct nl_cache *  cache,
struct nl_dump_params params,
struct nl_object *  filter 
)

Dump all elements of a cache (filtered).

Parameters
cachecache to dump
paramsdumping parameters
filterfilter object

Dumps all elements of the cache to the file descriptor fd given they match the given filter filter.

Definition at line 1211 of file cache.c.

References nl_dump_params::dp_buf, nl_dump_params::dp_buflen, nl_dump_params::dp_type, NL_DUMP_DETAILS, and nl_object_match_filter().

Referenced by nl_cache_dump().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ nl_cache_foreach()

void nl_cache_foreach ( struct nl_cache *  cache,
void(*)(struct nl_object *, void *)  cb,
void *  arg 
)

Call a callback on each element of the cache.

Parameters
cachecache to iterate on
cbcallback function
argargument passed to callback function

Calls a callback function cb on each element of the cache. The argument arg is passed on the callback function.

Definition at line 1277 of file cache.c.

References nl_cache_foreach_filter().

+ Here is the call graph for this function:

◆ nl_cache_foreach_filter()

void nl_cache_foreach_filter ( struct nl_cache *  cache,
struct nl_object *  filter,
void(*)(struct nl_object *, void *)  cb,
void *  arg 
)

Call a callback on each element of the cache (filtered).

Parameters
cachecache to iterate on
filterfilter object
cbcallback function
argargument passed to callback function

Calls a callback function cb on each element of the cache that matches the filter. The argument arg is passed on to the callback function.

Definition at line 1294 of file cache.c.

References nl_object_get(), nl_object_match_filter(), and nl_object_put().

Referenced by nl_cache_foreach(), rtnl_class_foreach_child(), rtnl_class_foreach_cls(), rtnl_qdisc_foreach_child(), and rtnl_qdisc_foreach_cls().

+ Here is the call graph for this function:
+ Here is the caller graph for this function: