nlmsg(3)

📦
version 1.0.5 · 2 versions
, in debian trixie, ubuntu noble, ubuntu questing

okay bestie, buckle up 🎀 this is nlmsg, the Netlink message helper page from the Library Functions Manual. It's giving "I write raw netlink packets by hand and I'm thriving" energy. Let's go 💅

🌸 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 🌈

so like. a Netlink message. the blueprint. the whole vibe, laid out for you 🦋:

|<----------------- 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. no cap, that's the whole structure. iconic. 👑

👑 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

  • 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 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

  • nlh — pointer to a netlink header

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

  • 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.

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.

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 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

  • 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.

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 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

  • nlh — current netlink message that we are handling
  • 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

  • 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 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

  • 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.

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.

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.

💜 AUTHOR 💜

Generated automatically by Doxygen for libmnl from the source code.

and that's the whole page bestie, you ate that 🍓✨ this one shipped with libmnl, Version 1.0.5, and it's filed under the manual name nlmsg(3) — go forth and build your netlink messages like the main character you are 💅👑🦋

📦 where this page comes from