Modules | Functions | Variables

Netlink message helpers

Collaboration diagram for Netlink message helpers:

Modules

 Netlink message batch helpers

Functions

EXPORT_SYMBOL size_t mnl_nlmsg_size (size_t len)
EXPORT_SYMBOL size_t mnl_nlmsg_get_payload_len (const struct nlmsghdr *nlh)
EXPORT_SYMBOL struct nlmsghdr * mnl_nlmsg_put_header (void *buf)
EXPORT_SYMBOL void * mnl_nlmsg_put_extra_header (struct nlmsghdr *nlh, size_t size)
EXPORT_SYMBOL void * mnl_nlmsg_get_payload (const struct nlmsghdr *nlh)
EXPORT_SYMBOL void * mnl_nlmsg_get_payload_offset (const struct nlmsghdr *nlh, size_t offset)
EXPORT_SYMBOL bool mnl_nlmsg_ok (const struct nlmsghdr *nlh, int len)
EXPORT_SYMBOL struct nlmsghdr * mnl_nlmsg_next (const struct nlmsghdr *nlh, int *len)
EXPORT_SYMBOL void * mnl_nlmsg_get_payload_tail (const struct nlmsghdr *nlh)
EXPORT_SYMBOL bool mnl_nlmsg_seq_ok (const struct nlmsghdr *nlh, unsigned int seq)
EXPORT_SYMBOL bool mnl_nlmsg_portid_ok (const struct nlmsghdr *nlh, unsigned int portid)
EXPORT_SYMBOL void mnl_nlmsg_fprintf (FILE *fd, const void *data, size_t datalen, size_t extra_header_size)

Variables

size_t mnl_nlmsg_batch::limit
size_t mnl_nlmsg_batch::buflen
void * mnl_nlmsg_batch::cur
bool mnl_nlmsg_batch::overflow

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

EXPORT_SYMBOL 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:
fd pointer to file type
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 361 of file nlmsg.c.

EXPORT_SYMBOL void* mnl_nlmsg_get_payload ( const struct nlmsghdr *  nlh  ) 

mnl_nlmsg_get_payload - get a pointer to the payload of the netlink message

Parameters:
nlh pointer to a netlink header

This function returns a pointer to the payload of the netlink message.

Definition at line 116 of file nlmsg.c.

EXPORT_SYMBOL size_t mnl_nlmsg_get_payload_len ( const struct nlmsghdr *  nlh  ) 

mnl_nlmsg_get_payload_len - get the length of the Netlink payload

Parameters:
nlh pointer to the header of the Netlink message

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.

EXPORT_SYMBOL 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:
nlh pointer to a netlink header
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.

EXPORT_SYMBOL void* mnl_nlmsg_get_payload_tail ( const struct nlmsghdr *  nlh  ) 

mnl_nlmsg_get_payload_tail - get the ending of the netlink message

Parameters:
nlh pointer to netlink message

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 186 of file nlmsg.c.

EXPORT_SYMBOL struct nlmsghdr* mnl_nlmsg_next ( const struct nlmsghdr *  nlh,
int *  len 
) [read]

mnl_nlmsg_next - get the next netlink message in a multipart message

Parameters:
nlh current netlink message that we are handling
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.

EXPORT_SYMBOL bool mnl_nlmsg_ok ( const struct nlmsghdr *  nlh,
int  len 
)

mnl_nlmsg_ok - check a there is room for netlink message

Parameters:
nlh netlink message that we want to check
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 1 on success and 0 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 151 of file nlmsg.c.

EXPORT_SYMBOL bool mnl_nlmsg_portid_ok ( const struct nlmsghdr *  nlh,
unsigned int  portid 
)

mnl_nlmsg_portid_ok - perform portID origin check

Parameters:
nlh current netlink message that we are handling
seq 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.

EXPORT_SYMBOL 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:
nlh pointer to Netlink header
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 102 of file nlmsg.c.

EXPORT_SYMBOL struct nlmsghdr* mnl_nlmsg_put_header ( void *  buf  )  [read]

mnl_nlmsg_put_header - reserve and prepare room for Netlink header

Parameters:
buf memory already allocated to store the Netlink header

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.

EXPORT_SYMBOL bool mnl_nlmsg_seq_ok ( const struct nlmsghdr *  nlh,
unsigned int  seq 
)

mnl_nlmsg_seq_ok - perform sequence tracking

Parameters:
nlh current netlink message that we are handling
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.

EXPORT_SYMBOL size_t mnl_nlmsg_size ( size_t  len  ) 

mnl_nlmsg_size - calculate the size of Netlink message (without alignment)

Parameters:
len length of the Netlink payload

This function returns the size of a netlink message (header plus payload) without alignment.

Definition at line 54 of file nlmsg.c.