libnl  3.4.0
cache.c
1 /*
2  * lib/cache.c Caching Module
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation version 2.1
7  * of the License.
8  *
9  * Copyright (c) 2003-2012 Thomas Graf <tgraf@suug.ch>
10  */
11 
12 /**
13  * @ingroup cache_mngt
14  * @defgroup cache Cache
15  *
16  * @code
17  * Cache Management | | Type Specific Cache Operations
18  *
19  * | | +----------------+ +------------+
20  * | request update | | msg_parser |
21  * | | +----------------+ +------------+
22  * +- - - - -^- - - - - - - -^- -|- - - -
23  * nl_cache_update: | | | |
24  * 1) --------- co_request_update ------+ | |
25  * | | |
26  * 2) destroy old cache +----------- pp_cb ---------|---+
27  * | | |
28  * 3) ---------- nl_recvmsgs ----------+ +- cb_valid -+
29  * +--------------+ | | | |
30  * | nl_cache_add |<-----+ + - - -v- -|- - - - - - - - - - -
31  * +--------------+ | | +-------------+
32  * | nl_recvmsgs |
33  * | | +-----|-^-----+
34  * +---v-|---+
35  * | | | nl_recv |
36  * +---------+
37  * | | Core Netlink
38  * @endcode
39  *
40  * Related sections in the development guide:
41  * - @core_doc{core_cache, Caching System}
42  *
43  * @{
44  *
45  * Header
46  * ------
47  * ~~~~{.c}
48  * #include <netlink/cache.h>
49  * ~~~~
50  */
51 
52 #include <netlink-private/netlink.h>
53 #include <netlink/netlink.h>
54 #include <netlink/cache.h>
55 #include <netlink/object.h>
56 #include <netlink/hashtable.h>
57 #include <netlink/utils.h>
58 
59 /**
60  * @name Access Functions
61  * @{
62  */
63 
64 /**
65  * Return the number of items in the cache
66  * @arg cache cache handle
67  */
68 int nl_cache_nitems(struct nl_cache *cache)
69 {
70  return cache->c_nitems;
71 }
72 
73 /**
74  * Return the number of items matching a filter in the cache
75  * @arg cache Cache object.
76  * @arg filter Filter object.
77  */
78 int nl_cache_nitems_filter(struct nl_cache *cache, struct nl_object *filter)
79 {
80  struct nl_object *obj;
81  int nitems = 0;
82 
83  if (cache->c_ops == NULL)
84  BUG();
85 
86  nl_list_for_each_entry(obj, &cache->c_items, ce_list) {
87  if (filter && !nl_object_match_filter(obj, filter))
88  continue;
89 
90  nitems++;
91  }
92 
93  return nitems;
94 }
95 
96 /**
97  * Returns \b true if the cache is empty.
98  * @arg cache Cache to check
99  * @return \a true if the cache is empty, otherwise \b false is returned.
100  */
101 int nl_cache_is_empty(struct nl_cache *cache)
102 {
103  return nl_list_empty(&cache->c_items);
104 }
105 
106 /**
107  * Return the operations set of the cache
108  * @arg cache cache handle
109  */
110 struct nl_cache_ops *nl_cache_get_ops(struct nl_cache *cache)
111 {
112  return cache->c_ops;
113 }
114 
115 /**
116  * Return the first element in the cache
117  * @arg cache cache handle
118  */
119 struct nl_object *nl_cache_get_first(struct nl_cache *cache)
120 {
121  if (nl_list_empty(&cache->c_items))
122  return NULL;
123 
124  return nl_list_entry(cache->c_items.next,
125  struct nl_object, ce_list);
126 }
127 
128 /**
129  * Return the last element in the cache
130  * @arg cache cache handle
131  */
132 struct nl_object *nl_cache_get_last(struct nl_cache *cache)
133 {
134  if (nl_list_empty(&cache->c_items))
135  return NULL;
136 
137  return nl_list_entry(cache->c_items.prev,
138  struct nl_object, ce_list);
139 }
140 
141 /**
142  * Return the next element in the cache
143  * @arg obj current object
144  */
145 struct nl_object *nl_cache_get_next(struct nl_object *obj)
146 {
147  if (nl_list_at_tail(obj, &obj->ce_cache->c_items, ce_list))
148  return NULL;
149  else
150  return nl_list_entry(obj->ce_list.next,
151  struct nl_object, ce_list);
152 }
153 
154 /**
155  * Return the previous element in the cache
156  * @arg obj current object
157  */
158 struct nl_object *nl_cache_get_prev(struct nl_object *obj)
159 {
160  if (nl_list_at_head(obj, &obj->ce_cache->c_items, ce_list))
161  return NULL;
162  else
163  return nl_list_entry(obj->ce_list.prev,
164  struct nl_object, ce_list);
165 }
166 
167 /** @} */
168 
169 /**
170  * @name Cache Allocation/Deletion
171  * @{
172  */
173 
174 /**
175  * Allocate new cache
176  * @arg ops Cache operations
177  *
178  * Allocate and initialize a new cache based on the cache operations
179  * provided.
180  *
181  * @return Allocated cache or NULL if allocation failed.
182  */
183 struct nl_cache *nl_cache_alloc(struct nl_cache_ops *ops)
184 {
185  struct nl_cache *cache;
186 
187  cache = calloc(1, sizeof(*cache));
188  if (!cache)
189  return NULL;
190 
191  nl_init_list_head(&cache->c_items);
192  cache->c_ops = ops;
193  cache->c_flags |= ops->co_flags;
194  cache->c_refcnt = 1;
195 
196  /*
197  * If object type provides a hash keygen
198  * functions, allocate a hash table for the
199  * cache objects for faster lookups
200  */
201  if (ops->co_obj_ops->oo_keygen) {
202  int hashtable_size;
203 
204  if (ops->co_hash_size)
205  hashtable_size = ops->co_hash_size;
206  else
207  hashtable_size = NL_MAX_HASH_ENTRIES;
208 
209  cache->hashtable = nl_hash_table_alloc(hashtable_size);
210  }
211 
212  NL_DBG(2, "Allocated cache %p <%s>.\n", cache, nl_cache_name(cache));
213 
214  return cache;
215 }
216 
217 /**
218  * Allocate new cache and fill it
219  * @arg ops Cache operations
220  * @arg sock Netlink socket
221  * @arg result Result pointer
222  *
223  * Allocate new cache and fill it. Equivalent to calling:
224  * @code
225  * cache = nl_cache_alloc(ops);
226  * nl_cache_refill(sock, cache);
227  * @endcode
228  *
229  * @see nl_cache_alloc
230  *
231  * @return 0 on success or a negative error code.
232  */
233 int nl_cache_alloc_and_fill(struct nl_cache_ops *ops, struct nl_sock *sock,
234  struct nl_cache **result)
235 {
236  struct nl_cache *cache;
237  int err;
238 
239  if (!(cache = nl_cache_alloc(ops)))
240  return -NLE_NOMEM;
241 
242  if (sock && (err = nl_cache_refill(sock, cache)) < 0) {
243  nl_cache_free(cache);
244  return err;
245  }
246 
247  *result = cache;
248  return 0;
249 }
250 
251 /**
252  * Allocate new cache based on type name
253  * @arg kind Name of cache type
254  * @arg result Result pointer
255  *
256  * Lookup cache ops via nl_cache_ops_lookup() and allocate the cache
257  * by calling nl_cache_alloc(). Stores the allocated cache in the
258  * result pointer provided.
259  *
260  * @see nl_cache_alloc
261  *
262  * @return 0 on success or a negative error code.
263  */
264 int nl_cache_alloc_name(const char *kind, struct nl_cache **result)
265 {
266  struct nl_cache_ops *ops;
267  struct nl_cache *cache;
268 
269  ops = nl_cache_ops_lookup_safe(kind);
270  if (!ops)
271  return -NLE_NOCACHE;
272 
273  cache = nl_cache_alloc(ops);
274  nl_cache_ops_put(ops);
275  if (!cache)
276  return -NLE_NOMEM;
277 
278  *result = cache;
279  return 0;
280 }
281 
282 /**
283  * Allocate new cache containing a subset of an existing cache
284  * @arg orig Original cache to base new cache on
285  * @arg filter Filter defining the subset to be filled into the new cache
286  *
287  * Allocates a new cache matching the type of the cache specified by
288  * \p orig. Iterates over the \p orig cache applying the specified
289  * \p filter and copies all objects that match to the new cache.
290  *
291  * The copied objects are clones but do not contain a reference to each
292  * other. Later modifications to objects in the original cache will
293  * not affect objects in the new cache.
294  *
295  * @return A newly allocated cache or NULL.
296  */
297 struct nl_cache *nl_cache_subset(struct nl_cache *orig,
298  struct nl_object *filter)
299 {
300  struct nl_cache *cache;
301  struct nl_object *obj;
302 
303  if (!filter)
304  BUG();
305 
306  cache = nl_cache_alloc(orig->c_ops);
307  if (!cache)
308  return NULL;
309 
310  NL_DBG(2, "Filling subset of cache %p <%s> with filter %p into %p\n",
311  orig, nl_cache_name(orig), filter, cache);
312 
313  nl_list_for_each_entry(obj, &orig->c_items, ce_list) {
314  if (!nl_object_match_filter(obj, filter))
315  continue;
316 
317  nl_cache_add(cache, obj);
318  }
319 
320  return cache;
321 }
322 
323 /**
324  * Allocate new cache and copy the contents of an existing cache
325  * @arg cache Original cache to base new cache on
326  *
327  * Allocates a new cache matching the type of the cache specified by
328  * \p cache. Iterates over the \p cache cache and copies all objects
329  * to the new cache.
330  *
331  * The copied objects are clones but do not contain a reference to each
332  * other. Later modifications to objects in the original cache will
333  * not affect objects in the new cache.
334  *
335  * @return A newly allocated cache or NULL.
336  */
337 struct nl_cache *nl_cache_clone(struct nl_cache *cache)
338 {
339  struct nl_cache_ops *ops = nl_cache_get_ops(cache);
340  struct nl_cache *clone;
341  struct nl_object *obj;
342 
343  clone = nl_cache_alloc(ops);
344  if (!clone)
345  return NULL;
346 
347  NL_DBG(2, "Cloning %p into %p\n", cache, clone);
348 
349  nl_list_for_each_entry(obj, &cache->c_items, ce_list)
350  nl_cache_add(clone, obj);
351 
352  return clone;
353 }
354 
355 /**
356  * Remove all objects of a cache.
357  * @arg cache Cache to clear
358  *
359  * The objects are unliked/removed from the cache by calling
360  * nl_cache_remove() on each object in the cache. If any of the objects
361  * to not contain any further references to them, those objects will
362  * be freed.
363  *
364  * Unlike with nl_cache_free(), the cache is not freed just emptied.
365  */
366 void nl_cache_clear(struct nl_cache *cache)
367 {
368  struct nl_object *obj, *tmp;
369 
370  NL_DBG(2, "Clearing cache %p <%s>...\n", cache, nl_cache_name(cache));
371 
372  nl_list_for_each_entry_safe(obj, tmp, &cache->c_items, ce_list)
373  nl_cache_remove(obj);
374 }
375 
376 static void __nl_cache_free(struct nl_cache *cache)
377 {
378  nl_cache_clear(cache);
379 
380  if (cache->hashtable)
381  nl_hash_table_free(cache->hashtable);
382 
383  NL_DBG(2, "Freeing cache %p <%s>...\n", cache, nl_cache_name(cache));
384  free(cache);
385 }
386 
387 /**
388  * Increase reference counter of cache
389  * @arg cache Cache
390  */
391 void nl_cache_get(struct nl_cache *cache)
392 {
393  cache->c_refcnt++;
394 
395  NL_DBG(3, "Incremented cache %p <%s> reference count to %d\n",
396  cache, nl_cache_name(cache), cache->c_refcnt);
397 }
398 
399 /**
400  * Free a cache.
401  * @arg cache Cache to free.
402  *
403  * Calls nl_cache_clear() to remove all objects associated with the
404  * cache and frees the cache afterwards.
405  *
406  * @see nl_cache_clear()
407  */
408 void nl_cache_free(struct nl_cache *cache)
409 {
410  if (!cache)
411  return;
412 
413  cache->c_refcnt--;
414 
415  NL_DBG(3, "Decremented cache %p <%s> reference count, %d remaining\n",
416  cache, nl_cache_name(cache), cache->c_refcnt);
417 
418  if (cache->c_refcnt <= 0)
419  __nl_cache_free(cache);
420 }
421 
422 void nl_cache_put(struct nl_cache *cache)
423 {
424  return nl_cache_free(cache);
425 }
426 
427 /** @} */
428 
429 /**
430  * @name Cache Modifications
431  * @{
432  */
433 
434 static int __cache_add(struct nl_cache *cache, struct nl_object *obj)
435 {
436  int ret;
437 
438  obj->ce_cache = cache;
439 
440  if (cache->hashtable) {
441  ret = nl_hash_table_add(cache->hashtable, obj);
442  if (ret < 0) {
443  obj->ce_cache = NULL;
444  return ret;
445  }
446  }
447 
448  nl_list_add_tail(&obj->ce_list, &cache->c_items);
449  cache->c_nitems++;
450 
451  NL_DBG(3, "Added object %p to cache %p <%s>, nitems %d\n",
452  obj, cache, nl_cache_name(cache), cache->c_nitems);
453 
454  return 0;
455 }
456 
457 /**
458  * Add object to cache.
459  * @arg cache Cache
460  * @arg obj Object to be added to the cache
461  *
462  * Adds the object \p obj to the specified \p cache. In case the object
463  * is already associated with another cache, the object is cloned before
464  * adding it to the cache. In this case, the sole reference to the object
465  * will be the one of the cache. Therefore clearing/freeing the cache
466  * will result in the object being freed again.
467  *
468  * If the object has not been associated with a cache yet, the reference
469  * counter of the object is incremented to account for the additional
470  * reference.
471  *
472  * The type of the object and cache must match, otherwise an error is
473  * returned (-NLE_OBJ_MISMATCH).
474  *
475  * @see nl_cache_move()
476  *
477  * @return 0 or a negative error code.
478  */
479 int nl_cache_add(struct nl_cache *cache, struct nl_object *obj)
480 {
481  struct nl_object *new;
482  int ret = 0;
483 
484  if (cache->c_ops->co_obj_ops != obj->ce_ops)
485  return -NLE_OBJ_MISMATCH;
486 
487  if (!nl_list_empty(&obj->ce_list)) {
488  NL_DBG(3, "Object %p already in cache, cloning new object\n", obj);
489 
490  new = nl_object_clone(obj);
491  if (!new)
492  return -NLE_NOMEM;
493  } else {
494  nl_object_get(obj);
495  new = obj;
496  }
497 
498  ret = __cache_add(cache, new);
499  if (ret < 0)
500  nl_object_put(new);
501 
502  return ret;
503 }
504 
505 /**
506  * Move object from one cache to another
507  * @arg cache Cache to move object to.
508  * @arg obj Object subject to be moved
509  *
510  * Removes the the specified object \p obj from its associated cache
511  * and moves it to another cache.
512  *
513  * If the object is not associated with a cache, the function behaves
514  * just like nl_cache_add().
515  *
516  * The type of the object and cache must match, otherwise an error is
517  * returned (-NLE_OBJ_MISMATCH).
518  *
519  * @see nl_cache_add()
520  *
521  * @return 0 on success or a negative error code.
522  */
523 int nl_cache_move(struct nl_cache *cache, struct nl_object *obj)
524 {
525  if (cache->c_ops->co_obj_ops != obj->ce_ops)
526  return -NLE_OBJ_MISMATCH;
527 
528  NL_DBG(3, "Moving object %p from cache %p to cache %p\n",
529  obj, obj->ce_cache, cache);
530 
531  /* Acquire reference, if already in a cache this will be
532  * reverted during removal */
533  nl_object_get(obj);
534 
535  if (!nl_list_empty(&obj->ce_list))
536  nl_cache_remove(obj);
537 
538  return __cache_add(cache, obj);
539 }
540 
541 /**
542  * Remove object from cache.
543  * @arg obj Object to remove from cache
544  *
545  * Removes the object \c obj from the cache it is associated with. The
546  * reference counter of the object will be decremented. If the reference
547  * to the object was the only one remaining, the object will be freed.
548  *
549  * If no cache is associated with the object, this function is a NOP.
550  */
551 void nl_cache_remove(struct nl_object *obj)
552 {
553  int ret;
554  struct nl_cache *cache = obj->ce_cache;
555 
556  if (cache == NULL)
557  return;
558 
559  if (cache->hashtable) {
560  ret = nl_hash_table_del(cache->hashtable, obj);
561  if (ret < 0)
562  NL_DBG(2, "Failed to delete %p from cache %p <%s>.\n",
563  obj, cache, nl_cache_name(cache));
564  }
565 
566  nl_list_del(&obj->ce_list);
567  obj->ce_cache = NULL;
568  nl_object_put(obj);
569  cache->c_nitems--;
570 
571  NL_DBG(2, "Deleted object %p from cache %p <%s>.\n",
572  obj, cache, nl_cache_name(cache));
573 }
574 
575 /** @} */
576 
577 /**
578  * @name Synchronization
579  * @{
580  */
581 
582 /**
583  * Set synchronization arg1 of cache
584  * @arg cache Cache
585  * @arg arg argument
586  *
587  * Synchronization arguments are used to specify filters when
588  * requesting dumps from the kernel.
589  */
590 void nl_cache_set_arg1(struct nl_cache *cache, int arg)
591 {
592  cache->c_iarg1 = arg;
593 }
594 
595 /**
596  * Set synchronization arg2 of cache
597  * @arg cache Cache
598  * @arg arg argument
599  *
600  * Synchronization arguments are used to specify filters when
601  * requesting dumps from the kernel.
602  */
603 void nl_cache_set_arg2(struct nl_cache *cache, int arg)
604 {
605  cache->c_iarg2 = arg;
606 }
607 
608 /**
609  * Set cache flags
610  * @arg cache Cache
611  * @arg flags Flags
612  */
613 void nl_cache_set_flags(struct nl_cache *cache, unsigned int flags)
614 {
615  cache->c_flags |= flags;
616 }
617 
618 /**
619  * Invoke the request-update operation
620  * @arg sk Netlink socket.
621  * @arg cache Cache
622  *
623  * This function causes the \e request-update function of the cache
624  * operations to be invoked. This usually causes a dump request to
625  * be sent over the netlink socket which triggers the kernel to dump
626  * all objects of a specific type to be dumped onto the netlink
627  * socket for pickup.
628  *
629  * The behaviour of this function depends on the implemenation of
630  * the \e request_update function of each individual type of cache.
631  *
632  * This function will not have any effects on the cache (unless the
633  * request_update implementation of the cache operations does so).
634  *
635  * Use nl_cache_pickup() to pick-up (read) the objects from the socket
636  * and fill them into the cache.
637  *
638  * @see nl_cache_pickup(), nl_cache_resync()
639  *
640  * @return 0 on success or a negative error code. Some implementations
641  * of co_request_update() return a positive number on success that is
642  * the number of bytes sent. Treat any non-negative number as success too.
643  */
644 static int nl_cache_request_full_dump(struct nl_sock *sk,
645  struct nl_cache *cache)
646 {
647  if (sk->s_proto != cache->c_ops->co_protocol)
648  return -NLE_PROTO_MISMATCH;
649 
650  if (cache->c_ops->co_request_update == NULL)
651  return -NLE_OPNOTSUPP;
652 
653  NL_DBG(2, "Requesting update from kernel for cache %p <%s>\n",
654  cache, nl_cache_name(cache));
655 
656  return cache->c_ops->co_request_update(cache, sk);
657 }
658 
659 /** @cond SKIP */
660 struct update_xdata {
661  struct nl_cache_ops *ops;
662  struct nl_parser_param *params;
663 };
664 
665 static int update_msg_parser(struct nl_msg *msg, void *arg)
666 {
667  struct update_xdata *x = arg;
668  int ret = 0;
669 
670  ret = nl_cache_parse(x->ops, &msg->nm_src, msg->nm_nlh, x->params);
671  if (ret == -NLE_EXIST)
672  return NL_SKIP;
673  else
674  return ret;
675 }
676 /** @endcond */
677 
678 /**
679  * Pick-up a netlink request-update with your own parser
680  * @arg sk Netlink socket
681  * @arg cache Cache
682  * @arg param Parser parameters
683  */
684 static int __cache_pickup(struct nl_sock *sk, struct nl_cache *cache,
685  struct nl_parser_param *param)
686 {
687  int err;
688  struct nl_cb *cb;
689  struct update_xdata x = {
690  .ops = cache->c_ops,
691  .params = param,
692  };
693 
694  NL_DBG(2, "Picking up answer for cache %p <%s>\n",
695  cache, nl_cache_name(cache));
696 
697  cb = nl_cb_clone(sk->s_cb);
698  if (cb == NULL)
699  return -NLE_NOMEM;
700 
701  nl_cb_set(cb, NL_CB_VALID, NL_CB_CUSTOM, update_msg_parser, &x);
702 
703  err = nl_recvmsgs(sk, cb);
704  if (err < 0)
705  NL_DBG(2, "While picking up for %p <%s>, recvmsgs() returned %d: %s\n",
706  cache, nl_cache_name(cache), err, nl_geterror(err));
707 
708  nl_cb_put(cb);
709 
710  return err;
711 }
712 
713 static int pickup_checkdup_cb(struct nl_object *c, struct nl_parser_param *p)
714 {
715  struct nl_cache *cache = (struct nl_cache *)p->pp_arg;
716  struct nl_object *old;
717 
718  old = nl_cache_search(cache, c);
719  if (old) {
720  if (nl_object_update(old, c) == 0) {
721  nl_object_put(old);
722  return 0;
723  }
724 
725  nl_cache_remove(old);
726  nl_object_put(old);
727  }
728 
729  return nl_cache_add(cache, c);
730 }
731 
732 static int pickup_cb(struct nl_object *c, struct nl_parser_param *p)
733 {
734  struct nl_cache *cache = p->pp_arg;
735 
736  return nl_cache_add(cache, c);
737 }
738 
739 static int __nl_cache_pickup(struct nl_sock *sk, struct nl_cache *cache,
740  int checkdup)
741 {
742  struct nl_parser_param p;
743 
744  p.pp_cb = checkdup ? pickup_checkdup_cb : pickup_cb;
745  p.pp_arg = cache;
746 
747  if (sk->s_proto != cache->c_ops->co_protocol)
748  return -NLE_PROTO_MISMATCH;
749 
750  return __cache_pickup(sk, cache, &p);
751 }
752 
753 /**
754  * Pickup a netlink dump response and put it into a cache.
755  * @arg sk Netlink socket.
756  * @arg cache Cache to put items into.
757  *
758  * Waits for netlink messages to arrive, parses them and puts them into
759  * the specified cache.
760  *
761  * @return 0 on success or a negative error code.
762  */
763 int nl_cache_pickup_checkdup(struct nl_sock *sk, struct nl_cache *cache)
764 {
765  return __nl_cache_pickup(sk, cache, 1);
766 }
767 
768 /**
769  * Pickup a netlink dump response and put it into a cache.
770  * @arg sk Netlink socket.
771  * @arg cache Cache to put items into.
772  *
773  * Waits for netlink messages to arrive, parses them and puts them into
774  * the specified cache. If an old object with same key attributes is
775  * present in the cache, it is replaced with the new object.
776  * If the old object type supports an update operation, an update is
777  * attempted before a replace.
778  *
779  * @return 0 on success or a negative error code.
780  */
781 int nl_cache_pickup(struct nl_sock *sk, struct nl_cache *cache)
782 {
783  return __nl_cache_pickup(sk, cache, 0);
784 }
785 
786 static int cache_include(struct nl_cache *cache, struct nl_object *obj,
787  struct nl_msgtype *type, change_func_t cb,
788  change_func_v2_t cb_v2, void *data)
789 {
790  struct nl_object *old;
791  struct nl_object *clone = NULL;
792  uint64_t diff = 0;
793 
794  switch (type->mt_act) {
795  case NL_ACT_NEW:
796  case NL_ACT_DEL:
797  old = nl_cache_search(cache, obj);
798  if (old) {
799  if (cb_v2 && old->ce_ops->oo_update) {
800  clone = nl_object_clone(old);
801  diff = nl_object_diff64(old, obj);
802  }
803  /*
804  * Some objects types might support merging the new
805  * object with the old existing cache object.
806  * Handle them first.
807  */
808  if (nl_object_update(old, obj) == 0) {
809  if (cb_v2) {
810  cb_v2(cache, clone, obj, diff,
811  NL_ACT_CHANGE, data);
812  nl_object_put(clone);
813  } else if (cb)
814  cb(cache, old, NL_ACT_CHANGE, data);
815  nl_object_put(old);
816  return 0;
817  }
818  nl_object_put(clone);
819 
820  nl_cache_remove(old);
821  if (type->mt_act == NL_ACT_DEL) {
822  if (cb_v2)
823  cb_v2(cache, old, NULL, 0, NL_ACT_DEL,
824  data);
825  else if (cb)
826  cb(cache, old, NL_ACT_DEL, data);
827  nl_object_put(old);
828  }
829  }
830 
831  if (type->mt_act == NL_ACT_NEW) {
832  nl_cache_move(cache, obj);
833  if (old == NULL) {
834  if (cb_v2) {
835  cb_v2(cache, NULL, obj, 0, NL_ACT_NEW,
836  data);
837  } else if (cb)
838  cb(cache, obj, NL_ACT_NEW, data);
839  } else if (old) {
840  diff = 0;
841  if (cb || cb_v2)
842  diff = nl_object_diff64(old, obj);
843  if (diff && cb_v2) {
844  cb_v2(cache, old, obj, diff, NL_ACT_CHANGE,
845  data);
846  } else if (diff && cb)
847  cb(cache, obj, NL_ACT_CHANGE, data);
848 
849  nl_object_put(old);
850  }
851  }
852  break;
853  default:
854  NL_DBG(2, "Unknown action associated to object %p\n", obj);
855  return 0;
856  }
857 
858  return 0;
859 }
860 
861 int nl_cache_include(struct nl_cache *cache, struct nl_object *obj,
862  change_func_t change_cb, void *data)
863 {
864  struct nl_cache_ops *ops = cache->c_ops;
865  int i;
866 
867  if (ops->co_obj_ops != obj->ce_ops)
868  return -NLE_OBJ_MISMATCH;
869 
870  for (i = 0; ops->co_msgtypes[i].mt_id >= 0; i++)
871  if (ops->co_msgtypes[i].mt_id == obj->ce_msgtype)
872  return cache_include(cache, obj, &ops->co_msgtypes[i],
873  change_cb, NULL, data);
874 
875  NL_DBG(3, "Object %p does not seem to belong to cache %p <%s>\n",
876  obj, cache, nl_cache_name(cache));
877 
878  return -NLE_MSGTYPE_NOSUPPORT;
879 }
880 
881 int nl_cache_include_v2(struct nl_cache *cache, struct nl_object *obj,
882  change_func_v2_t change_cb, void *data)
883 {
884  struct nl_cache_ops *ops = cache->c_ops;
885  int i;
886 
887  if (ops->co_obj_ops != obj->ce_ops)
888  return -NLE_OBJ_MISMATCH;
889 
890  for (i = 0; ops->co_msgtypes[i].mt_id >= 0; i++)
891  if (ops->co_msgtypes[i].mt_id == obj->ce_msgtype)
892  return cache_include(cache, obj, &ops->co_msgtypes[i],
893  NULL, change_cb, data);
894 
895  NL_DBG(3, "Object %p does not seem to belong to cache %p <%s>\n",
896  obj, cache, nl_cache_name(cache));
897 
898  return -NLE_MSGTYPE_NOSUPPORT;
899 }
900 
901 static int resync_cb(struct nl_object *c, struct nl_parser_param *p)
902 {
903  struct nl_cache_assoc *ca = p->pp_arg;
904 
905  if (ca->ca_change_v2)
906  return nl_cache_include_v2(ca->ca_cache, c, ca->ca_change_v2,
907  ca->ca_change_data);
908  else
909  return nl_cache_include(ca->ca_cache, c, ca->ca_change,
910  ca->ca_change_data);
911 }
912 
913 int nl_cache_resync(struct nl_sock *sk, struct nl_cache *cache,
914  change_func_t change_cb, void *data)
915 {
916  struct nl_object *obj, *next;
917  struct nl_af_group *grp;
918  struct nl_cache_assoc ca = {
919  .ca_cache = cache,
920  .ca_change = change_cb,
921  .ca_change_data = data,
922  };
923  struct nl_parser_param p = {
924  .pp_cb = resync_cb,
925  .pp_arg = &ca,
926  };
927  int err;
928 
929  if (sk->s_proto != cache->c_ops->co_protocol)
930  return -NLE_PROTO_MISMATCH;
931 
932  NL_DBG(1, "Resyncing cache %p <%s>...\n", cache, nl_cache_name(cache));
933 
934  /* Mark all objects so we can see if some of them are obsolete */
935  nl_cache_mark_all(cache);
936 
937  grp = cache->c_ops->co_groups;
938  do {
939  if (grp && grp->ag_group &&
940  (cache->c_flags & NL_CACHE_AF_ITER))
941  nl_cache_set_arg1(cache, grp->ag_family);
942 
943 restart:
944  err = nl_cache_request_full_dump(sk, cache);
945  if (err < 0)
946  goto errout;
947 
948  err = __cache_pickup(sk, cache, &p);
949  if (err == -NLE_DUMP_INTR)
950  goto restart;
951  else if (err < 0)
952  goto errout;
953 
954  if (grp)
955  grp++;
956  } while (grp && grp->ag_group &&
957  (cache->c_flags & NL_CACHE_AF_ITER));
958 
959  nl_list_for_each_entry_safe(obj, next, &cache->c_items, ce_list) {
960  if (nl_object_is_marked(obj)) {
961  nl_object_get(obj);
962  nl_cache_remove(obj);
963  if (change_cb)
964  change_cb(cache, obj, NL_ACT_DEL, data);
965  nl_object_put(obj);
966  }
967  }
968 
969  NL_DBG(1, "Finished resyncing %p <%s>\n", cache, nl_cache_name(cache));
970 
971  err = 0;
972 errout:
973  return err;
974 }
975 
976 /** @} */
977 
978 /**
979  * @name Parsing
980  * @{
981  */
982 
983 /** @cond SKIP */
984 int nl_cache_parse(struct nl_cache_ops *ops, struct sockaddr_nl *who,
985  struct nlmsghdr *nlh, struct nl_parser_param *params)
986 {
987  int i, err;
988 
989  if (!nlmsg_valid_hdr(nlh, ops->co_hdrsize))
990  return -NLE_MSG_TOOSHORT;
991 
992  for (i = 0; ops->co_msgtypes[i].mt_id >= 0; i++) {
993  if (ops->co_msgtypes[i].mt_id == nlh->nlmsg_type) {
994  err = ops->co_msg_parser(ops, who, nlh, params);
995  if (err != -NLE_OPNOTSUPP)
996  goto errout;
997  }
998  }
999 
1000 
1001  err = -NLE_MSGTYPE_NOSUPPORT;
1002 errout:
1003  return err;
1004 }
1005 /** @endcond */
1006 
1007 /**
1008  * Parse a netlink message and add it to the cache.
1009  * @arg cache cache to add element to
1010  * @arg msg netlink message
1011  *
1012  * Parses a netlink message by calling the cache specific message parser
1013  * and adds the new element to the cache. If an old object with same key
1014  * attributes is present in the cache, it is replaced with the new object.
1015  * If the old object type supports an update operation, an update is
1016  * attempted before a replace.
1017  *
1018  * @return 0 or a negative error code.
1019  */
1020 int nl_cache_parse_and_add(struct nl_cache *cache, struct nl_msg *msg)
1021 {
1022  struct nl_parser_param p = {
1023  .pp_cb = pickup_cb,
1024  .pp_arg = cache,
1025  };
1026 
1027  return nl_cache_parse(cache->c_ops, NULL, nlmsg_hdr(msg), &p);
1028 }
1029 
1030 /**
1031  * (Re)fill a cache with the contents in the kernel.
1032  * @arg sk Netlink socket.
1033  * @arg cache cache to update
1034  *
1035  * Clears the specified cache and fills it with the current state in
1036  * the kernel.
1037  *
1038  * @return 0 or a negative error code.
1039  */
1040 int nl_cache_refill(struct nl_sock *sk, struct nl_cache *cache)
1041 {
1042  struct nl_af_group *grp;
1043  int err;
1044 
1045  if (sk->s_proto != cache->c_ops->co_protocol)
1046  return -NLE_PROTO_MISMATCH;
1047 
1048  nl_cache_clear(cache);
1049  grp = cache->c_ops->co_groups;
1050  do {
1051  if (grp && grp->ag_group &&
1052  (cache->c_flags & NL_CACHE_AF_ITER))
1053  nl_cache_set_arg1(cache, grp->ag_family);
1054 
1055 restart:
1056  err = nl_cache_request_full_dump(sk, cache);
1057  if (err < 0)
1058  return err;
1059 
1060  NL_DBG(2, "Updating cache %p <%s> for family %u, request sent, waiting for reply\n",
1061  cache, nl_cache_name(cache), grp ? grp->ag_family : AF_UNSPEC);
1062 
1063  err = nl_cache_pickup(sk, cache);
1064  if (err == -NLE_DUMP_INTR) {
1065  NL_DBG(2, "Dump interrupted, restarting!\n");
1066  goto restart;
1067  } else if (err < 0)
1068  break;
1069 
1070  if (grp)
1071  grp++;
1072  } while (grp && grp->ag_group &&
1073  (cache->c_flags & NL_CACHE_AF_ITER));
1074 
1075  return err;
1076 }
1077 
1078 /** @} */
1079 
1080 /**
1081  * @name Utillities
1082  * @{
1083  */
1084 static struct nl_object *__cache_fast_lookup(struct nl_cache *cache,
1085  struct nl_object *needle)
1086 {
1087  struct nl_object *obj;
1088 
1089  obj = nl_hash_table_lookup(cache->hashtable, needle);
1090  if (obj) {
1091  nl_object_get(obj);
1092  return obj;
1093  }
1094 
1095  return NULL;
1096 }
1097 
1098 /**
1099  * Search object in cache
1100  * @arg cache Cache
1101  * @arg needle Object to look for.
1102  *
1103  * Searches the cache for an object which matches the object \p needle.
1104  * The function nl_object_identical() is used to determine if the
1105  * objects match. If a matching object is found, the reference counter
1106  * is incremented and the object is returned.
1107  *
1108  * Therefore, if an object is returned, the reference to the object
1109  * must be returned by calling nl_object_put() after usage.
1110  *
1111  * @return Reference to object or NULL if not found.
1112  */
1113 struct nl_object *nl_cache_search(struct nl_cache *cache,
1114  struct nl_object *needle)
1115 {
1116  struct nl_object *obj;
1117 
1118  if (cache->hashtable)
1119  return __cache_fast_lookup(cache, needle);
1120 
1121  nl_list_for_each_entry(obj, &cache->c_items, ce_list) {
1122  if (nl_object_identical(obj, needle)) {
1123  nl_object_get(obj);
1124  return obj;
1125  }
1126  }
1127 
1128  return NULL;
1129 }
1130 
1131 /**
1132  * Find object in cache
1133  * @arg cache Cache
1134  * @arg filter object acting as a filter
1135  *
1136  * Searches the cache for an object which matches the object filter.
1137  * If the filter attributes matches the object type id attributes,
1138  * and the cache supports hash lookups, a faster hashtable lookup
1139  * is used to return the object. Else, function nl_object_match_filter() is
1140  * used to determine if the objects match. If a matching object is
1141  * found, the reference counter is incremented and the object is returned.
1142  *
1143  * Therefore, if an object is returned, the reference to the object
1144  * must be returned by calling nl_object_put() after usage.
1145  *
1146  * @return Reference to object or NULL if not found.
1147  */
1148 struct nl_object *nl_cache_find(struct nl_cache *cache,
1149  struct nl_object *filter)
1150 {
1151  struct nl_object *obj;
1152 
1153  if (cache->c_ops == NULL)
1154  BUG();
1155 
1156  if ((nl_object_get_id_attrs(filter) == filter->ce_mask)
1157  && cache->hashtable)
1158  return __cache_fast_lookup(cache, filter);
1159 
1160  nl_list_for_each_entry(obj, &cache->c_items, ce_list) {
1161  if (nl_object_match_filter(obj, filter)) {
1162  nl_object_get(obj);
1163  return obj;
1164  }
1165  }
1166 
1167  return NULL;
1168 }
1169 
1170 /**
1171  * Mark all objects of a cache
1172  * @arg cache Cache
1173  *
1174  * Marks all objects of a cache by calling nl_object_mark() on each
1175  * object associated with the cache.
1176  */
1177 void nl_cache_mark_all(struct nl_cache *cache)
1178 {
1179  struct nl_object *obj;
1180 
1181  NL_DBG(2, "Marking all objects in cache %p <%s>\n",
1182  cache, nl_cache_name(cache));
1183 
1184  nl_list_for_each_entry(obj, &cache->c_items, ce_list)
1185  nl_object_mark(obj);
1186 }
1187 
1188 /** @} */
1189 
1190 /**
1191  * @name Dumping
1192  * @{
1193  */
1194 
1195 /**
1196  * Dump all elements of a cache.
1197  * @arg cache cache to dump
1198  * @arg params dumping parameters
1199  *
1200  * Dumps all elements of the \a cache to the file descriptor \a fd.
1201  */
1202 void nl_cache_dump(struct nl_cache *cache, struct nl_dump_params *params)
1203 {
1204  nl_cache_dump_filter(cache, params, NULL);
1205 }
1206 
1207 /**
1208  * Dump all elements of a cache (filtered).
1209  * @arg cache cache to dump
1210  * @arg params dumping parameters (optional)
1211  * @arg filter filter object
1212  *
1213  * Dumps all elements of the \a cache to the file descriptor \a fd
1214  * given they match the given filter \a filter.
1215  */
1216 void nl_cache_dump_filter(struct nl_cache *cache,
1217  struct nl_dump_params *params,
1218  struct nl_object *filter)
1219 {
1220  int type = params ? params->dp_type : NL_DUMP_DETAILS;
1221  struct nl_object_ops *ops;
1222  struct nl_object *obj;
1223 
1224  NL_DBG(2, "Dumping cache %p <%s> with filter %p\n",
1225  cache, nl_cache_name(cache), filter);
1226 
1227  if (type > NL_DUMP_MAX || type < 0)
1228  BUG();
1229 
1230  if (cache->c_ops == NULL)
1231  BUG();
1232 
1233  ops = cache->c_ops->co_obj_ops;
1234  if (!ops->oo_dump[type])
1235  return;
1236 
1237  if (params && params->dp_buf)
1238  memset(params->dp_buf, 0, params->dp_buflen);
1239 
1240  nl_list_for_each_entry(obj, &cache->c_items, ce_list) {
1241  if (filter && !nl_object_match_filter(obj, filter))
1242  continue;
1243 
1244  NL_DBG(4, "Dumping object %p...\n", obj);
1245  dump_from_ops(obj, params);
1246  }
1247 }
1248 
1249 /** @} */
1250 
1251 /**
1252  * @name Iterators
1253  * @{
1254  */
1255 
1256 /**
1257  * Call a callback on each element of the cache.
1258  * @arg cache cache to iterate on
1259  * @arg cb callback function
1260  * @arg arg argument passed to callback function
1261  *
1262  * Calls a callback function \a cb on each element of the \a cache.
1263  * The argument \a arg is passed on the callback function.
1264  */
1265 void nl_cache_foreach(struct nl_cache *cache,
1266  void (*cb)(struct nl_object *, void *), void *arg)
1267 {
1268  nl_cache_foreach_filter(cache, NULL, cb, arg);
1269 }
1270 
1271 /**
1272  * Call a callback on each element of the cache (filtered).
1273  * @arg cache cache to iterate on
1274  * @arg filter filter object
1275  * @arg cb callback function
1276  * @arg arg argument passed to callback function
1277  *
1278  * Calls a callback function \a cb on each element of the \a cache
1279  * that matches the \a filter. The argument \a arg is passed on
1280  * to the callback function.
1281  */
1282 void nl_cache_foreach_filter(struct nl_cache *cache, struct nl_object *filter,
1283  void (*cb)(struct nl_object *, void *), void *arg)
1284 {
1285  struct nl_object *obj, *tmp;
1286 
1287  if (cache->c_ops == NULL)
1288  BUG();
1289 
1290  nl_list_for_each_entry_safe(obj, tmp, &cache->c_items, ce_list) {
1291  if (filter) {
1292  int diff = nl_object_match_filter(obj, filter);
1293 
1294  NL_DBG(3, "%p<->%p object difference: %x\n",
1295  obj, filter, diff);
1296 
1297  if (!diff)
1298  continue;
1299  }
1300 
1301  /* Caller may hold obj for a long time */
1302  nl_object_get(obj);
1303 
1304  cb(obj, arg);
1305 
1306  nl_object_put(obj);
1307  }
1308 }
1309 
1310 /** @} */
1311 
1312 /** @} */
char * dp_buf
Alternatively the output may be redirected into a buffer.
Definition: types.h:88
void nl_cache_ops_put(struct nl_cache_ops *ops)
Decrement reference counter.
Definition: cache_mngt.c:65
struct nl_object * nl_cache_get_prev(struct nl_object *obj)
Return the previous element in the cache.
Definition: cache.c:158
int nl_cache_alloc_name(const char *kind, struct nl_cache **result)
Allocate new cache based on type name.
Definition: cache.c:264
struct nl_cache * nl_cache_subset(struct nl_cache *orig, struct nl_object *filter)
Allocate new cache containing a subset of an existing cache.
Definition: cache.c:297
Customized handler specified by the user.
Definition: handlers.h:83
enum nl_dump_type dp_type
Specifies the type of dump that is requested.
Definition: types.h:38
void nl_object_get(struct nl_object *obj)
Acquire a reference on a object.
Definition: object.c:204
void nl_cache_get(struct nl_cache *cache)
Increase reference counter of cache.
Definition: cache.c:391
void nl_hash_table_free(nl_hash_table_t *ht)
Free hashtable including all nodes.
Definition: hashtable.c:56
struct nl_object * nl_cache_find(struct nl_cache *cache, struct nl_object *filter)
Find object in cache.
Definition: cache.c:1148
void nl_cache_dump_filter(struct nl_cache *cache, struct nl_dump_params *params, struct nl_object *filter)
Dump all elements of a cache (filtered).
Definition: cache.c:1216
void nl_cache_foreach_filter(struct nl_cache *cache, struct nl_object *filter, void(*cb)(struct nl_object *, void *), void *arg)
Call a callback on each element of the cache (filtered).
Definition: cache.c:1282
struct nl_object * nl_cache_get_last(struct nl_cache *cache)
Return the last element in the cache.
Definition: cache.c:132
nl_hash_table_t * nl_hash_table_alloc(int size)
Allocate hashtable.
Definition: hashtable.c:29
Dump all attributes but no statistics.
Definition: types.h:23
struct nl_cb * nl_cb_clone(struct nl_cb *orig)
Clone an existing callback handle.
Definition: handlers.c:230
uint32_t nl_object_get_id_attrs(struct nl_object *obj)
Return object id attribute mask.
Definition: object.c:551
int nl_cb_set(struct nl_cb *cb, enum nl_cb_type type, enum nl_cb_kind kind, nl_recvmsg_msg_cb_t func, void *arg)
Set up a callback.
Definition: handlers.c:293
int nl_cache_pickup_checkdup(struct nl_sock *sk, struct nl_cache *cache)
Pickup a netlink dump response and put it into a cache.
Definition: cache.c:763
int nl_recvmsgs(struct nl_sock *sk, struct nl_cb *cb)
Receive a set of messages from a netlink socket.
Definition: nl.c:1077
struct nl_object * nl_hash_table_lookup(nl_hash_table_t *ht, struct nl_object *obj)
Lookup identical object in hashtable.
Definition: hashtable.c:86
uint64_t nl_object_diff64(struct nl_object *a, struct nl_object *b)
Compute bitmask representing difference in attribute values.
Definition: object.c:361
void nl_cache_free(struct nl_cache *cache)
Free a cache.
Definition: cache.c:408
void nl_cache_set_arg1(struct nl_cache *cache, int arg)
Set synchronization arg1 of cache.
Definition: cache.c:590
struct nl_object * nl_cache_search(struct nl_cache *cache, struct nl_object *needle)
Search object in cache.
Definition: cache.c:1113
void nl_cache_foreach(struct nl_cache *cache, void(*cb)(struct nl_object *, void *), void *arg)
Call a callback on each element of the cache.
Definition: cache.c:1265
Skip this message.
Definition: handlers.h:66
struct nlmsghdr * nlmsg_hdr(struct nl_msg *n)
Return actual netlink message.
Definition: msg.c:540
void nl_cache_remove(struct nl_object *obj)
Remove object from cache.
Definition: cache.c:551
int nl_hash_table_add(nl_hash_table_t *ht, struct nl_object *obj)
Add object to hashtable.
Definition: hashtable.c:117
int nl_cache_is_empty(struct nl_cache *cache)
Returns true if the cache is empty.
Definition: cache.c:101
void nl_cache_clear(struct nl_cache *cache)
Remove all objects of a cache.
Definition: cache.c:366
struct nl_cache_ops * nl_cache_ops_lookup_safe(const char *name)
Lookup cache operations by name.
Definition: cache_mngt.c:99
void nl_cache_set_arg2(struct nl_cache *cache, int arg)
Set synchronization arg2 of cache.
Definition: cache.c:603
void nl_cache_dump(struct nl_cache *cache, struct nl_dump_params *params)
Dump all elements of a cache.
Definition: cache.c:1202
Message is valid.
Definition: handlers.h:95
int nl_cache_parse_and_add(struct nl_cache *cache, struct nl_msg *msg)
Parse a netlink message and add it to the cache.
Definition: cache.c:1020
int nl_cache_nitems(struct nl_cache *cache)
Return the number of items in the cache.
Definition: cache.c:68
struct nl_object * nl_cache_get_next(struct nl_object *obj)
Return the next element in the cache.
Definition: cache.c:145
int nl_cache_refill(struct nl_sock *sk, struct nl_cache *cache)
(Re)fill a cache with the contents in the kernel.
Definition: cache.c:1040
void nl_object_put(struct nl_object *obj)
Release a reference from an object.
Definition: object.c:215
void nl_cache_mark_all(struct nl_cache *cache)
Mark all objects of a cache.
Definition: cache.c:1177
int nl_cache_move(struct nl_cache *cache, struct nl_object *obj)
Move object from one cache to another.
Definition: cache.c:523
int nl_object_identical(struct nl_object *a, struct nl_object *b)
Check if the identifiers of two objects are identical.
Definition: object.c:313
int nl_cache_nitems_filter(struct nl_cache *cache, struct nl_object *filter)
Return the number of items matching a filter in the cache.
Definition: cache.c:78
Dumping parameters.
Definition: types.h:33
void nl_cache_set_flags(struct nl_cache *cache, unsigned int flags)
Set cache flags.
Definition: cache.c:613
int nl_hash_table_del(nl_hash_table_t *ht, struct nl_object *obj)
Remove object from hashtable.
Definition: hashtable.c:161
struct nl_cache_ops * nl_cache_get_ops(struct nl_cache *cache)
Return the operations set of the cache.
Definition: cache.c:110
size_t dp_buflen
Length of the buffer dp_buf.
Definition: types.h:93
#define NL_CACHE_AF_ITER
Explicitely iterate over all address families when updating the cache.
Definition: cache.h:45
int nl_object_match_filter(struct nl_object *obj, struct nl_object *filter)
Match a filter against an object.
Definition: object.c:405
void nl_object_mark(struct nl_object *obj)
Add mark to object.
Definition: object.c:252
struct nl_cache * nl_cache_clone(struct nl_cache *cache)
Allocate new cache and copy the contents of an existing cache.
Definition: cache.c:337
int nl_object_update(struct nl_object *dst, struct nl_object *src)
Merge a cacheable object.
Definition: object.c:154
int nl_cache_add(struct nl_cache *cache, struct nl_object *obj)
Add object to cache.
Definition: cache.c:479
struct nl_object * nl_object_clone(struct nl_object *obj)
Allocate a new object and copy all data from an existing object.
Definition: object.c:110
int nl_object_is_marked(struct nl_object *obj)
Return true if object is marked.
Definition: object.c:271
struct nl_object * nl_cache_get_first(struct nl_cache *cache)
Return the first element in the cache.
Definition: cache.c:119
int nl_cache_alloc_and_fill(struct nl_cache_ops *ops, struct nl_sock *sock, struct nl_cache **result)
Allocate new cache and fill it.
Definition: cache.c:233
struct nl_cache * nl_cache_alloc(struct nl_cache_ops *ops)
Allocate new cache.
Definition: cache.c:183
int nl_cache_pickup(struct nl_sock *sk, struct nl_cache *cache)
Pickup a netlink dump response and put it into a cache.
Definition: cache.c:781