--- name: "snl" section: "3" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/snl" --- # snl(3) simple netlink library ## NAME **snl\_init**, **snl\_free**, **snl\_read\_message**, **snl\_send**, **snl\_get\_seq**, **snl\_allocz**, **snl\_clear\_lb**, **snl\_parse\_nlmsg**, **snl\_parse\_header**, **snl\_parse\_attrs**, **snl\_parse\_attrs\_raw**, **snl\_attr\_get\_flag**, **snl\_attr\_get\_ip**, **snl\_attr\_get\_uint16**, **snl\_attr\_get\_uint32**, **snl\_attr\_get\_string**, **snl\_attr\_get\_stringn**, **snl\_attr\_get\_nla**, **snl\_field\_get\_uint8**, **snl\_field\_get\_uint16**, **snl\_field\_get\_uint32** – simple netlink library ## SYNOPSIS **#include \** **#include \** *bool*\ **snl\_init**(*struct snl\_state \*ss*, *int netlink\_family*); **snl\_free**(*struct snl\_state \*ss*); *struct nlmsghdr \**\ **snl\_read\_message**(*struct snl\_state \*ss*); *bool*\ **snl\_send**(*struct snl\_state \*ss*, *void \*data*, *int sz*); *uint32\_t*\ **snl\_get\_seq**(*struct snl\_state \*ss*); *void \**\ **snl\_allocz**(*struct snl\_state \*ss*, *int len*); **snl\_clear\_lb**(*struct snl\_state \*ss*); *bool*\ **snl\_parse\_nlmsg**(*struct snl\_state \*ss*, *struct nlmsghdr \*hdr*, *const struct snl\_hdr\_parser \*ps*, *void \*target*); *bool*\ **snl\_parse\_header**(*struct snl\_state \*ss*, *void \*hdr*, *int len*, *const struct snl\_hdr\_parser \*ps*, *int pslen*, *void \*target*); *bool*\ **snl\_parse\_attrs**(*struct snl\_state \*ss*, *struct nlmsghdr \*hdr*, *int hdrlen*, *const struct snl\_attr\_parser \*ps*, *int pslen*, *void \*target*); *bool*\ **snl\_parse\_attrs\_raw**(*struct snl\_state \*ss*, *struct nlattr \*nla\_head*, *int len*, *const struct snl\_attr\_parser \*ps*, *int pslen*, *void \*target*); *bool*\ **snl\_attr\_get\_flag**(*struct snl\_state \*ss*, *struct nlattr \*nla*, *void \*target*); *bool*\ **snl\_attr\_get\_uint8**(*struct snl\_state \*ss*, *struct nlattr \*nla*, *void \*target*); *bool*\ **snl\_attr\_get\_uint16**(*struct snl\_state \*ss*, *struct nlattr \*nla*, *void \*target*); *bool*\ **snl\_attr\_get\_uint32**(*struct snl\_state \*ss*, *struct nlattr \*nla*, *void \*target*); *bool*\ **snl\_attr\_get\_uint64**(*struct snl\_state \*ss*, *struct nlattr \*nla*, *void \*target*); *bool*\ **snl\_attr\_get\_string**(*struct snl\_state \*ss*, *struct nlattr \*nla*, *void \*target*); *bool*\ **snl\_attr\_get\_stringn**(*struct snl\_state \*ss*, *struct nlattr \*nla*, *void \*target*); *bool*\ **snl\_attr\_get\_nla**(*struct snl\_state \*ss*, *struct nlattr \*nla*, *void \*target*); *bool*\ **snl\_attr\_get\_ip**(*struct snl\_state \*ss*, *struct nlattr \*nla*, *void \*target*); *bool*\ **snl\_attr\_get\_ipvia**(*struct snl\_state \*ss*, *struct nlattr \*nla*, *void \*target*); ## DESCRIPTION The [snl(3)](/snl/3.md) library provides an easy way of sending and receiving Netlink messages, taking care of serialisation and deserialisation. ### INITIALISATION Call **snl\_init**() with a pointer to the struct snl\_state and the desired Netlink family to initialise the library instance. To free the library instance, call **snl\_free**(). The library functions are NOT multithread-safe. If multithreading is desired, consider initializing an instance per thread. ### MEMORY ALLOCATION The library uses pre-allocated extendable memory buffers to handle message parsing. The typical usage pattern is to allocate the necessary data structures during the message parsing or writing process via **snl\_allocz**() and free all allocated data at once using **snl\_clear\_lb**() after handling the message. ### COMPOSING AND SENDING MESSAGES The library does not currently offer any wrappers for writing netlink messages. Simple request messages can be composed by filling in all needed fields directly. Example for constructing an interface dump request: ``` struct { struct nlmsghdr hdr; struct ifinfomsg ifmsg; } msg = { .hdr.nlmsg_type = RTM_GETLINK, .hdr.nlmsg_flags = NLM_F_DUMP | NLM_F_REQUEST, .hdr.nlmsg_seq = snl_get_seq(ss), }; msg.hdr.nlmsg_len = sizeof(msg); ``` **snl\_get\_seq**() can be used to generate a unique message number. To send the resulting message, **snl\_send**() can be used. ### RECEIVING AND PARSING MESSAGES To receive a message, use **snl\_read\_message**(). Currently, this call is blocking. The library provides an easy way to convert the message to the pre-defined C structure. For each message type, one needs to define rules, converting the protocol header fields and the desired attributes to the specified structure. It can be accomplished by using message parsers. Each message parser consists of an array of attribute getters and an array of header field getters. The former array needs to be sorted by the attribute type. There is a **SNL\_VERIFY\_PARSERS**() macro to check if the order is correct. **SNL\_DECLARE\_PARSER**(*parser\_name*, *family header type*, *struct snl\_field\_parser\[\]*, *struct snl\_attr\_parser\[\]*) can be used to create a new parser. **SNL\_DECLARE\_ATTR\_PARSER**(*parser\_name*, *struct snl\_field\_parser\[\]*) can be used to create an attribute-only message parser. Each attribute getter needs to be embedded in the following structure: ``` typedef bool snl_parse_attr_f(struct snl_state *ss, struct nlattr *attr, const void *arg, void *target); struct snl_attr_parser { uint16_t type; /* Attribute type */ uint16_t off; /* field offset in the target structure */ snl_parse_attr_f *cb; /* getter function to call */ const void *arg; /* getter function custom argument */ }; ``` The generic attribute getter has the following signature: *bool* **snl\_attr\_get\_\**(*struct snl\_state \*ss*, *struct nlattr \*nla*, *const void \*arg*, *void \*target*). nla contains the pointer of the attribute to use as the datasource. The target field is the pointer to the field in the target structure. It is up to the getter to know the type of the target field. The getter must check the input attribute and return false if the attribute is not formed correctly. Otherwise, the getter fetches the attribute value and stores it in the target, then returns true. It is possible to use **snl\_allocz**() to create the desired data structure . A number of predefined getters for the common data types exist. **snl\_attr\_get\_flag**() converts a flag-type attribute to an uint8\_t value of 1 or 0, depending on the attribute presence. **snl\_attr\_get\_uint8**() stores a uint8\_t type attribute into the uint8\_t target field. **snl\_attr\_get\_uint16**() stores a uint16\_t type attribute into the uint16\_t target field. **snl\_attr\_get\_uint32**() stores a uint32\_t type attribute into the uint32\_t target field. **snl\_attr\_get\_uint64**() stores a uint64\_t type attribute into the uint64\_t target field. **snl\_attr\_get\_ip**() and **snl\_attr\_get\_ipvia**() stores a pointer to the sockaddr structure with the IPv4/IPv6 address contained in the attribute. Sockaddr is allocated using **snl\_allocz**(). **snl\_attr\_get\_string**() stores a pointer to the NULL-terminated string. The string itself is allocated using **snl\_allocz**(). **snl\_attr\_get\_nla**() stores a pointer to the specified attribute. **snl\_attr\_get\_stringn**() stores a pointer to the non-NULL-terminated string. Similarly, each family header getter needs to be embedded in the following structure: ``` typedef void snl_parse_field_f(struct snl_state *ss, void *hdr, void *target); struct snl_field_parser { uint16_t off_in; /* field offset in the input structure */ uint16_t off_out;/* field offset in the target structure */ snl_parse_field_f *cb; /* getter function to call */ }; ``` The generic field getter has the following signature: *void* snl\_field\_get\_\ "struct snl\_state \*ss" "void \*src" "void \*target" . A number of pre-defined getters for the common data types exist. **snl\_field\_get\_uint8**() fetches an uint8\_t value and stores it in the target. **snl\_field\_get\_uint16**() fetches an uint8\_t value and stores it in the target. **snl\_field\_get\_uint32**() fetches an uint32\_t value and stores it in the target. ## EXAMPLES The following example demonstrates how to list all system interfaces using netlink. ``` #include #include #include #include "netlink/netlink_snl.h" #include "netlink/netlink_snl_route.h" struct nl_parsed_link { uint32_t ifi_index; uint32_t ifla_mtu; char *ifla_ifname; }; #define _IN(_field) offsetof(struct ifinfomsg, _field) #define _OUT(_field) offsetof(struct nl_parsed_link, _field) static const struct snl_attr_parser ap_link[] = { { .type = IFLA_IFNAME, .off = _OUT(ifla_ifname), .cb = snl_attr_get_string }, { .type = IFLA_MTU, .off = _OUT(ifla_mtu), .cb = snl_attr_get_uint32 }, }; static const struct snl_field_parser fp_link[] = { {.off_in = _IN(ifi_index), .off_out = _OUT(ifi_index), .cb = snl_field_get_uint32 }, }; #undef _IN #undef _OUT SNL_DECLARE_PARSER(link_parser, struct ifinfomsg, fp_link, ap_link); int main(int ac, char *argv[]) { struct snl_state ss; if (!snl_init(&ss, NETLINK_ROUTE)) return (1); struct { struct nlmsghdr hdr; struct ifinfomsg ifmsg; } msg = { .hdr.nlmsg_type = RTM_GETLINK, .hdr.nlmsg_flags = NLM_F_DUMP | NLM_F_REQUEST, .hdr.nlmsg_seq = snl_get_seq(&ss), }; msg.hdr.nlmsg_len = sizeof(msg); if (!snl_send(&ss, &msg, sizeof(msg))) { snl_free(&ss); return (1); } struct nlmsghdr *hdr; while ((hdr = snl_read_message(&ss)) != NULL && hdr->nlmsg_type != NLMSG_DONE) { if (hdr->nlmsg_seq != msg.hdr.nlmsg_seq) break; struct nl_parsed_link link = {}; if (!snl_parse_nlmsg(&ss, hdr, &link_parser, &link)) continue; printf("Link#%u %s mtu %u\n", link.ifi_index, link.ifla_ifname, link.ifla_mtu); } return (0); } ``` ## SEE ALSO [genetlink(4)](/genetlink/4.md), [netlink(4)](/netlink/4.md), and [rtnetlink(4)](/rtnetlink/4.md) ## HISTORY The SNL library appeared in FreeBSD 13.2. ## AUTHORS This library was implemented by Alexander Chernikov ⟨*melifaro@FreeBSD.org*⟩.