Messages
[Core Netlink API]


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              |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1) Creating a new netlink message
 // The most common way to start creating a message is by providing an
 // defined netlink header to nlmsg_build():
 struct nlmsghdr hdr = {
        .nlmsg_type = MY_TYPE,
        .nlmsg_flags = MY_FLAGS,
 };
 struct nl_msg *msg = nlmsg_build(&hdr);

 // For simple usages where only the message type and flags is of
 // interenst a shortcut can be taken:
 struct nl_msg *msg = nlmsg_build_simple(MY_TYPE, MY_FLAGS);

 // When using a headerless message for creating nested attributes
 // the header is not required and nlmsg_build_no_hdr() may be used:
 struct nl_msg *msg = nlmsg_build_no_hdr();

 // The header can later be retrieved with nlmsg_hdr() and changed again:
 nlmsg_hdr(msg)->nlmsg_flags |= YET_ANOTHER_FLAG;
2) Appending data to the message
 // Payload may be added to the message via nlmsg_append(). The fourth
 // parameter specifies whether to pad up to NLMSG_ALIGN to make sure
 // that a possible further data block is properly aligned.
 nlmsg_append(msg, &mydata, sizeof(mydata), 0);
3) Cleaning up message construction
 // After successful use of the message, the memory must be freed
 // using nlmsg_free()
 nlmsg_free(msg);
Example 2 (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);
 }


Data Structures

struct  nlmsghdr
 Netlink message header. More...
struct  nlmsgerr
 Netlink error message. More...

Netlink Message Type Translations

char * nl_nlmsgtype2str (int type, char *buf, size_t size)
 Convert netlink message type number to character string.
int nl_str2nlmsgtype (const char *name)
 Convert character string to netlink message type.

Size Calculations

int nlmsg_msg_size (int payload)
 length of netlink message not including padding
int nlmsg_total_size (int payload)
 length of netlink message including padding
int nlmsg_padlen (int payload)
 length of padding at the message's tail

Payload Access

void * nlmsg_data (const struct nlmsghdr *nlh)
 head of message payload
void * nlmsg_tail (const struct nlmsghdr *nlh)
 head of message payload
int nlmsg_len (const struct nlmsghdr *nlh)
 length of message payload

Attribute Access

nlattrnlmsg_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_ok (const struct nlmsghdr *nlh, int remaining)
 check if the netlink message fits into the remaining bytes
nlmsghdrnlmsg_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
nlattrnlmsg_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

nl_msg * nlmsg_new (void)
nl_msg * nlmsg_build (struct nlmsghdr *hdr)
 Build a new netlink message.
nl_msg * nlmsg_build_simple (int nlmsgtype, int flags)
nl_msg * nlmsg_build_no_hdr (void)
nl_msg * nlmsg_convert (struct nlmsghdr *hdr)
int nlmsg_append (struct nl_msg *n, void *data, size_t len, int pad)
 Append raw data to a netlink message.
nlmsghdrnlmsg_put (struct nl_msg *n, uint32_t pid, uint32_t seq, int type, int payload, int flags)
 nlmsg_put - Add a netlink message header
nlmsghdrnlmsg_hdr (struct nl_msg *n)
 Return actual netlink message.
void nlmsg_free (struct nl_msg *n)
 Free a netlink message.

Attribute Modification

void nlmsg_set_proto (struct nl_msg *msg, int protocol)
int nlmsg_get_proto (struct nl_msg *msg)
void nlmsg_set_src (struct nl_msg *msg, struct sockaddr_nl *addr)
sockaddr_nlnlmsg_get_src (struct nl_msg *msg)
void nlmsg_set_dst (struct nl_msg *msg, struct sockaddr_nl *addr)
sockaddr_nlnlmsg_get_dst (struct nl_msg *msg)
void nlmsg_set_creds (struct nl_msg *msg, struct ucred *creds)
ucred * nlmsg_get_creds (struct nl_msg *msg)

Netlink Message Flags Translations

char * nl_nlmsg_flags2str (int flags, char *buf, size_t len)
 Translate netlink message flags into a character string (Reentrant).

Direct Parsing

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

Iterators

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

Standard message flags

#define NLM_F_REQUEST   1
 Must be set on all request messages (typically from user space to kernel space).
#define NLM_F_MULTI   2
 Indicates the message is part of a multipart message terminated by NLMSG_DONE.
#define NLM_F_ACK   4
 Request for an acknowledgment on success.
#define NLM_F_ECHO   8
 Echo this request.

Additional message flags for GET requests

#define NLM_F_ROOT   0x100
 Return the complete table instead of a single entry.
#define NLM_F_MATCH   0x200
 Return all entries matching criteria passed in message content.
#define NLM_F_ATOMIC   0x400
 Return an atomic snapshot of the table being referenced.
#define NLM_F_DUMP   (NLM_F_ROOT|NLM_F_MATCH)
 Dump all entries.

Additional messsage flags for NEW requests

#define NLM_F_REPLACE   0x100
 Replace existing matching config object with this request.
#define NLM_F_EXCL   0x200
 Don't replace the config object if it already exists.
#define NLM_F_CREATE   0x400
 Create config object if it doesn't already exist.
#define NLM_F_APPEND   0x800
 Add to the end of the object list.

Standard Message types

#define NLMSG_NOOP   0x1
 No operation, message must be ignored.
#define NLMSG_ERROR   0x2
 The message signals an error and the payload contains a nlmsgerr structure.
#define NLMSG_DONE   0x3
 Message terminates a multipart message.
#define NLMSG_OVERRUN   0x4
 The message signals that data got lost.
#define NLMSG_MIN_TYPE   0x10
 Lower limit of reserved message types.


Define Documentation

#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 88 of file msg.h.

#define NLM_F_REQUEST   1

Must be set on all request messages (typically from user space to kernel space).

Definition at line 86 of file netlink-kernel.h.

Referenced by nl_send_auto_complete().

#define NLM_F_ROOT   0x100

Return the complete table instead of a single entry.

Definition at line 115 of file netlink-kernel.h.

#define NLM_F_REPLACE   0x100

Replace existing matching config object with this request.

Definition at line 145 of file netlink-kernel.h.

Referenced by rtnl_cls_build_change_request(), rtnl_neigh_build_change_request(), and rtnl_qdisc_build_change_request().

#define NLMSG_NOOP   0x1

No operation, message must be ignored.

Definition at line 177 of file netlink-kernel.h.

Referenced by nl_recvmsgs().

#define nlmsg_for_each_msg ( pos,
head,
len,
rem   ) 

Value:

for (pos = head, rem = len; \
             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
rem initialized to len, holds bytes currently remaining in stream

Definition at line 99 of file msg.h.

#define NLM_F_MULTI   2

Indicates the message is part of a multipart message terminated by NLMSG_DONE.

Definition at line 92 of file netlink-kernel.h.

#define NLM_F_ACK   4

Request for an acknowledgment on success.

Definition at line 97 of file netlink-kernel.h.

Referenced by nl_recvmsgs(), and nl_send_auto_complete().

#define NLM_F_ECHO   8

Echo this request.

Definition at line 102 of file netlink-kernel.h.

#define NLM_F_MATCH   0x200

Return all entries matching criteria passed in message content.

Definition at line 120 of file netlink-kernel.h.

#define NLM_F_ATOMIC   0x400

Return an atomic snapshot of the table being referenced.

This may require special privileges because it has the potential to interrupt service in the FE for a longer time.

Definition at line 127 of file netlink-kernel.h.

#define NLM_F_DUMP   (NLM_F_ROOT|NLM_F_MATCH)

Dump all entries.

Definition at line 132 of file netlink-kernel.h.

#define NLM_F_EXCL   0x200

Don't replace the config object if it already exists.

Definition at line 150 of file netlink-kernel.h.

#define NLM_F_CREATE   0x400

Create config object if it doesn't already exist.

Definition at line 155 of file netlink-kernel.h.

Referenced by rtnl_addr_build_add_request(), rtnl_class_build_add_request(), rtnl_cls_build_add_request(), rtnl_neigh_build_add_request(), rtnl_qdisc_build_add_request(), rtnl_route_build_add_request(), and rtnl_rule_build_add_request().

#define NLM_F_APPEND   0x800

Add to the end of the object list.

Definition at line 160 of file netlink-kernel.h.

#define NLMSG_ERROR   0x2

The message signals an error and the payload contains a nlmsgerr structure.

This can be looked at as a NACK and typically it is from FEC to CPC.

Definition at line 184 of file netlink-kernel.h.

Referenced by nl_recvmsgs().

#define NLMSG_DONE   0x3

Message terminates a multipart message.

Definition at line 189 of file netlink-kernel.h.

Referenced by nl_recvmsgs().

#define NLMSG_OVERRUN   0x4

The message signals that data got lost.

Definition at line 194 of file netlink-kernel.h.

Referenced by nl_recvmsgs().

#define NLMSG_MIN_TYPE   0x10

Lower limit of reserved message types.

Definition at line 199 of file netlink-kernel.h.


Function Documentation

int nlmsg_msg_size ( int  payload  ) 

length of netlink message not including padding

Parameters:
payload length of message payload

Definition at line 166 of file msg.c.

Referenced by nl_recvmsgs(), nl_send_simple(), nlmsg_new(), nlmsg_padlen(), nlmsg_parse(), nlmsg_put(), nlmsg_total_size(), and nlmsg_validate().

int nlmsg_total_size ( int  payload  ) 

length of netlink message including padding

Parameters:
payload length of message payload

Definition at line 175 of file msg.c.

References nlmsg_msg_size().

Referenced by nlmsg_padlen().

int nlmsg_padlen ( int  payload  ) 

length of padding at the message's tail

Parameters:
payload length of message payload

Definition at line 184 of file msg.c.

References nlmsg_msg_size(), and nlmsg_total_size().

Referenced by nlmsg_put().

void* nlmsg_data ( const struct nlmsghdr nlh  ) 

head of message payload

Parameters:
nlh netlink messsage header

Definition at line 200 of file msg.c.

Referenced by nl_recvmsgs(), nla_put_nested(), nlmsg_attrdata(), and nlmsg_put().

void* nlmsg_tail ( const struct nlmsghdr nlh  ) 

head of message payload

Parameters:
nlh netlink messsage header

Definition at line 205 of file msg.c.

References nlmsghdr::nlmsg_len.

Referenced by nla_nest_end(), nla_nest_start(), and nla_reserve().

int nlmsg_len ( const struct nlmsghdr nlh  ) 

length of message payload

Parameters:
nlh netlink message header

Definition at line 214 of file msg.c.

References nlmsghdr::nlmsg_len.

Referenced by nla_put_nested(), and nlmsg_attrlen().

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

head of attributes data

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

Definition at line 231 of file msg.c.

References nlmsg_data().

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

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 242 of file msg.c.

References nlmsg_len().

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

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 259 of file msg.c.

References nlmsghdr::nlmsg_len.

Referenced by nl_recvmsgs().

struct nlmsghdr* nlmsg_next ( struct nlmsghdr nlh,
int *  remaining 
)

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 274 of file msg.c.

References nlmsghdr::nlmsg_len.

Referenced by nl_recvmsgs().

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 293 of file msg.c.

References nla_parse(), nlmsg_attrdata(), nlmsg_attrlen(), nlmsghdr::nlmsg_len, and nlmsg_msg_size().

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

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 311 of file msg.c.

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

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 324 of file msg.c.

References nla_validate(), nlmsg_attrdata(), nlmsg_attrlen(), nlmsghdr::nlmsg_len, and nlmsg_msg_size().

struct nl_msg* nlmsg_build ( struct nlmsghdr hdr  ) 

Build a new netlink message.

Parameters:
hdr Netlink message header template
Builds a new netlink message with a tailroom for the netlink 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 373 of file msg.c.

References nlmsg_new().

Referenced by nl_send_simple(), nlmsg_build_no_hdr(), nlmsg_build_simple(), and rtnl_neightbl_build_change_request().

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

Append raw data to a netlink message.

Parameters:
n netlink message
data data to add
len length of data
pad add padding at the end?
Extends the netlink message as needed and appends the data of given length to the message. The length of the message is not aligned to anything. The caller is responsible to provide a length and evtentually padded data to fullfil any alignment requirements.

Returns:
0 on success or a negative error code
Attention:
Appending of improperly aligned raw data may result in a corrupt message. It is left to you to add the right amount of data to have the message aligned to NLMSG_ALIGNTO in the end.

Definition at line 441 of file msg.c.

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

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

nlmsg_put - Add a netlink message header

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

Definition at line 469 of file msg.c.

References nlmsg_data(), nlmsghdr::nlmsg_flags, nlmsghdr::nlmsg_len, nlmsg_msg_size(), nlmsg_padlen(), nlmsghdr::nlmsg_pid, nlmsghdr::nlmsg_seq, and nlmsghdr::nlmsg_type.

struct nlmsghdr* nlmsg_hdr ( struct nl_msg *  n  ) 

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 499 of file msg.c.

Referenced by nl_cache_parse_and_add(), nl_msg_parse(), nl_send_auto_complete(), and nl_sendmsg().

void nlmsg_free ( struct nl_msg *  n  ) 

Free a netlink message.

Parameters:
n netlink message
Destroys a netlink message and frees up all used memory.

Precondition:
The message must be unused.

Definition at line 512 of file msg.c.

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

char* nl_nlmsgtype2str ( int  type,
char *  buf,
size_t  size 
)

Convert netlink message type number to character string.

Parameters:
type Netlink message type.
buf Destination buffer.
size Size of destination buffer.
Converts a netlink message type number to a character string and stores it in the provided buffer.

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

Definition at line 597 of file msg.c.

int nl_str2nlmsgtype ( const char *  name  ) 

Convert character string to netlink message type.

Parameters:
name Name of netlink message type.
Converts the provided character string specifying a netlink message type into the corresponding numeric value

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

Definition at line 613 of file msg.c.

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

Translate netlink message flags into a character string (Reentrant).

Parameters:
flags netlink message flags
buf destination buffer
len buffer length
Translates netlink message flags into a character string and stores it in the provided buffer.

Returns:
The destination buffer

Definition at line 636 of file msg.c.


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