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