blob: 8fee8c852f34b862f8654d09fc6a3e7448aee80c (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
/*
* lib/doc.c Documentation Purpose
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation version 2.1
* of the License.
*
* Copyright (c) 2003-2006 Thomas Graf <tgraf@suug.ch>
*/
/**
* @mainpage
*
* @section remarks Remarks
*
* @subsection cache_alloc Allocation of Caches
*
* Almost all subsystem provide a function to allocate a new cache
* of some form. The function usually looks like this:
* @code
* struct nl_cache *<object name>_alloc_cache(struct nl_handle *handle)
* @endcode
*
* These functions allocate a new cache for the own object type,
* initializes it properly and updates it to represent the current
* state of their master, e.g. a link cache would include all
* links currently configured in the kernel.
*
* Some of the allocation functions may take additional arguments
* to further specify what will be part of the cache.
*
* All such functions return a newly allocated cache or NULL
* in case of an error.
*
* @subsection addr Setting of Addresses
* @code
* int <object name>_set_addr(struct nl_object *, struct nl_addr *)
* @endcode
*
* All attribute functions avaiable for assigning addresses to objects
* take a struct nl_addr argument. The provided address object is
* validated against the address family of the object if known already.
* The assignment fails if the address families mismatch. In case the
* address family has not been specified yet, the address family of
* the new address is elected to be the new requirement.
*
* The function will acquire a new reference on the address object
* before assignment, the caller is NOT responsible for this.
*
* All functions return 0 on success or a negative error code.
*
* @subsection flags Flags to Character StringTranslations
* All functions converting a set of flags to a character string follow
* the same principles, therefore, the following information applies
* to all functions convertings flags to a character string and vice versa.
*
* @subsubsection flags2str Flags to Character String
* @code
* char *<object name>_flags2str(int flags, char *buf, size_t len)
* @endcode
* @arg flags Flags.
* @arg buf Destination buffer.
* @arg len Buffer length.
*
* Converts the specified flags to a character string separated by
* commas and stores it in the specified destination buffer.
*
* @return The destination buffer
*
* @subsubsection str2flags Character String to Flags
* @code
* int <object name>_str2flags(const char *name)
* @endcode
* @arg name Name of flag.
*
* Converts the provided character string specifying a flag
* to the corresponding numeric value.
*
* @return Link flag or a negative value if none was found.
*
* @subsubsection type2str Type to Character String
* @code
* char *<object name>_<type>2str(int type, char *buf, size_t len)
* @endcode
* @arg type Type as numeric value
* @arg buf Destination buffer.
* @arg len Buffer length.
*
* Converts an identifier (type) to a character string and stores
* it in the specified destination buffer.
*
* @return The destination buffer or the type encoded in hexidecimal
* form if the identifier is unknown.
*
* @subsubsection str2type Character String to Type
* @code
* int <object name>_str2<type>(const char *name)
* @endcode
* @arg name Name of identifier (type).
*
* Converts the provided character string specifying a identifier
* to the corresponding numeric value.
*
* @return Identifier as numeric value or a negative value if none was found.
*/
|
