Connection management, sending & receiving of data. More...

Connection Management
int	nl_connect (struct nl_sock *sk, int protocol)
	Create file descriptor and bind socket. More...

void	nl_close (struct nl_sock *sk)
	Close Netlink socket. More...

Send
int	nl_sendto (struct nl_sock sk, void buf, size_t size)
	Transmit raw data over Netlink socket. More...

int	nl_sendmsg (struct nl_sock sk, struct nl_msg msg, struct msghdr *hdr)
	Transmit Netlink message using sendmsg() More...

int	nl_send_iovec (struct nl_sock sk, struct nl_msg msg, struct iovec *iov, unsigned iovlen)
	Transmit Netlink message (taking IO vector) More...

int	nl_send (struct nl_sock sk, struct nl_msg msg)
	Transmit Netlink message. More...

void	nl_complete_msg (struct nl_sock sk, struct nl_msg msg)
	Finalize Netlink message. More...

int	nl_send_auto (struct nl_sock sk, struct nl_msg msg)
	Finalize and transmit Netlink message. More...

int	nl_send_sync (struct nl_sock sk, struct nl_msg msg)
	Finalize and transmit Netlink message and wait for ACK or error message. More...

int	nl_send_simple (struct nl_sock sk, int type, int flags, void buf, size_t size)
	Construct and transmit a Netlink message. More...

Receive
int	nl_recv (struct nl_sock sk, struct sockaddr_nl nla, unsigned char buf, struct ucred creds)
	Receive data from netlink socket. More...

int	nl_recvmsgs_report (struct nl_sock sk, struct nl_cb cb)
	Receive a set of messages from a netlink socket and report parsed messages. More...

int	nl_recvmsgs (struct nl_sock sk, struct nl_cb cb)
	Receive a set of messages from a netlink socket. More...

int	nl_recvmsgs_default (struct nl_sock *sk)
	Receive a set of message from a netlink socket using handlers in nl_sock. More...

int	nl_wait_for_ack (struct nl_sock *sk)
	Wait for ACK. More...

int	nl_pickup (struct nl_sock sk, int(parser)(struct nl_cache_ops , struct sockaddr_nl , struct nlmsghdr , struct nl_parser_param ), struct nl_object **result)
	Pickup netlink answer, parse is and return object. More...

int	nl_pickup_keep_syserr (struct nl_sock sk, int(parser)(struct nl_cache_ops , struct sockaddr_nl , struct nlmsghdr , struct nl_parser_param ), struct nl_object *result, int syserror)
	Pickup netlink answer, parse is and return object with preserving system error. More...

Deprecated
void	nl_auto_complete (struct nl_sock sk, struct nl_msg msg)

int	nl_send_auto_complete (struct nl_sock sk, struct nl_msg msg)

Detailed Description

Connection management, sending & receiving of data.

Related sections in the development guide:

Header

#include <netlink/netlink.h>

Function Documentation

◆ nl_connect()

int nl_connect	(	struct nl_sock *	sk,
		int	protocol
	)

Create file descriptor and bind socket.

Parameters

sk	Netlink socket (required)
protocol	Netlink protocol to use (required)

Creates a new Netlink socket using socket() and binds the socket to the protocol and local port specified in the sk socket object. Fails if the socket is already connected.

Note: If available, the close-on-exec (SOCK_CLOEXEC) feature is enabled automatically on the new file descriptor. This causes the socket to be closed automatically if any of the exec family functions succeed. This is essential for multi threaded programs.; The local port (nl_socket_get_local_port()) is unspecified after creating a new socket. It only gets determined when accessing the port the first time or during nl_connect(). When nl_connect() fails during bind() due to ADDRINUSE, it will retry with different ports if the port is unspecified. Unless you want to enforce the use of a specific local port, don't access the local port (or reset it to unspecified by calling nl_socket_set_local_port(sk, 0)). This capability is indicated by NL_CAPABILITY_NL_CONNECT_RETRY_GENERATE_PORT_ON_ADDRINUSE.; nl_connect() creates and sets the file descriptor. You can setup the file descriptor yourself by creating and binding it, and then calling nl_socket_set_fd(). The result will be the same.

See also: nl_socket_alloc(); nl_close(); nl_socket_set_fd()

Returns: 0 on success or a negative error code.

Return values

-NLE_BAD_SOCK Socket is already connected

Definition at line 97 of file nl.c.

References nl_socket_set_buffer_size(), and nl_socket_set_local_port().

Referenced by genl_connect(), idiagnl_connect(), nfnl_connect(), and nl_cache_mngr_alloc().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ nl_close()

void nl_close ( struct nl_sock * sk )

Close Netlink socket.

Parameters

sk	Netlink socket (required)

Closes the Netlink socket using close().

Note: The socket is closed automatically if a struct nl_sock object is freed using nl_socket_free().

See also: nl_connect()

Definition at line 224 of file nl.c.

Referenced by nl_cache_mngr_free().

Here is the caller graph for this function:

◆ nl_sendto()

int nl_sendto	(	struct nl_sock *	sk,
		void *	buf,
		size_t	size
	)

Transmit raw data over Netlink socket.

Parameters

sk	Netlink socket (required)
buf	Buffer carrying data to send (required)
size	Size of buffer (required)

Transmits "raw" data over the specified Netlink socket. Unlike the other transmit functions it does not modify the data in any way. It directly passes the buffer buf of size to sendto().

The message is addressed to the peer as specified in the socket by either the nl_socket_set_peer_port() or nl_socket_set_peer_groups() function.

Note: Because there is no indication on the message boundaries of the data being sent, the NL_CB_MSG_OUT callback handler will not be invoked for data that is being sent using this function.

See also: nl_socket_set_peer_port(); nl_socket_set_peer_groups(); nl_sendmsg()

Returns: Number of bytes sent or a negative error code.

Definition at line 264 of file nl.c.

◆ nl_sendmsg()

int nl_sendmsg	(	struct nl_sock *	sk,
		struct nl_msg *	msg,
		struct msghdr *	hdr
	)

Transmit Netlink message using sendmsg()

Parameters

sk	Netlink socket (required)
msg	Netlink message to be sent (required)
hdr	sendmsg() message header (required)

Transmits the message specified in hdr over the Netlink socket using the sendmsg() system call.

Attention: The msg argument will not be used to derive the message payload that is being sent out. The msg argument is only passed on to the NL_CB_MSG_OUT callback. The caller is responsible to initialize the hdr struct properly and have it point to the message payload and socket address.

Note: This function uses nlmsg_set_src() to modify the msg argument prior to invoking the NL_CB_MSG_OUT callback to provide the local port number.

Callback Invocation:\n This function triggers the <tt>NL_CB_MSG_OUT</tt> callback.

Attention: Think twice before using this function. It provides a low level access to the Netlink socket. Among other limitations, it does not add credentials even if enabled or respect the destination address specified in the msg object.

See also: nl_socket_set_local_port(); nl_send_auto(); nl_send_iovec()

Returns: Number of bytes sent on success or a negative error code.

Note: This is a low level API function. A high level function implementing the same functionality with a simplified usage pattern exists. This function is available as an alternative if the default library behaviour is not desirable.

Definition at line 321 of file nl.c.

References NL_CB_MSG_OUT, and NL_OK.

Referenced by nl_send_iovec().

Here is the caller graph for this function:

◆ nl_send_iovec()

int nl_send_iovec	(	struct nl_sock *	sk,
		struct nl_msg *	msg,
		struct iovec *	iov,
		unsigned	iovlen
	)

Transmit Netlink message (taking IO vector)

Parameters

sk	Netlink socket (required)
msg	Netlink message to be sent (required)
iov	IO vector to be sent (required)
iovlen	Number of struct iovec to be sent (required)

This function is identical to nl_send() except that instead of taking a struct nl_msg object it takes an IO vector. Please see the description of nl_send().

Callback Invocation:\n This function triggers the <tt>NL_CB_MSG_OUT</tt> callback.

See also: nl_send()

Returns: Number of bytes sent on success or a negative error code.

Note: This is a low level API function. A high level function implementing the same functionality with a simplified usage pattern exists. This function is available as an alternative if the default library behaviour is not desirable.

Definition at line 367 of file nl.c.

References nl_sendmsg().

Referenced by nl_send().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ nl_send()

int nl_send	(	struct nl_sock *	sk,
		struct nl_msg *	msg
	)

Transmit Netlink message.

Parameters

sk	Netlink socket (required)
msg	Netlink message (required)

Transmits the Netlink message msg over the Netlink socket using the sendmsg() system call. This function is based on nl_send_iovec() but takes care of initializing a struct iovec based on the msg object.

The message is addressed to the peer as specified in the socket by either the nl_socket_set_peer_port() or nl_socket_set_peer_groups() function. The peer address can be overwritten by specifying an address in the msg object using nlmsg_set_dst().

If present in the msg, credentials set by the nlmsg_set_creds() function are added to the control buffer of the message.

Overwriting Capability:: Calls to this function can be overwritten by providing an alternative using the nl_cb_overwrite_send() function.

Callback Invocation:\n This function triggers the <tt>NL_CB_MSG_OUT</tt> callback.

Attention: Unlike nl_send_auto(), this function does not finalize the message in terms of automatically adding needed flags or filling out port numbers.

See also: nl_send_auto(); nl_send_iovec(); nl_socket_set_peer_port(); nl_socket_set_peer_groups(); nlmsg_set_dst(); nlmsg_set_creds(); nl_cb_overwrite_send()

Returns: Number of bytes sent on success or a negative error code.

Definition at line 441 of file nl.c.

References nl_send_iovec(), and nlmsg_hdr().

Referenced by nl_send_auto().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ nl_complete_msg()

void nl_complete_msg	(	struct nl_sock *	sk,
		struct nl_msg *	msg
	)

Finalize Netlink message.

Parameters

sk	Netlink socket (required)
msg	Netlink message (required)

This function finalizes a Netlink message by completing the message with desirable flags and values depending on the socket configuration.

If not yet filled out, the source address of the message (nlmsg_pid) will be set to the local port number of the socket.
If not yet specified, the next available sequence number is assigned to the message (nlmsg_seq).
If not yet specified, the protocol field of the message will be set to the protocol field of the socket.
The NLM_F_REQUEST Netlink message flag will be set.
The NLM_F_ACK flag will be set if Auto-ACK mode is enabled on the socket.

Definition at line 475 of file nl.c.

References NL_AUTO_PORT, NL_AUTO_SEQ, and nlmsg_hdr().

Referenced by nl_auto_complete(), and nl_send_auto().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ nl_send_auto()

int nl_send_auto	(	struct nl_sock *	sk,
		struct nl_msg *	msg
	)

Finalize and transmit Netlink message.

Parameters

sk	Netlink socket (required)
msg	Netlink message (required)

Finalizes the message by passing it to nl_complete_msg() and transmits it by passing it to nl_send().

Callback Invocation:\n This function triggers the <tt>NL_CB_MSG_OUT</tt> callback.

See also: nl_complete_msg(); nl_send()

Returns: Number of bytes sent or a negative error code.

Definition at line 510 of file nl.c.

References nl_complete_msg(), and nl_send().

Referenced by nl_send_auto_complete(), nl_send_simple(), nl_send_sync(), and rtnl_link_get_kernel().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ nl_send_sync()

int nl_send_sync	(	struct nl_sock *	sk,
		struct nl_msg *	msg
	)

Finalize and transmit Netlink message and wait for ACK or error message.

Parameters

sk	Netlink socket (required)
msg	Netlink message (required)

Passes the msg to nl_send_auto() to finalize and transmit it. Frees the message and waits (sleeps) for the ACK or error message to be received.

Attention: Disabling Auto-ACK (nl_socket_disable_auto_ack()) will cause this function to return immediately after transmitting the message. However, the peer may still be returning an error message in response to the request. It is the responsibility of the caller to handle such messages.

Callback Invocation:\n This function triggers the <tt>NL_CB_MSG_OUT</tt> callback.

Attention: This function frees the msg object after transmitting it by calling nlmsg_free().

See also: nl_send_auto().; nl_wait_for_ack()

Returns: 0 on success or a negative error code.

Definition at line 542 of file nl.c.

References nl_send_auto(), and nlmsg_free().

Referenced by rtnl_act_add(), rtnl_act_change(), rtnl_act_delete(), rtnl_class_add(), rtnl_class_delete(), rtnl_cls_add(), rtnl_cls_change(), rtnl_cls_delete(), rtnl_link_add(), rtnl_link_delete(), rtnl_qdisc_add(), rtnl_qdisc_delete(), and rtnl_qdisc_update().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ nl_send_simple()

int nl_send_simple	(	struct nl_sock *	sk,
		int	type,
		int	flags,
		void *	buf,
		size_t	size
	)

Construct and transmit a Netlink message.

Parameters

sk	Netlink socket (required)
type	Netlink message type (required)
flags	Netlink message flags (optional)
buf	Data buffer (optional)
size	Size of data buffer (optional)

Allocates a new Netlink message based on type and flags. If buf points to payload of length size that payload will be appended to the message.

Sends out the message using nl_send_auto() and frees the message afterwards.

See also: nl_send_auto()

Returns: Number of characters sent on success or a negative error code.

Return values

-NLE_NOMEM Unable to allocate Netlink message

Definition at line 574 of file nl.c.

References nl_send_auto(), nlmsg_alloc_simple(), nlmsg_append(), and nlmsg_free().

Referenced by genl_send_simple(), idiagnl_send_simple(), nfnl_send_simple(), and nl_rtgen_request().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ nl_recv()

int nl_recv	(	struct nl_sock *	sk,
		struct sockaddr_nl *	nla,
		unsigned char **	buf,
		struct ucred **	creds
	)

Receive data from netlink socket.

Parameters

sk	Netlink socket (required)
nla	Netlink socket structure to hold address of peer (required)
buf	Destination pointer for message content (required)
creds	Destination pointer for credentials (optional)

Receives data from a connected netlink socket using recvmsg() and returns the number of bytes read. The read data is stored in a newly allocated buffer that is assigned to *buf. The peer's netlink address will be stored in *nla.

This function blocks until data is available to be read unless the socket has been put into non-blocking mode using nl_socket_set_nonblocking() in which case this function will return immediately with a return value of -NLA_AGAIN (versions before 3.2.22 returned instead 0, in which case you should check first clear errno and then check for errno EAGAIN).

The buffer size used when reading from the netlink socket and thus limiting the maximum size of a netlink message that can be read defaults to the size of a memory page (getpagesize()). The buffer size can be modified on a per socket level using the function nl_socket_set_msg_buf_size().

If message peeking is enabled using nl_socket_enable_msg_peek() the size of the message to be read will be determined using the MSG_PEEK flag prior to performing the actual read. This leads to an additional recvmsg() call for every read operation which has performance implications and is not recommended for high throughput protocols.

An eventual interruption of the recvmsg() system call is automatically handled by retrying the operation.

If receiving of credentials has been enabled using the function nl_socket_set_passcred(), this function will allocate a new struct ucred filled with the received credentials and assign it to *creds. The caller is responsible for freeing the buffer.

Note: The caller is responsible to free the returned data buffer and if enabled, the credentials buffer.

See also: nl_socket_set_nonblocking(); nl_socket_set_msg_buf_size(); nl_socket_enable_msg_peek(); nl_socket_set_passcred()

Returns: Number of bytes read, 0 on EOF, 0 on no data event (non-blocking mode), or a negative error code.

Definition at line 652 of file nl.c.

◆ nl_recvmsgs_report()

int nl_recvmsgs_report	(	struct nl_sock *	sk,
		struct nl_cb *	cb
	)

Receive a set of messages from a netlink socket and report parsed messages.

Parameters

sk	Netlink socket.
cb	set of callbacks to control behaviour.

This function is identical to nl_recvmsgs() to the point that it will return the number of parsed messages instead of 0 on success.

See also: nl_recvmsgs()

Returns: Number of received messages or a negative error code from nl_recv().

Definition at line 1046 of file nl.c.

Referenced by nl_cache_mngr_data_ready(), and nl_recvmsgs().

Here is the caller graph for this function:

◆ nl_recvmsgs()

int nl_recvmsgs	(	struct nl_sock *	sk,
		struct nl_cb *	cb
	)

Receive a set of messages from a netlink socket.

Parameters

sk	Netlink socket.
cb	set of callbacks to control behaviour.

Repeatedly calls nl_recv() or the respective replacement if provided by the application (see nl_cb_overwrite_recv()) and parses the received data as netlink messages. Stops reading if one of the callbacks returns NL_STOP or nl_recv returns either 0 or a negative error code.

A non-blocking sockets causes the function to return immediately if no data is available.

See also: nl_recvmsgs_report()

Returns: 0 on success or a negative error code from nl_recv().

Definition at line 1071 of file nl.c.

References nl_recvmsgs_report().

Referenced by nl_pickup_keep_syserr(), nl_recvmsgs_default(), and nl_wait_for_ack().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ nl_recvmsgs_default()

int nl_recvmsgs_default ( struct nl_sock * sk )

Receive a set of message from a netlink socket using handlers in nl_sock.

Parameters

sk	Netlink socket.

Calls nl_recvmsgs() with the handlers configured in the netlink socket.

Definition at line 1087 of file nl.c.

References nl_recvmsgs().

Here is the call graph for this function:

◆ nl_wait_for_ack()

int nl_wait_for_ack ( struct nl_sock * sk )

Wait for ACK.

Parameters

sk	Netlink socket.

Precondition: The netlink socket must be in blocking state.

Waits until an ACK is received for the latest not yet acknowledged netlink message.

Definition at line 1106 of file nl.c.

References NL_CB_ACK, nl_cb_clone(), NL_CB_CUSTOM, nl_cb_set(), and nl_recvmsgs().

Here is the call graph for this function:

◆ nl_pickup()

int nl_pickup	(	struct nl_sock *	sk,
		int()(struct nl_cache_ops , struct sockaddr_nl , struct nlmsghdr , struct nl_parser_param *)	parser,
		struct nl_object **	result
	)

Pickup netlink answer, parse is and return object.

Parameters

sk	Netlink socket
parser	Parser function to parse answer
result	Result pointer to return parsed object

Returns: 0 on success or a negative error code.

Definition at line 1172 of file nl.c.

References nl_pickup_keep_syserr().

Here is the call graph for this function:

◆ nl_pickup_keep_syserr()

int nl_pickup_keep_syserr	(	struct nl_sock *	sk,
		int()(struct nl_cache_ops , struct sockaddr_nl , struct nlmsghdr , struct nl_parser_param *)	parser,
		struct nl_object **	result,
		int *	syserror
	)

Pickup netlink answer, parse is and return object with preserving system error.

Parameters

sk	Netlink socket
parser	Parser function to parse answer
result	Result pointer to return parsed object
syserr	Result pointer for the system error in case of failure