share/man/man3/snl.3

   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
  94 The
  95 .Xr snl 3
  96 library provides an easy way of sending and receiving Netlink messages,
  97 taking care of serialisation and deserialisation.
  98 .Ss INITIALISATION
  99 Call
 100 .Fn snl_init
 101 with a pointer to the
 102 .Dv struct snl_state
 103 and the desired Netlink family to initialise the library instance.
 104 To free the library instance, call
 105 .Fn snl_free .
 106 .Pp
 107 The library functions are NOT multithread-safe.
 108 If multithreading is desired, consider initializing an instance
 109 per thread.
 110 .Ss MEMORY ALLOCATION
 111 The library uses pre-allocated extendable memory buffers to handle message parsing.
 112 The typical usage pattern is to allocate the necessary data structures during the
 113 message parsing or writing process via
 114 .Fn snl_allocz
 115 and free all allocated data at once using
 116 .Fn snl_clear_lb
 117 after handling the message.
 118 .Ss COMPOSING AND SENDING MESSAGES
 119 The library does not currently offer any wrappers for writing netlink messages.
 120 Simple request messages can be composed by filling in all needed fields directly.
 121 Example 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
 134 can be used to generate a unique message number.
 135 To send the resulting message,
 136 .Fn snl_send
 137 can be used.
 138 .Ss RECEIVING AND PARSING MESSAGES
 139 To receive a message, use
 140 .Fn snl_read_message .
 141 Currently, this call is blocking.
 142 .Pp
 143 The library provides an easy way to convert the message to the pre-defined C
 144 structure.
 145 For each message type, one needs to define rules, converting the protocol header
 146 fields and the desired attributes to the specified structure.
 147 It can be accomplished by using message parsers.
 148 Each message parser consists of an array of attribute getters and an array of
 149 header field getters.
 150 The former array needs to be sorted by the attribute type.
 151 There is a
 152 .Fn SNL_VERIFY_PARSERS
 153 macro 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[]"
 155 can be used to create a new parser.
 156 .Fn SNL_DECLARE_ATTR_PARSER "parser_name" "struct snl_field_parser[]"
 157 can be used to create an attribute-only message parser.
 158 .Pp
 159 Each attribute getter needs to be embedded in the following structure:
 160 .Bd -literal
 161 typedef bool snl_parse_attr_f(struct snl_state *ss, struct nlattr *attr, const void *arg, void *target);
 162 struct 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
 169 The 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" .
 172 nla contains the pointer of the attribute to use as the datasource.
 173 The target field is the pointer to the field in the target structure.
 174 It is up to the getter to know the type of the target field.
 175 The getter must check the input attribute and return
 176 false if the attribute is not formed correctly.
 177 Otherwise, the getter fetches the attribute value and stores it in the target,
 178 then returns true.
 179 It is possible to use
 180 .Fn snl_allocz
 181 to create the desired data structure .
 182 A number of predefined getters for the common data types exist.
 183 .Fn snl_attr_get_flag
 184 converts a flag-type attribute to an uint8_t value of 1 or 0, depending on the
 185 attribute presence.
 186 .Fn snl_attr_get_uint8
 187 stores a uint8_t type attribute into the uint8_t target field.
 188 .Fn snl_attr_get_uint16
 189 stores a uint16_t type attribute into the uint16_t target field.
 190 .Fn snl_attr_get_uint32
 191 stores a uint32_t type attribute into the uint32_t target field.
 192 .Fn snl_attr_get_uint64
 193 stores a uint64_t type attribute into the uint64_t target field.
 194 .Fn snl_attr_get_ip
 195 and
 196 .Fn snl_attr_get_ipvia
 197 stores a pointer to the sockaddr structure with the IPv4/IPv6 address contained
 198 in the attribute.
 199 Sockaddr is allocated using
 200 .Fn snl_allocz .
 201 .Fn snl_attr_get_string
 202 stores a pointer to the NULL-terminated string.
 203 The string itself is allocated using
 204 .Fn snl_allocz .
 205 .Fn snl_attr_get_nla
 206 stores a pointer to the specified attribute.
 207 .Fn snl_attr_get_stringn
 208 stores a pointer to the non-NULL-terminated string.
 209 .Pp
 210 Similarly, each family header getter needs to be embedded in the following structure:
 211 .Bd -literal
 212 typedef void snl_parse_field_f(struct snl_state *ss, void *hdr, void *target);
 213 struct 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
 219 The generic field getter has the following signature:
 220 .Ft "void"
 221 snl_field_get_<type> "struct snl_state *ss" "void *src" "void *target" .
 222 A number of pre-defined getters for the common data types exist.
 223 .Fn "snl_field_get_uint8"
 224 fetches an uint8_t value and stores it in the target.
 225 .Fn "snl_field_get_uint16"
 226 fetches an uint8_t value and stores it in the target.
 227 .Fn "snl_field_get_uint32"
 228 fetches an uint32_t value and stores it in the target.
 229 .Sh EXAMPLES
 230 The following example demonstrates how to list all system interfaces
 231 using 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
 240 struct 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)
 248 static 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 };
 252 static 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
 257 SNL_DECLARE_PARSER(link_parser, struct ifinfomsg, fp_link, ap_link);
 258
 259
 260 int
 261 main(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 ,
 300 and
 301 .Xr rtnetlink 4
 302 .Sh HISTORY
 303 The
 304 .Dv SNL
 305 library appeared in
 306 .Fx 13.2 .
 307 .Sh AUTHORS
 308 This library was implemented by
 309 .An Alexander Chernikov Aq Mt melifaro@FreeBSD.org .