libnl  3.2.24-rc1
Send & Receive Data

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...
 

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

int nl_connect ( struct nl_sock *  sk,
int  protocol 
)

Create file descriptor and bind socket.

Parameters
skNetlink socket (required)
protocolNetlink 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.
See Also
nl_socket_alloc()
nl_close()
Returns
0 on success or a negative error code.
Return values
-NLE_BAD_SOCKSocket is already connected

Definition at line 85 of file nl.c.

References nl_socket_set_buffer_size().

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:

void nl_close ( struct nl_sock *  sk)

Close Netlink socket.

Parameters
skNetlink 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 157 of file nl.c.

Referenced by nl_cache_mngr_free().

+ Here is the caller graph for this function:

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

Transmit raw data over Netlink socket.

Parameters
skNetlink socket (required)
bufBuffer carrying data to send (required)
sizeSize 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 197 of file nl.c.

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

Transmit Netlink message using sendmsg()

Parameters
skNetlink socket (required)
msgNetlink message to be sent (required)
hdrsendmsg() 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:
This function triggers the NL_CB_MSG_OUT 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.

Definition at line 251 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:

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

Transmit Netlink message (taking IO vector)

Parameters
skNetlink socket (required)
msgNetlink message to be sent (required)
iovIO vector to be sent (required)
iovlenNumber 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:
This function triggers the NL_CB_MSG_OUT callback.
See Also
nl_send()
Returns
Number of bytes sent on success or a negative error code.

Definition at line 294 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:

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

Transmit Netlink message.

Parameters
skNetlink socket (required)
msgNetlink 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:
This function triggers the NL_CB_MSG_OUT 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 368 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:

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

Finalize Netlink message.

Parameters
skNetlink socket (required)
msgNetlink 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 402 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:

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

Finalize and transmit Netlink message.

Parameters
skNetlink socket (required)
msgNetlink message (required)

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

Callback Invocation:
This function triggers the NL_CB_MSG_OUT callback.
See Also
nl_complete_msg()
nl_send()
Returns
Number of bytes sent or a negative error code.

Definition at line 437 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:

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
skNetlink socket (required)
msgNetlink 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:
This function triggers the NL_CB_MSG_OUT 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 469 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:

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

Construct and transmit a Netlink message.

Parameters
skNetlink socket (required)
typeNetlink message type (required)
flagsNetlink message flags (optional)
bufData buffer (optional)
sizeSize 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_NOMEMUnable to allocate Netlink message

Definition at line 501 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:

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

Receive data from netlink socket.

Parameters
skNetlink socket (required)
nlaNetlink socket structure to hold address of peer (required)
bufDestination pointer for message content (required)
credsDestination 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 0.

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 577 of file nl.c.

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
skNetlink socket.
cbset 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 950 of file nl.c.

Referenced by nl_cache_mngr_data_ready(), and nl_recvmsgs().

+ Here is the caller graph for this function:

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

Receive a set of messages from a netlink socket.

Parameters
skNetlink socket.
cbset 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 975 of file nl.c.

References nl_recvmsgs_report().

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

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

int nl_recvmsgs_default ( struct nl_sock *  sk)

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

Parameters
skNetlink socket.

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

Definition at line 991 of file nl.c.

References nl_recvmsgs().

+ Here is the call graph for this function:

int nl_wait_for_ack ( struct nl_sock *  sk)

Wait for ACK.

Parameters
skNetlink 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 1010 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:

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
skNetlink socket
parserParser function to parse answer
resultResult pointer to return parsed object
Returns
0 on success or a negative error code.

Definition at line 1068 of file nl.c.

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

Referenced by rtnl_link_get_kernel().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

void nl_auto_complete ( struct nl_sock *  sk,
struct nl_msg *  msg 
)
Deprecated:
Please use nl_complete_msg()

Definition at line 1106 of file nl.c.

References nl_complete_msg().

+ Here is the call graph for this function:

int nl_send_auto_complete ( struct nl_sock *  sk,
struct nl_msg *  msg 
)
Deprecated:
Please use nl_send_auto()

Definition at line 1114 of file nl.c.

References nl_send_auto().

Referenced by flnl_lookup(), rtnl_addr_add(), rtnl_addr_delete(), rtnl_link_change(), rtnl_neigh_add(), rtnl_neigh_delete(), rtnl_neightbl_change(), rtnl_rule_add(), and rtnl_rule_delete().

+ Here is the call graph for this function:

+ Here is the caller graph for this function: