SNL(3)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

💅 SNL — simple netlink library 💅

okay so bestie, today we're learning snl, a lil library from the Library Functions Manual section 3. it's giving "netlink but make it not a nightmare" and honestly? iconic. it handles the serialisation and deserialisation of Netlink messages for you so you don't have to rawdog the byte layout yourself. slay.

the whole squad of functions is: 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.

✨ SYNOPSIS ✨

first things first, the includes 🫶

#include <netlink/netlink_snl.h>
#include <netlink/netlink_snl_route.h>

then the whole cast, in order, no skipping:

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) library is literally your bestie for sending and receiving Netlink messages — it takes care of serialisation and deserialisation so you don't have to. no cap, that's the whole vibe.

💖 INITIALISATION 💖

call snl_init() with a pointer to the struct snl_state and the Netlink family you want, and boom — your library instance is initialised. when you're done with it, call snl_free() to free it. clean up after yourself, periodt.

⚠️ vibe check: the library functions are NOT multithread-safe. like, at all. if you want multithreading, consider initialising an instance per thread. iykyk.

🎀 MEMORY ALLOCATION 🎀

the library uses pre-allocated, extendable memory buffers to handle message parsing. the typical usage pattern is: allocate the data structures you need while you're parsing or writing the message using snl_allocz(), then free all of the allocated data at once with snl_clear_lb() after you're done handling the message. it's giving "mass cleanup, one call, no crumbs". 💅

🦋 COMPOSING AND SENDING MESSAGES 🦋

rght now the library does not offer any wrappers for writing netlink messages — so you're on your own for the writing part, bestie. simple request messages can be composed by filling in all the needed fields directly. here's the 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 ✨ and to send the resulting message, you use snl_send(). that's it, that's the whole flow.

🌈 RECEIVING AND PARSING MESSAGES 🌈

to receive a message, use snl_read_message(). heads up tho: currently, this call is blocking. so like, it will sit there and wait. 🫠

the library provides an easy way to convert the message to the pre-defined C structure. for each message type, you need to define rules that convert the protocol header fields and the desired attributes to the specified structure. you do this with 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 — don't skip that part, it's important. there's a SNL_VERIFY_PARSERS() macro to check if the order is correct. you can use SNL_DECLARE_PARSER(parser_name, family header type, struct snl_field_parser[], struct snl_attr_parser[]) to create a new parser, and SNL_DECLARE_ATTR_PARSER(parser_name, struct snl_field_parser[]) 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_<type>(struct snl_state *ss, struct nlattr *nla, const void *arg, void *target). nla contains the pointer of the attribute to use as the datasource, and the target field is the pointer to the field in the target structure. it's 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. you can use snl_allocz() to create the desired data structure. 💖

a number of predefined getters for the common data types exist, and they're all gorgeous:

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() store a pointer to the sockaddr structure with the IPv4/IPv6 address contained in the attribute. the 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_<type> "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 🔥

this example demonstrates how to list all system interfaces using netlink. it's lowkey a whole mood, so here's the entire thing, character for character:

#include <stdio.h>

#include <netlink/netlink.h>
#include <netlink/netlink_route.h>
#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 %u0, link.ifi_index, link.ifla_ifname, link.ifla_mtu);
        }

        return (0);
}

👀 SEE ALSO 👀

go read genetlink(4), netlink(4), and rtnetlink(4) — bestie homework, do it. 📚

⭐ HISTORY ⭐

the SNL library appeared in FreeBSD 13.2. she's a legend, she's an icon, and she is the moment.

💜 AUTHORS 💜

this library was implemented by Alexander Chernikov <melifaro@FreeBSD.org>. thank you for your service, king 🫡

and that's a wrap on the manual page, bestie!! this page ships with Debian, dated December 16, 2022, and it lives at SNL(3) in the Library Functions Manual if you ever need to find her again. go forth and parse, mwah 💖✨🎀

📦 where this page comes from

freebsd 14.5: base 14.5
freebsd 15.1: base 15.1
nixpkgs unstable: source
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms