Logo Search packages:      
Sourcecode: libnl version File versions  Download package

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);
 }


Classes

struct  nlmsgerr
struct  nlmsghdr

Netlink Message Type Translations

static struct trans_tbl nl_msgtypes []
char * nl_nlmsgtype2str (int type, char *buf, size_t size)
int nl_str2nlmsgtype (const char *name)

Direct Parsing

int nl_msg_parse (struct nl_msg *msg, void(*cb)(struct nl_object *, void *), void *arg)
static int parse_cb (struct nl_object *obj, struct nl_parser_param *p)

Netlink Message Flags Translations

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

Message Building/Access

int nlmsg_append (struct nl_msg *n, void *data, size_t len, int pad)
struct nl_msg * nlmsg_build (struct nlmsghdr *hdr)
struct nl_msg * nlmsg_build_no_hdr (void)
struct nl_msg * nlmsg_build_simple (int nlmsgtype, int flags)
struct nl_msg * nlmsg_convert (struct nlmsghdr *hdr)
void nlmsg_free (struct nl_msg *n)
struct nlmsghdrnlmsg_hdr (struct nl_msg *n)
struct nl_msg * nlmsg_new (void)
struct nlmsghdrnlmsg_put (struct nl_msg *n, uint32_t pid, uint32_t seq, int type, int payload, int flags)

Attribute Access

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

Payload Access

void * nlmsg_data (const struct nlmsghdr *nlh)
int nlmsg_len (const struct nlmsghdr *nlh)
void * nlmsg_tail (const struct nlmsghdr *nlh)

Message Parsing

struct nlattrnlmsg_find_attr (struct nlmsghdr *nlh, int hdrlen, int attrtype)
struct nlmsghdrnlmsg_next (struct nlmsghdr *nlh, int *remaining)
int nlmsg_ok (const struct nlmsghdr *nlh, int remaining)
int nlmsg_parse (struct nlmsghdr *nlh, int hdrlen, struct nlattr *tb[], int maxtype, struct nla_policy *policy)
int nlmsg_validate (struct nlmsghdr *nlh, int hdrlen, int maxtype, struct nla_policy *policy)

Attribute Modification

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

Size Calculations

int nlmsg_msg_size (int payload)
int nlmsg_padlen (int payload)
int nlmsg_total_size (int payload)

Additional messsage flags for NEW requests

#define NLM_F_REPLACE   0x100

Standard message flags

#define NLM_F_REQUEST   1

Additional message flags for GET requests

#define NLM_F_ROOT   0x100

Iterators

#define nlmsg_for_each_attr(pos, nlh, hdrlen, rem)
#define nlmsg_for_each_msg(pos, head, len, rem)

Standard Message types

#define NLMSG_NOOP   0x1


Generated by  Doxygen 1.6.0   Back to index