Core Netlink API


Detailed Description

1) Creating the netlink handle

 struct nl_handle *handle;

 // Allocate and initialize a new netlink handle
 handle = nl_handle_new();

 // Are multiple handles being allocated? You have to provide a unique
 // netlink process id and overwrite the default local process id.
 nl_handle_set_pid(handle, MY_UNIQUE_PID);

 // Is this socket used for event processing? You need to disable sequence
 // number checking in order to be able to receive messages not explicitely
 // requested.
 nl_disable_sequence_check(handle);

 // Use nl_handle_get_fd() to fetch the file description, for example to
 // put a socket into non-blocking i/o mode.
 fcntl(nl_handle_get_fd(handle), F_SETFL, O_NONBLOCK);

2) Joining Groups
 // You may join/subscribe to as many groups as you want, don't forget
 // to eventually disable sequence number checking. Note: Joining must
 // be done before connecting/binding the socket.
 nl_join_groups(handle, GROUP_ID1 | GROUP_ID2);
3) Connecting the socket
 // Bind and connect the socket to a protocol, NETLINK_ROUTE in this example.
 nl_connect(handle, NETLINK_ROUTE);
4) Sending data
 // The most rudimentary method is to use nl_sendto() simply pushing
 // a piece of data to the other netlink peer. This method is not
 // recommended.
 const char buf[] = { 0x01, 0x02, 0x03, 0x04 };
 nl_sendto(handle, buf, sizeof(buf));

 // A more comfortable interface is nl_send() taking a pointer to
 // a netlink message.
 struct nl_msg *msg = my_msg_builder();
 nl_send(handle, nlmsg_hdr(msg));

 // nl_sendmsg() provides additional control over the sendmsg() message
 // header in order to allow more specific addressing of multiple peers etc.
 struct msghdr hdr = { ... };
 nl_sendmsg(handle, nlmsg_hdr(msg), &hdr);

 // You're probably too lazy to fill out the netlink pid, sequence number
 // and message flags all the time. nl_send_auto_complete() automatically
 // extends your message header as needed with an appropriate sequence
 // number, the netlink pid stored in the netlink handle and the message
 // flags NLM_F_REQUEST and NLM_F_ACK
 nl_send_auto_complete(handle, nlmsg_hdr(msg));

 // Simple protocols don't require the complex message construction interface
 // and may favour nl_send_simple() to easly send a bunch of payload
 // encapsulated in a netlink message header.
 nl_send_simple(handle, MY_MSG_TYPE, 0, buf, sizeof(buf));
5) Receiving data
 // nl_recv() receives a single message allocating a buffer for the message
 // content and gives back the pointer to you.
 struct sockaddr_nl peer;
 unsigned char *msg;
 nl_recv(handle, &peer, &msg);

 // nl_recvmsgs() receives a bunch of messages until the callback system
 // orders it to state, usually after receving a compolete multi part
 // message series.
 nl_recvmsgs(handle, my_callback_configuration);

 // nl_recvmsgs_def() acts just like nl_recvmsg() but uses the callback
 // configuration stored in the handle.
 nl_recvmsgs_def(handle);

 // In case you want to wait for the ACK to be recieved that you requested
 // with your latest message, you can call nl_wait_for_ack()
 nl_wait_for_ack(handle);
6) Cleaning up
 // Close the socket first to release kernel memory
 nl_close(handle);

 // Finally destroy the netlink handle
 nl_handle_destroy(handle);


Modules

 Attributes
 Netlink Attributes Construction/Parsing Interface.
 Callbacks/Customization
 Customization via callbacks.
 Messages
 Netlink Message Construction/Parsing Interface.

Data Structures

struct  sockaddr_nl
 Netlink socket address. More...

Netlink Family Translations

char * nl_nlfamily2str (int family, char *buf, size_t size)
 Convert netlink family to character string.
int nl_str2nlfamily (const char *name)
 Convert character string to netlink family.

Handle Management

nl_handle * nl_handle_alloc_nondefault (enum nl_cb_kind kind)
 Allocate and initialize new non-default netlink handle.
nl_handle * nl_handle_alloc (void)
 Allocate and initialize new netlink handle.
void nl_handle_destroy (struct nl_handle *handle)
 Destroy netlink handle.

Utilities

int nl_set_buffer_size (struct nl_handle *handle, int rxbuf, int txbuf)
 Set socket buffer size of netlink handle.
int nl_set_passcred (struct nl_handle *handle, int state)
 Enable/disable credential passing on netlink handle.
void nl_join_groups (struct nl_handle *handle, int groups)
 Join multicast groups.
int nl_join_group (struct nl_handle *handle, int group)
 Set socket buffer size of netlink handle.
void nl_disable_sequence_check (struct nl_handle *handle)
 Disable sequence number checking.
#define SOL_NETLINK   270
 Set socket buffer size of netlink handle.

Acccess Functions

pid_t nl_handle_get_pid (struct nl_handle *handle)
 Get netlink process identifier of netlink handle.
void nl_handle_set_pid (struct nl_handle *handle, pid_t pid)
 Set netlink process identifier of netlink handle.
pid_t nl_handle_get_peer_pid (struct nl_handle *handle)
 Get netlink process identifier of peer from netlink handle.
void nl_handle_set_peer_pid (struct nl_handle *handle, pid_t pid)
 Set netlink process identifier of peer in netlink handle.
int nl_handle_get_fd (struct nl_handle *handle)
 Get file descriptor of netlink handle.
sockaddr_nlnl_handle_get_local_addr (struct nl_handle *handle)
 Get local netlink address of netlink handle.
sockaddr_nlnl_handle_get_peer_addr (struct nl_handle *handle)
 Get peer netlink address of netlink handle.
nl_cb * nl_handle_get_cb (struct nl_handle *handle)
 Get callback configuration of netlink handle.

Connection Management

int nl_connect (struct nl_handle *handle, int protocol)
 Create and connect netlink socket.
void nl_close (struct nl_handle *handle)
 Close/Disconnect netlink socket.

Send

int nl_sendto (struct nl_handle *handle, void *buf, size_t size)
 Send raw data over netlink socket.
int nl_sendmsg (struct nl_handle *handle, struct nl_msg *msg, struct msghdr *hdr)
 Send netlink message with control over sendmsg() message header.
int nl_send (struct nl_handle *handle, struct nl_msg *msg)
 Send netlink message.
int nl_send_auto_complete (struct nl_handle *handle, struct nl_msg *msg)
 Send netlink message and check & extend header values as needed.
int nl_send_simple (struct nl_handle *handle, int type, int flags, void *buf, size_t size)
 Send simple netlink message using nl_send_auto_complete().

Receive

int nl_recv (struct nl_handle *handle, struct sockaddr_nl *nla, unsigned char **buf, struct ucred **creds)
 Receive netlink message from netlink socket.
int nl_recvmsgs (struct nl_handle *handle, struct nl_cb *cb)
 Receive a set of messages from a netlink socket.
int nl_recvmsgs_def (struct nl_handle *handle)
 Receive a set of message from a netlink socket using handlers in nl_handle.
int nl_wait_for_ack (struct nl_handle *handle)
 Wait for ACK.


Define Documentation

#define SOL_NETLINK   270

Set socket buffer size of netlink handle.

Parameters:
handle Netlink handle.
rxbuf New receive socket buffer size in bytes.
txbuf New transmit socket buffer size in bytes.
Sets the socket buffer size of a netlink handle to the specified values rxbuf and txbuf. Providing a value of 0 assumes a good default value.

Note:
It is not required to call this function prior to nl_connect().
Returns:
0 on sucess or a negative error code.

Definition at line 275 of file nl.c.

Referenced by nl_join_group().


Function Documentation

struct nl_handle* nl_handle_alloc_nondefault ( enum nl_cb_kind  kind  ) 

Allocate and initialize new non-default netlink handle.

Parameters:
kind Kind of callback handler to use per default.
Allocates and initializes a new netlink handle, the netlink process id is set to the local process id which may conflict if multiple handles are created, therefore you may have to overwrite it using nl_handle_set_pid(). The initial sequence number is initialized to the current UNIX time.

Returns:
Newly allocated netlink handle or NULL.

Definition at line 140 of file nl.c.

References nl_cb_new(), and nl_handle_destroy().

Referenced by nl_handle_alloc().

struct nl_handle* nl_handle_alloc ( void   ) 

Allocate and initialize new netlink handle.

Allocates and initializes a new netlink handle, the netlink process id is set to the local process id which may conflict if multiple handles are created, therefore you may have to overwrite it using nl_handle_set_pid(). The initial sequence number is initialized to the current UNIX time. The default callback (NL_CB_DEFAULT) handlers are being used.

Returns:
Newly allocated netlink handle or NULL.

Definition at line 176 of file nl.c.

References NL_CB_DEFAULT, and nl_handle_alloc_nondefault().

void nl_handle_destroy ( struct nl_handle *  handle  ) 

Destroy netlink handle.

Parameters:
handle Netlink handle.

Definition at line 185 of file nl.c.

References nl_cb_destroy().

Referenced by nl_handle_alloc_nondefault().

int nl_set_buffer_size ( struct nl_handle *  handle,
int  rxbuf,
int  txbuf 
)

Set socket buffer size of netlink handle.

Parameters:
handle Netlink handle.
rxbuf New receive socket buffer size in bytes.
txbuf New transmit socket buffer size in bytes.
Sets the socket buffer size of a netlink handle to the specified values rxbuf and txbuf. Providing a value of 0 assumes a good default value.

Note:
It is not required to call this function prior to nl_connect().
Returns:
0 on sucess or a negative error code.

Definition at line 214 of file nl.c.

Referenced by nl_connect().

int nl_set_passcred ( struct nl_handle *  handle,
int  state 
)

Enable/disable credential passing on netlink handle.

Parameters:
handle Netlink handle
state New state (0 - disabled, 1 - enabled)

Definition at line 244 of file nl.c.

void nl_join_groups ( struct nl_handle *  handle,
int  groups 
)

Join multicast groups.

Parameters:
handle Netlink handle.
groups Bitmask of groups to join.
Note:
Joining of groups must be done prior to connecting/binding the socket (nl_connect()).

Definition at line 269 of file nl.c.

int nl_join_group ( struct nl_handle *  handle,
int  group 
)

Set socket buffer size of netlink handle.

Parameters:
handle Netlink handle.
rxbuf New receive socket buffer size in bytes.
txbuf New transmit socket buffer size in bytes.
Sets the socket buffer size of a netlink handle to the specified values rxbuf and txbuf. Providing a value of 0 assumes a good default value.

Note:
It is not required to call this function prior to nl_connect().
Returns:
0 on sucess or a negative error code.

Definition at line 278 of file nl.c.

References SOL_NETLINK.

void nl_disable_sequence_check ( struct nl_handle *  handle  ) 

Disable sequence number checking.

Parameters:
handle Netlink handle.
Disables checking of sequence numbers on the netlink handle. This is required to allow messages to be processed which were not requested by a preceding request message, e.g. netlink events.

Definition at line 304 of file nl.c.

References NL_CB_CUSTOM, NL_CB_SEQ_CHECK, nl_cb_set(), and nl_handle_get_cb().

pid_t nl_handle_get_pid ( struct nl_handle *  handle  ) 

Get netlink process identifier of netlink handle.

Parameters:
handle Netlink handle.
Returns:
Netlink process identifier.

Definition at line 322 of file nl.c.

void nl_handle_set_pid ( struct nl_handle *  handle,
pid_t  pid 
)

Set netlink process identifier of netlink handle.

Parameters:
handle Netlink handle.
pid New netlink process identifier.

Definition at line 332 of file nl.c.

pid_t nl_handle_get_peer_pid ( struct nl_handle *  handle  ) 

Get netlink process identifier of peer from netlink handle.

Parameters:
handle Netlink handle.
Returns:
Netlink process identifier.

Definition at line 342 of file nl.c.

void nl_handle_set_peer_pid ( struct nl_handle *  handle,
pid_t  pid 
)

Set netlink process identifier of peer in netlink handle.

Parameters:
handle Netlink handle.
pid New netlink process identifier.

Definition at line 352 of file nl.c.

int nl_handle_get_fd ( struct nl_handle *  handle  ) 

Get file descriptor of netlink handle.

Parameters:
handle Netlink handle.
Returns:
File descriptor of netlink socket or -1 if not connected.

Definition at line 362 of file nl.c.

struct sockaddr_nl* nl_handle_get_local_addr ( struct nl_handle *  handle  ) 

Get local netlink address of netlink handle.

Parameters:
handle Netlink handle.
Returns:
Local netlink address.

Definition at line 372 of file nl.c.

struct sockaddr_nl* nl_handle_get_peer_addr ( struct nl_handle *  handle  ) 

Get peer netlink address of netlink handle.

Parameters:
handle Netlink handle.
Note:
The peer address is undefined while the socket is unconnected.
Returns:
Netlink address of the peer.

Definition at line 383 of file nl.c.

struct nl_cb* nl_handle_get_cb ( struct nl_handle *  handle  ) 

Get callback configuration of netlink handle.

Parameters:
handle Netlink handle.
Returns:
Currently active callback configuration or NULL if not available.

Definition at line 393 of file nl.c.

Referenced by nl_cache_pickup(), nl_disable_sequence_check(), nl_sendmsg(), and nl_wait_for_ack().

int nl_connect ( struct nl_handle *  handle,
int  protocol 
)

Create and connect netlink socket.

Parameters:
handle Netlink handle.
protocol Netlink protocol to use.
Creates a netlink socket using the specified protocol, binds the socket and issues a connection attempt.

Returns:
0 on success or a negative error code.

Definition at line 415 of file nl.c.

References nl_set_buffer_size().

void nl_close ( struct nl_handle *  handle  ) 

Close/Disconnect netlink socket.

Parameters:
handle Netlink handle

Definition at line 456 of file nl.c.

int nl_sendto ( struct nl_handle *  handle,
void *  buf,
size_t  size 
)

Send raw data over netlink socket.

Parameters:
handle Netlink handle.
buf Data buffer.
size Size of data buffer.
Returns:
Number of characters written on success or a negative error code.

Definition at line 480 of file nl.c.

int nl_sendmsg ( struct nl_handle *  handle,
struct nl_msg *  msg,
struct msghdr *  hdr 
)

Send netlink message with control over sendmsg() message header.

Parameters:
handle Netlink handle.
msg Netlink message to be sent.
hdr Sendmsg() message header.
Returns:
Number of characters sent on sucess or a negative error code.

Definition at line 499 of file nl.c.

References NL_CB_MSG_OUT, nl_handle_get_cb(), NL_PROCEED, nlmsg_hdr(), nlmsghdr::nlmsg_len, and nlmsg_set_src().

Referenced by nl_send().

int nl_send ( struct nl_handle *  handle,
struct nl_msg *  msg 
)

Send netlink message.

Parameters:
handle Netlink handle
msg Netlink message to be sent.
See also:
nl_sendmsg()
Returns:
Number of characters sent on success or a negative error code.

Definition at line 534 of file nl.c.

References sockaddr_nl::nl_family, nl_sendmsg(), nlmsg_get_creds(), and nlmsg_get_dst().

Referenced by nl_send_auto_complete().

int nl_send_auto_complete ( struct nl_handle *  handle,
struct nl_msg *  msg 
)

Send netlink message and check & extend header values as needed.

Parameters:
handle Netlink handle.
msg Netlink message to be sent.
Checks the netlink message nlh for completness and extends it as required before sending it out. Checked fields include pid, sequence nr, and flags.

See also:
nl_send()
Returns:
Number of characters sent or a negative error code.

Definition at line 582 of file nl.c.

References nl_send(), NLM_F_ACK, NLM_F_REQUEST, nlmsghdr::nlmsg_flags, nlmsg_hdr(), nlmsghdr::nlmsg_pid, and nlmsghdr::nlmsg_seq.

Referenced by flnl_lookup(), nl_send_simple(), rtnl_addr_add(), rtnl_addr_delete(), rtnl_class_add(), rtnl_cls_add(), rtnl_cls_change(), rtnl_cls_delete(), rtnl_link_change(), rtnl_neigh_add(), rtnl_neigh_change(), rtnl_neigh_delete(), rtnl_neightbl_change(), rtnl_qdisc_add(), rtnl_qdisc_change(), rtnl_qdisc_delete(), rtnl_rule_add(), and rtnl_rule_delete().

int nl_send_simple ( struct nl_handle *  handle,
int  type,
int  flags,
void *  buf,
size_t  size 
)

Send simple netlink message using nl_send_auto_complete().

Parameters:
handle Netlink handle.
type Netlink message type.
flags Netlink message flags.
buf Data buffer.
size Size of data buffer.
Builds a netlink message with the specified type and flags and appends the specified data as payload to the message.

See also:
nl_send_auto_complete()
Returns:
Number of characters sent on success or a negative error code.

Definition at line 615 of file nl.c.

References nl_send_auto_complete(), nlmsg_append(), nlmsg_build(), nlmsg_free(), nlmsghdr::nlmsg_len, and nlmsg_msg_size().

Referenced by nl_rtgen_request().

int nl_recv ( struct nl_handle *  handle,
struct sockaddr_nl nla,
unsigned char **  buf,
struct ucred **  creds 
)

Receive netlink message from netlink socket.

Parameters:
handle Netlink handle.
nla Destination pointer for peer's netlink address.
buf Destination pointer for message content.
creds Destination pointer for credentials.
Receives a netlink message, allocates a buffer in *buf and stores the message content. The peer's netlink address is stored in *nla. The caller is responsible for freeing the buffer allocated in *buf if a positive value is returned. Interruped system calls are handled by repeating the read. The input buffer size is determined by peeking before the actual read is done.

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

Returns:
Number of octets read, 0 on EOF or a negative error code.

Definition at line 665 of file nl.c.

Referenced by nl_recvmsgs().

int nl_recvmsgs ( struct nl_handle *  handle,
struct nl_cb *  cb 
)

Receive a set of messages from a netlink socket.

Parameters:
handle netlink handle
cb set of callbacks to control the behaviour.
Repeatedly calls nl_recv() and parses the messages as netlink messages. Stops reading if one of the callbacks returns NL_EXIT 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.

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

Definition at line 765 of file nl.c.

References NL_CB_ACK, NL_CB_FINISH, NL_CB_INVALID, NL_CB_MSG_IN, NL_CB_OVERRUN, NL_CB_SEND_ACK, NL_CB_SEQ_CHECK, NL_CB_SKIPPED, NL_CB_VALID, NL_EXIT, nl_recv(), NL_SKIP, NLM_F_ACK, nlmsg_convert(), nlmsg_data(), NLMSG_DONE, NLMSG_ERROR, nlmsg_free(), nlmsg_msg_size(), nlmsg_next(), NLMSG_NOOP, nlmsg_ok(), NLMSG_OVERRUN, nlmsg_set_creds(), nlmsg_set_proto(), and nlmsg_set_src().

Referenced by nl_cache_pickup(), nl_recvmsgs_def(), and nl_wait_for_ack().

int nl_recvmsgs_def ( struct nl_handle *  handle  ) 

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

Parameters:
handle netlink handle
Calls nl_recvmsgs() with the handlers configured in the netlink handle.

Definition at line 986 of file nl.c.

References nl_recvmsgs().

int nl_wait_for_ack ( struct nl_handle *  handle  ) 

Wait for ACK.

Parameters:
handle netlink handle
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 1007 of file nl.c.

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

Referenced by rtnl_addr_add(), rtnl_addr_delete(), rtnl_class_add(), rtnl_cls_add(), rtnl_cls_change(), rtnl_cls_delete(), rtnl_link_change(), rtnl_neigh_add(), rtnl_neigh_change(), rtnl_neigh_delete(), rtnl_neightbl_change(), rtnl_qdisc_add(), rtnl_qdisc_change(), rtnl_qdisc_delete(), rtnl_rule_add(), and rtnl_rule_delete().

char* nl_nlfamily2str ( int  family,
char *  buf,
size_t  size 
)

Convert netlink family to character string.

Parameters:
family Netlink family.
buf Destination buffer.
size Size of destination buffer.
Converts a netlink family to a character string and stores it in the specified destination buffer.

Returns:
The destination buffer or the family encoded in hexidecimal form if no match was found.

Definition at line 1059 of file nl.c.

int nl_str2nlfamily ( const char *  name  ) 

Convert character string to netlink family.

Parameters:
name Name of netlink family.
Converts the provided character string specifying a netlink family to the corresponding numeric value.

Returns:
Numeric netlink family or a negative value if no match was found.

Definition at line 1074 of file nl.c.


Generated on Fri Apr 27 14:14:07 2007 for libnl by  doxygen 1.5.1