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