2 .\" Copyright (C) 2022 Alexander Chernikov <melifaro@FreeBSD.org>.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nm snl_read_message ,
38 .Nm snl_parse_header ,
40 .Nm snl_parse_attrs_raw ,
41 .Nm snl_attr_get_flag ,
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"
53 .In netlink/netlink_snl.h
54 .In netlink/netlink_snl_route.h
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"
61 .Fn snl_send "struct snl_state *ss" "void *data" "int sz"
63 .Fn snl_get_seq "struct snl_state *ss"
65 .Fn snl_allocz "struct snl_state *ss" "int len"
66 .Fn snl_clear_lb "struct snl_state *ss"
68 .Fn snl_parse_nlmsg "struct snl_state *ss" "struct nlmsghdr *hdr" "const struct snl_hdr_parser *ps" "void *target"
70 .Fn snl_parse_header "struct snl_state *ss" "void *hdr" "int len" "const struct snl_hdr_parser *ps" "int pslen" "void *target"
72 .Fn snl_parse_attrs "struct snl_state *ss" "struct nlmsghdr *hdr" "int hdrlen" "const struct snl_attr_parser *ps" "int pslen" "void *target"
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"
76 .Fn snl_attr_get_flag "struct snl_state *ss" "struct nlattr *nla" "void *target"
78 .Fn snl_attr_get_uint8 "struct snl_state *ss" "struct nlattr *nla" "void *target"
80 .Fn snl_attr_get_uint16 "struct snl_state *ss" "struct nlattr *nla" "void *target"
82 .Fn snl_attr_get_uint32 "struct snl_state *ss" "struct nlattr *nla" "void *target"
84 .Fn snl_attr_get_uint64 "struct snl_state *ss" "struct nlattr *nla" "void *target"
86 .Fn snl_attr_get_string "struct snl_state *ss" "struct nlattr *nla" "void *target"
88 .Fn snl_attr_get_stringn "struct snl_state *ss" "struct nlattr *nla" "void *target"
90 .Fn snl_attr_get_nla "struct snl_state *ss" "struct nlattr *nla" "void *target"
92 .Fn snl_attr_get_ip "struct snl_state *ss" "struct nlattr *nla" "void *target"
94 .Fn snl_attr_get_ipvia "struct snl_state *ss" "struct nlattr *nla" "void *target"
98 library provides an easy way of sending and receiving Netlink messages,
99 taking care of serialisation and deserialisation.
103 with a pointer to the
105 and the desired Netlink family to initialise the library instance.
106 To free the library instance, call
109 The library functions are NOT multithread-safe.
110 If multithreading is desired, consider initializing an instance
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
117 and free all allocated data at once using
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:
127 struct ifinfomsg ifmsg;
129 .hdr.nlmsg_type = RTM_GETLINK,
130 .hdr.nlmsg_flags = NLM_F_DUMP | NLM_F_REQUEST,
131 .hdr.nlmsg_seq = snl_get_seq(ss),
133 msg.hdr.nlmsg_len = sizeof(msg);
136 can be used to generate a unique message number.
137 To send the resulting message,
140 .Ss RECEIVING AND PARSING MESSAGES
141 To receive a message, use
142 .Fn snl_read_message .
143 Currently, this call is blocking.
145 The library provides an easy way to convert the message to the pre-defined C
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.
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.
161 Each attribute getter needs to be embedded in the following structure:
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 */
171 The generic attribute getter has the following signature:
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,
181 It is possible to use
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
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.
198 .Fn snl_attr_get_ipvia
199 stores a pointer to the sockaddr structure with the IPv4/IPv6 address contained
201 Sockaddr is allocated using
203 .Fn snl_attr_get_string
204 stores a pointer to the NULL-terminated string.
205 The string itself is allocated using
208 stores a pointer to the specified attribute.
209 .Fn snl_attr_get_stringn
210 stores a pointer to the non-NULL-terminated string.
212 Similarly, each family header getter needs to be embedded in the following structure:
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 */
221 The generic field getter has the following signature:
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.
232 The following example demonstrates how to list all system interfaces
237 #include <netlink/netlink.h>
238 #include <netlink/netlink_route.h>
239 #include "netlink/netlink_snl.h"
240 #include "netlink/netlink_snl_route.h"
242 struct nl_parsed_link {
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 },
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 },
259 SNL_DECLARE_PARSER(link_parser, struct ifinfomsg, fp_link, ap_link);
263 main(int ac, char *argv[])
267 if (!snl_init(&ss, NETLINK_ROUTE))
272 struct ifinfomsg ifmsg;
274 .hdr.nlmsg_type = RTM_GETLINK,
275 .hdr.nlmsg_flags = NLM_F_DUMP | NLM_F_REQUEST,
276 .hdr.nlmsg_seq = snl_get_seq(&ss),
278 msg.hdr.nlmsg_len = sizeof(msg);
280 if (!snl_send(&ss, &msg, sizeof(msg))) {
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)
290 struct nl_parsed_link link = {};
291 if (!snl_parse_nlmsg(&ss, hdr, &link_parser, &link))
293 printf("Link#%u %s mtu %u\n", link.ifi_index, link.ifla_ifname, link.ifla_mtu);
310 This library was implemented by
311 .An Alexander Chernikov Aq Mt melifaro@FreeBSD.org .