Modules | Defines

Messages
[Core]

Netlink Message Construction/Parsing Interface. More...

Modules

 Attributes
 

Netlink Attributes Construction/Parsing Interface.


Defines

#define NL_AUTO_PORT   0
 Will cause the netlink port to be set to the port assigned to the netlink icoket ust before sending the message off.
#define NL_AUTO_SEQ   0
 May be used to refer to a sequence number which should be automatically set just before sending the message off.

Netlink Message Type Translations



char * nl_nlmsgtype2str (int type, char *buf, size_t size)
int nl_str2nlmsgtype (const char *name)

Size Calculations



int nlmsg_size (int payload)
 Calculates size of netlink message based on payload length.
int nlmsg_msg_size (int payload)
int nlmsg_total_size (int payload)
 Calculates size of netlink message including padding based on payload length.
int nlmsg_padlen (int payload)
 Size of padding that needs to be added at end of message.

Access to Message Payload



void * nlmsg_data (const struct nlmsghdr *nlh)
 Return pointer to message payload.
void * nlmsg_tail (const struct nlmsghdr *nlh)
int nlmsg_datalen (const struct nlmsghdr *nlh)
 Return length of message payload.
int nlmsg_len (const struct nlmsghdr *nlh)

Attribute Access



struct nlattr * nlmsg_attrdata (const struct nlmsghdr *nlh, int hdrlen)
 head of attributes data
int nlmsg_attrlen (const struct nlmsghdr *nlh, int hdrlen)
 length of attributes data

Message Parsing



int nlmsg_valid_hdr (const struct nlmsghdr *nlh, int hdrlen)
int nlmsg_ok (const struct nlmsghdr *nlh, int remaining)
 check if the netlink message fits into the remaining bytes
struct nlmsghdr * nlmsg_next (struct nlmsghdr *nlh, int *remaining)
 next netlink message in message stream
int nlmsg_parse (struct nlmsghdr *nlh, int hdrlen, struct nlattr *tb[], int maxtype, struct nla_policy *policy)
 parse attributes of a netlink message
struct nlattr * nlmsg_find_attr (struct nlmsghdr *nlh, int hdrlen, int attrtype)
 nlmsg_find_attr - find a specific attribute in a netlink message
int nlmsg_validate (struct nlmsghdr *nlh, int hdrlen, int maxtype, struct nla_policy *policy)
 nlmsg_validate - validate a netlink message including attributes

Message Building/Access



struct nl_msg * nlmsg_alloc (void)
 Allocate a new netlink message with the default maximum payload size.
struct nl_msg * nlmsg_alloc_size (size_t max)
 Allocate a new netlink message with maximum payload size specified.
struct nl_msg * nlmsg_inherit (struct nlmsghdr *hdr)
 Allocate a new netlink message and inherit netlink message header.
struct nl_msg * nlmsg_alloc_simple (int nlmsgtype, int flags)
 Allocate a new netlink message.
void nlmsg_set_default_size (size_t max)
 Set the default maximum message payload size for allocated messages.
struct nl_msg * nlmsg_convert (struct nlmsghdr *hdr)
 Convert a netlink message received from a netlink socket to a nl_msg.
void * nlmsg_reserve (struct nl_msg *n, size_t len, int pad)
 Reserve room for additional data in a netlink message.
int nlmsg_append (struct nl_msg *n, void *data, size_t len, int pad)
 Append data to tail of a netlink message.
int nlmsg_expand (struct nl_msg *n, size_t newlen)
 Expand maximum payload size of a netlink message.
struct nlmsghdr * nlmsg_put (struct nl_msg *n, uint32_t pid, uint32_t seq, int type, int payload, int flags)
 Add a netlink message header to a netlink message.
struct nlmsghdr * nlmsg_hdr (struct nl_msg *n)
 Return actual netlink message.
void nlmsg_get (struct nl_msg *msg)
 Acquire a reference on a netlink message.
void nlmsg_free (struct nl_msg *msg)
 Release a reference from an netlink message.

Attributes



void nlmsg_set_proto (struct nl_msg *msg, int protocol)
int nlmsg_get_proto (struct nl_msg *msg)
size_t nlmsg_get_max_size (struct nl_msg *msg)
void nlmsg_set_src (struct nl_msg *msg, struct sockaddr_nl *addr)
struct sockaddr_nl * nlmsg_get_src (struct nl_msg *msg)
void nlmsg_set_dst (struct nl_msg *msg, struct sockaddr_nl *addr)
struct sockaddr_nl * nlmsg_get_dst (struct nl_msg *msg)
void nlmsg_set_creds (struct nl_msg *msg, struct ucred *creds)
struct ucred * nlmsg_get_creds (struct nl_msg *msg)

Netlink Message Flags Translations



char * nl_nlmsg_flags2str (int flags, char *buf, size_t len)

Direct Parsing



int nl_msg_parse (struct nl_msg *msg, void(*cb)(struct nl_object *, void *), void *arg)

Dumping



void nl_msg_dump (struct nl_msg *msg, FILE *ofd)
 Dump message in human readable format to file descriptor.

Iterators



#define nlmsg_for_each_attr(pos, nlh, hdrlen, rem)
 Iterate over a stream of attributes in a message.
#define nlmsg_for_each(pos, head, len)
 Iterate over a stream of messages.
#define nlmsg_for_each_msg(pos, head, len, rem)   nlmsg_for_each(pos, head, len)

Detailed Description

Netlink Message Construction/Parsing Interface.

The following information is partly extracted from RFC3549 (ftp://ftp.rfc-editor.org/in-notes/rfc3549.txt)

Message Format
Netlink messages consist of a byte stream with one or multiple Netlink headers and an associated payload. If the payload is too big to fit into a single message it, can be split over multiple Netlink messages, collectively called a multipart message. For multipart messages, the first and all following headers have the NLM_F_MULTI Netlink header flag set, except for the last header which has the Netlink header type NLMSG_DONE.
The Netlink message header (struct nlmsghdr) is shown below.
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                          Length                             |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |            Type              |           Flags              |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                      Sequence Number                        |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                      Process ID (PID)                       |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
The netlink message header and payload must be aligned properly:
  <------- NLMSG_ALIGN(hlen) ------> <---- NLMSG_ALIGN(len) --->
 +----------------------------+- - -+- - - - - - - - - - -+- - -+
 |           Header           | Pad |       Payload       | Pad |
 |      struct nlmsghdr       |     |                     |     |
 +----------------------------+- - -+- - - - - - - - - - -+- - -+
Message Format:
    <--- nlmsg_total_size(payload)  --->
    <-- nlmsg_msg_size(payload) ->
   +----------+- - -+-------------+- - -+-------- - -
   | nlmsghdr | Pad |   Payload   | Pad | nlmsghdr
   +----------+- - -+-------------+- - -+-------- - -
   nlmsg_data(nlh)---^                   ^
   nlmsg_next(nlh)-----------------------+
The payload may consist of arbitary data but may have strict alignment and formatting rules depening on the specific netlink families.
    <---------------------- nlmsg_len(nlh) --------------------->
    <------ hdrlen ------>       <- nlmsg_attrlen(nlh, hdrlen) ->
   +----------------------+- - -+--------------------------------+
   |     Family Header    | Pad |           Attributes           |
   +----------------------+- - -+--------------------------------+
   nlmsg_attrdata(nlh, hdrlen)---^
The ACK Netlink Message
This message is actually used to denote both an ACK and a NACK. Typically, the direction is from FEC to CPC (in response to an ACK request message). However, the CPC should be able to send ACKs back to FEC when requested.
  0                   1                   2                   3
  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                       Netlink message header                  |
 |                       type = NLMSG_ERROR                      |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                          Error code                           |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                       OLD Netlink message header              |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Example
 // Various methods exist to create/allocate a new netlink
 // message. 
 //
 // nlmsg_alloc() will allocate an empty netlink message with
 // a maximum payload size which defaults to the page size of
 // the system. This default size can be modified using the
 // function nlmsg_set_default_size().
 struct nl_msg *msg = nlmsg_alloc();

 // Very often, the message type and message flags are known
 // at allocation time while the other fields are auto generated:
 struct nl_msg *msg = nlmsg_alloc_simple(MY_TYPE, MY_FLAGS);

 // Alternatively an existing netlink message header can be used
 // to inherit the header values:
 struct nlmsghdr hdr = {
        .nlmsg_type = MY_TYPE,
        .nlmsg_flags = MY_FLAGS,
 };
 struct nl_msg *msg = nlmsg_inherit(&hdr);

 // Last but not least, netlink messages received from netlink sockets
 // can be converted into nl_msg objects using nlmsg_convert(). This
 // will create a message with a maximum payload size which equals the
 // length of the existing netlink message, therefore no more data can
 // be appened without calling nlmsg_expand() first.
 struct nl_msg *msg = nlmsg_convert(nlh_from_nl_sock);

 // Payload may be added to the message via nlmsg_append(). The fourth
 // parameter specifies the number of alignment bytes the data should
 // be padding with at the end. Common values are 0 to disable it or
 // NLMSG_ALIGNTO to ensure proper netlink message padding.
 nlmsg_append(msg, &mydata, sizeof(mydata), 0);

 // Sometimes it may be necessary to reserve room for data but defer
 // the actual copying to a later point, nlmsg_reserve() can be used
 // for this purpose:
 void *data = nlmsg_reserve(msg, sizeof(mydata), NLMSG_ALIGNTO);

 // Attributes may be added using the attributes interface.

 // After successful use of the message, the memory must be freed
 // using nlmsg_free()
 nlmsg_free(msg);
4) Parsing messages
 int n;
 unsigned char *buf;
 struct nlmsghdr *hdr;

 n = nl_recv(handle, NULL, &buf);
 
 hdr = (struct nlmsghdr *) buf;
 while (nlmsg_ok(hdr, n)) {
        // Process message here...
        hdr = nlmsg_next(hdr, &n);
 }

Define Documentation

#define NL_AUTO_PORT   0

Will cause the netlink port to be set to the port assigned to the netlink icoket ust before sending the message off.

Note:
Requires the use of nl_send_auto()!

Definition at line 33 of file msg.h.

#define NL_AUTO_SEQ   0

May be used to refer to a sequence number which should be automatically set just before sending the message off.

Note:
Requires the use of nl_send_auto()!

Definition at line 44 of file msg.h.

#define nlmsg_for_each_attr (   pos,
  nlh,
  hdrlen,
  rem 
)
Value:
nla_for_each_attr(pos, nlmsg_attrdata(nlh, hdrlen), \
                          nlmsg_attrlen(nlh, hdrlen), rem)

Iterate over a stream of attributes in a message.

Parameters:
pos loop counter, set to current attribute
nlh netlink message header
hdrlen length of family header
rem initialized to len, holds bytes currently remaining in stream

Definition at line 123 of file msg.h.

#define nlmsg_for_each (   pos,
  head,
  len 
)
Value:
for (int rem = len, pos = head; \
                nlmsg_ok(pos, rem); \
                pos = nlmsg_next(pos, &rem))

Iterate over a stream of messages.

Parameters:
pos loop counter, set to current message
head head of message stream
len length of message stream

Definition at line 133 of file msg.h.


Function Documentation

int nlmsg_size ( int  payload  ) 

Calculates size of netlink message based on payload length.

Parameters:
payload Length of payload

See 4.1.1 Alignment for more information on alignment.

Returns:
size of netlink message without padding.

Definition at line 188 of file msg.c.

int nlmsg_total_size ( int  payload  ) 

Calculates size of netlink message including padding based on payload length.

Parameters:
payload Length of payload

This function is idential to nlmsg_size() + nlmsg_padlen().

See 4.1.1 Alignment for more information on alignment.

Returns:
Size of netlink message including padding.

Definition at line 208 of file msg.c.

Referenced by nlmsg_padlen(), and nlmsg_set_default_size().

Here is the caller graph for this function:

int nlmsg_padlen ( int  payload  ) 

Size of padding that needs to be added at end of message.

Parameters:
payload Length of payload

Calculates the number of bytes of padding which is required to be added to the end of the message to ensure that the next netlink message header begins properly aligned to NLMSG_ALIGNTO.

See 4.1.1 Alignment for more information on alignment.

Returns:
Number of bytes of padding needed.

Definition at line 225 of file msg.c.

References nlmsg_total_size().

Here is the call graph for this function:

void* nlmsg_data ( const struct nlmsghdr *  nlh  ) 

Return pointer to message payload.

Parameters:
nlh Netlink message header
Returns:
Pointer to start of message payload.

Definition at line 243 of file msg.c.

Referenced by genlmsg_put(), nfnlmsg_family(), nfnlmsg_res_id(), nl_msg_dump(), nla_put(), nla_put_nested(), nla_reserve(), and nlmsg_attrdata().

Here is the caller graph for this function:

int nlmsg_datalen ( const struct nlmsghdr *  nlh  ) 

Return length of message payload.

Parameters:
nlh Netlink message header
Returns:
Length of message payload in bytes.

Definition at line 259 of file msg.c.

Referenced by nla_put_nested().

Here is the caller graph for this function:

struct nlattr* nlmsg_attrdata ( const struct nlmsghdr *  nlh,
int  hdrlen 
) [read]

head of attributes data

Parameters:
nlh netlink message header
hdrlen length of family specific header

Definition at line 281 of file msg.c.

References nlmsg_data().

Referenced by nl_msg_dump(), nlmsg_find_attr(), nlmsg_parse(), and nlmsg_validate().

Here is the call graph for this function:

Here is the caller graph for this function:

int nlmsg_attrlen ( const struct nlmsghdr *  nlh,
int  hdrlen 
)

length of attributes data

Parameters:
nlh netlink message header
hdrlen length of family specific header

Definition at line 292 of file msg.c.

Referenced by nl_msg_dump(), nlmsg_find_attr(), nlmsg_parse(), and nlmsg_validate().

Here is the caller graph for this function:

int nlmsg_ok ( const struct nlmsghdr *  nlh,
int  remaining 
)

check if the netlink message fits into the remaining bytes

Parameters:
nlh netlink message header
remaining number of bytes remaining in message stream

Definition at line 317 of file msg.c.

struct nlmsghdr* nlmsg_next ( struct nlmsghdr *  nlh,
int *  remaining 
) [read]

next netlink message in message stream

Parameters:
nlh netlink message header
remaining number of bytes remaining in message stream
Returns:
the next netlink message in the message stream and decrements remaining by the size of the current message.

Definition at line 332 of file msg.c.

int nlmsg_parse ( struct nlmsghdr *  nlh,
int  hdrlen,
struct nlattr *  tb[],
int  maxtype,
struct nla_policy policy 
)

parse attributes of a netlink message

Parameters:
nlh netlink message header
hdrlen length of family specific header
tb destination array with maxtype+1 elements
maxtype maximum attribute type to be expected
policy validation policy

See nla_parse()

Definition at line 351 of file msg.c.

References nla_parse(), nlmsg_attrdata(), and nlmsg_attrlen().

Here is the call graph for this function:

struct nlattr* nlmsg_find_attr ( struct nlmsghdr *  nlh,
int  hdrlen,
int  attrtype 
) [read]

nlmsg_find_attr - find a specific attribute in a netlink message

Parameters:
nlh netlink message header
hdrlen length of familiy specific header
attrtype type of attribute to look for

Returns the first attribute which matches the specified type.

Definition at line 369 of file msg.c.

References nla_find(), nlmsg_attrdata(), and nlmsg_attrlen().

Here is the call graph for this function:

int nlmsg_validate ( struct nlmsghdr *  nlh,
int  hdrlen,
int  maxtype,
struct nla_policy policy 
)

nlmsg_validate - validate a netlink message including attributes

Parameters:
nlh netlinket message header
hdrlen length of familiy specific header
maxtype maximum attribute type to be expected
policy validation policy

Definition at line 382 of file msg.c.

References nla_validate(), nlmsg_attrdata(), and nlmsg_attrlen().

Here is the call graph for this function:

struct nl_msg* nlmsg_alloc ( void   )  [read]

Allocate a new netlink message with the default maximum payload size.

Allocates a new netlink message without any further payload. The maximum payload size defaults to PAGESIZE or as otherwise specified with nlmsg_set_default_size().

Returns:
Newly allocated netlink message or NULL.

Definition at line 439 of file msg.c.

Referenced by nlmsg_inherit(), and rtnl_neightbl_build_change_request().

Here is the caller graph for this function:

struct nl_msg* nlmsg_inherit ( struct nlmsghdr *  hdr  )  [read]

Allocate a new netlink message and inherit netlink message header.

Parameters:
hdr Netlink message header template

Allocates a new netlink message and inherits the original message header. If hdr is not NULL it will be used as a template for the netlink message header, otherwise the header is left blank.

Returns:
Newly allocated netlink message or NULL

Definition at line 462 of file msg.c.

References nlmsg_alloc().

Referenced by nl_msg_dump(), and nlmsg_alloc_simple().

Here is the call graph for this function:

Here is the caller graph for this function:

struct nl_msg* nlmsg_alloc_simple ( int  nlmsgtype,
int  flags 
) [read]

Allocate a new netlink message.

Parameters:
nlmsgtype Netlink message type
flags Message flags.
Returns:
Newly allocated netlink message or NULL.

Definition at line 486 of file msg.c.

References nlmsg_inherit().

Referenced by flnl_lookup_build_request(), nfnlmsg_alloc_simple(), nl_send_simple(), rtnl_link_build_change_request(), rtnl_neightbl_build_change_request(), and rtnl_qdisc_build_delete_request().

Here is the call graph for this function:

Here is the caller graph for this function:

void nlmsg_set_default_size ( size_t  max  ) 

Set the default maximum message payload size for allocated messages.

Parameters:
max Size of payload in bytes.

Definition at line 505 of file msg.c.

References nlmsg_total_size().

Here is the call graph for this function:

struct nl_msg* nlmsg_convert ( struct nlmsghdr *  hdr  )  [read]

Convert a netlink message received from a netlink socket to a nl_msg.

Parameters:
hdr Netlink message received from netlink socket.

Allocates a new netlink message and copies all of the data pointed to by hdr into the new message object.

Returns:
Newly allocated netlink message or NULL.

Definition at line 522 of file msg.c.

References nlmsg_free().

Here is the call graph for this function:

void* nlmsg_reserve ( struct nl_msg *  n,
size_t  len,
int  pad 
)

Reserve room for additional data in a netlink message.

Parameters:
n netlink message
len length of additional data to reserve room for
pad number of bytes to align data to

Reserves room for additional data at the tail of the an existing netlink message. Eventual padding required will be zeroed out.

Returns:
Pointer to start of additional data tailroom or NULL.

Definition at line 550 of file msg.c.

Referenced by nla_nest_end(), nlmsg_append(), and nlmsg_put().

Here is the caller graph for this function:

int nlmsg_append ( struct nl_msg *  n,
void *  data,
size_t  len,
int  pad 
)

Append data to tail of a netlink message.

Parameters:
n netlink message
data data to add
len length of data
pad Number of bytes to align data to.

Extends the netlink message as needed and appends the data of given length to the message.

Returns:
0 on success or a negative error code

Definition at line 585 of file msg.c.

References nlmsg_reserve().

Referenced by flnl_lookup_build_request(), nl_send_simple(), rtnl_link_build_change_request(), rtnl_neightbl_build_change_request(), and rtnl_qdisc_build_delete_request().

Here is the call graph for this function:

Here is the caller graph for this function:

int nlmsg_expand ( struct nl_msg *  n,
size_t  newlen 
)

Expand maximum payload size of a netlink message.

Parameters:
n Netlink message.
newlen New maximum payload size.

Reallocates the payload section of a netlink message and increases the maximum payload size of the message.

Note:
Any pointers pointing to old payload block will be stale and need to be refetched. Therfore, do not expand while constructing nested attributes or while reserved data blocks are held.
Returns:
0 on success or a negative error code.

Definition at line 613 of file msg.c.

struct nlmsghdr* nlmsg_put ( struct nl_msg *  n,
uint32_t  pid,
uint32_t  seq,
int  type,
int  payload,
int  flags 
) [read]

Add a netlink message header to a netlink message.

Parameters:
n netlink message
pid netlink process id or NL_AUTO_PID
seq sequence number of message or NL_AUTO_SEQ
type message type
payload length of message payload
flags message flags

Adds or overwrites the netlink message header in an existing message object. If payload is greater-than zero additional room will be reserved, f.e. for family specific headers. It can be accesed via nlmsg_data().

Returns:
A pointer to the netlink message header or NULL.

Definition at line 646 of file msg.c.

References nlmsg_reserve().

Referenced by genlmsg_put(), and nfnlmsg_put().

Here is the call graph for this function:

Here is the caller graph for this function:

struct nlmsghdr* nlmsg_hdr ( struct nl_msg *  n  )  [read]

Return actual netlink message.

Parameters:
n netlink message

Returns the actual netlink message casted to the type of the netlink message header.

Returns:
A pointer to the netlink message.

Definition at line 679 of file msg.c.

Referenced by nl_cache_parse_and_add(), nl_msg_dump(), and nl_send().

Here is the caller graph for this function:

void nlmsg_get ( struct nl_msg *  msg  ) 

Acquire a reference on a netlink message.

Parameters:
msg message to acquire reference from

Definition at line 688 of file msg.c.

void nlmsg_free ( struct nl_msg *  msg  ) 
void nl_msg_dump ( struct nl_msg *  msg,
FILE *  ofd 
)

Dump message in human readable format to file descriptor.

Parameters:
msg Message to print
ofd File descriptor.

Definition at line 1000 of file msg.c.

References nl_cache_ops_associate(), nlmsg_attrdata(), nlmsg_attrlen(), nlmsg_data(), nlmsg_free(), nlmsg_hdr(), and nlmsg_inherit().

Here is the call graph for this function: