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