libnl: Send & Receive Data

libnl 3.10.0

Send & Receive Data
Core Library (libnl)

## Connection Management
int | nl_connect (struct nl_sock *sk, int protocol)
| Create file descriptor and bind socket.
void | nl_close (struct nl_sock *sk)
| Close Netlink socket.

## Send
int | nl_sendto (struct nl_sock *sk, void *buf, size_t size)
| Transmit raw data over Netlink socket.
int | nl_sendmsg (struct nl_sock *sk, struct nl_msg *msg, struct msghdr *hdr)
| Transmit Netlink message using sendmsg()
int | nl_send_iovec (struct nl_sock *sk, struct nl_msg *msg, struct iovec *iov, unsigned iovlen)
| Transmit Netlink message (taking IO vector)
int | nl_send (struct nl_sock *sk, struct nl_msg *msg)
| Transmit Netlink message.
void | nl_complete_msg (struct nl_sock *sk, struct nl_msg *msg)
| Finalize Netlink message.
int | nl_send_auto (struct nl_sock *sk, struct nl_msg *msg)
| Finalize and transmit Netlink message.
int | nl_send_sync (struct nl_sock *sk, struct nl_msg *msg)
| Finalize and transmit Netlink message and wait for ACK or error message.
int | nl_send_simple (struct nl_sock *sk, int type, int flags, void *buf, size_t size)
| Construct and transmit a Netlink message.

## Receive
int | nl_recv (struct nl_sock *sk, struct sockaddr_nl *nla, unsigned char **buf, struct ucred **creds)
| Receive data from netlink socket.
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.
int | nl_recvmsgs (struct nl_sock *sk, struct nl_cb *cb)
| Receive a set of messages from a netlink socket.
int | nl_recvmsgs_default (struct nl_sock *sk)
| Receive a set of message from a netlink socket using handlers in nl_sock.
int | nl_wait_for_ack (struct nl_sock *sk)
| Wait for ACK.
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.
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.

## 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:

- Sending & Receiving (Netlink Core Library Development Guide)
- Sockets (Netlink Core Library 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 102 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_ex().

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 229 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 269 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 `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.

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 326 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 `NL_CB_MSG_OUT` 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 372 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 `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 446 of file nl.c.

References nl_cb::cb_send_ow, 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 480 of file nl.c.

References NL_AUTO_PORT, NL_AUTO_SEQ, nl_socket_use_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 `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 515 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 `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 547 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 579 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 657 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 1052 of file nl.c.

References nl_cb::cb_recvmsgs_ow.

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 1077 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 1093 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 1112 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 1178 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

Returns
  0 on success or a negative error code.

Definition at line 1195 of file nl.c.

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

Referenced by nl_pickup(), and rtnl_link_get_kernel().

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

## ◆ nl_auto_complete()

void nl_auto_complete | ( | struct nl_sock * | sk,
|  | struct nl_msg * | msg )

Deprecated
  Please use nl_complete_msg()

Definition at line 1239 of file nl.c.

References nl_complete_msg().

Here is the call graph for this function:

## ◆ nl_send_auto_complete()

int nl_send_auto_complete | ( | struct nl_sock * | sk,
|  | struct nl_msg * | msg )

Deprecated
  Please use nl_send_auto()

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