/usr/include/netlink/object-api.h is in libnl2-dev 2.0-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 | /*
* netlink/object-api.c Object API
*
* 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-2007 Thomas Graf <tgraf@suug.ch>
*/
#ifndef NETLINK_OBJECT_API_H_
#define NETLINK_OBJECT_API_H_
#include <netlink/netlink.h>
#include <netlink/utils.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* @ingroup object
* @defgroup object_api Object API
* @brief
*
* @par 1) Object Definition
* @code
* // Define your object starting with the common object header
* struct my_obj {
* NLHDR_COMMON
* int my_data;
* };
*
* // Fill out the object operations structure
* struct nl_object_ops my_ops = {
* .oo_name = "my_obj",
* .oo_size = sizeof(struct my_obj),
* };
*
* // At this point the object can be allocated, you may want to provide a
* // separate _alloc() function to ease allocting objects of this kind.
* struct nl_object *obj = nl_object_alloc(&my_ops);
*
* // And release it again...
* nl_object_put(obj);
* @endcode
*
* @par 2) Allocating additional data
* @code
* // You may require to allocate additional data and store it inside
* // object, f.e. assuming there is a field `ptr'.
* struct my_obj {
* NLHDR_COMMON
* void * ptr;
* };
*
* // And at some point you may assign allocated data to this field:
* my_obj->ptr = calloc(1, ...);
*
* // In order to not introduce any memory leaks you have to release
* // this data again when the last reference is given back.
* static void my_obj_free_data(struct nl_object *obj)
* {
* struct my_obj *my_obj = nl_object_priv(obj);
*
* free(my_obj->ptr);
* }
*
* // Also when the object is cloned, you must ensure for your pointer
* // stay valid even if one of the clones is freed by either making
* // a clone as well or increase the reference count.
* static int my_obj_clone(struct nl_object *src, struct nl_object *dst)
* {
* struct my_obj *my_src = nl_object_priv(src);
* struct my_obj *my_dst = nl_object_priv(dst);
*
* if (src->ptr) {
* dst->ptr = calloc(1, ...);
* memcpy(dst->ptr, src->ptr, ...);
* }
* }
*
* struct nl_object_ops my_ops = {
* ...
* .oo_free_data = my_obj_free_data,
* .oo_clone = my_obj_clone,
* };
* @endcode
*
* @par 3) Object Dumping
* @code
* static int my_obj_dump_detailed(struct nl_object *obj,
* struct nl_dump_params *params)
* {
* struct my_obj *my_obj = nl_object_priv(obj);
*
* // It is absolutely essential to use nl_dump() when printing
* // any text to make sure the dumping parameters are respected.
* nl_dump(params, "Obj Integer: %d\n", my_obj->my_int);
*
* // Before we can dump the next line, make sure to prefix
* // this line correctly.
* nl_new_line(params);
*
* // You may also split a line into multiple nl_dump() calls.
* nl_dump(params, "String: %s ", my_obj->my_string);
* nl_dump(params, "String-2: %s\n", my_obj->another_string);
* }
*
* struct nl_object_ops my_ops = {
* ...
* .oo_dump[NL_DUMP_FULL] = my_obj_dump_detailed,
* };
* @endcode
*
* @par 4) Object Attributes
* @code
* // The concept of object attributes is optional but can ease the typical
* // case of objects that have optional attributes, e.g. a route may have a
* // nexthop assigned but it is not required to.
*
* // The first step to define your object specific bitmask listing all
* // attributes
* #define MY_ATTR_FOO (1<<0)
* #define MY_ATTR_BAR (1<<1)
*
* // When assigning an optional attribute to the object, make sure
* // to mark its availability.
* my_obj->foo = 123123;
* my_obj->ce_mask |= MY_ATTR_FOO;
*
* // At any time you may use this mask to check for the availability
* // of the attribute, e.g. while dumping
* if (my_obj->ce_mask & MY_ATTR_FOO)
* nl_dump(params, "foo %d ", my_obj->foo);
*
* // One of the big advantages of this concept is that it allows for
* // standardized comparisons which make it trivial for caches to
* // identify unique objects by use of unified comparison functions.
* // In order for it to work, your object implementation must provide
* // a comparison function and define a list of attributes which
* // combined together make an object unique.
*
* static int my_obj_compare(struct nl_object *_a, struct nl_object *_b,
* uint32_t attrs, int flags)
* {
* struct my_obj *a = nl_object_priv(_a):
* struct my_obj *b = nl_object_priv(_b):
* int diff = 0;
*
* // We help ourselves in defining our own DIFF macro which will
* // call ATTR_DIFF() on both objects which will make sure to only
* // compare the attributes if required.
* #define MY_DIFF(ATTR, EXPR) ATTR_DIFF(attrs, MY_ATTR_##ATTR, a, b, EXPR)
*
* // Call our own diff macro for each attribute to build a bitmask
* // representing the attributes which mismatch.
* diff |= MY_DIFF(FOO, a->foo != b->foo)
* diff |= MY_DIFF(BAR, strcmp(a->bar, b->bar))
*
* return diff;
* }
*
* // In order to identify identical objects with differing attributes
* // you must specify the attributes required to uniquely identify
* // your object. Make sure to not include too many attributes, this
* // list is used when caches look for an old version of an object.
* struct nl_object_ops my_ops = {
* ...
* .oo_id_attrs = MY_ATTR_FOO,
* .oo_compare = my_obj_compare,
* };
* @endcode
* @{
*/
/**
* Common Object Header
*
* This macro must be included as first member in every object
* definition to allow objects to be cached.
*/
#define NLHDR_COMMON \
int ce_refcnt; \
struct nl_object_ops * ce_ops; \
struct nl_cache * ce_cache; \
struct nl_list_head ce_list; \
int ce_msgtype; \
int ce_flags; \
uint32_t ce_mask;
/**
* Return true if attribute is available in both objects
* @arg A an object
* @arg B another object
* @arg ATTR attribute bit
*
* @return True if the attribute is available, otherwise false is returned.
*/
#define AVAILABLE(A, B, ATTR) (((A)->ce_mask & (B)->ce_mask) & (ATTR))
/**
* Return true if attribute is available in only one of both objects
* @arg A an object
* @arg B another object
* @arg ATTR attribute bit
*
* @return True if the attribute is available in only one of both objects,
* otherwise false is returned.
*/
#define AVAILABLE_MISMATCH(A, B, ATTR) (((A)->ce_mask ^ (B)->ce_mask) & (ATTR))
/**
* Return true if attributes mismatch
* @arg A an object
* @arg B another object
* @arg ATTR attribute bit
* @arg EXPR Comparison expression
*
* This function will check if the attribute in question is available
* in both objects, if not this will count as a mismatch.
*
* If available the function will execute the expression which must
* return true if the attributes mismatch.
*
* @return True if the attribute mismatch, or false if they match.
*/
#define ATTR_MISMATCH(A, B, ATTR, EXPR) (AVAILABLE_MISMATCH(A, B, ATTR) || \
(AVAILABLE(A, B, ATTR) && (EXPR)))
/**
* Return attribute bit if attribute does not match
* @arg LIST list of attributes to be compared
* @arg ATTR attribute bit
* @arg A an object
* @arg B another object
* @arg EXPR Comparison expression
*
* This function will check if the attribute in question is available
* in both objects, if not this will count as a mismatch.
*
* If available the function will execute the expression which must
* return true if the attributes mismatch.
*
* In case the attributes mismatch, the attribute is returned, otherwise
* 0 is returned.
*
* @code
* diff |= ATTR_DIFF(attrs, MY_ATTR_FOO, a, b, a->foo != b->foo);
* @endcode
*/
#define ATTR_DIFF(LIST, ATTR, A, B, EXPR) \
({ int diff = 0; \
if (((LIST) & (ATTR)) && ATTR_MISMATCH(A, B, ATTR, EXPR)) \
diff = ATTR; \
diff; })
/**
* Object Operations
*/
struct nl_object_ops
{
/**
* Unique name of object type
*
* Must be in the form family/name, e.g. "route/addr"
*/
char * oo_name;
/** Size of object including its header */
size_t oo_size;
/* List of attributes needed to uniquely identify the object */
uint32_t oo_id_attrs;
/**
* Constructor function
*
* Will be called when a new object of this type is allocated.
* Can be used to initialize members such as lists etc.
*/
void (*oo_constructor)(struct nl_object *);
/**
* Destructor function
*
* Will be called when an object is freed. Must free all
* resources which may have been allocated as part of this
* object.
*/
void (*oo_free_data)(struct nl_object *);
/**
* Cloning function
*
* Will be called when an object needs to be cloned. Please
* note that the generic object code will make an exact
* copy of the object first, therefore you only need to take
* care of members which require reference counting etc.
*
* May return a negative error code to abort cloning.
*/
int (*oo_clone)(struct nl_object *, struct nl_object *);
/**
* Dumping functions
*
* Will be called when an object is dumped. The implementations
* have to use nl_dump(), nl_dump_line(), and nl_new_line() to
* dump objects.
*
* The functions must return the number of lines printed.
*/
void (*oo_dump[NL_DUMP_MAX+1])(struct nl_object *,
struct nl_dump_params *);
/**
* Comparison function
*
* Will be called when two objects of the same type are
* compared. It takes the two objects in question, an object
* specific bitmask defining which attributes should be
* compared and flags to control the behaviour.
*
* The function must return a bitmask with the relevant bit
* set for each attribute that mismatches.
*/
int (*oo_compare)(struct nl_object *, struct nl_object *,
uint32_t, int);
char *(*oo_attrs2str)(int, char *, size_t);
};
/** @} */
#ifdef __cplusplus
}
#endif
#endif
|