]>
Commit | Line | Data |
---|---|---|
1e4369d7 JB |
1 | From fec10a282355def49133e63b8a4591cc51b46478 Mon Sep 17 00:00:00 2001 |
2 | From: Thomas Graf <tgraf@redhat.com> | |
3 | Date: Thu, 10 May 2012 12:03:59 +0200 | |
4 | Subject: [PATCH] doc: documentation restructuring | |
5 | ||
6 | - changes the modules hierarchy to better represent the set of libaries | |
7 | - list the header file that needs to be included | |
8 | - remove examples/doc from api ref that is included in the guide | |
9 | - add references to the guide | |
10 | - fix doxygen api linking for version 1.8.0 | |
11 | - readd doxygen mainpage to config file | |
12 | - fix a couple of doxygen doc bugs | |
13 | --- | |
14 | configure.in | 12 +-- | |
15 | doc/Doxyfile.in | 13 +- | |
16 | doc/Makefile.am | 21 ++-- | |
17 | doc/README | 4 +- | |
18 | doc/api/.gitignore | 1 + | |
19 | doc/core.txt | 11 ++ | |
20 | doc/gen-tags.sh | 10 +- | |
21 | doc/src/toc.c | 17 +-- | |
22 | doc/tags2dict.sh | 8 - | |
23 | include/netlink/attr.h | 14 +- | |
24 | include/netlink/types.h | 8 +- | |
25 | include/netlink/utils.h | 4 +- | |
26 | lib/addr.c | 30 ++-- | |
27 | lib/attr.c | 359 ++--------------------------------------------- | |
28 | lib/cache.c | 9 ++ | |
29 | lib/cache_mngr.c | 17 ++- | |
30 | lib/cache_mngt.c | 14 ++- | |
31 | lib/data.c | 16 ++- | |
32 | lib/fib_lookup/lookup.c | 3 +- | |
33 | lib/genl/genl.c | 4 +- | |
34 | lib/handlers.c | 21 +-- | |
35 | lib/msg.c | 152 ++------------------- | |
36 | lib/netfilter/nfnl.c | 4 +- | |
37 | lib/nl.c | 110 ++++++--------- | |
38 | lib/object.c | 16 ++- | |
39 | lib/route/link.c | 3 +- | |
40 | lib/route/rtnl.c | 4 +- | |
41 | lib/socket.c | 16 ++- | |
42 | lib/utils.c | 30 ++++- | |
43 | 29 files changed, 250 insertions(+), 681 deletions(-) | |
44 | delete mode 100755 doc/tags2dict.sh | |
45 | ||
46 | diff --git a/configure.in b/configure.in | |
47 | index ed059c3..800354d 100644 | |
48 | --- a/configure.in | |
49 | +++ b/configure.in | |
50 | @@ -91,17 +91,6 @@ if test "x$generate_doc" != "xno"; then | |
51 | AC_MSG_ERROR([*** doxygen package required to generate documentation]) | |
52 | fi | |
53 | ||
54 | - link_doc=yes | |
55 | - AC_CHECK_PROG(HAVE_XMLSTARLET, [xmlstarlet], yes, no) | |
56 | - if test "x$HAVE_XMLSTARLET" = "xno"; then | |
57 | - if test "x$generate_doc" = "xyes"; then | |
58 | - AC_MSG_ERROR([*** xmlstarlet package required to generate documentation]) | |
59 | - else | |
60 | - AC_MSG_WARN([*** xmlstarlet not found, linking to APi reference disabled]) | |
61 | - link_doc=no | |
62 | - fi | |
63 | - fi | |
64 | - | |
65 | AC_CHECK_PROG(HAVE_ASCIIDOC, [asciidoc], yes, no) | |
66 | if test "x$HAVE_ASCIIDOC" = "xno"; then | |
67 | if test "x$generate_doc" = "xyes"; then | |
68 | @@ -123,6 +112,7 @@ if test "x$generate_doc" != "xno"; then | |
69 | fi | |
70 | fi | |
71 | ||
72 | + link_doc=yes | |
73 | if test "x$HAVE_DOXYGEN" = "xno"; then | |
74 | AC_MSG_WARN([*** Disabling API linking due to missing doxygen package]) | |
75 | link_doc=no | |
76 | diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in | |
77 | index 8bb4fd5..d515db2 100644 | |
78 | --- a/doc/Doxyfile.in | |
79 | +++ b/doc/Doxyfile.in | |
80 | @@ -181,11 +181,11 @@ TAB_SIZE = 8 | |
81 | ||
82 | ALIASES = arg=\param | |
83 | ||
84 | -ALIASES += ref_asciidoc{3}="<a href=\"../\1.html#\2\">\3</a>" | |
85 | -ALIASES += ref_core{2}="\ref_asciidoc{core,\1,\2 (Netlink Library)}" | |
86 | -ALIASES += ref_route{2}="\ref_asciidoc{route,\1,\2 (Routing Family Library)}" | |
87 | -ALIASES += core_doc{2}="\par Related Documentation:\n\ref_core{\1,\2}" | |
88 | -ALIASES += route_doc{2}="\par Related Documentation:\n\ref_route{\1,\2}" | |
89 | +ALIASES += ref_asciidoc{3}="<a href=\"../\1.html#\2\"><b>\3</b></a>" | |
90 | +ALIASES += ref_core{2}="\ref_asciidoc{core,\1,\2 (Netlink Core Library Development Guide)}" | |
91 | +ALIASES += ref_route{2}="\ref_asciidoc{route,\1,\2 (Netlink Routing Development Guide)}" | |
92 | +ALIASES += core_doc{2}="\ref_core{\1,\2}" | |
93 | +ALIASES += route_doc{2}="\ref_route{\1,\2}" | |
94 | ||
95 | # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C | |
96 | # sources only. Doxygen will then generate output that is more tailored for C. | |
97 | @@ -590,7 +590,8 @@ WARN_LOGFILE = | |
98 | INPUT = @top_srcdir@/lib \ | |
99 | @top_srcdir@/src/lib \ | |
100 | @top_srcdir@/include/netlink \ | |
101 | - @top_srcdir@/src | |
102 | + @top_srcdir@/src \ | |
103 | + @top_srcdir@/doc/src | |
104 | ||
105 | # This tag can be used to specify the character encoding of the source files | |
106 | # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is | |
107 | diff --git a/doc/Makefile.am b/doc/Makefile.am | |
108 | index 142dc31..ffa2245 100644 | |
109 | --- a/doc/Makefile.am | |
110 | +++ b/doc/Makefile.am | |
111 | @@ -20,7 +20,6 @@ EXTRA_DIST = \ | |
112 | doxygen-link.py \ | |
113 | gen-tags.sh \ | |
114 | resolve-asciidoc-refs.py \ | |
115 | - tags2dict.sh \ | |
116 | stylesheets/asciidoc.css \ | |
117 | stylesheets/asciidoc-manpage.css \ | |
118 | stylesheets/docbook-xsl.css \ | |
119 | @@ -78,28 +77,26 @@ EXTRA_DIST = \ | |
120 | images/icons/callouts/14.png \ | |
121 | images/icons/callouts/15.png | |
122 | ||
123 | -%.html: %.txt | |
124 | +link_doc: | |
125 | if LINK_DOC | |
126 | + ./gen-tags.sh > libnl.dict | |
127 | +else | |
128 | + @echo "Warning: Linking to API reference is disabled, check configure output" | |
129 | +endif | |
130 | + | |
131 | + | |
132 | +%.html: %.txt link_doc | |
133 | ./resolve-asciidoc-refs.py $< > asciidoc.tmp | |
134 | asciidoc $(ASCIIDOCOPTS) -o $@ asciidoc.tmp | |
135 | +if LINK_DOC | |
136 | ./doxygen-link.py libnl.dict $@ > asciidoc.tmp | |
137 | mv asciidoc.tmp $@ | |
138 | -else | |
139 | - asciidoc $(ASCIIDOCOPTS) -o $@ $< | |
140 | endif | |
141 | ||
142 | asciidoc: core.html route.html index.html | |
143 | ||
144 | -link_doc: | |
145 | -if LINK_DOC | |
146 | - ./gen-tags.sh | ./tags2dict.sh > libnl.dict | |
147 | -else | |
148 | - @echo "Warning: Linking to API reference is disabled, check configure output" | |
149 | -endif | |
150 | - | |
151 | api_ref: | |
152 | doxygen Doxyfile; | |
153 | - $(MAKE) link_doc | |
154 | ||
155 | gendoc: | |
156 | if GENERATE_DOC | |
157 | diff --git a/doc/README b/doc/README | |
158 | index 0c230a2..0784e13 100644 | |
159 | --- a/doc/README | |
160 | +++ b/doc/README | |
161 | @@ -6,5 +6,5 @@ mscgen | |
162 | mscgen-filter-1.2 | |
163 | http://code.google.com/p/asciidoc-mscgen-filter/ | |
164 | ||
165 | -asciidoc 8.6.x | |
166 | -doxygen | |
167 | +asciidoc > 8.6.x | |
168 | +doxygen > 1.8.0 | |
169 | #diff --git a/doc/api/.gitignore b/doc/api/.gitignore | |
170 | #index 821cf65..e57ca88 100644 | |
171 | #--- a/doc/api/.gitignore | |
172 | #+++ b/doc/api/.gitignore | |
173 | #@@ -3,5 +3,6 @@ | |
174 | # *.css | |
175 | # *.map | |
176 | # *.md5 | |
177 | #+*.js | |
178 | # formula.repository | |
179 | # jquery.js | |
180 | diff --git a/doc/core.txt b/doc/core.txt | |
181 | index 7f26e05..8a26dba 100644 | |
182 | --- a/doc/core.txt | |
183 | +++ b/doc/core.txt | |
184 | @@ -2811,6 +2811,17 @@ is stored in +*result+. | |
185 | NOTE: Make sure to return the reference to an address using | |
186 | `nl_addr_put()` after usage to allow memory being freed. | |
187 | ||
188 | +.Example: Transform character string to abstract address | |
189 | +[source,c] | |
190 | +----- | |
191 | +struct nl_addr *a = nl_addr_parse("::1", AF_UNSPEC); | |
192 | +printf("Address family: %s\n", nl_af2str(nl_addr_get_family(a))); | |
193 | +nl_addr_put(a); | |
194 | +a = nl_addr_parse("11:22:33:44:55:66", AF_UNSPEC); | |
195 | +printf("Address family: %s\n", nl_af2str(nl_addr_get_family(a))); | |
196 | +nl_addr_put(a); | |
197 | +----- | |
198 | + | |
199 | .Address References | |
200 | ||
201 | Abstract addresses use reference counting to account for all users of | |
202 | diff --git a/doc/gen-tags.sh b/doc/gen-tags.sh | |
203 | index aba6672..862ec09 100755 | |
204 | --- a/doc/gen-tags.sh | |
205 | +++ b/doc/gen-tags.sh | |
206 | @@ -5,16 +5,10 @@ | |
207 | # written by Carsten Haitzler <ras...@rasterman.com> | |
208 | # | |
209 | ||
210 | -echo '<libnltags>' | |
211 | for f in api/group__*.html | |
212 | do | |
213 | bf=$(basename $f) | |
214 | ||
215 | - grep -oE '<!-- doxytag.* -->' $f | | |
216 | - sed 's/<!-- doxytag:/<libnltag/' | | |
217 | - sed "s/-->/file=\"$bf\" \/>/" | | |
218 | - sed "s/ ref=\"/ href=\"$bf#/" | | |
219 | - sed 's/ member="\([^:]*::\)\([^"]*\)"/ member="\2"/' | | |
220 | - sed 's/ member="\([^"]*\)"/ short="\1"/' | |
221 | + grep -oE "href=\"$bf#[a-z0-9]+\">[^<]+</a>" $f | | |
222 | + sed 's/href="\([^"]*\)">\([^<]*\)<\/a>/\2=api\/\1/' | |
223 | done | |
224 | -echo '</libnltags>' | |
225 | #diff --git a/doc/src/toc.c b/doc/src/toc.c | |
226 | #index ba7e07a..570c1df 100644 | |
227 | #--- a/doc/src/toc.c | |
228 | #+++ b/doc/src/toc.c | |
229 | #@@ -9,11 +9,11 @@ | |
230 | # | |
231 | # libnl is a set of libraries to deal with the netlink protocol and some | |
232 | # of the high level protocols implemented on top of it. The goal is to | |
233 | #-provide APIs on different levels of abstraction. The core library libnl.so | |
234 | #+provide APIs on different levels of abstraction. The core library libnl | |
235 | # provides a fundamental set of functions to deal with sockets, construct | |
236 | # messages, and send/receive those messages. Additional high level interfaces | |
237 | # for several individual netlink protocols are provided in separate | |
238 | #-libraries (e.g. "nl-route.so", "nl-genl.so", ...). | |
239 | #+libraries (e.g. "nl-route", "nl-genl", ...). | |
240 | # | |
241 | # The library is designed to ensure that all components are optional, i.e. | |
242 | # even though the core library provides a caching system which allows to | |
243 | #@@ -33,16 +33,9 @@ version is used with a considerably older kernel. | |
244 | # \subsection tree_dev Development Tree | |
245 | # | |
246 | # @code | |
247 | #-git://git.kernel.org/pub/scm/libs/netlink/libnl.git | |
248 | #+git://git.infradead.org/users/tgr/libnl.git | |
249 | # @endcode | |
250 | #-- Web: http://www.kernel.org/pub/scm/libs/netlink/libnl.git | |
251 | #- | |
252 | #-\subsection tree_stable Stable Tree | |
253 | #- | |
254 | #-@code | |
255 | #-git://git.kernel.org/pub/scm/libs/netlink/libnl-stable.git | |
256 | #-@endcode | |
257 | #-- Web: http://www.kernel.org/pub/scm/libs/netlink/libnl-stable.git | |
258 | #+- Web: http://git.infradead.org/users/tgr/libnl.git | |
259 | # | |
260 | # \section main_website Website | |
261 | # | |
262 | #@@ -50,7 +43,7 @@ git://git.kernel.org/pub/scm/libs/netlink/libnl-stable.git | |
263 | # | |
264 | # \section main_mailinglist Mailinglist | |
265 | # | |
266 | #-Please post question and patches to the libnl mailinglist: | |
267 | #+Please post questions and patches to the libnl mailinglist: | |
268 | # | |
269 | # @code | |
270 | # libnl@lists.infradead.org | |
271 | diff --git a/doc/tags2dict.sh b/doc/tags2dict.sh | |
272 | deleted file mode 100755 | |
273 | index 76407af..0000000 | |
274 | --- a/doc/tags2dict.sh | |
275 | +++ /dev/null | |
276 | @@ -1,8 +0,0 @@ | |
277 | -#!/bin/bash | |
278 | -xmlstarlet sel -t \ | |
279 | - -m "/libnltags/libnltag[@href]" \ | |
280 | - -v "@short" \ | |
281 | - -o "=api/" \ | |
282 | - -v "@href" \ | |
283 | - -n | |
284 | - | |
285 | diff --git a/include/netlink/attr.h b/include/netlink/attr.h | |
286 | index 8479c23..4d32113 100644 | |
287 | --- a/include/netlink/attr.h | |
288 | +++ b/include/netlink/attr.h | |
289 | @@ -28,12 +28,12 @@ struct nl_msg; | |
290 | * @{ | |
291 | */ | |
292 | ||
293 | - /** | |
294 | - * @ingroup attr | |
295 | - * Basic attribute data types | |
296 | - * | |
297 | - * See \ref attr_datatypes for more details. | |
298 | - */ | |
299 | +/** | |
300 | + * @ingroup attr | |
301 | + * Basic attribute data types | |
302 | + * | |
303 | + * See section @core_doc{core_attr_parse,Attribute Parsing} for more details. | |
304 | + */ | |
305 | enum { | |
306 | NLA_UNSPEC, /**< Unspecified type, binary data chunk */ | |
307 | NLA_U8, /**< 8 bit integer */ | |
308 | @@ -55,7 +55,7 @@ enum { | |
309 | * @ingroup attr | |
310 | * Attribute validation policy. | |
311 | * | |
312 | - * See \ref attr_datatypes for more details. | |
313 | + * See section @core_doc{core_attr_parse,Attribute Parsing} for more details. | |
314 | */ | |
315 | struct nla_policy { | |
316 | /** Type of attribute or NLA_UNSPEC */ | |
317 | diff --git a/include/netlink/types.h b/include/netlink/types.h | |
318 | index f6dade3..09cc5bd 100644 | |
319 | --- a/include/netlink/types.h | |
320 | +++ b/include/netlink/types.h | |
321 | @@ -1,12 +1,12 @@ | |
322 | /* | |
323 | - * netlink/netlink-types.h Netlink Types | |
324 | + * netlink/types.h Definition of public types | |
325 | * | |
326 | * This library is free software; you can redistribute it and/or | |
327 | * modify it under the terms of the GNU Lesser General Public | |
328 | * License as published by the Free Software Foundation version 2.1 | |
329 | * of the License. | |
330 | * | |
331 | - * Copyright (c) 2003-2006 Thomas Graf <tgraf@suug.ch> | |
332 | + * Copyright (c) 2003-2012 Thomas Graf <tgraf@suug.ch> | |
333 | */ | |
334 | ||
335 | #ifndef __NETLINK_TYPES_H_ | |
336 | @@ -15,8 +15,8 @@ | |
337 | #include <stdio.h> | |
338 | ||
339 | /** | |
340 | - * Dumping types (dp_type) | |
341 | * @ingroup utils | |
342 | + * Enumeration of dumping variations (dp_type) | |
343 | */ | |
344 | enum nl_dump_type { | |
345 | NL_DUMP_LINE, /**< Dump object briefly on one line */ | |
346 | @@ -27,8 +27,8 @@ enum nl_dump_type { | |
347 | #define NL_DUMP_MAX (__NL_DUMP_MAX - 1) | |
348 | ||
349 | /** | |
350 | - * Dumping parameters | |
351 | * @ingroup utils | |
352 | + * Dumping parameters | |
353 | */ | |
354 | struct nl_dump_params | |
355 | { | |
356 | diff --git a/include/netlink/utils.h b/include/netlink/utils.h | |
357 | index a1ef82e..4d7b969 100644 | |
358 | --- a/include/netlink/utils.h | |
359 | +++ b/include/netlink/utils.h | |
360 | @@ -6,7 +6,7 @@ | |
361 | * License as published by the Free Software Foundation version 2.1 | |
362 | * of the License. | |
363 | * | |
364 | - * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch> | |
365 | + * Copyright (c) 2003-2012 Thomas Graf <tgraf@suug.ch> | |
366 | */ | |
367 | ||
368 | #ifndef NETLINK_UTILS_H_ | |
369 | @@ -31,7 +31,7 @@ extern "C" { | |
370 | #define NL_PROB_MIN 0x0 | |
371 | ||
372 | /** | |
373 | - * Upper probability limit | |
374 | + * Upper probability limit nl_dump_type | |
375 | * @ingroup utils | |
376 | */ | |
377 | #define NL_PROB_MAX 0xffffffff | |
378 | diff --git a/lib/addr.c b/lib/addr.c | |
379 | index 30c708d..89d3d4f 100644 | |
380 | --- a/lib/addr.c | |
381 | +++ b/lib/addr.c | |
382 | @@ -1,28 +1,30 @@ | |
383 | /* | |
384 | - * lib/addr.c Abstract Address | |
385 | + * lib/addr.c Network Address | |
386 | * | |
387 | * This library is free software; you can redistribute it and/or | |
388 | * modify it under the terms of the GNU Lesser General Public | |
389 | * License as published by the Free Software Foundation version 2.1 | |
390 | * of the License. | |
391 | * | |
392 | - * Copyright (c) 2003-2010 Thomas Graf <tgraf@suug.ch> | |
393 | + * Copyright (c) 2003-2012 Thomas Graf <tgraf@suug.ch> | |
394 | */ | |
395 | ||
396 | /** | |
397 | - * @ingroup core | |
398 | - * @defgroup addr Abstract Address | |
399 | + * @ingroup core_types | |
400 | + * @defgroup addr Network Address | |
401 | + * | |
402 | + * Abstract data type representing any kind of network address | |
403 | + * | |
404 | + * Related sections in the development guide: | |
405 | + * - @core_doc{_abstract_address, Network Addresses} | |
406 | * | |
407 | - * @par 1) Transform character string to abstract address | |
408 | - * @code | |
409 | - * struct nl_addr *a = nl_addr_parse("::1", AF_UNSPEC); | |
410 | - * printf("Address family: %s\n", nl_af2str(nl_addr_get_family(a))); | |
411 | - * nl_addr_put(a); | |
412 | - * a = nl_addr_parse("11:22:33:44:55:66", AF_UNSPEC); | |
413 | - * printf("Address family: %s\n", nl_af2str(nl_addr_get_family(a))); | |
414 | - * nl_addr_put(a); | |
415 | - * @endcode | |
416 | * @{ | |
417 | + * | |
418 | + * Header | |
419 | + * ------ | |
420 | + * ~~~~{.c} | |
421 | + * #include <netlink/addr.h> | |
422 | + * ~~~~ | |
423 | */ | |
424 | ||
425 | #include <netlink-local.h> | |
426 | @@ -163,7 +165,7 @@ static void addr_destroy(struct nl_addr *addr) | |
427 | } | |
428 | ||
429 | /** | |
430 | - * @name Creating Abstract Addresses | |
431 | + * @name Creating Abstract Network Addresses | |
432 | * @{ | |
433 | */ | |
434 | ||
435 | diff --git a/lib/attr.c b/lib/attr.c | |
436 | index a045351..6ef6cd9 100644 | |
437 | --- a/lib/attr.c | |
438 | +++ b/lib/attr.c | |
439 | @@ -22,356 +22,16 @@ | |
440 | * @defgroup attr Attributes | |
441 | * Netlink Attributes Construction/Parsing Interface | |
442 | * | |
443 | - * \section attr_sec Netlink Attributes | |
444 | - * Netlink attributes allow for data chunks of arbitary length to be | |
445 | - * attached to a netlink message. Each attribute is encoded with a | |
446 | - * type and length field, both 16 bits, stored in the attribute header | |
447 | - * preceding the attribute data. The main advantage of using attributes | |
448 | - * over packing everything into the family header is that the interface | |
449 | - * stays extendable as new attributes can supersede old attributes while | |
450 | - * remaining backwards compatible. Also attributes can be defined optional | |
451 | - * thus avoiding the transmission of unnecessary empty data blocks. | |
452 | - * Special nested attributes allow for more complex data structures to | |
453 | - * be transmitted, e.g. trees, lists, etc. | |
454 | - * | |
455 | - * While not required, netlink attributes typically follow the family | |
456 | - * header of a netlink message and must be properly aligned to NLA_ALIGNTO: | |
457 | - * @code | |
458 | - * +----------------+- - -+---------------+- - -+------------+- - -+ | |
459 | - * | Netlink Header | Pad | Family Header | Pad | Attributes | Pad | | |
460 | - * +----------------+- - -+---------------+- - -+------------+- - -+ | |
461 | - * @endcode | |
462 | - * | |
463 | - * The actual attributes are chained together each separately aligned to | |
464 | - * NLA_ALIGNTO. The position of an attribute is defined based on the | |
465 | - * length field of the preceding attributes: | |
466 | - * @code | |
467 | - * +-------------+- - -+-------------+- - -+------ | |
468 | - * | Attribute 1 | Pad | Attribute 2 | Pad | ... | |
469 | - * +-------------+- - -+-------------+- - -+------ | |
470 | - * nla_next(attr1)------^ | |
471 | - * @endcode | |
472 | - * | |
473 | - * The attribute itself consists of the attribute header followed by | |
474 | - * the actual payload also aligned to NLA_ALIGNTO. The function nla_data() | |
475 | - * returns a pointer to the start of the payload while nla_len() returns | |
476 | - * the length of the payload in bytes. | |
477 | - * | |
478 | - * \b Note: Be aware, NLA_ALIGNTO equals to 4 bytes, therefore it is not | |
479 | - * safe to dereference any 64 bit data types directly. | |
480 | - * | |
481 | - * @code | |
482 | - * <----------- nla_total_size(payload) -----------> | |
483 | - * <-------- nla_attr_size(payload) ---------> | |
484 | - * +------------------+- - -+- - - - - - - - - +- - -+ | |
485 | - * | Attribute Header | Pad | Payload | Pad | | |
486 | - * +------------------+- - -+- - - - - - - - - +- - -+ | |
487 | - * nla_data(nla)-------------^ | |
488 | - * <- nla_len(nla) -> | |
489 | - * @endcode | |
490 | - * | |
491 | - * @subsection attr_datatypes Attribute Data Types | |
492 | - * A number of basic data types are supported to simplify access and | |
493 | - * validation of netlink attributes. This data type information is | |
494 | - * not encoded in the attribute, both the kernel and userspace part | |
495 | - * are required to share this information on their own. | |
496 | - * | |
497 | - * One of the major advantages of these basic types is the automatic | |
498 | - * validation of each attribute based on an attribute policy. The | |
499 | - * validation covers most of the checks required to safely use | |
500 | - * attributes and thus keeps the individual sanity check to a minimum. | |
501 | - * | |
502 | - * Never access attribute payload without ensuring basic validation | |
503 | - * first, attributes may: | |
504 | - * - not be present even though required | |
505 | - * - contain less actual payload than expected | |
506 | - * - fake a attribute length which exceeds the end of the message | |
507 | - * - contain unterminated character strings | |
508 | - * | |
509 | - * Policies are defined as array of the struct nla_policy. The array is | |
510 | - * indexed with the attribute type, therefore the array must be sized | |
511 | - * accordingly. | |
512 | - * @code | |
513 | - * static struct nla_policy my_policy[ATTR_MAX+1] = { | |
514 | - * [ATTR_FOO] = { .type = ..., .minlen = ..., .maxlen = ... }, | |
515 | - * }; | |
516 | - * | |
517 | - * err = nla_validate(attrs, attrlen, ATTR_MAX, &my_policy); | |
518 | - * @endcode | |
519 | - * | |
520 | - * Some basic validations are performed on every attribute, regardless of type. | |
521 | - * - If the attribute type exceeds the maximum attribute type specified or | |
522 | - * the attribute type is lesser-or-equal than zero, the attribute will | |
523 | - * be silently ignored. | |
524 | - * - If the payload length falls below the \a minlen value the attribute | |
525 | - * will be rejected. | |
526 | - * - If \a maxlen is non-zero and the payload length exceeds the \a maxlen | |
527 | - * value the attribute will be rejected. | |
528 | - * | |
529 | - * | |
530 | - * @par Unspecific Attribute (NLA_UNSPEC) | |
531 | - * This is the standard type if no type is specified. It is used for | |
532 | - * binary data of arbitary length. Typically this attribute carries | |
533 | - * a binary structure or a stream of bytes. | |
534 | - * @par | |
535 | - * @code | |
536 | - * // In this example, we will assume a binary structure requires to | |
537 | - * // be transmitted. The definition of the structure will typically | |
538 | - * // go into a header file available to both the kernel and userspace | |
539 | - * // side. | |
540 | - * // | |
541 | - * // Note: Be careful when putting 64 bit data types into a structure. | |
542 | - * // The attribute payload is only aligned to 4 bytes, dereferencing | |
543 | - * // the member may fail. | |
544 | - * struct my_struct { | |
545 | - * int a; | |
546 | - * int b; | |
547 | - * }; | |
548 | - * | |
549 | - * // The validation function will not enforce an exact length match to | |
550 | - * // allow structures to grow as required. Note: While it is allowed | |
551 | - * // to add members to the end of the structure, changing the order or | |
552 | - * // inserting members in the middle of the structure will break your | |
553 | - * // binary interface. | |
554 | - * static struct nla_policy my_policy[ATTR_MAX+1] = { | |
555 | - * [ATTR_MY_STRICT] = { .type = NLA_UNSPEC, | |
556 | - * .minlen = sizeof(struct my_struct) }, | |
557 | - * | |
558 | - * // The binary structure is appened to the message using nla_put() | |
559 | - * struct my_struct foo = { .a = 1, .b = 2 }; | |
560 | - * nla_put(msg, ATTR_MY_STRUCT, sizeof(foo), &foo); | |
561 | - * | |
562 | - * // On the receiving side, a pointer to the structure pointing inside | |
563 | - * // the message payload is returned by nla_get(). | |
564 | - * if (attrs[ATTR_MY_STRUCT]) | |
565 | - * struct my_struct *foo = nla_get(attrs[ATTR_MY_STRUCT]); | |
566 | - * @endcode | |
567 | - * | |
568 | - * @par Integers (NLA_U8, NLA_U16, NLA_U32, NLA_U64) | |
569 | - * Integers come in different sizes from 8 bit to 64 bit. However, since the | |
570 | - * payload length is aligned to 4 bytes, integers smaller than 32 bit are | |
571 | - * only useful to enforce the maximum range of values. | |
572 | - * @par | |
573 | - * \b Note: There is no difference made between signed and unsigned integers. | |
574 | - * The validation only enforces the minimal payload length required to store | |
575 | - * an integer of specified type. | |
576 | - * @par | |
577 | - * @code | |
578 | - * // Even though possible, it does not make sense to specify .minlen or | |
579 | - * // .maxlen for integer types. The data types implies the corresponding | |
580 | - * // minimal payload length. | |
581 | - * static struct nla_policy my_policy[ATTR_MAX+1] = { | |
582 | - * [ATTR_FOO] = { .type = NLA_U32 }, | |
583 | - * | |
584 | - * // Numeric values can be appended directly using the respective | |
585 | - * // nla_put_uxxx() function | |
586 | - * nla_put_u32(msg, ATTR_FOO, 123); | |
587 | - * | |
588 | - * // Same for the receiving side. | |
589 | - * if (attrs[ATTR_FOO]) | |
590 | - * uint32_t foo = nla_get_u32(attrs[ATTR_FOO]); | |
591 | - * @endcode | |
592 | - * | |
593 | - * @par Character string (NLA_STRING) | |
594 | - * This data type represents a NUL terminated character string of variable | |
595 | - * length. For binary data streams the type NLA_UNSPEC is recommended. | |
596 | - * @par | |
597 | - * @code | |
598 | - * // Enforce a NUL terminated character string of at most 4 characters | |
599 | - * // including the NUL termination. | |
600 | - * static struct nla_policy my_policy[ATTR_MAX+1] = { | |
601 | - * [ATTR_BAR] = { .type = NLA_STRING, maxlen = 4 }, | |
602 | - * | |
603 | - * // nla_put_string() creates a string attribute of the necessary length | |
604 | - * // and appends it to the message including the NUL termination. | |
605 | - * nla_put_string(msg, ATTR_BAR, "some text"); | |
606 | - * | |
607 | - * // It is safe to use the returned character string directly if the | |
608 | - * // attribute has been validated as the validation enforces the proper | |
609 | - * // termination of the string. | |
610 | - * if (attrs[ATTR_BAR]) | |
611 | - * char *text = nla_get_string(attrs[ATTR_BAR]); | |
612 | - * @endcode | |
613 | - * | |
614 | - * @par Flag (NLA_FLAG) | |
615 | - * This attribute type may be used to indicate the presence of a flag. The | |
616 | - * attribute is only valid if the payload length is zero. The presence of | |
617 | - * the attribute header indicates the presence of the flag. | |
618 | - * @par | |
619 | - * @code | |
620 | - * // This attribute type is special as .minlen and .maxlen have no effect. | |
621 | - * static struct nla_policy my_policy[ATTR_MAX+1] = { | |
622 | - * [ATTR_FLAG] = { .type = NLA_FLAG }, | |
623 | - * | |
624 | - * // nla_put_flag() appends a zero sized attribute to the message. | |
625 | - * nla_put_flag(msg, ATTR_FLAG); | |
626 | - * | |
627 | - * // There is no need for a receival function, the presence is the value. | |
628 | - * if (attrs[ATTR_FLAG]) | |
629 | - * // flag is present | |
630 | - * @endcode | |
631 | - * | |
632 | - * @par Micro Seconds (NLA_MSECS) | |
633 | - * | |
634 | - * @par Nested Attribute (NLA_NESTED) | |
635 | - * Attributes can be nested and put into a container to create groups, lists | |
636 | - * or to construct trees of attributes. Nested attributes are often used to | |
637 | - * pass attributes to a subsystem where the top layer has no knowledge of the | |
638 | - * configuration possibilities of each subsystem. | |
639 | - * @par | |
640 | - * \b Note: When validating the attributes using nlmsg_validate() or | |
641 | - * nlmsg_parse() it will only affect the top level attributes. Each | |
642 | - * level of nested attributes must be validated seperately using | |
643 | - * nla_parse_nested() or nla_validate(). | |
644 | - * @par | |
645 | - * @code | |
646 | - * // The minimal length policy may be used to enforce the presence of at | |
647 | - * // least one attribute. | |
648 | - * static struct nla_policy my_policy[ATTR_MAX+1] = { | |
649 | - * [ATTR_OPTS] = { .type = NLA_NESTED, minlen = NLA_HDRLEN }, | |
650 | - * | |
651 | - * // Nested attributes are constructed by enclosing the attributes | |
652 | - * // to be nested with calls to nla_nest_start() respetively nla_nest_end(). | |
653 | - * struct nlattr *opts = nla_nest_start(msg, ATTR_OPTS); | |
654 | - * nla_put_u32(msg, ATTR_FOO, 123); | |
655 | - * nla_put_string(msg, ATTR_BAR, "some text"); | |
656 | - * nla_nest_end(msg, opts); | |
657 | - * | |
658 | - * // Various methods exist to parse nested attributes, the easiest being | |
659 | - * // nla_parse_nested() which also allows validation in the same step. | |
660 | - * if (attrs[ATTR_OPTS]) { | |
661 | - * struct nlattr *nested[ATTR_MAX+1]; | |
662 | - * | |
663 | - * nla_parse_nested(nested, ATTR_MAX, attrs[ATTR_OPTS], &policy); | |
664 | - * | |
665 | - * if (nested[ATTR_FOO]) | |
666 | - * uint32_t foo = nla_get_u32(nested[ATTR_FOO]); | |
667 | - * } | |
668 | - * @endcode | |
669 | - * | |
670 | - * @subsection attr_exceptions Exception Based Attribute Construction | |
671 | - * Often a large number of attributes are added to a message in a single | |
672 | - * function. In order to simplify error handling, a second set of | |
673 | - * construction functions exist which jump to a error label when they | |
674 | - * fail instead of returning an error code. This second set consists | |
675 | - * of macros which are named after their error code based counterpart | |
676 | - * except that the name is written all uppercase. | |
677 | - * | |
678 | - * All of the macros jump to the target \c nla_put_failure if they fail. | |
679 | - * @code | |
680 | - * void my_func(struct nl_msg *msg) | |
681 | - * { | |
682 | - * NLA_PUT_U32(msg, ATTR_FOO, 10); | |
683 | - * NLA_PUT_STRING(msg, ATTR_BAR, "bar"); | |
684 | - * | |
685 | - * return 0; | |
686 | - * | |
687 | - * nla_put_failure: | |
688 | - * return -NLE_NOMEM; | |
689 | - * } | |
690 | - * @endcode | |
691 | - * | |
692 | - * @subsection attr_examples Examples | |
693 | - * @par Example 1.1 Constructing a netlink message with attributes. | |
694 | - * @code | |
695 | - * struct nl_msg *build_msg(int ifindex, struct nl_addr *lladdr, int mtu) | |
696 | - * { | |
697 | - * struct nl_msg *msg; | |
698 | - * struct nlattr *info, *vlan; | |
699 | - * struct ifinfomsg ifi = { | |
700 | - * .ifi_family = AF_INET, | |
701 | - * .ifi_index = ifindex, | |
702 | - * }; | |
703 | - * | |
704 | - * // Allocate a new netlink message, type=RTM_SETLINK, flags=NLM_F_ECHO | |
705 | - * if (!(msg = nlmsg_alloc_simple(RTM_SETLINK, NLM_F_ECHO))) | |
706 | - * return NULL; | |
707 | - * | |
708 | - * // Append the family specific header (struct ifinfomsg) | |
709 | - * if (nlmsg_append(msg, &ifi, sizeof(ifi), NLMSG_ALIGNTO) < 0) | |
710 | - * goto nla_put_failure | |
711 | - * | |
712 | - * // Append a 32 bit integer attribute to carry the MTU | |
713 | - * NLA_PUT_U32(msg, IFLA_MTU, mtu); | |
714 | - * | |
715 | - * // Append a unspecific attribute to carry the link layer address | |
716 | - * NLA_PUT_ADDR(msg, IFLA_ADDRESS, lladdr); | |
717 | - * | |
718 | - * // Append a container for nested attributes to carry link information | |
719 | - * if (!(info = nla_nest_start(msg, IFLA_LINKINFO))) | |
720 | - * goto nla_put_failure; | |
721 | - * | |
722 | - * // Put a string attribute into the container | |
723 | - * NLA_PUT_STRING(msg, IFLA_INFO_KIND, "vlan"); | |
724 | - * | |
725 | - * // Append another container inside the open container to carry | |
726 | - * // vlan specific attributes | |
727 | - * if (!(vlan = nla_nest_start(msg, IFLA_INFO_DATA))) | |
728 | - * goto nla_put_failure; | |
729 | - * | |
730 | - * // add vlan specific info attributes here... | |
731 | - * | |
732 | - * // Finish nesting the vlan attributes and close the second container. | |
733 | - * nla_nest_end(msg, vlan); | |
734 | - * | |
735 | - * // Finish nesting the link info attribute and close the first container. | |
736 | - * nla_nest_end(msg, info); | |
737 | - * | |
738 | - * return msg; | |
739 | - * | |
740 | - * // If any of the construction macros fails, we end up here. | |
741 | - * nla_put_failure: | |
742 | - * nlmsg_free(msg); | |
743 | - * return NULL; | |
744 | - * } | |
745 | - * @endcode | |
746 | - * | |
747 | - * @par Example 2.1 Parsing a netlink message with attributes. | |
748 | - * @code | |
749 | - * int parse_message(struct nl_msg *msg) | |
750 | - * { | |
751 | - * // The policy defines two attributes: a 32 bit integer and a container | |
752 | - * // for nested attributes. | |
753 | - * struct nla_policy attr_policy[ATTR_MAX+1] = { | |
754 | - * [ATTR_FOO] = { .type = NLA_U32 }, | |
755 | - * [ATTR_BAR] = { .type = NLA_NESTED }, | |
756 | - * }; | |
757 | - * struct nlattr *attrs[ATTR_MAX+1]; | |
758 | - * int err; | |
759 | - * | |
760 | - * // The nlmsg_parse() function will make sure that the message contains | |
761 | - * // enough payload to hold the header (struct my_hdr), validates any | |
762 | - * // attributes attached to the messages and stores a pointer to each | |
763 | - * // attribute in the attrs[] array accessable by attribute type. | |
764 | - * if ((err = nlmsg_parse(nlmsg_hdr(msg), sizeof(struct my_hdr), attrs, | |
765 | - * ATTR_MAX, attr_policy)) < 0) | |
766 | - * goto errout; | |
767 | - * | |
768 | - * if (attrs[ATTR_FOO]) { | |
769 | - * // It is safe to directly access the attribute payload without | |
770 | - * // any further checks since nlmsg_parse() enforced the policy. | |
771 | - * uint32_t foo = nla_get_u32(attrs[ATTR_FOO]); | |
772 | - * } | |
773 | - * | |
774 | - * if (attrs[ATTR_BAR]) { | |
775 | - * struct nlattr *nested[NESTED_MAX+1]; | |
776 | - * | |
777 | - * // Attributes nested in a container can be parsed the same way | |
778 | - * // as top level attributes. | |
779 | - * if ((err = nla_parse_nested(nested, NESTED_MAX, attrs[ATTR_BAR], | |
780 | - * nested_policy)) < 0) | |
781 | - * goto errout; | |
782 | - * | |
783 | - * // Process nested attributes here. | |
784 | - * } | |
785 | - * | |
786 | - * err = 0; | |
787 | - * errout: | |
788 | - * return err; | |
789 | - * } | |
790 | - * @endcode | |
791 | + * Related sections in the development guide: | |
792 | + * - @core_doc{core_attr,Netlink Attributes} | |
793 | * | |
794 | * @{ | |
795 | + * | |
796 | + * Header | |
797 | + * ------ | |
798 | + * ~~~~{.c} | |
799 | + * #include <netlink/attr.h> | |
800 | + * ~~~~ | |
801 | */ | |
802 | ||
803 | /** | |
804 | @@ -628,8 +288,7 @@ errout: | |
805 | * than the maximum type specified will be silently ignored in order to | |
806 | * maintain backwards compatibility. | |
807 | * | |
808 | - * See \ref attr_datatypes for more details on what kind of validation | |
809 | - * checks are performed on each attribute data type. | |
810 | + * See section @core_doc{core_attr_parse,Attribute Parsing} for more details. | |
811 | * | |
812 | * @return 0 on success or a negative error code. | |
813 | */ | |
814 | diff --git a/lib/cache.c b/lib/cache.c | |
815 | index 814c616..5cfae67 100644 | |
816 | --- a/lib/cache.c | |
817 | +++ b/lib/cache.c | |
818 | @@ -37,7 +37,16 @@ | |
819 | * | | Core Netlink | |
820 | * @endcode | |
821 | * | |
822 | + * Related sections in the development guide: | |
823 | + * - @core_doc{core_cache, Caching System} | |
824 | + * | |
825 | * @{ | |
826 | + * | |
827 | + * Header | |
828 | + * ------ | |
829 | + * ~~~~{.c} | |
830 | + * #include <netlink/cache.h> | |
831 | + * ~~~~ | |
832 | */ | |
833 | ||
834 | #include <netlink-local.h> | |
835 | diff --git a/lib/cache_mngr.c b/lib/cache_mngr.c | |
836 | index 0f0df51..cdf2b7b 100644 | |
837 | --- a/lib/cache_mngr.c | |
838 | +++ b/lib/cache_mngr.c | |
839 | @@ -12,9 +12,24 @@ | |
840 | /** | |
841 | * @ingroup cache_mngt | |
842 | * @defgroup cache_mngr Manager | |
843 | - * @brief Automatically keep caches up to date | |
844 | + * @brief Manager keeping caches up to date automatically. | |
845 | + * | |
846 | + * The cache manager keeps caches up to date automatically by listening to | |
847 | + * netlink notifications and integrating the received information into the | |
848 | + * existing cache. | |
849 | + * | |
850 | + * @note This functionality is still considered experimental. | |
851 | + * | |
852 | + * Related sections in the development guide: | |
853 | + * - @core_doc{_cache_manager,Cache Manager} | |
854 | * | |
855 | * @{ | |
856 | + * | |
857 | + * Header | |
858 | + * ------ | |
859 | + * ~~~~{.c} | |
860 | + * #include <netlink/cache.h> | |
861 | + * ~~~~ | |
862 | */ | |
863 | ||
864 | #include <netlink-local.h> | |
865 | diff --git a/lib/cache_mngt.c b/lib/cache_mngt.c | |
866 | index a9ecf27..6691454 100644 | |
867 | --- a/lib/cache_mngt.c | |
868 | +++ b/lib/cache_mngt.c | |
869 | @@ -6,13 +6,23 @@ | |
870 | * License as published by the Free Software Foundation version 2.1 | |
871 | * of the License. | |
872 | * | |
873 | - * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch> | |
874 | + * Copyright (c) 2003-2012 Thomas Graf <tgraf@suug.ch> | |
875 | */ | |
876 | ||
877 | /** | |
878 | * @ingroup core | |
879 | - * @defgroup cache_mngt Caching | |
880 | + * @defgroup cache_mngt Caching System | |
881 | + * | |
882 | + * Related sections in the development guide: | |
883 | + * - @core_doc{core_cache, Caching System} | |
884 | + * | |
885 | * @{ | |
886 | + * | |
887 | + * Header | |
888 | + * ------ | |
889 | + * ~~~~{.c} | |
890 | + * #include <netlink/cache.h> | |
891 | + * ~~~~ | |
892 | */ | |
893 | ||
894 | #include <netlink-local.h> | |
895 | diff --git a/lib/data.c b/lib/data.c | |
896 | index 03cd9fe..e4196b1 100644 | |
897 | --- a/lib/data.c | |
898 | +++ b/lib/data.c | |
899 | @@ -6,13 +6,25 @@ | |
900 | * License as published by the Free Software Foundation version 2.1 | |
901 | * of the License. | |
902 | * | |
903 | - * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch> | |
904 | + * Copyright (c) 2003-2012 Thomas Graf <tgraf@suug.ch> | |
905 | */ | |
906 | ||
907 | /** | |
908 | - * @ingroup core | |
909 | + * @ingroup core_types | |
910 | * @defgroup data Abstract Data | |
911 | + * | |
912 | + * Abstract data type representing a binary data blob. | |
913 | + * | |
914 | + * Related sections in the development guide: | |
915 | + * - @core_doc{_abstract_data, Abstract Data} | |
916 | + * | |
917 | * @{ | |
918 | + * | |
919 | + * Header | |
920 | + * ------ | |
921 | + * ~~~~{.c} | |
922 | + * #include <netlink/data.h> | |
923 | + * ~~~~ | |
924 | */ | |
925 | ||
926 | #include <netlink-local.h> | |
927 | diff --git a/lib/fib_lookup/lookup.c b/lib/fib_lookup/lookup.c | |
928 | index 6018251..ec82c16 100644 | |
929 | --- a/lib/fib_lookup/lookup.c | |
930 | +++ b/lib/fib_lookup/lookup.c | |
931 | @@ -6,10 +6,11 @@ | |
932 | * License as published by the Free Software Foundation version 2.1 | |
933 | * of the License. | |
934 | * | |
935 | - * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch> | |
936 | + * Copyright (c) 2003-2012 Thomas Graf <tgraf@suug.ch> | |
937 | */ | |
938 | ||
939 | /** | |
940 | + * @ingroup rtnl | |
941 | * @defgroup fib_lookup FIB Lookup | |
942 | * @brief | |
943 | * @{ | |
944 | diff --git a/lib/genl/genl.c b/lib/genl/genl.c | |
945 | index 055be91..6e6a764 100644 | |
946 | --- a/lib/genl/genl.c | |
947 | +++ b/lib/genl/genl.c | |
948 | @@ -6,11 +6,11 @@ | |
949 | * License as published by the Free Software Foundation version 2.1 | |
950 | * of the License. | |
951 | * | |
952 | - * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch> | |
953 | + * Copyright (c) 2003-2012 Thomas Graf <tgraf@suug.ch> | |
954 | */ | |
955 | ||
956 | /** | |
957 | - * @defgroup genl Generic Netlink | |
958 | + * @defgroup genl Generic Netlink Library (libnl-genl) | |
959 | * | |
960 | * @par Message Format | |
961 | * @code | |
962 | diff --git a/lib/handlers.c b/lib/handlers.c | |
963 | index f13b89e..74276a1 100644 | |
964 | --- a/lib/handlers.c | |
965 | +++ b/lib/handlers.c | |
966 | @@ -13,21 +13,16 @@ | |
967 | * @ingroup core | |
968 | * @defgroup cb Callbacks/Customization | |
969 | * | |
970 | - * @details | |
971 | - * @par 1) Setting up a callback set | |
972 | - * @code | |
973 | - * // Allocate a callback set and initialize it to the verbose default set | |
974 | - * struct nl_cb *cb = nl_cb_alloc(NL_CB_VERBOSE); | |
975 | + * Related sections in the development guide: | |
976 | + * - @core_doc{core_cb, Callback Configuration} | |
977 | * | |
978 | - * // Modify the set to call my_func() for all valid messages | |
979 | - * nl_cb_set(cb, NL_CB_VALID, NL_CB_CUSTOM, my_func, NULL); | |
980 | - * | |
981 | - * // Set the error message handler to the verbose default implementation | |
982 | - * // and direct it to print all errors to the given file descriptor. | |
983 | - * FILE *file = fopen(...); | |
984 | - * nl_cb_err(cb, NL_CB_VERBOSE, NULL, file); | |
985 | - * @endcode | |
986 | * @{ | |
987 | + * | |
988 | + * Header | |
989 | + * ------ | |
990 | + * ~~~~{.c} | |
991 | + * #include <netlink/handlers.h> | |
992 | + * ~~~~ | |
993 | */ | |
994 | ||
995 | #include <netlink-local.h> | |
996 | diff --git a/lib/msg.c b/lib/msg.c | |
997 | index 235ee82..18174b5 100644 | |
998 | --- a/lib/msg.c | |
999 | +++ b/lib/msg.c | |
1000 | @@ -6,156 +6,24 @@ | |
1001 | * License as published by the Free Software Foundation version 2.1 | |
1002 | * of the License. | |
1003 | * | |
1004 | - * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch> | |
1005 | + * Copyright (c) 2003-2012 Thomas Graf <tgraf@suug.ch> | |
1006 | */ | |
1007 | ||
1008 | /** | |
1009 | * @ingroup core | |
1010 | - * @defgroup msg Messages | |
1011 | + * @defgroup msg Message Construction & Parsing | |
1012 | * Netlink Message Construction/Parsing Interface | |
1013 | * | |
1014 | - * The following information is partly extracted from RFC3549 | |
1015 | - * (ftp://ftp.rfc-editor.org/in-notes/rfc3549.txt) | |
1016 | + * Related sections in the development guide: | |
1017 | + * - @core_doc{_message_parsing_amp_construction,Message Parsing & Construction} | |
1018 | * | |
1019 | - * @par Message Format | |
1020 | - * Netlink messages consist of a byte stream with one or multiple | |
1021 | - * Netlink headers and an associated payload. If the payload is too big | |
1022 | - * to fit into a single message it, can be split over multiple Netlink | |
1023 | - * messages, collectively called a multipart message. For multipart | |
1024 | - * messages, the first and all following headers have the \c NLM_F_MULTI | |
1025 | - * Netlink header flag set, except for the last header which has the | |
1026 | - * Netlink header type \c NLMSG_DONE. | |
1027 | - * | |
1028 | - * @par | |
1029 | - * The Netlink message header (struct nlmsghdr) is shown below. | |
1030 | - * @code | |
1031 | - * 0 1 2 3 | |
1032 | - * 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 | |
1033 | - * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
1034 | - * | Length | | |
1035 | - * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
1036 | - * | Type | Flags | | |
1037 | - * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
1038 | - * | Sequence Number | | |
1039 | - * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
1040 | - * | Process ID (PID) | | |
1041 | - * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
1042 | - * @endcode | |
1043 | - * | |
1044 | - * @par | |
1045 | - * The netlink message header and payload must be aligned properly: | |
1046 | - * @code | |
1047 | - * <------- NLMSG_ALIGN(hlen) ------> <---- NLMSG_ALIGN(len) ---> | |
1048 | - * +----------------------------+- - -+- - - - - - - - - - -+- - -+ | |
1049 | - * | Header | Pad | Payload | Pad | | |
1050 | - * | struct nlmsghdr | | | | | |
1051 | - * +----------------------------+- - -+- - - - - - - - - - -+- - -+ | |
1052 | - * @endcode | |
1053 | - * @par | |
1054 | - * Message Format: | |
1055 | - * @code | |
1056 | - * <--- nlmsg_total_size(payload) ---> | |
1057 | - * <-- nlmsg_msg_size(payload) -> | |
1058 | - * +----------+- - -+-------------+- - -+-------- - - | |
1059 | - * | nlmsghdr | Pad | Payload | Pad | nlmsghdr | |
1060 | - * +----------+- - -+-------------+- - -+-------- - - | |
1061 | - * nlmsg_data(nlh)---^ ^ | |
1062 | - * nlmsg_next(nlh)-----------------------+ | |
1063 | - * @endcode | |
1064 | - * @par | |
1065 | - * The payload may consist of arbitary data but may have strict | |
1066 | - * alignment and formatting rules depening on the specific netlink | |
1067 | - * families. | |
1068 | - * @par | |
1069 | - * @code | |
1070 | - * <---------------------- nlmsg_len(nlh) ---------------------> | |
1071 | - * <------ hdrlen ------> <- nlmsg_attrlen(nlh, hdrlen) -> | |
1072 | - * +----------------------+- - -+--------------------------------+ | |
1073 | - * | Family Header | Pad | Attributes | | |
1074 | - * +----------------------+- - -+--------------------------------+ | |
1075 | - * nlmsg_attrdata(nlh, hdrlen)---^ | |
1076 | - * @endcode | |
1077 | - * @par The ACK Netlink Message | |
1078 | - * This message is actually used to denote both an ACK and a NACK. | |
1079 | - * Typically, the direction is from FEC to CPC (in response to an ACK | |
1080 | - * request message). However, the CPC should be able to send ACKs back | |
1081 | - * to FEC when requested. | |
1082 | - * @code | |
1083 | - * 0 1 2 3 | |
1084 | - * 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 | |
1085 | - * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
1086 | - * | Netlink message header | | |
1087 | - * | type = NLMSG_ERROR | | |
1088 | - * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
1089 | - * | Error code | | |
1090 | - * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
1091 | - * | OLD Netlink message header | | |
1092 | - * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | |
1093 | - * @endcode | |
1094 | - * | |
1095 | - * @par Example | |
1096 | - * @code | |
1097 | - * // Various methods exist to create/allocate a new netlink | |
1098 | - * // message. | |
1099 | - * // | |
1100 | - * // nlmsg_alloc() will allocate an empty netlink message with | |
1101 | - * // a maximum payload size which defaults to the page size of | |
1102 | - * // the system. This default size can be modified using the | |
1103 | - * // function nlmsg_set_default_size(). | |
1104 | - * struct nl_msg *msg = nlmsg_alloc(); | |
1105 | - * | |
1106 | - * // Very often, the message type and message flags are known | |
1107 | - * // at allocation time while the other fields are auto generated: | |
1108 | - * struct nl_msg *msg = nlmsg_alloc_simple(MY_TYPE, MY_FLAGS); | |
1109 | - * | |
1110 | - * // Alternatively an existing netlink message header can be used | |
1111 | - * // to inherit the header values: | |
1112 | - * struct nlmsghdr hdr = { | |
1113 | - * .nlmsg_type = MY_TYPE, | |
1114 | - * .nlmsg_flags = MY_FLAGS, | |
1115 | - * }; | |
1116 | - * struct nl_msg *msg = nlmsg_inherit(&hdr); | |
1117 | - * | |
1118 | - * // Last but not least, netlink messages received from netlink sockets | |
1119 | - * // can be converted into nl_msg objects using nlmsg_convert(). This | |
1120 | - * // will create a message with a maximum payload size which equals the | |
1121 | - * // length of the existing netlink message, therefore no more data can | |
1122 | - * // be appened without calling nlmsg_expand() first. | |
1123 | - * struct nl_msg *msg = nlmsg_convert(nlh_from_nl_sock); | |
1124 | - * | |
1125 | - * // Payload may be added to the message via nlmsg_append(). The fourth | |
1126 | - * // parameter specifies the number of alignment bytes the data should | |
1127 | - * // be padding with at the end. Common values are 0 to disable it or | |
1128 | - * // NLMSG_ALIGNTO to ensure proper netlink message padding. | |
1129 | - * nlmsg_append(msg, &mydata, sizeof(mydata), 0); | |
1130 | - * | |
1131 | - * // Sometimes it may be necessary to reserve room for data but defer | |
1132 | - * // the actual copying to a later point, nlmsg_reserve() can be used | |
1133 | - * // for this purpose: | |
1134 | - * void *data = nlmsg_reserve(msg, sizeof(mydata), NLMSG_ALIGNTO); | |
1135 | - * | |
1136 | - * // Attributes may be added using the attributes interface. | |
1137 | - * | |
1138 | - * // After successful use of the message, the memory must be freed | |
1139 | - * // using nlmsg_free() | |
1140 | - * nlmsg_free(msg); | |
1141 | - * @endcode | |
1142 | - * | |
1143 | - * @par 4) Parsing messages | |
1144 | - * @code | |
1145 | - * int n; | |
1146 | - * unsigned char *buf; | |
1147 | - * struct nlmsghdr *hdr; | |
1148 | - * | |
1149 | - * n = nl_recv(handle, NULL, &buf); | |
1150 | - * | |
1151 | - * hdr = (struct nlmsghdr *) buf; | |
1152 | - * while (nlmsg_ok(hdr, n)) { | |
1153 | - * // Process message here... | |
1154 | - * hdr = nlmsg_next(hdr, &n); | |
1155 | - * } | |
1156 | - * @endcode | |
1157 | * @{ | |
1158 | + * | |
1159 | + * Header | |
1160 | + * ------ | |
1161 | + * ~~~~{.c} | |
1162 | + * #include <netlink/msg.h> | |
1163 | + * ~~~~ | |
1164 | */ | |
1165 | ||
1166 | #include <netlink-local.h> | |
1167 | diff --git a/lib/netfilter/nfnl.c b/lib/netfilter/nfnl.c | |
1168 | index ddce4b9..6d27c44 100644 | |
1169 | --- a/lib/netfilter/nfnl.c | |
1170 | +++ b/lib/netfilter/nfnl.c | |
1171 | @@ -6,13 +6,13 @@ | |
1172 | * License as published by the Free Software Foundation version 2.1 | |
1173 | * of the License. | |
1174 | * | |
1175 | - * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch> | |
1176 | + * Copyright (c) 2003-2012 Thomas Graf <tgraf@suug.ch> | |
1177 | * Copyright (c) 2007 Philip Craig <philipc@snapgear.com> | |
1178 | * Copyright (c) 2007 Secure Computing Corporation | |
1179 | */ | |
1180 | ||
1181 | /** | |
1182 | - * @defgroup nfnl Netfilter Netlink | |
1183 | + * @defgroup nfnl Netfilter Library (libnl-nf) | |
1184 | * | |
1185 | * @par Message Format | |
1186 | * @code | |
1187 | diff --git a/lib/nl.c b/lib/nl.c | |
1188 | index 7e59130..64e1382 100644 | |
1189 | --- a/lib/nl.c | |
1190 | +++ b/lib/nl.c | |
1191 | @@ -6,78 +6,22 @@ | |
1192 | * License as published by the Free Software Foundation version 2.1 | |
1193 | * of the License. | |
1194 | * | |
1195 | - * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch> | |
1196 | + * Copyright (c) 2003-2012 Thomas Graf <tgraf@suug.ch> | |
1197 | */ | |
1198 | ||
1199 | /** | |
1200 | - * @defgroup core Core | |
1201 | - * | |
1202 | - * @details | |
1203 | - * @par 1) Connecting the socket | |
1204 | - * @code | |
1205 | - * // Bind and connect the socket to a protocol, NETLINK_ROUTE in this example. | |
1206 | - * nl_connect(sk, NETLINK_ROUTE); | |
1207 | - * @endcode | |
1208 | - * | |
1209 | - * @par 2) Sending data | |
1210 | - * @code | |
1211 | - * // The most rudimentary method is to use nl_sendto() simply pushing | |
1212 | - * // a piece of data to the other netlink peer. This method is not | |
1213 | - * // recommended. | |
1214 | - * const char buf[] = { 0x01, 0x02, 0x03, 0x04 }; | |
1215 | - * nl_sendto(sk, buf, sizeof(buf)); | |
1216 | - * | |
1217 | - * // A more comfortable interface is nl_send() taking a pointer to | |
1218 | - * // a netlink message. | |
1219 | - * struct nl_msg *msg = my_msg_builder(); | |
1220 | - * nl_send(sk, nlmsg_hdr(msg)); | |
1221 | - * | |
1222 | - * // nl_sendmsg() provides additional control over the sendmsg() message | |
1223 | - * // header in order to allow more specific addressing of multiple peers etc. | |
1224 | - * struct msghdr hdr = { ... }; | |
1225 | - * nl_sendmsg(sk, nlmsg_hdr(msg), &hdr); | |
1226 | - * | |
1227 | - * // You're probably too lazy to fill out the netlink pid, sequence number | |
1228 | - * // and message flags all the time. nl_send_auto_complete() automatically | |
1229 | - * // extends your message header as needed with an appropriate sequence | |
1230 | - * // number, the netlink pid stored in the netlink socket and the message | |
1231 | - * // flags NLM_F_REQUEST and NLM_F_ACK (if not disabled in the socket) | |
1232 | - * nl_send_auto_complete(sk, nlmsg_hdr(msg)); | |
1233 | - * | |
1234 | - * // Simple protocols don't require the complex message construction interface | |
1235 | - * // and may favour nl_send_simple() to easly send a bunch of payload | |
1236 | - * // encapsulated in a netlink message header. | |
1237 | - * nl_send_simple(sk, MY_MSG_TYPE, 0, buf, sizeof(buf)); | |
1238 | - * @endcode | |
1239 | - * | |
1240 | - * @par 3) Receiving data | |
1241 | - * @code | |
1242 | - * // nl_recv() receives a single message allocating a buffer for the message | |
1243 | - * // content and gives back the pointer to you. | |
1244 | - * struct sockaddr_nl peer; | |
1245 | - * unsigned char *msg; | |
1246 | - * nl_recv(sk, &peer, &msg); | |
1247 | - * | |
1248 | - * // nl_recvmsgs() receives a bunch of messages until the callback system | |
1249 | - * // orders it to state, usually after receving a compolete multi part | |
1250 | - * // message series. | |
1251 | - * nl_recvmsgs(sk, my_callback_configuration); | |
1252 | - * | |
1253 | - * // nl_recvmsgs_default() acts just like nl_recvmsg() but uses the callback | |
1254 | - * // configuration stored in the socket. | |
1255 | - * nl_recvmsgs_default(sk); | |
1256 | - * | |
1257 | - * // In case you want to wait for the ACK to be recieved that you requested | |
1258 | - * // with your latest message, you can call nl_wait_for_ack() | |
1259 | - * nl_wait_for_ack(sk); | |
1260 | - * @endcode | |
1261 | - * | |
1262 | - * @par 4) Closing | |
1263 | - * @code | |
1264 | - * // Close the socket first to release kernel memory | |
1265 | - * nl_close(sk); | |
1266 | - * @endcode | |
1267 | - * | |
1268 | + * @defgroup core Core Library (libnl) | |
1269 | + * | |
1270 | + * Socket handling, connection management, sending and receiving of data, | |
1271 | + * message construction and parsing, object caching system, ... | |
1272 | + * | |
1273 | + * This is the API reference of the core library. It is not meant as a guide | |
1274 | + * but as a reference. Please refer to the core library guide for detailed | |
1275 | + * documentation on the library architecture and examples: | |
1276 | + * | |
1277 | + * * @ref_asciidoc{core,_,Netlink Core Library Development Guide} | |
1278 | + * | |
1279 | + * | |
1280 | * @{ | |
1281 | */ | |
1282 | ||
1283 | @@ -89,6 +33,30 @@ | |
1284 | #include <netlink/attr.h> | |
1285 | ||
1286 | /** | |
1287 | + * @defgroup core_types Data Types | |
1288 | + * | |
1289 | + * Core library data types | |
1290 | + * @{ | |
1291 | + * @} | |
1292 | + * | |
1293 | + * @defgroup send_recv Send & Receive Data | |
1294 | + * | |
1295 | + * Connection management, sending & receiving of data | |
1296 | + * | |
1297 | + * Related sections in the development guide: | |
1298 | + * - @core_doc{core_send_recv, Sending & Receiving} | |
1299 | + * - @core_doc{core_sockets, Sockets} | |
1300 | + * | |
1301 | + * @{ | |
1302 | + * | |
1303 | + * Header | |
1304 | + * ------ | |
1305 | + * ~~~~{.c} | |
1306 | + * #include <netlink/netlink.h> | |
1307 | + * ~~~~ | |
1308 | + */ | |
1309 | + | |
1310 | +/** | |
1311 | * @name Connection Management | |
1312 | * @{ | |
1313 | */ | |
1314 | @@ -541,6 +509,7 @@ abort: | |
1315 | return 0; | |
1316 | } | |
1317 | ||
1318 | +/** @cond SKIP */ | |
1319 | #define NL_CB_CALL(cb, type, msg) \ | |
1320 | do { \ | |
1321 | err = nl_cb_call(cb, type, msg); \ | |
1322 | @@ -556,6 +525,7 @@ do { \ | |
1323 | goto out; \ | |
1324 | } \ | |
1325 | } while (0) | |
1326 | +/** @endcond */ | |
1327 | ||
1328 | static int recvmsgs(struct nl_sock *sk, struct nl_cb *cb) | |
1329 | { | |
1330 | @@ -923,3 +893,5 @@ errout: | |
1331 | /** @} */ | |
1332 | ||
1333 | /** @} */ | |
1334 | + | |
1335 | +/** @} */ | |
1336 | diff --git a/lib/object.c b/lib/object.c | |
1337 | index 554d09b..7606535 100644 | |
1338 | --- a/lib/object.c | |
1339 | +++ b/lib/object.c | |
1340 | @@ -10,9 +10,21 @@ | |
1341 | */ | |
1342 | ||
1343 | /** | |
1344 | - * @ingroup cache | |
1345 | - * @defgroup object Object | |
1346 | + * @ingroup core_types | |
1347 | + * @defgroup object Object (Cacheable) | |
1348 | + * | |
1349 | + * Generic object data type, for inheritance purposes to implement cacheable | |
1350 | + * data types. | |
1351 | + * | |
1352 | + * Related sections in the development guide: | |
1353 | + * | |
1354 | * @{ | |
1355 | + * | |
1356 | + * Header | |
1357 | + * ------ | |
1358 | + * ~~~~{.c} | |
1359 | + * #include <netlink/object.h> | |
1360 | + * ~~~~ | |
1361 | */ | |
1362 | ||
1363 | #include <netlink-local.h> | |
1364 | diff --git a/lib/route/link.c b/lib/route/link.c | |
1365 | index 4da40a0..0a17110 100644 | |
1366 | --- a/lib/route/link.c | |
1367 | +++ b/lib/route/link.c | |
1368 | @@ -1442,8 +1442,7 @@ struct rtnl_link *rtnl_link_alloc(void) | |
1369 | ||
1370 | /** | |
1371 | * Return a link object reference | |
1372 | - * | |
1373 | - * @copydetails nl_object_put() | |
1374 | + * @arg link Link object | |
1375 | */ | |
1376 | void rtnl_link_put(struct rtnl_link *link) | |
1377 | { | |
1378 | diff --git a/lib/route/rtnl.c b/lib/route/rtnl.c | |
1379 | index e5c0798..12a7e97 100644 | |
1380 | --- a/lib/route/rtnl.c | |
1381 | +++ b/lib/route/rtnl.c | |
1382 | @@ -6,11 +6,11 @@ | |
1383 | * License as published by the Free Software Foundation version 2.1 | |
1384 | * of the License. | |
1385 | * | |
1386 | - * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch> | |
1387 | + * Copyright (c) 2003-2012 Thomas Graf <tgraf@suug.ch> | |
1388 | */ | |
1389 | ||
1390 | /** | |
1391 | - * @defgroup rtnl Routing Family | |
1392 | + * @defgroup rtnl Routing Library (libnl-route) | |
1393 | * @{ | |
1394 | */ | |
1395 | ||
1396 | diff --git a/lib/socket.c b/lib/socket.c | |
1397 | index 01b9872..7e3ebf6 100644 | |
1398 | --- a/lib/socket.c | |
1399 | +++ b/lib/socket.c | |
1400 | @@ -6,13 +6,25 @@ | |
1401 | * License as published by the Free Software Foundation version 2.1 | |
1402 | * of the License. | |
1403 | * | |
1404 | - * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch> | |
1405 | + * Copyright (c) 2003-2012 Thomas Graf <tgraf@suug.ch> | |
1406 | */ | |
1407 | ||
1408 | /** | |
1409 | - * @ingroup core | |
1410 | + * @ingroup core_types | |
1411 | * @defgroup socket Socket | |
1412 | + * | |
1413 | + * Representation of a netlink socket | |
1414 | + * | |
1415 | + * Related sections in the development guide: | |
1416 | + * - @core_doc{core_sockets, Netlink Sockets} | |
1417 | + * | |
1418 | * @{ | |
1419 | + * | |
1420 | + * Header | |
1421 | + * ------ | |
1422 | + * ~~~~{.c} | |
1423 | + * #include <netlink/socket.h> | |
1424 | + * ~~~~ | |
1425 | */ | |
1426 | ||
1427 | #include <pthread.h> | |
1428 | diff --git a/lib/utils.c b/lib/utils.c | |
1429 | index 83d424f..5a35a53 100644 | |
1430 | --- a/lib/utils.c | |
1431 | +++ b/lib/utils.c | |
1432 | @@ -6,13 +6,22 @@ | |
1433 | * License as published by the Free Software Foundation version 2.1 | |
1434 | * of the License. | |
1435 | * | |
1436 | - * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch> | |
1437 | + * Copyright (c) 2003-2012 Thomas Graf <tgraf@suug.ch> | |
1438 | */ | |
1439 | ||
1440 | /** | |
1441 | * @ingroup core | |
1442 | * @defgroup utils Utilities | |
1443 | + * | |
1444 | + * Collection of helper functions | |
1445 | + * | |
1446 | * @{ | |
1447 | + * | |
1448 | + * Header | |
1449 | + * ------ | |
1450 | + * ~~~~{.c} | |
1451 | + * #include <netlink/utils.h> | |
1452 | + * ~~~~ | |
1453 | */ | |
1454 | ||
1455 | #include <netlink-local.h> | |
1456 | @@ -21,10 +30,24 @@ | |
1457 | #include <linux/socket.h> | |
1458 | ||
1459 | /** | |
1460 | - * Debug level | |
1461 | + * Global variable indicating the desired level of debugging output. | |
1462 | + * | |
1463 | + * Level | Messages Printed | |
1464 | + * ----- | --------------------------------------------------------- | |
1465 | + * 0 | Debugging output disabled | |
1466 | + * 1 | Warnings, important events and notifications | |
1467 | + * 2 | More or less important debugging messages | |
1468 | + * 3 | Repetitive events causing a flood of debugging messages | |
1469 | + * 4 | Even less important messages | |
1470 | + * | |
1471 | + * If available, the variable will be initialized to the value of the | |
1472 | + * environment variable `NLDBG`. The default value is 0 (disabled). | |
1473 | + * | |
1474 | + * For more information, see section @core_doc{_debugging, Debugging}. | |
1475 | */ | |
1476 | int nl_debug = 0; | |
1477 | ||
1478 | +/** @cond SKIP */ | |
1479 | struct nl_dump_params nl_debug_dp = { | |
1480 | .dp_type = NL_DUMP_DETAILS, | |
1481 | }; | |
1482 | @@ -84,9 +107,10 @@ int __nl_read_num_str_file(const char *path, int (*cb)(long, const char *)) | |
1483 | ||
1484 | return 0; | |
1485 | } | |
1486 | +/** @endcond */ | |
1487 | ||
1488 | /** | |
1489 | - * @name Unit Pretty-Printing | |
1490 | + * @name Pretty Printing of Numbers | |
1491 | * @{ | |
1492 | */ | |
1493 | ||
1494 | -- | |
1495 | 1.7.6.5 | |
1496 |