Netlink Library (libnl)

The libraries provide a broad set of APIs of which most applications only require a small subset of it. Depending on the type of application, some users may only be interested in the low level netlink messaging API while others wish to make heavy use of the high level API.

In any case it is recommended to get familiar with the netlink protocol first.

The low level APIs are described in:

Projects using autoconf may use PKG_CHECK_MODULES() to check if a specific version of libnl is available on the system. The example below also shows how to retrieve the CFLAGS and linking dependencies required to link against the library.

The following example shows how to check for a specific version of libnl. If found, it extends the CFLAGS and LIBS variable appropriately:

The main header file is <netlink/netlink.h>. Additional headers may need to be included in your sources depending on the subsystems and components your program makes use of.

If your code wishes to be capable to link against multiple versions of libnl you may have direct the compiler to only include portions on the code depending on the version of libnl that it is compiled against.

The library has been compiled with debugging statements enabled it will print debug information to stderr if the environment variable NLDBG is set to > 0.

It is often useful to peek into the stream of netlink messages exchanged with other sockets. Setting the environment variable NLCB=debug will cause the debugging message handlers to be used which in turn print the netlink messages exchanged in a human readable format to to stderr:

The netlink address (port) consists of a 32bit integer. Port 0 (zero) is reserved for the kernel and refers to the kernel side socket of each netlink protocol family. Other port numbers usually refer to user space owned sockets, although this is not enforced.

The above figure illustrates three applications and the kernel side exposing two kernel side sockets. It shows the common netlink use cases:

The most common form of netlink usage is for a user space application to send requests to the kernel and process the reply which is either an error message or a success notification.

Netlink may also be used as an IPC mechanism to communicate between user space applications directly. Communication is not limited to two peers, any number of peers may communicate with each other and multicasting capabilities allow to reach multiple peers with a single message.

In order for the sockets to be visible to each other, both sockets must be created for the same netlink protocol family.

This form of netlink communication is typically found in user space daemons that need to act on certain kernel events. Such daemons will typically maintain a netlink socket subscribed to a multicast group that is used by the kernel to notify interested user space parties about specific events.

Use of multicasting is preferred over direct addressing due to the flexibility in exchanging the user space component at any time without the kernel noticing.

A netlink protocol is typically based on messages and consists of the netlink message header (struct nlmsghdr) plus the payload attached to it. The payload can consist of arbitrary data but usually contains a fixed size protocol specific header followed by a stream of attributes.

Netlink differs between requests, notifications, and replies. Requests are messages which have the NLM_F_REQUEST flag set and are meant to request an action from the receiver. A request is typically sent from a userspace process to the kernel. While not strictly enforced, requests should carry a sequence number incremented for each request sent.

Depending on the nature of the request, the receiver may reply to the request with another netlink message. The sequence number of a reply must match the sequence number of the request it relates to.

Notifications are of informal nature and no reply is expected, therefore the sequence number is typically set to 0.

The type of message is primarly identified by its 16 bit message type set in the message header. The following standard message types are defined:

Every netlink protocol is free to define own message types. Note that message type values < NLMSG_MIN_TYPE (0x10) are reserved and may not be used.

It is common practice to use own message types to implement RPC schemas. Suppose the goal of the netlink protocol you are implementing is allow configuration of a particular network device, therefore you want to provide read/write access to various configuration options. The typical "netlink way" of doing this would be to define two message types MSG_SETCFG, MSG_GETCFG:

Sending a MSG_GETCFG request message will typically trigger a reply with the message type MSG_SETCFG containing the current configuration. In object oriented terms one would describe this as "the kernel sets the local copy of the configuration in userspace".

The configuration may be changed by sending a MSG_SETCFG which will be responded to with either a ACK (see ACKs) or a error message (see Error Message).

Optionally, the kernel may send out notifications for configuration changes allowing userspace to listen for changes instead of polling frequently. Notifications typically reuse an existing message type and rely on the application using a separate socket to differ between requests and notifications but you may also specify a separate message type.

Netlink allows the use of sequence numbers to help relate replies to requests. It should be noted that unlike in protocols such as TCP there is no strict enforcment of the sequence number. The sole purpose of sequence numbers is to assist a sender in relating replies to the corresponding requests. See Message Types for more information.

Sequence numbers are managed on a per socket basis, see Sequence Numbers for more information on how to use sequence numbers.

TODO

See Multicast Group Subscriptions

The netlink socket and all related attributes including the actual file descriptor are represented by struct nl_sock.

The application must allocate an instance of struct nl_sock for each netlink socket it wishes to use.

The library will automatically take care of sequence number handling for the application. A sequence number counter is stored in the socket structure which is used and incremented automatically when a message needs to be sent which is expected to generate a reply such as an error or any other message type that needs to be related to the original message.

Alternatively, the counter can be used directly via the function nl_socket_use_seq(). It will return the current value of the counter and increment it by one afterwards.

Most applications will not want to deal with sequence number handling themselves though. When using nl_send_auto() the sequence number is filled in automatically and matched again when a reply is received. See section Sending and Receiving of Messages / Data for more information.

This behaviour can and must be disabled if the netlink protocol implemented does not use a request/reply model, e.g. when a socket is used to receive notification messages.

For more information on the theory behind netlink sequence numbers, see section Sequence Numbers.

Each socket can subscribe to any number of multicast groups of the netlink protocol it is connected to. The socket will then receive a copy of each message sent to any of the groups. Multicast groups are commonly used to implement event notifications.

Prior to kernel 2.6.14 the group subscription was performed using a bitmask which limited the number of groups per protocol family to 32. This outdated interface can still be accessed via the function nl_join_groups() even though it is not recommended for new code.

Starting with 2.6.14 a new method was introduced which supports subscribing to an almost infinite number of multicast groups.

See Callback Configurations for more information on callback hooks and overwriting capabilities.

Each socket is assigned a callback configuration which controls the behaviour of the socket. This is f.e. required to have a separate message receive function per socket. It is perfectly legal to share callback configurations between sockets though.

The following functions can be used to access and set the callback configuration of a socket:

Additionaly a shortcut exists to modify the callback configuration assigned to a socket directly:

The local port number uniquely identifies the socket and is used to address it. A unique local port is generated automatically when the socket is allocated. It will consist of the Process ID (22 bits) and a random number (10 bits) thus allowing up to 1024 sockets per process.

See section Addressing for more information on port numbers.

A peer port can be assigned to the socket which will result in all unicast messages sent over the socket to be addresses to the peer. If no peer is specified, the message is sent to the kernel which will try to automatically bind the socket to a kernel side socket of the same netlink protocol family. It is common practice not to bind the socket to a peer port as typically only one kernel side socket exists per netlink protocol family.

See section Addressing for more information on port numbers.

Netlink uses the BSD socket interface, therefore a file descriptor is behind each socket and you may use it directly.

If a socket is used to only receive notifications it usually is best to put the socket in non-blocking mode and periodically poll for new notifications.

The socket buffer is used to queue netlink messages between sender and receiver. The size of these buffers specifies the maximum size you will be able to write() to a netlink socket, i.e. it will indirectly define the maximum message size. The default is 32KiB.

TODO

The following functions allow to enable/disable Auto-ACK mode on a socket. See Auto-ACK Mode for more information on what implications that has. Auto-ACK mode is enabled by default.

If enabled, message peeking causes nl_recv() to try and use MSG_PEEK to retrieve the size of the next message received and allocate a buffer of that size. Message peeking is enabled by default but can be disabled using the following function:

If enabled, each received netlink message from the kernel will include an additional struct nl_pktinfo in the control message. The following function can be used to enable/disable receival of packet information.

The standard method of sending a netlink message over a netlink socket is to use the function nl_send_auto(). It will automatically complete the netlink message by filling the missing bits and pieces in the netlink message header and will deal with addressing based on the options and address set in the netlink socket. The message is then passed on to nl_send().

If the default sending semantics implemented by nl_send() do not suit the application, it may overwrite the sending function nl_send() by specifying an own implementation using the function nl_cb_overwrite_send().

If you do not require any of the automatic message completion functionality you may use nl_send() directly but beware that any internal calls to nl_send_auto() by the library to send netlink messages will still use nl_send(). Therefore if you wish to use any higher level interfaces and the behaviour of nl_send() is to your dislike then you must overwrite the nl_send() function via nl_cb_overwrite_send()

The purpose of nl_send() is to embed the netlink message into a iovec structure and pass it on to nl_send_iovec().

nl_send_iovec() expects a finalized netlink message and fills out the struct msghdr used for addressing. It will first check if the struct nl_msg is addressed to a specific peer (see nlmsg_set_dst()). If not, it will try to fall back to the peer address specified in the socket (see nl_socket_set_peer_port(). Otherwise the message will be sent unaddressed and it is left to the kernel to find the correct peer.

nl_send_iovec() also adds credentials if present and enabled (see [core_sk_cred]).

The message is then passed on to nl_sendmsg().

nl_sendmsg() expects a finalized netlink message and an optional struct msghdr containing the peer address. It will copy the local address as defined in the socket (see nl_socket_set_local_port()) into the netlink message header.

At this point, construction of the message finished and it is ready to be sent.

Before sending the application has one last chance to modify the message. It is passed to the NL_CB_MSG_OUT callback function which may inspect or modify the message and return an error code. If this error code is NL_OK the message is sent using sendmsg() resulting in the number of bytes written being returned. Otherwise the message sending process is aborted and the error code specified by the callback function is returned. See Modifiying Socket Callback Configuration for more information on how to set callbacks.

If you wish to send raw data over a netlink socket, the following function will pass on any buffer provided to it directly to sendto():

A special interface exists for sending of trivial messages. The function expects the netlink message type, optional netlink message flags, and an optional data buffer and data length.

The function will construct a netlink message header based on the message type and flags provided and append the data buffer as message payload. The newly constructed message is sent with nl_send_auto().

The following example will send a netlink request message causing the kernel to dump a list of all network links to userspace:

The easiest method to receive netlink messages is to call nl_recvmsgs_default(). It will receive messages based on the semantics defined in the socket. The application may customize these in detail although the default behaviour will probably suit most applications.

nl_recvmsgs_default() will also be called internally by the library whenever it needs to receive and parse a netlink message.

The function will fetch the callback configuration stored in the socket and call nl_recvmsgs():

nl_recvmsgs() implements the actual receiving loop, it blocks until a netlink message has been received unless the socket has been put into non-blocking mode.

For the unlikely scenario that certain required receive characteristics can not be achieved by fine tuning the internal recvmsgs function using the callback configuration (see Modifiying Socket Callback Configuration) the application may provide a complete own implementation of it and overwrite all calls to nl_recvmsgs() with the function nl_cb_overwrite_recvmsgs().

If the application does not provide its own recvmsgs() implementation with the function nl_cb_overwrite_recvmsgs() the following characteristics apply while receiving data from a netlink socket:

The function nl_recv() is invoked first to receive data from the netlink socket. This function may be overwritten by the application by an own implementation using the function nl_cb_overwrite_recv(). This may be useful if the netlink byte stream is in fact not received from a socket directly but is read from a file or another source.

If data has been read, it will be attemped to parse the data. This will be done repeately until the parser returns NL_STOP, an error was returned or all data has been parsed.

In case the last message parsed successfully was a multipart message (see Multipart Messages) and the parser did not quit due to either an error or NL_STOP nl_recv() respectively the applications own implementation will be called again and the parser starts all over.

See [core_parse_character] for information on how to extract valid netlink messages from the parser and on how to control the behaviour of it.

The internal parser is invoked for each netlink message received from a netlink socket. It is typically fed by nl_recv() (see [core_recv_character]).

The parser will first ensure that the length of the data stream provided is sufficient to contain a netlink message header and that the message length as specified in the message header does not exceed it.

If this criteria is met, a new struct nl_msg is allocated and the message is passed on to the the callback function NL_CB_MSG_IN if one is set. Like any other callback function, it may return NL_SKIP to skip the current message but continue parsing the next message or NL_STOP to stop parsing completely.

The next step is to check the sequence number of the message against the currently expected sequence number. The application may provide its own sequence number checking algorithm by setting the callback function NL_CB_SEQ_CHECK to its own implementation. In fact, calling nl_socket_disable_seq_check() to disable sequence number checking will do nothing more than set the NL_CB_SEQ_CHECK hook to a function which always returns NL_OK.

Another callback hook NL_CB_SEND_ACK exists which is called if the message has the NLM_F_ACK flag set. Although I am not aware of any userspace netlink socket doing this, the application may want to send an ACK message back to the sender (see ACKs).

TODO

See Netlink Protocol Fundamentals for an introduction to the netlink protocol and its message format.

Most netlink protocols enforce a strict alignment policy for all boundries. The alignment value is defined by NLMSG_ALIGNTO and is fixed to 4 bytes. Therefore all netlink message headers, begin of payload sections, protocol specific headers, and attribute sections must start at an offset which is a multiple of NLMSG_ALIGNTO.

The library provides a set of function to handle alignment requirements automatically. The function nlmsg_total_size() returns the total size of a netlink message including the padding to ensure the next message header is aligned correctly.

If you need to know if padding needs to be added at the end of a message, nlmsg_padlen() returns the number of padding bytes that need to be added for a specific payload length.

The library offers two different methods of parsing netlink messages. It offers a low level interface for applications which want to do all the parsing manually. This method is described below. Alternatively the library also offers an interface to implement a parser as part of a cache operations set which is especially useful when your protocol deals with objects of any sort such as network links, routes, etc. This high level interface is described in Cache System.

What you receive from a netlink socket is typically a stream of messages. You will be given a buffer and its length, the buffer may contain any number of netlink messages.

The first message header starts at the beginning of message stream. Any subsequent message headers are access by calling nlmsg_next() on the previous header.

The function nlmsg_next() will automatically substract the size of the previous message from the remaining number of bytes.

Please note, there is no indication in the previous message whether another message follows or not. You must assume that more messages follow until all bytes of the message stream have been processed.

To simplify this, the function nlmsg_ok() exists which returns true if another message fits into the remaining number of bytes in the message stream. nlmsg_valid_hdr() is similar, it checks whether a specific netlink message contains at least a minimum of payload.

A typical use of these functions looks like this:

The above can also be written using the iterator nlmsg_for_each():

The message payload is appended to the message header and is guranteed to start at a multiple of NLMSG_ALIGNTO. Padding at the end of the message header is added if necessary to ensure this. The function nlmsg_data() will calculate the necessary offset based on the message and returns a pointer to the start of the message payload.

The length of the message payload is returned by nlmsg_datalen().

The payload may consist of arbitary data but may have strict alignment and formatting rules depening on the actual netlink protocol.

Most netlink protocols use netlink attributes. It not only makes the protocol self documenting but also gives flexibility in expanding the protocol at a later point. New attributes can be added at any time and older attributes can be obsoleted by newer ones without breaking binary compatibility of the protocol.

The function nlmsg_attrdata() returns a pointer to the begin of the attributes section. The length of the attributes section is returned by the function nlmsg_attrlen().

See Attributes for more information on how to use netlink attributes.

The function nlmsg_parse() validate a complete netlink message in one step. If hdrlen > 0 it will first call nlmsg_valid_hdr() to check if the protocol header fits into the message. If there is more payload to parse, it will assume it to be attributes and parse the payload accordingly. The function behaves exactly like nla_parse() when parsing attributes, see [core_attr_parse_easy].

The function nlmsg_validate() is based on nla_validate() and behaves exactly the same as nlmsg_parse() except that it only validates and will not fill a array with pointers to each attribute.

See [core_attr_parse_easy] for an example and more information on attribute parsing.

See Message Format for information on the netlink message format and alignment requirements.

Message construction is based on struct nl_msg which uses an internal buffer to store the actual netlink message. struct nl_msg does not point to the netlink message header. Use nlmsg_hdr() to retrieve a pointer to the netlink message header.

At allocation time, a maximum message size is specified. It defaults to a page (PAGE_SIZE). The application constructing the message will reserve space out of this maximum message size repeatedly for each header or attribute added. This allows construction of messages across various layers of code where lower layers do not need to know about the space requirements of upper layers.

Why is setting the maximum message size necessary? This question is often raised in combination with the proposed solution of reallocating the message payload buffer on the fly using realloc(). While it is possible to reallocate the buffer during construction using nlmsg_expand() it will make all pointers into the message buffer become stale. This breaks usage of nlmsg_hdr(), nla_nest_start(), and nla_nest_end() and is therefore not acceptable as default behaviour.

The first step in constructing a new netlink message it to allocate a struct nl_msg to hold the message header and payload. Several functions exist to simplify various tasks.

The function nlmsg_alloc() is the default message allocation function. It allocates a new message using the default maximum message size which equals to one page (PAGE_SIZE). The application can change the default size for messages by calling nlmsg_set_default_size():

Instead of changing the default message size, the function nlmsg_alloc_size() can be used to allocate a message with a individual maximum message size.

If the netlink message header is already known at allocation time, the application may sue nlmsg_inherit(). It will allocate a message using the default maximum message size and copy the header into the message. Calling nlmsg_inherit with set to NULL is equivalent to calling nlmsg_alloc().

Alternatively nlmsg_alloc_simple() takes a netlink message type and netlink message flags. It is equivalent to nlmsg_inherit() except that it takes the two common header fields as arguments instead of a complete header.

After allocating struct nl_msg, the netlink message header needs to be added unless one of the function nlmsg_alloc_simple() or nlmsg_inherit() have been used for allocation in which case this step will replace the netlink message header already in place.

The function nlmsg_put() will build a netlink message header out of nlmsg_type, nlmsg_flags, seqnr, and port and copy it into the netlink message. seqnr can be set to NL_AUTO_SEQ to indiciate that the next possible sequence number should be used automatically. To use this feature, the message must be sent using the function nl_send_auto(). Like port, the argument seqnr can be set to NL_AUTO_PORT indicating that the local port assigned to the socket should be used as source port. This is generally a good idea unless you are replying to a request. See Netlink Protocol Fundamentals for more information on how to fill the header.

Most functions described later on will automatically take care of reserving room for the data that is added to the end of the netlink message. In some situations it may be requried for the application to reserve room directly though.

The function nlmsg_reserve() reserves len bytes at the end of the netlink message and returns a pointer to the start of the reserved area. The pad argument can be used to request len to be aligned to any number of bytes prior to reservation.

The following example requests to reserve a 17 bytes area at the end of message aligned to 4 bytes. Therefore a total of 20 bytes will be reserved.

The function nlmsg_append() appends len bytes at the end of the message, padding it if requested and necessary.

It is equivalent to calling nlmsg_reserve() and `memcpy()`ing the data into the freshly reserved data section.

Construction of attributes and addition of attribtues to the message is covereted in section Attributes.

Netlink attributes allow for any number of data chunks of arbitary length to be attached to a netlink message. See [core_msg_attr] for more information on where attributes are stored in the message.

The format of the attributes data returned by nlmsg_attrdata() is as follows:

Every attribute must start at an offset which is a multiple of NLA_ALIGNTO (4 bytes). If you need to know whether an attribute needs to be padded at the end, the function nla_padlen() returns the number of padding bytes that will or need to be added.

Every attribute is encoded with a type and length field, both 16 bits, stored in the attribute header (struct nlattr) preceding the attribute payload. The length of an attribute is used to calculate the offset to the next attribute.

Although most applications will use one of the functions from the nlmsg_parse() family (See [core_attr_parse_easy]) an interface exists to split the attributes stream manually.

As described in Attribute Format the attributes section contains a infinite sequence or stream of attributes. The pointer returned by nlmsg_attrdata() (See [core_msg_attr]) points to the first attribute header. Any subsequent attribute is accessed with the function nla_next() based on the previous header.

The semantics are equivalent to nlmsg_next() and thus nla_next() will also subtract the size of the previous attribute from the remaining number of bytes in the attributes stream.

Like messages, attributes do not contain an indicator whether another attribute follows or not. The only indication is the number of bytes left in the attribute stream. The function nla_ok() exists to determine whether another attribute fits into the remaining number of bytes or not.

A typical use of nla_ok() and nla_next() looks like this:

Once the individual attributes have been sorted out by either splitting the attributes stream or using another interface the attribute header and payload can be accessed.

The functions nla_len() and nla_type() can be used to access the attribute header. nla_len() will return the length of the payload not including eventual padding bytes. nla_type returns the attribute type.

The function nla_data() will return a pointer to the attribute payload. Please note that due to NLA_ALIGNTO being 4 bytes it may not be safe to cast and dereference the pointer for any datatype larger than 32 bit depending on the architecture the application is run on.

When receiving netlink attributes, the receiver has certain expections on how the attributes should look like. These expectations must be defined to make sure the sending side meets our expecations. For this purpose, a attribute validation interface exists which must be used prior to accessing any payload.

All functions providing attribute validation functionality are based on struct nla_policy:

The type member specifies the datatype of the attribute, e.g. NLA_U32, NLA_STRING, NLA_FLAG. The default is NLA_UNSPEC. The minlen member defines the minmum payload length of an attribute to be considered a valid attribute. The value for minlen is implicit for most basic datatypes such as integers or flags. The maxlen member can be used to define a maximum payload length for an attribute to still be considered valid.

One of the functions which use struct nla_policy is nla_validate(). The function expects an array of struct nla_policy and will access the array using the attribute type as index. If an attribute type is out of bounds the attribute is assumed to be valid. This is intentional behaviour to allow older applications not yet aware of recently introduced attributes to continue functioning.

The function nla_validate() returns 0 if all attributes are valid, otherwise a validation failure specific error code is returned.

Most applications will rarely use nla_validate() directly but use nla_parse() instead which takes care of validation in the same way but also parses the the attributes in the same step. See [core_attr_parse_easy] for an example and more information.

The validation process in detail:

Most applications will not want to deal with splitting attribute streams themselves as described in [core_attr_parse_split] A much easier method is to use nla_parse().

The function nla_parse() will iterate over a stream of attributes, validate each attribute as described in [core_attr_validation] If the validation of all attributes succeeds, a pointer to each attribute is stored in the attrs array at attrs[nla_type(attr)].

As an alernative to nla_parse() the function nlmsg_parse() can be used to parse the message and its attributes in one step. See [core_attr_parse_easy] for information on how to use these functions.

The following example demonstrates how to parse a netlink message sent over a netlink protocol which does not use protocol headers. The example does enforce a attribute policy however, the attribute MY_ATTR_FOO must be a 32 bit integer, and the attribute MY_ATTR_BAR must be a string with a maximum length of 16 characters.

An application only interested in a single attribute can use one of the functions nla_find() or nlmsg_find_attr(). These function will iterate over all attributes, search for a matching attribute and return a pointer to the corresponding attribute header.

The interface to add attributes to a netlink message is based on the regular message construction interface. It assumes that the message header and an eventual protocol header has been added to the message already.

The function nla_reserve() adds an attribute header at the end of the message and reserves room for len bytes of payload. The function returns a pointer to the attribute payload section inside the message. Padding is added at the end of the attribute to ensure the next attribute is properly aligned.

The function nla_put() is base don nla_reserve() but takes an additional pointer data pointing to a buffer containing the attribute payload. It will copy the buffer into the message automatically.

See Attribute Data Types for datatype specific attribute construction functions.

Like in the kernel API an exception based construction interface is provided. The behaviour of the macros is identical to their regular function counterparts except that in case of an error, the target nla_put_failure is jumped.

See Attribute Data Types for more information on the datatype specific exception based variants.

A number of basic data types have been defined to simplify access and validation of attributes. The datatype is not encoded in the attribute, therefore bthe sender and receiver are required to use the same definition on what attribute is of what type.

Besides simplified access to the payload of such datatypes, the major advantage is the automatic validation of each attribute based on a policy. The validation ensures safe access to the payload by checking for minimal payload size and can also be used to enforce maximum payload size for some datatypes.

Callback hooks are spread across the library to provide entry points for message processing and to take action upon certain events.

Callback functions may return the following return codes:

The library provides three sets of default callback implementations: * NL_CB_DEFAULT This is the default set. It implets the default behaviour. See the table below for more information on the return codes of each function. * NL_CB_VERBOSE This set is based on the default set but will cause an error message to be printed to stderr for error messages, invalid messages, message overruns and unhandled valid messages. The arg pointer in nl_cb_set() and nl_cb_err() can be used to provide a FILE * which overwrites stderr. * NL_CB_DEBUG This set is intended for debugging purposes. It is based on the verbose set but will decode and dump each message sent or received to the console.

Any function called by NL_CB_MSG_OUT may return a negative error code to prevent the message from being sent and the error code being returned.

nl_recvmsgs() callback hooks (ordered by priority):

Any of these functions may return NL_OK, NL_SKIP, or NL_STOP.

Message processing callback functions are set with nl_cb_set():

A special function prototype is used for the error message callback hook:

When the library needs to send or receive netlink messages in high level interfaces it does so by calling its own low level API. In the case the default characteristics are not sufficient for the application, it may overwrite several internal function calls with own implementations.

See Receiving Netlink Messages for more information on how and when recvmsgs() is called internally.

The following criteras must be met if a recvmsgs() implementation is supposed to work with high level interfaces:

Often it is sufficient to overwrite nl_recv() which is responsible from receiving the actual data from the socket instead of replacing the complete recvmsgs() logic.

See Receive Characteristics for more information on how and when nl_recv() is called internally.

The following criteras must be met for an own nl_recv() implementation:

See Sending Netlink Messages for more information on how and when nl_send() is called internally.

Own implementations must send the netlink message and return 0 on success or a negative error code.

Almost all subsystem provide a function to allocate a new cache of some form. The function usually looks like this:

These functions allocate a new cache for the own object type, initializes it properly and updates it to represent the current state of their master, e.g. a link cache would include all links currently configured in the kernel.

Some of the allocation functions may take additional arguments to further specify what will be part of the cache.

All such functions return a newly allocated cache or NULL in case of an error.

The purpose of a cache manager is to keep track of caches and automatically receive event notifications to keep the caches up to date with the kernel state. Each manager has exactly one netlink socket assigned which limits the scope of each manager to exactly one netlink family. Therefore all caches committed to a manager must be part of the same netlink family. Due to the nature of a manager, it is not possible to have a cache maintain two instances of the same cache type. The socket is subscribed to the event notification group of each cache and also put into non-blocking mode. Functions exist to poll() on the socket to wait for new events to be received.

Most netlink protocols deal with networking related topics and thus dealing with network addresses is a common task.

Currently the following address families are supported:

The function nl_addr_alloc() allocates a new empty address. The maxsize argument defines the maximum length of an address in bytes. The size of an address is address family specific. If the address family and address data are known at allocation time the function nl_addr_build() can be used alternatively. You may also clone an address by calling nl_addr_clone()

If the address is transported in a netlink attribute, the function nl_addr_alloc_attr() allocates a new address based on the payload of the attribute provided. The family argument is used to specify the address family of the address, set to AF_UNSPEC if unknown.

If the address is provided by a user, it is usually stored in a human readable format. The function nl_addr_parse() parses a character string representing an address and allocates a new address based on it.

If parsing succeeds the function returns 0 and the allocated address is stored in *result.

Abstract addresses use reference counting to account for all users of a particular address. After the last user has returned the reference the address is freed.

If you pass on a address object to another function and you are not sure how long it will be used, make sure to call nl_addr_get() to acquire an additional reference and have that function or code path call nl_addr_put() as soon as it has finished using the address.

You may call nl_addr_shared() at any time to check if you are the only user of an address.

The address is usually set at allocation time. If it was unknown at that time it can be specified later by calling nl_addr_set_family() and is accessed with the function nl_addr_get_family().

The same is true for the actual address data. It is typically present at allocation time. For exceptions it can be specified later or overwritten with the function nl_addr_set_binary_addr(). Beware that the length of the address may not exceed maxlen specified at allocation time. The address data is returned by the function nl_addr_get_binary_addr() and its length by the function nl_addr_get_len().

If you only want to check if the address data consists of all zeros the function nl_addr_iszero() is a shortcut to that.

The abstract data type is a trivial datatype with the primary purpose to simplify usage of netlink attributes of arbitary length.

The function nl_data_alloc() alloctes a new abstract data object and fill it with the provided data. nl_data_alloc_attr() does the same but bases the data on the payload of a netlink attribute. New data objects can also be allocated by cloning existing ones by using nl_data_clone().

The function nl_data_get() returns a pointer to the data, the size of data is returned by nl_data_get_size().

The function nl_data_append() reallocates the internal data buffers and appends the specified buf to the existing data.