1.\" 2.\" Copyright (C) 2022 Alexander Chernikov <melifaro@FreeBSD.org>. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.Dd December 16, 2022 25.Dt SNL 3 26.Os 27.Sh NAME 28.Nm snl_init , 29.Nm snl_free , 30.Nm snl_read_message , 31.Nm snl_send , 32.Nm snl_get_seq , 33.Nm snl_allocz , 34.Nm snl_clear_lb , 35.Nm snl_parse_nlmsg , 36.Nm snl_parse_header , 37.Nm snl_parse_attrs , 38.Nm snl_parse_attrs_raw , 39.Nm snl_attr_get_flag , 40.Nm snl_attr_get_ip , 41.Nm snl_attr_get_uint16 , 42.Nm snl_attr_get_uint32 , 43.Nm snl_attr_get_string , 44.Nm snl_attr_get_stringn , 45.Nm snl_attr_get_nla , 46.Nm snl_field_get_uint8 , 47.Nm snl_field_get_uint16 , 48.Nm snl_field_get_uint32 49.Nd "simple netlink library" 50.Sh SYNOPSIS 51.In netlink/netlink_snl.h 52.In netlink/netlink_snl_route.h 53.Ft "bool" 54.Fn snl_init "struct snl_state *ss" "int netlink_family" 55.Fn snl_free "struct snl_state *ss" 56.Ft "struct nlmsghdr *" 57.Fn snl_read_message "struct snl_state *ss" 58.Ft "bool" 59.Fn snl_send "struct snl_state *ss" "void *data" "int sz" 60.Ft "uint32_t" 61.Fn snl_get_seq "struct snl_state *ss" 62.Ft "void *" 63.Fn snl_allocz "struct snl_state *ss" "int len" 64.Fn snl_clear_lb "struct snl_state *ss" 65.Ft "bool" 66.Fn snl_parse_nlmsg "struct snl_state *ss" "struct nlmsghdr *hdr" "const struct snl_hdr_parser *ps" "void *target" 67.Ft "bool" 68.Fn snl_parse_header "struct snl_state *ss" "void *hdr" "int len" "const struct snl_hdr_parser *ps" "int pslen" "void *target" 69.Ft "bool" 70.Fn snl_parse_attrs "struct snl_state *ss" "struct nlmsghdr *hdr" "int hdrlen" "const struct snl_attr_parser *ps" "int pslen" "void *target" 71.Ft "bool" 72.Fn snl_parse_attrs_raw "struct snl_state *ss" "struct nlattr *nla_head" "int len" "const struct snl_attr_parser *ps" "int pslen" "void *target" 73.Ft "bool" 74.Fn snl_attr_get_flag "struct snl_state *ss" "struct nlattr *nla" "void *target" 75.Ft "bool" 76.Fn snl_attr_get_uint8 "struct snl_state *ss" "struct nlattr *nla" "void *target" 77.Ft "bool" 78.Fn snl_attr_get_uint16 "struct snl_state *ss" "struct nlattr *nla" "void *target" 79.Ft "bool" 80.Fn snl_attr_get_uint32 "struct snl_state *ss" "struct nlattr *nla" "void *target" 81.Ft "bool" 82.Fn snl_attr_get_uint64 "struct snl_state *ss" "struct nlattr *nla" "void *target" 83.Ft "bool" 84.Fn snl_attr_get_string "struct snl_state *ss" "struct nlattr *nla" "void *target" 85.Ft "bool" 86.Fn snl_attr_get_stringn "struct snl_state *ss" "struct nlattr *nla" "void *target" 87.Ft "bool" 88.Fn snl_attr_get_nla "struct snl_state *ss" "struct nlattr *nla" "void *target" 89.Ft "bool" 90.Fn snl_attr_get_ip "struct snl_state *ss" "struct nlattr *nla" "void *target" 91.Ft "bool" 92.Fn snl_attr_get_ipvia "struct snl_state *ss" "struct nlattr *nla" "void *target" 93.Sh DESCRIPTION 94The 95.Xr snl 3 96library provides an easy way of sending and receiving Netlink messages, 97taking care of serialisation and deserialisation. 98.Ss INITIALISATION 99Call 100.Fn snl_init 101with a pointer to the 102.Dv struct snl_state 103and the desired Netlink family to initialise the library instance. 104To free the library instance, call 105.Fn snl_free . 106.Pp 107The library functions are NOT multithread-safe. 108If multithreading is desired, consider initializing an instance 109per thread. 110.Ss MEMORY ALLOCATION 111The library uses pre-allocated extendable memory buffers to handle message parsing. 112The typical usage pattern is to allocate the necessary data structures during the 113message parsing or writing process via 114.Fn snl_allocz 115and free all allocated data at once using 116.Fn snl_clear_lb 117after handling the message. 118.Ss COMPOSING AND SENDING MESSAGES 119The library does not currently offer any wrappers for writing netlink messages. 120Simple request messages can be composed by filling in all needed fields directly. 121Example for constructing an interface dump request: 122.Bd -literal 123 struct { 124 struct nlmsghdr hdr; 125 struct ifinfomsg ifmsg; 126 } msg = { 127 .hdr.nlmsg_type = RTM_GETLINK, 128 .hdr.nlmsg_flags = NLM_F_DUMP | NLM_F_REQUEST, 129 .hdr.nlmsg_seq = snl_get_seq(ss), 130 }; 131 msg.hdr.nlmsg_len = sizeof(msg); 132.Ed 133.Fn snl_get_seq 134can be used to generate a unique message number. 135To send the resulting message, 136.Fn snl_send 137can be used. 138.Ss RECEIVING AND PARSING MESSAGES 139To receive a message, use 140.Fn snl_read_message . 141Currently, this call is blocking. 142.Pp 143The library provides an easy way to convert the message to the pre-defined C 144structure. 145For each message type, one needs to define rules, converting the protocol header 146fields and the desired attributes to the specified structure. 147It can be accomplished by using message parsers. 148Each message parser consists of an array of attribute getters and an array of 149header field getters. 150The former array needs to be sorted by the attribute type. 151There is a 152.Fn SNL_VERIFY_PARSERS 153macro to check if the order is correct. 154.Fn SNL_DECLARE_PARSER "parser_name" "family header type" "struct snl_field_parser[]" "struct snl_attr_parser[]" 155can be used to create a new parser. 156.Fn SNL_DECLARE_ATTR_PARSER "parser_name" "struct snl_field_parser[]" 157can be used to create an attribute-only message parser. 158.Pp 159Each attribute getter needs to be embedded in the following structure: 160.Bd -literal 161typedef bool snl_parse_attr_f(struct snl_state *ss, struct nlattr *attr, const void *arg, void *target); 162struct snl_attr_parser { 163 uint16_t type; /* Attribute type */ 164 uint16_t off; /* field offset in the target structure */ 165 snl_parse_attr_f *cb; /* getter function to call */ 166 const void *arg; /* getter function custom argument */ 167}; 168.Ed 169The generic attribute getter has the following signature: 170.Ft "bool" 171.Fn snl_attr_get_<type> "struct snl_state *ss" "struct nlattr *nla" "const void *arg" "void *target" . 172nla contains the pointer of the attribute to use as the datasource. 173The target field is the pointer to the field in the target structure. 174It is up to the getter to know the type of the target field. 175The getter must check the input attribute and return 176false if the attribute is not formed correctly. 177Otherwise, the getter fetches the attribute value and stores it in the target, 178then returns true. 179It is possible to use 180.Fn snl_allocz 181to create the desired data structure . 182A number of predefined getters for the common data types exist. 183.Fn snl_attr_get_flag 184converts a flag-type attribute to an uint8_t value of 1 or 0, depending on the 185attribute presence. 186.Fn snl_attr_get_uint8 187stores a uint8_t type attribute into the uint8_t target field. 188.Fn snl_attr_get_uint16 189stores a uint16_t type attribute into the uint16_t target field. 190.Fn snl_attr_get_uint32 191stores a uint32_t type attribute into the uint32_t target field. 192.Fn snl_attr_get_uint64 193stores a uint64_t type attribute into the uint64_t target field. 194.Fn snl_attr_get_ip 195and 196.Fn snl_attr_get_ipvia 197stores a pointer to the sockaddr structure with the IPv4/IPv6 address contained 198in the attribute. 199Sockaddr is allocated using 200.Fn snl_allocz . 201.Fn snl_attr_get_string 202stores a pointer to the NULL-terminated string. 203The string itself is allocated using 204.Fn snl_allocz . 205.Fn snl_attr_get_nla 206stores a pointer to the specified attribute. 207.Fn snl_attr_get_stringn 208stores a pointer to the non-NULL-terminated string. 209.Pp 210Similarly, each family header getter needs to be embedded in the following structure: 211.Bd -literal 212typedef void snl_parse_field_f(struct snl_state *ss, void *hdr, void *target); 213struct snl_field_parser { 214 uint16_t off_in; /* field offset in the input structure */ 215 uint16_t off_out;/* field offset in the target structure */ 216 snl_parse_field_f *cb; /* getter function to call */ 217}; 218.Ed 219The generic field getter has the following signature: 220.Ft "void" 221snl_field_get_<type> "struct snl_state *ss" "void *src" "void *target" . 222A number of pre-defined getters for the common data types exist. 223.Fn "snl_field_get_uint8" 224fetches an uint8_t value and stores it in the target. 225.Fn "snl_field_get_uint16" 226fetches an uint8_t value and stores it in the target. 227.Fn "snl_field_get_uint32" 228fetches an uint32_t value and stores it in the target. 229.Sh EXAMPLES 230The following example demonstrates how to list all system interfaces 231using netlink. 232.Bd -literal 233#include <stdio.h> 234 235#include <netlink/netlink.h> 236#include <netlink/netlink_route.h> 237#include "netlink/netlink_snl.h" 238#include "netlink/netlink_snl_route.h" 239 240struct nl_parsed_link { 241 uint32_t ifi_index; 242 uint32_t ifla_mtu; 243 char *ifla_ifname; 244}; 245 246#define _IN(_field) offsetof(struct ifinfomsg, _field) 247#define _OUT(_field) offsetof(struct nl_parsed_link, _field) 248static const struct snl_attr_parser ap_link[] = { 249 { .type = IFLA_IFNAME, .off = _OUT(ifla_ifname), .cb = snl_attr_get_string }, 250 { .type = IFLA_MTU, .off = _OUT(ifla_mtu), .cb = snl_attr_get_uint32 }, 251}; 252static const struct snl_field_parser fp_link[] = { 253 {.off_in = _IN(ifi_index), .off_out = _OUT(ifi_index), .cb = snl_field_get_uint32 }, 254}; 255#undef _IN 256#undef _OUT 257SNL_DECLARE_PARSER(link_parser, struct ifinfomsg, fp_link, ap_link); 258 259 260int 261main(int ac, char *argv[]) 262{ 263 struct snl_state ss; 264 265 if (!snl_init(&ss, NETLINK_ROUTE)) 266 return (1); 267 268 struct { 269 struct nlmsghdr hdr; 270 struct ifinfomsg ifmsg; 271 } msg = { 272 .hdr.nlmsg_type = RTM_GETLINK, 273 .hdr.nlmsg_flags = NLM_F_DUMP | NLM_F_REQUEST, 274 .hdr.nlmsg_seq = snl_get_seq(&ss), 275 }; 276 msg.hdr.nlmsg_len = sizeof(msg); 277 278 if (!snl_send(&ss, &msg, sizeof(msg))) { 279 snl_free(&ss); 280 return (1); 281 } 282 283 struct nlmsghdr *hdr; 284 while ((hdr = snl_read_message(&ss)) != NULL && hdr->nlmsg_type != NLMSG_DONE) { 285 if (hdr->nlmsg_seq != msg.hdr.nlmsg_seq) 286 break; 287 288 struct nl_parsed_link link = {}; 289 if (!snl_parse_nlmsg(&ss, hdr, &link_parser, &link)) 290 continue; 291 printf("Link#%u %s mtu %u\n", link.ifi_index, link.ifla_ifname, link.ifla_mtu); 292 } 293 294 return (0); 295} 296.Ed 297.Sh SEE ALSO 298.Xr genetlink 4 , 299.Xr netlink 4 , 300and 301.Xr rtnetlink 4 302.Sh HISTORY 303The 304.Dv SNL 305library appeared in 306.Fx 13.2 . 307.Sh AUTHORS 308This library was implemented by 309.An Alexander Chernikov Aq Mt melifaro@FreeBSD.org . 310