Netlink Message Construction/Parsing Interface.
More...
Modules |
| Attributes |
| Netlink Attributes Construction/Parsing Interface.
|
Macros |
#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.
|
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
|
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_free (struct nl_msg *n) |
| Free a 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 Type Translations |
char * | nl_nlmsgtype2str (int type, char *buf, size_t size) |
int | nl_str2nlmsgtype (const char *name) |
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_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.
|
Detailed Description
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 |
+----------------------------+- - -+- - - - - - - - - - -+- - -+
- Message Format:
+----------+- - -+-------------+- - -+-------- - -
+----------+- - -+-------------+- - -+-------- - -
- The payload may consist of arbitary data but may have strict alignment and formatting rules depening on the specific netlink families.
<----------------------
nlmsg_len(nlh) --------------------->
+----------------------+- - -+--------------------------------+
| Family Header | Pad | Attributes |
+----------------------+- - -+--------------------------------+
- 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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Error code |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| OLD Netlink message header |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Example
.nlmsg_flags = MY_FLAGS,
};
- 4) Parsing messages
int n;
unsigned char *buf;
}
Macro Definition Documentation
#define nlmsg_for_each_attr |
( |
|
pos, |
|
|
|
nlh, |
|
|
|
hdrlen, |
|
|
|
rem |
|
) |
| |
Value:- 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 126 of file msg.h.
#define nlmsg_for_each_msg |
( |
|
pos, |
|
|
|
head, |
|
|
|
len, |
|
|
|
rem |
|
) |
| |
Value:for (pos = head, rem = len; \
nlmsg_ok(pos, rem); \
- 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 137 of file msg.h.
#define NLM_F_ATOMIC 0x400 |
This may require special privileges because it has the potential to interrupt service in the FE for a longer time.
Definition at line 106 of file netlink-kernel.h.
This can be looked at as a NACK and typically it is from FEC to CPC.
Definition at line 159 of file netlink-kernel.h.
Function Documentation
int nlmsg_msg_size |
( |
int |
payload | ) |
|
int nlmsg_total_size |
( |
int |
payload | ) |
|
int nlmsg_padlen |
( |
int |
payload | ) |
|
void* nlmsg_data |
( |
const struct nlmsghdr * |
nlh | ) |
|
int nlmsg_len |
( |
const struct nlmsghdr * |
nlh | ) |
|
struct nlattr* nlmsg_attrdata |
( |
const struct nlmsghdr * |
nlh, |
|
|
int |
hdrlen |
|
) |
| |
|
read |
int nlmsg_attrlen |
( |
const struct nlmsghdr * |
nlh, |
|
|
int |
hdrlen |
|
) |
| |
int nlmsg_ok |
( |
const struct nlmsghdr * |
nlh, |
|
|
int |
remaining |
|
) |
| |
- Parameters
-
nlh | netlink message header |
remaining | number of bytes remaining in message stream |
Definition at line 285 of file msg.c.
References nlmsghdr::nlmsg_len.
- 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 300 of file msg.c.
References nlmsghdr::nlmsg_len.
int nlmsg_parse |
( |
struct nlmsghdr * |
nlh, |
|
|
int |
hdrlen, |
|
|
struct nlattr * |
tb[], |
|
|
int |
maxtype, |
|
|
struct nla_policy * |
policy |
|
) |
| |
- 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 319 of file msg.c.
References nla_parse(), nlmsg_attrdata(), and nlmsg_attrlen().
struct nlattr* nlmsg_find_attr |
( |
struct nlmsghdr * |
nlh, |
|
|
int |
hdrlen, |
|
|
int |
attrtype |
|
) |
| |
|
read |
- 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 337 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 |
|
) |
| |
struct nl_msg* nlmsg_alloc |
( |
void |
| ) |
|
|
read |
struct nl_msg* nlmsg_inherit |
( |
struct nlmsghdr * |
hdr | ) |
|
|
read |
struct nl_msg* nlmsg_alloc_simple |
( |
int |
nlmsgtype, |
|
|
int |
flags |
|
) |
| |
|
read |
void nlmsg_set_default_size |
( |
size_t |
max | ) |
|
struct nl_msg* nlmsg_convert |
( |
struct nlmsghdr * |
hdr | ) |
|
|
read |
- 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 484 of file msg.c.
References nlmsg_free(), and nlmsghdr::nlmsg_len.
void* nlmsg_reserve |
( |
struct nl_msg * |
n, |
|
|
size_t |
len, |
|
|
int |
pad |
|
) |
| |
- 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 512 of file msg.c.
References nlmsg_len().
Referenced by nlmsg_append(), and nlmsg_put().
int nlmsg_append |
( |
struct nl_msg * |
n, |
|
|
void * |
data, |
|
|
size_t |
len, |
|
|
int |
pad |
|
) |
| |
int nlmsg_expand |
( |
struct nl_msg * |
n, |
|
|
size_t |
newlen |
|
) |
| |
- 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 580 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 |
struct nlmsghdr* nlmsg_hdr |
( |
struct nl_msg * |
n | ) |
|
|
read |
void nlmsg_free |
( |
struct nl_msg * |
n | ) |
|
- Parameters
-
Destroys a netlink message and frees up all used memory.
- Precondition
- The message must be unused.
Definition at line 659 of file msg.c.
Referenced by flnl_lookup(), flnl_lookup_build_request(), nfnlmsg_alloc_simple(), nl_msg_dump(), nl_send_simple(), nlmsg_convert(), 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().
void nl_msg_dump |
( |
struct nl_msg * |
msg, |
|
|
FILE * |
ofd |
|
) |
| |
- Parameters
-
msg | Message to print |
ofd | File descriptor. |
Definition at line 950 of file msg.c.
References nlmsgerr::error, nlmsgerr::msg, nl_cache_ops_associate(), nlmsg_attrdata(), nlmsg_attrlen(), nlmsg_data(), nlmsg_free(), nlmsg_hdr(), nlmsg_inherit(), nlmsghdr::nlmsg_len, nlmsg_len(), nlmsg_msg_size(), and nlmsghdr::nlmsg_type.