Manager keeping caches up to date automatically. More...

Functions
int	nl_cache_mngr_alloc (struct nl_sock sk, int protocol, int flags, struct nl_cache_mngr *result)
	Allocate new cache manager. More...

int	nl_cache_mngr_add_cache (struct nl_cache_mngr mngr, struct nl_cache cache, change_func_t cb, void *data)
	Add cache to cache manager. More...

int	nl_cache_mngr_add_cache_v2 (struct nl_cache_mngr mngr, struct nl_cache cache, change_func_v2_t cb, void *data)
	Add cache to cache manager. More...

int	nl_cache_mngr_add (struct nl_cache_mngr mngr, const char name, change_func_t cb, void data, struct nl_cache *result)
	Add cache to cache manager. More...

int	nl_cache_mngr_get_fd (struct nl_cache_mngr *mngr)
	Get socket file descriptor. More...

int	nl_cache_mngr_poll (struct nl_cache_mngr *mngr, int timeout)
	Check for event notifications. More...

int	nl_cache_mngr_data_ready (struct nl_cache_mngr *mngr)
	Receive available event notifications. More...

void	nl_cache_mngr_info (struct nl_cache_mngr mngr, struct nl_dump_params p)
	Print information about cache manager. More...

void	nl_cache_mngr_free (struct nl_cache_mngr *mngr)
	Free cache manager and all caches. More...

Detailed Description

Manager keeping caches up to date automatically.

The cache manager keeps caches up to date automatically by listening to netlink notifications and integrating the received information into the existing cache.

Note: This functionality is still considered experimental.

Related sections in the development guide:

Cache Manager (Netlink Core Library Development Guide)

Header

#include <netlink/cache.h>

Function Documentation

◆ nl_cache_mngr_alloc()

int nl_cache_mngr_alloc	(	struct nl_sock *	sk,
		int	protocol,
		int	flags,
		struct nl_cache_mngr **	result
	)

Allocate new cache manager.

Parameters

sk	Netlink socket or NULL to auto allocate
protocol	Netlink protocol this manager is used for
flags	Flags (`NL_AUTO_PROVIDE`)
result	Result pointer

Allocates a new cache manager for the specified netlink protocol.

If sk is not specified (NULL) a netlink socket matching the specified protocol will be automatically allocated.
The socket will be put in non-blocking mode and sequence checking will be disabled regardless of whether the socket was provided by the caller or automatically allocated.
The socket will be connected.

If the flag NL_AUTO_PROVIDE is specified, any cache added to the manager will automatically be made available to other users using nl_cache_mngt_provide().

Note: If the socket is provided by the caller, it is NOT recommended to use the socket for anything else besides receiving netlink notifications.

Returns: 0 on success or a negative error code.

Definition at line 136 of file cache_mngr.c.

References nl_cache_mngr_free(), nl_connect(), nl_socket_alloc(), nl_socket_disable_seq_check(), nl_socket_free(), and nl_socket_set_nonblocking().

Here is the call graph for this function:

◆ nl_cache_mngr_add_cache()

int nl_cache_mngr_add_cache	(	struct nl_cache_mngr *	mngr,
		struct nl_cache *	cache,
		change_func_t	cb,
		void *	data
	)

Add cache to cache manager.

Parameters

mngr	Cache manager.
cache	Cache to be added to cache manager
cb	Function to be called upon changes.
data	Argument passed on to change callback

Adds cache to the manager. The operation will trigger a full dump request from the kernel to initially fill the contents of the cache. The manager will subscribe to the notification group of the cache and keep track of any further changes.

The user is responsible for calling nl_cache_mngr_poll() or monitor the socket and call nl_cache_mngr_data_ready() to allow the library to process netlink notification events.

See also: nl_cache_mngr_poll(); nl_cache_mngr_data_ready()

Returns: 0 on success or a negative error code.; -NLE_PROTO_MISMATCH Protocol mismatch between cache manager and cache type; -NLE_OPNOTSUPP Cache type does not support updates; -NLE_EXIST Cache of this type already being managed

Definition at line 286 of file cache_mngr.c.

References nl_cache_mngt_provide(), and nl_cache_refill().

Referenced by nl_cache_mngr_add(), and nl_cache_mngr_add_cache_v2().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ nl_cache_mngr_add_cache_v2()

int nl_cache_mngr_add_cache_v2	(	struct nl_cache_mngr *	mngr,
		struct nl_cache *	cache,
		change_func_v2_t	cb,
		void *	data
	)

Add cache to cache manager.

Parameters

mngr	Cache manager.
cache	Cache to be added to cache manager
cb	V2 function to be called upon changes.
data	Argument passed on to change callback

Adds cache to the manager. The operation will trigger a full dump request from the kernel to initially fill the contents of the cache. The manager will subscribe to the notification group of the cache and keep track of any further changes.

The user is responsible for calling nl_cache_mngr_poll() or monitor the socket and call nl_cache_mngr_data_ready() to allow the library to process netlink notification events.

See also: nl_cache_mngr_poll(); nl_cache_mngr_data_ready()

Returns: 0 on success or a negative error code.; -NLE_PROTO_MISMATCH Protocol mismatch between cache manager and cache type; -NLE_OPNOTSUPP Cache type does not support updates; -NLE_EXIST Cache of this type already being managed

Definition at line 384 of file cache_mngr.c.

References nl_cache_mngr_add_cache().

Here is the call graph for this function:

◆ nl_cache_mngr_add()

int nl_cache_mngr_add	(	struct nl_cache_mngr *	mngr,
		const char *	name,
		change_func_t	cb,
		void *	data,
		struct nl_cache **	result
	)

Add cache to cache manager.

Parameters

mngr	Cache manager.
name	Name of cache to keep track of
cb	Function to be called upon changes.
data	Argument passed on to change callback
result	Pointer to store added cache (optional)

Allocates a new cache of the specified type and adds it to the manager. The operation will trigger a full dump request from the kernel to initially fill the contents of the cache. The manager will subscribe to the notification group of the cache and keep track of any further changes.

The user is responsible for calling nl_cache_mngr_poll() or monitor the socket and call nl_cache_mngr_data_ready() to allow the library to process netlink notification events.

Note: Versions up to 3.4.0 actually required the result argument, preventing NULL to be passed.

See also: nl_cache_mngr_poll(); nl_cache_mngr_data_ready()

Returns: 0 on success or a negative error code.; -NLE_NOCACHE Unknown cache type; -NLE_PROTO_MISMATCH Protocol mismatch between cache manager and cache type; -NLE_OPNOTSUPP Cache type does not support updates; -NLE_EXIST Cache of this type already being managed

Definition at line 425 of file cache_mngr.c.

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

Here is the call graph for this function:

◆ nl_cache_mngr_get_fd()

int nl_cache_mngr_get_fd ( struct nl_cache_mngr * mngr )

Get socket file descriptor.

Parameters

mngr	Cache Manager

Get the file descriptor of the socket associated with the manager.

Note: Do not use the socket for anything besides receiving notifications.

Definition at line 464 of file cache_mngr.c.

References nl_socket_get_fd().

Here is the call graph for this function:

◆ nl_cache_mngr_poll()

int nl_cache_mngr_poll	(	struct nl_cache_mngr *	mngr,
		int	timeout
	)

Check for event notifications.

Parameters

mngr	Cache Manager
timeout	Upper limit poll() will block, in milliseconds.

Causes poll() to be called to check for new event notifications being available. Calls nl_cache_mngr_data_ready() to process available data.

This functionally is ideally called regularly during an idle period.

A timeout can be specified in milliseconds to limit the time the function will wait for updates.

See also: nl_cache_mngr_data_ready()

Returns: The number of messages processed or a negative error code.

Definition at line 488 of file cache_mngr.c.

References nl_cache_mngr_data_ready(), and nl_socket_get_fd().

Here is the call graph for this function:

◆ nl_cache_mngr_data_ready()

int nl_cache_mngr_data_ready ( struct nl_cache_mngr * mngr )

Receive available event notifications.

Parameters

mngr	Cache manager

This function can be called if the socket associated to the manager contains updates to be received. This function should only be used if nl_cache_mngr_poll() is not used.

The function will process messages until there is no more data to be read from the socket.