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