table of contents
| nlmsg(3) | Library Functions Manual | nlmsg(3) |
NAME¶
nlmsg - Netlink message helpers
SYNOPSIS¶
Functions¶
size_t mnl_nlmsg_size (size_t len)
size_t mnl_nlmsg_get_payload_len (const struct nlmsghdr *nlh)
struct nlmsghdr * mnl_nlmsg_put_header (void *buf)
void * mnl_nlmsg_put_extra_header (struct nlmsghdr *nlh, size_t size)
void * mnl_nlmsg_get_payload (const struct nlmsghdr *nlh)
void * mnl_nlmsg_get_payload_offset (const struct nlmsghdr *nlh, size_t
offset)
bool mnl_nlmsg_ok (const struct nlmsghdr *nlh, int len)
struct nlmsghdr * mnl_nlmsg_next (const struct nlmsghdr *nlh, int *len)
void * mnl_nlmsg_get_payload_tail (const struct nlmsghdr *nlh)
bool mnl_nlmsg_seq_ok (const struct nlmsghdr *nlh, unsigned int seq)
bool mnl_nlmsg_portid_ok (const struct nlmsghdr *nlh, unsigned int
portid)
void mnl_nlmsg_fprintf (FILE *fd, const void *data, size_t datalen,
size_t extra_header_size)
Detailed Description¶
Netlink message:
|<----------------- 4 bytes ------------------->|
|<----- 2 bytes ------>|<------- 2 bytes ------>|
|-----------------------------------------------|
| Message length (including header) |
|-----------------------------------------------|
| Message type | Message flags |
|-----------------------------------------------|
| Message sequence number |
|-----------------------------------------------|
| Netlink PortID |
|-----------------------------------------------|
| |
. Payload .
|_______________________________________________|
There is usually an extra header after the the Netlink header (at the beginning of the payload). This extra header is specific of the Netlink subsystem. After this extra header, it comes the sequence of attributes that are expressed in Type-Length-Value (TLV) format.
Function Documentation¶
void mnl_nlmsg_fprintf (FILE * fd, const void * data, size_t datalen, size_t extra_header_size)¶
mnl_nlmsg_fprintf - print netlink message to file
Parameters
data pointer to the buffer that contains messages to be printed
datalen length of data stored in the buffer
extra_header_size size of the extra header (if any)
This function prints the netlink header to a file handle. It may be useful for debugging purposes. One example of the output is the following:
---------------- ------------------ | 0000000040 | | message length | | 00016 | R-A- | | type | flags | | 1289148991 | | sequence number| | 0000000000 | | port ID | ---------------- ------------------ | 00 00 00 00 | | extra header | | 00 00 00 00 | | extra header | | 01 00 00 00 | | extra header | | 01 00 00 00 | | extra header | |00008|--|00003| |len |flags| type| | 65 74 68 30 | | data | e t h 0 ---------------- ------------------
This example above shows the netlink message that is send to kernel-space to set up the link interface eth0. The netlink and attribute header data are displayed in base 10 whereas the extra header and the attribute payload are expressed in base 16. The possible flags in the netlink header are:
- R, that indicates that NLM_F_REQUEST is set.
- M, that indicates that NLM_F_MULTI is set.
- A, that indicates that NLM_F_ACK is set.
- E, that indicates that NLM_F_ECHO is set.
The lack of one flag is displayed with '-'. On the other hand, the possible attribute flags available are:
- N, that indicates that NLA_F_NESTED is set.
- B, that indicates that NLA_F_NET_BYTEORDER is set.
Definition at line 360 of file nlmsg.c.
void * mnl_nlmsg_get_payload (const struct nlmsghdr * nlh)¶
mnl_nlmsg_get_payload - get a pointer to the payload of the netlink message
Parameters
This function returns a pointer to the payload of the netlink message.
Definition at line 117 of file nlmsg.c.
size_t mnl_nlmsg_get_payload_len (const struct nlmsghdr * nlh)¶
mnl_nlmsg_get_payload_len - get the length of the Netlink payload
Parameters
This function returns the Length of the netlink payload, ie. the length of the full message minus the size of the Netlink header.
Definition at line 66 of file nlmsg.c.
void * mnl_nlmsg_get_payload_offset (const struct nlmsghdr * nlh, size_t offset)¶
mnl_nlmsg_get_payload_offset - get a pointer to the payload of the message
Parameters
offset offset to the payload of the attributes TLV set
This function returns a pointer to the payload of the netlink message plus a given offset.
Definition at line 130 of file nlmsg.c.
void * mnl_nlmsg_get_payload_tail (const struct nlmsghdr * nlh)¶
mnl_nlmsg_get_payload_tail - get the ending of the netlink message
Parameters
This function returns a pointer to the netlink message tail. This is useful to build a message since we continue adding attributes at the end of the message.
Definition at line 187 of file nlmsg.c.
struct nlmsghdr * mnl_nlmsg_next (const struct nlmsghdr * nlh, int * len)¶
mnl_nlmsg_next - get the next netlink message in a multipart message
Parameters
len length of the remaining bytes in the buffer (passed by reference).
This function returns a pointer to the next netlink message that is part of a multi-part netlink message. Netlink can batch several messages into one buffer so that the receiver has to iterate over the whole set of Netlink messages.
You have to use mnl_nlmsg_ok() to check if the next Netlink message is valid.
Definition at line 172 of file nlmsg.c.
bool mnl_nlmsg_ok (const struct nlmsghdr * nlh, int len)¶
mnl_nlmsg_ok - check a there is room for netlink message
Parameters
len remaining bytes in a buffer that contains the netlink message
This function is used to check that a buffer that contains a netlink message has enough room for the netlink message that it stores, ie. this function can be used to verify that a netlink message is not malformed nor truncated.
This function does not set errno in case of error since it is intended for iterations. Thus, it returns true on success and false on error.
The len parameter may become negative in malformed messages during message iteration, that is why we use a signed integer.
Definition at line 152 of file nlmsg.c.
bool mnl_nlmsg_portid_ok (const struct nlmsghdr * nlh, unsigned int portid)¶
mnl_nlmsg_portid_ok - perform portID origin check
Parameters
portid netlink portid that we want to check
This functions returns true if the origin is fulfilled, otherwise false is returned. We skip the tracking for netlink message whose portID is zero since it is reserved for event-based kernel notifications. On the other hand, if portid is set but the message PortID is not (i.e. this is an event message coming from kernel-space), then we also skip the tracking. This approach is good if we use the same socket to send commands to kernel-space (that we want to track) and to listen to events (that we do not track).
Definition at line 226 of file nlmsg.c.
void * mnl_nlmsg_put_extra_header (struct nlmsghdr * nlh, size_t size)¶
mnl_nlmsg_put_extra_header - reserve and prepare room for an extra header
Parameters
size size of the extra header that we want to put
This function sets to zero the room that is required to put the extra header after the initial Netlink header. This function also increases the nlmsg_len field. You have to invoke mnl_nlmsg_put_header() before you call this function. This function returns a pointer to the extra header.
Definition at line 101 of file nlmsg.c.
struct nlmsghdr * mnl_nlmsg_put_header (void * buf)¶
mnl_nlmsg_put_header - reserve and prepare room for Netlink header
Parameters
This function sets to zero the room that is required to put the Netlink header in the memory buffer passed as parameter. This function also initializes the nlmsg_len field to the size of the Netlink header. This function returns a pointer to the Netlink header structure.
Definition at line 80 of file nlmsg.c.
bool mnl_nlmsg_seq_ok (const struct nlmsghdr * nlh, unsigned int seq)¶
mnl_nlmsg_seq_ok - perform sequence tracking
Parameters
seq last sequence number used to send a message
This functions returns true if the sequence tracking is fulfilled, otherwise false is returned. We skip the tracking for netlink messages whose sequence number is zero since it is usually reserved for event-based kernel notifications. On the other hand, if seq is set but the message sequence number is not set (i.e. this is an event message coming from kernel-space), then we also skip the tracking. This approach is good if we use the same socket to send commands to kernel-space (that we want to track) and to listen to events (that we do not track).
Definition at line 206 of file nlmsg.c.
size_t mnl_nlmsg_size (size_t len)¶
mnl_nlmsg_size - calculate the size of Netlink message (without alignment)
Parameters
This function returns the size of a netlink message (header plus payload) without alignment.
Definition at line 54 of file nlmsg.c.
Author¶
Generated automatically by Doxygen for libmnl from the source code.
| Version 1.0.5 | libmnl |