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

Messages
[Core]


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


Modules

 Attributes

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)

Message Building/Access

static struct nl_msg * __nlmsg_alloc (size_t len)
struct nl_msg * nlmsg_alloc (void)
struct nl_msg * nlmsg_alloc_simple (int nlmsgtype, int flags)
struct nl_msg * nlmsg_alloc_size (size_t max)
int nlmsg_append (struct nl_msg *n, void *data, size_t len, int pad)
struct nl_msg * nlmsg_convert (struct nlmsghdr *hdr)
int nlmsg_expand (struct nl_msg *n, size_t newlen)
void nlmsg_free (struct nl_msg *msg)
void nlmsg_get (struct nl_msg *msg)
struct nlmsghdrnlmsg_hdr (struct nl_msg *n)
struct nl_msg * nlmsg_inherit (struct nlmsghdr *hdr)
struct nlmsghdrnlmsg_put (struct nl_msg *n, uint32_t pid, uint32_t seq, int type, int payload, int flags)
void * nlmsg_reserve (struct nl_msg *n, size_t len, int pad)
void nlmsg_set_default_size (size_t max)

Dumping

static void dump_attrs (FILE *ofd, struct nlattr *attrs, int attrlen, int prefix)
static void dump_hex (FILE *ofd, char *start, int len, int prefix)
void nl_msg_dump (struct nl_msg *msg, FILE *ofd)
static void prefix_line (FILE *ofd, int prefix)
static void print_hdr (FILE *ofd, struct nl_msg *msg)

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)

Attribute Access

struct nlattr * nlmsg_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 nlattr * nlmsg_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_valid_hdr (const struct nlmsghdr *nlh, int hdrlen)
int nlmsg_validate (struct nlmsghdr *nlh, int hdrlen, int maxtype, struct nla_policy *policy)

Attributes

struct ucred * nlmsg_get_creds (struct nl_msg *msg)
struct sockaddr_nlnlmsg_get_dst (struct nl_msg *msg)
size_t nlmsg_get_max_size (struct nl_msg *msg)
int nlmsg_get_proto (struct nl_msg *msg)
struct sockaddr_nlnlmsg_get_src (struct nl_msg *msg)
void nlmsg_set_creds (struct nl_msg *msg, struct ucred *creds)
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

Defines

#define NL_AUTO_PID   0
 Will cause the netlink pid to be set to the pid assigned to the netlink handle (socket) just 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.

Functions

static void __init init_msg_size (void)

Variables

static size_t default_msg_size


Generated by  Doxygen 1.6.0   Back to index