libnl  3.2.21
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_list_for_each_entry(obj, &orig->c_items, ce_list) {
311  if (!nl_object_match_filter(obj, filter))
312  continue;
313 
314  nl_cache_add(cache, obj);
315  }
316 
317  return cache;
318 }
319 
320 /**
321  * Allocate new cache and copy the contents of an existing cache
322  * @arg cache Original cache to base new cache on
323  *
324  * Allocates a new cache matching the type of the cache specified by
325  * \p cache. Iterates over the \p cache cache and copies all objects
326  * to the new cache.
327  *
328  * The copied objects are clones but do not contain a reference to each
329  * other. Later modifications to objects in the original cache will
330  * not affect objects in the new cache.
331  *
332  * @return A newly allocated cache or NULL.
333  */
334 struct nl_cache *nl_cache_clone(struct nl_cache *cache)
335 {
336  struct nl_cache_ops *ops = nl_cache_get_ops(cache);
337  struct nl_cache *clone;
338  struct nl_object *obj;
339 
340  clone = nl_cache_alloc(ops);
341  if (!clone)
342  return NULL;
343 
344  nl_list_for_each_entry(obj, &cache->c_items, ce_list)
345  nl_cache_add(clone, obj);
346 
347  return clone;
348 }
349 
350 /**
351  * Remove all objects of a cache.
352  * @arg cache Cache to clear
353  *
354  * The objects are unliked/removed from the cache by calling
355  * nl_cache_remove() on each object in the cache. If any of the objects
356  * to not contain any further references to them, those objects will
357  * be freed.
358  *
359  * Unlike with nl_cache_free(), the cache is not freed just emptied.
360  */
361 void nl_cache_clear(struct nl_cache *cache)
362 {
363  struct nl_object *obj, *tmp;
364 
365  NL_DBG(1, "Clearing cache %p <%s>...\n", cache, nl_cache_name(cache));
366 
367  nl_list_for_each_entry_safe(obj, tmp, &cache->c_items, ce_list)
368  nl_cache_remove(obj);
369 }
370 
371 static void __nl_cache_free(struct nl_cache *cache)
372 {
373  nl_cache_clear(cache);
374 
375  if (cache->hashtable)
376  nl_hash_table_free(cache->hashtable);
377 
378  NL_DBG(1, "Freeing cache %p <%s>...\n", cache, nl_cache_name(cache));
379  free(cache);
380 }
381 
382 /**
383  * Increase reference counter of cache
384  * @arg cache Cache
385  */
386 void nl_cache_get(struct nl_cache *cache)
387 {
388  cache->c_refcnt++;
389 }
390 
391 /**
392  * Free a cache.
393  * @arg cache Cache to free.
394  *
395  * Calls nl_cache_clear() to remove all objects associated with the
396  * cache and frees the cache afterwards.
397  *
398  * @see nl_cache_clear()
399  */
400 void nl_cache_free(struct nl_cache *cache)
401 {
402  if (!cache)
403  return;
404 
405  cache->c_refcnt--;
406  NL_DBG(4, "Returned cache reference %p, %d remaining\n",
407  cache, cache->c_refcnt);
408 
409  if (cache->c_refcnt <= 0)
410  __nl_cache_free(cache);
411 }
412 
413 void nl_cache_put(struct nl_cache *cache)
414 {
415  return nl_cache_free(cache);
416 }
417 
418 /** @} */
419 
420 /**
421  * @name Cache Modifications
422  * @{
423  */
424 
425 static int __cache_add(struct nl_cache *cache, struct nl_object *obj)
426 {
427  int ret;
428 
429  obj->ce_cache = cache;
430 
431  if (cache->hashtable) {
432  ret = nl_hash_table_add(cache->hashtable, obj);
433  if (ret < 0) {
434  obj->ce_cache = NULL;
435  return ret;
436  }
437  }
438 
439  nl_list_add_tail(&obj->ce_list, &cache->c_items);
440  cache->c_nitems++;
441 
442  NL_DBG(1, "Added %p to cache %p <%s>.\n",
443  obj, cache, nl_cache_name(cache));
444 
445  return 0;
446 }
447 
448 /**
449  * Add object to cache.
450  * @arg cache Cache
451  * @arg obj Object to be added to the cache
452  *
453  * Adds the object \p obj to the specified \p cache. In case the object
454  * is already associated with another cache, the object is cloned before
455  * adding it to the cache. In this case, the sole reference to the object
456  * will be the one of the cache. Therefore clearing/freeing the cache
457  * will result in the object being freed again.
458  *
459  * If the object has not been associated with a cache yet, the reference
460  * counter of the object is incremented to account for the additional
461  * reference.
462  *
463  * The type of the object and cache must match, otherwise an error is
464  * returned (-NLE_OBJ_MISMATCH).
465  *
466  * @see nl_cache_move()
467  *
468  * @return 0 or a negative error code.
469  */
470 int nl_cache_add(struct nl_cache *cache, struct nl_object *obj)
471 {
472  struct nl_object *new;
473  int ret = 0;
474 
475  if (cache->c_ops->co_obj_ops != obj->ce_ops)
476  return -NLE_OBJ_MISMATCH;
477 
478  if (!nl_list_empty(&obj->ce_list)) {
479  new = nl_object_clone(obj);
480  if (!new)
481  return -NLE_NOMEM;
482  } else {
483  nl_object_get(obj);
484  new = obj;
485  }
486 
487  ret = __cache_add(cache, new);
488  if (ret < 0)
489  nl_object_put(new);
490 
491  return ret;
492 }
493 
494 /**
495  * Move object from one cache to another
496  * @arg cache Cache to move object to.
497  * @arg obj Object subject to be moved
498  *
499  * Removes the the specified object \p obj from its associated cache
500  * and moves it to another cache.
501  *
502  * If the object is not associated with a cache, the function behaves
503  * just like nl_cache_add().
504  *
505  * The type of the object and cache must match, otherwise an error is
506  * returned (-NLE_OBJ_MISMATCH).
507  *
508  * @see nl_cache_add()
509  *
510  * @return 0 on success or a negative error code.
511  */
512 int nl_cache_move(struct nl_cache *cache, struct nl_object *obj)
513 {
514  if (cache->c_ops->co_obj_ops != obj->ce_ops)
515  return -NLE_OBJ_MISMATCH;
516 
517  NL_DBG(3, "Moving object %p to cache %p\n", obj, cache);
518 
519  /* Acquire reference, if already in a cache this will be
520  * reverted during removal */
521  nl_object_get(obj);
522 
523  if (!nl_list_empty(&obj->ce_list))
524  nl_cache_remove(obj);
525 
526  return __cache_add(cache, obj);
527 }
528 
529 /**
530  * Remove object from cache.
531  * @arg obj Object to remove from cache
532  *
533  * Removes the object \c obj from the cache it is associated with. The
534  * reference counter of the object will be decremented. If the reference
535  * to the object was the only one remaining, the object will be freed.
536  *
537  * If no cache is associated with the object, this function is a NOP.
538  */
539 void nl_cache_remove(struct nl_object *obj)
540 {
541  int ret;
542  struct nl_cache *cache = obj->ce_cache;
543 
544  if (cache == NULL)
545  return;
546 
547  if (cache->hashtable) {
548  ret = nl_hash_table_del(cache->hashtable, obj);
549  if (ret < 0)
550  NL_DBG(3, "Failed to delete %p from cache %p <%s>.\n",
551  obj, cache, nl_cache_name(cache));
552  }
553 
554  nl_list_del(&obj->ce_list);
555  obj->ce_cache = NULL;
556  nl_object_put(obj);
557  cache->c_nitems--;
558 
559  NL_DBG(1, "Deleted %p from cache %p <%s>.\n",
560  obj, cache, nl_cache_name(cache));
561 }
562 
563 /** @} */
564 
565 /**
566  * @name Synchronization
567  * @{
568  */
569 
570 /**
571  * Set synchronization arg1 of cache
572  * @arg cache Cache
573  * @arg arg argument
574  *
575  * Synchronization arguments are used to specify filters when
576  * requesting dumps from the kernel.
577  */
578 void nl_cache_set_arg1(struct nl_cache *cache, int arg)
579 {
580  cache->c_iarg1 = arg;
581 }
582 
583 /**
584  * Set synchronization arg2 of cache
585  * @arg cache Cache
586  * @arg arg argument
587  *
588  * Synchronization arguments are used to specify filters when
589  * requesting dumps from the kernel.
590  */
591 void nl_cache_set_arg2(struct nl_cache *cache, int arg)
592 {
593  cache->c_iarg2 = arg;
594 }
595 
596 /**
597  * Set cache flags
598  * @arg cache Cache
599  * @arg flags Flags
600  */
601 void nl_cache_set_flags(struct nl_cache *cache, unsigned int flags)
602 {
603  cache->c_flags |= flags;
604 }
605 
606 /**
607  * Invoke the request-update operation
608  * @arg sk Netlink socket.
609  * @arg cache Cache
610  *
611  * This function causes the \e request-update function of the cache
612  * operations to be invoked. This usually causes a dump request to
613  * be sent over the netlink socket which triggers the kernel to dump
614  * all objects of a specific type to be dumped onto the netlink
615  * socket for pickup.
616  *
617  * The behaviour of this function depends on the implemenation of
618  * the \e request_update function of each individual type of cache.
619  *
620  * This function will not have any effects on the cache (unless the
621  * request_update implementation of the cache operations does so).
622  *
623  * Use nl_cache_pickup() to pick-up (read) the objects from the socket
624  * and fill them into the cache.
625  *
626  * @see nl_cache_pickup(), nl_cache_resync()
627  *
628  * @return 0 on success or a negative error code.
629  */
630 static int nl_cache_request_full_dump(struct nl_sock *sk,
631  struct nl_cache *cache)
632 {
633  NL_DBG(2, "Requesting dump from kernel for cache %p <%s>...\n",
634  cache, nl_cache_name(cache));
635 
636  if (cache->c_ops->co_request_update == NULL)
637  return -NLE_OPNOTSUPP;
638 
639  return cache->c_ops->co_request_update(cache, sk);
640 }
641 
642 /** @cond SKIP */
643 struct update_xdata {
644  struct nl_cache_ops *ops;
645  struct nl_parser_param *params;
646 };
647 
648 static int update_msg_parser(struct nl_msg *msg, void *arg)
649 {
650  struct update_xdata *x = arg;
651  int ret = 0;
652 
653  ret = nl_cache_parse(x->ops, &msg->nm_src, msg->nm_nlh, x->params);
654  if (ret == -NLE_EXIST)
655  return NL_SKIP;
656  else
657  return ret;
658 }
659 /** @endcond */
660 
661 /**
662  * Pick-up a netlink request-update with your own parser
663  * @arg sk Netlink socket
664  * @arg cache Cache
665  * @arg param Parser parameters
666  */
667 static int __cache_pickup(struct nl_sock *sk, struct nl_cache *cache,
668  struct nl_parser_param *param)
669 {
670  int err;
671  struct nl_cb *cb;
672  struct update_xdata x = {
673  .ops = cache->c_ops,
674  .params = param,
675  };
676 
677  NL_DBG(1, "Picking up answer for cache %p <%s>...\n",
678  cache, nl_cache_name(cache));
679 
680  cb = nl_cb_clone(sk->s_cb);
681  if (cb == NULL)
682  return -NLE_NOMEM;
683 
684  nl_cb_set(cb, NL_CB_VALID, NL_CB_CUSTOM, update_msg_parser, &x);
685 
686  err = nl_recvmsgs(sk, cb);
687  if (err < 0)
688  NL_DBG(2, "While picking up for %p <%s>, recvmsgs() returned " \
689  "%d: %s", cache, nl_cache_name(cache),
690  err, nl_geterror(err));
691 
692  nl_cb_put(cb);
693 
694  return err;
695 }
696 
697 static int pickup_cb(struct nl_object *c, struct nl_parser_param *p)
698 {
699  struct nl_cache *cache = (struct nl_cache *)p->pp_arg;
700  struct nl_object *old;
701 
702  old = nl_cache_search(cache, c);
703  if (old) {
704  if (nl_object_update(old, c) == 0) {
705  nl_object_put(old);
706  return 0;
707  }
708 
709  nl_cache_remove(old);
710  nl_object_put(old);
711  }
712 
713  return nl_cache_add(cache, c);
714 }
715 
716 /**
717  * Pickup a netlink dump response and put it into a cache.
718  * @arg sk Netlink socket.
719  * @arg cache Cache to put items into.
720  *
721  * Waits for netlink messages to arrive, parses them and puts them into
722  * the specified cache. If an old object with same key attributes is
723  * present in the cache, it is replaced with the new object.
724  * If the old object type supports an update operation, an update is
725  * attempted before a replace.
726  *
727  * @return 0 on success or a negative error code.
728  */
729 int nl_cache_pickup(struct nl_sock *sk, struct nl_cache *cache)
730 {
731  struct nl_parser_param p = {
732  .pp_cb = pickup_cb,
733  .pp_arg = cache,
734  };
735 
736  return __cache_pickup(sk, cache, &p);
737 }
738 
739 static int cache_include(struct nl_cache *cache, struct nl_object *obj,
740  struct nl_msgtype *type, change_func_t cb, void *data)
741 {
742  struct nl_object *old;
743 
744  switch (type->mt_act) {
745  case NL_ACT_NEW:
746  case NL_ACT_DEL:
747  old = nl_cache_search(cache, obj);
748  if (old) {
749  /*
750  * Some objects types might support merging the new
751  * object with the old existing cache object.
752  * Handle them first.
753  */
754  if (nl_object_update(old, obj) == 0) {
755  if (cb)
756  cb(cache, old, NL_ACT_CHANGE, data);
757  nl_object_put(old);
758  return 0;
759  }
760 
761  nl_cache_remove(old);
762  if (type->mt_act == NL_ACT_DEL) {
763  if (cb)
764  cb(cache, old, NL_ACT_DEL, data);
765  nl_object_put(old);
766  }
767  }
768 
769  if (type->mt_act == NL_ACT_NEW) {
770  nl_cache_move(cache, obj);
771  if (old == NULL && cb)
772  cb(cache, obj, NL_ACT_NEW, data);
773  else if (old) {
774  if (nl_object_diff(old, obj) && cb)
775  cb(cache, obj, NL_ACT_CHANGE, data);
776 
777  nl_object_put(old);
778  }
779  }
780  break;
781  default:
782  NL_DBG(2, "Unknown action associated to object %p\n", obj);
783  return 0;
784  }
785 
786  return 0;
787 }
788 
789 int nl_cache_include(struct nl_cache *cache, struct nl_object *obj,
790  change_func_t change_cb, void *data)
791 {
792  struct nl_cache_ops *ops = cache->c_ops;
793  int i;
794 
795  if (ops->co_obj_ops != obj->ce_ops)
796  return -NLE_OBJ_MISMATCH;
797 
798  for (i = 0; ops->co_msgtypes[i].mt_id >= 0; i++)
799  if (ops->co_msgtypes[i].mt_id == obj->ce_msgtype)
800  return cache_include(cache, obj, &ops->co_msgtypes[i],
801  change_cb, data);
802 
803  return -NLE_MSGTYPE_NOSUPPORT;
804 }
805 
806 static int resync_cb(struct nl_object *c, struct nl_parser_param *p)
807 {
808  struct nl_cache_assoc *ca = p->pp_arg;
809 
810  return nl_cache_include(ca->ca_cache, c, ca->ca_change, ca->ca_change_data);
811 }
812 
813 int nl_cache_resync(struct nl_sock *sk, struct nl_cache *cache,
814  change_func_t change_cb, void *data)
815 {
816  struct nl_object *obj, *next;
817  struct nl_af_group *grp;
818  struct nl_cache_assoc ca = {
819  .ca_cache = cache,
820  .ca_change = change_cb,
821  .ca_change_data = data,
822  };
823  struct nl_parser_param p = {
824  .pp_cb = resync_cb,
825  .pp_arg = &ca,
826  };
827  int err;
828 
829  NL_DBG(1, "Resyncing cache %p <%s>...\n", cache, nl_cache_name(cache));
830 
831  /* Mark all objects so we can see if some of them are obsolete */
832  nl_cache_mark_all(cache);
833 
834  grp = cache->c_ops->co_groups;
835  do {
836  if (grp && grp->ag_group &&
837  (cache->c_flags & NL_CACHE_AF_ITER))
838  nl_cache_set_arg1(cache, grp->ag_family);
839 
840 restart:
841  err = nl_cache_request_full_dump(sk, cache);
842  if (err < 0)
843  goto errout;
844 
845  err = __cache_pickup(sk, cache, &p);
846  if (err == -NLE_DUMP_INTR)
847  goto restart;
848  else if (err < 0)
849  goto errout;
850 
851  if (grp)
852  grp++;
853  } while (grp && grp->ag_group &&
854  (cache->c_flags & NL_CACHE_AF_ITER));
855 
856  nl_list_for_each_entry_safe(obj, next, &cache->c_items, ce_list) {
857  if (nl_object_is_marked(obj)) {
858  nl_object_get(obj);
859  nl_cache_remove(obj);
860  if (change_cb)
861  change_cb(cache, obj, NL_ACT_DEL, data);
862  nl_object_put(obj);
863  }
864  }
865 
866  NL_DBG(1, "Finished resyncing %p <%s>\n", cache, nl_cache_name(cache));
867 
868  err = 0;
869 errout:
870  return err;
871 }
872 
873 /** @} */
874 
875 /**
876  * @name Parsing
877  * @{
878  */
879 
880 /** @cond SKIP */
881 int nl_cache_parse(struct nl_cache_ops *ops, struct sockaddr_nl *who,
882  struct nlmsghdr *nlh, struct nl_parser_param *params)
883 {
884  int i, err;
885 
886  if (!nlmsg_valid_hdr(nlh, ops->co_hdrsize))
887  return -NLE_MSG_TOOSHORT;
888 
889  for (i = 0; ops->co_msgtypes[i].mt_id >= 0; i++) {
890  if (ops->co_msgtypes[i].mt_id == nlh->nlmsg_type) {
891  err = ops->co_msg_parser(ops, who, nlh, params);
892  if (err != -NLE_OPNOTSUPP)
893  goto errout;
894  }
895  }
896 
897 
898  err = -NLE_MSGTYPE_NOSUPPORT;
899 errout:
900  return err;
901 }
902 /** @endcond */
903 
904 /**
905  * Parse a netlink message and add it to the cache.
906  * @arg cache cache to add element to
907  * @arg msg netlink message
908  *
909  * Parses a netlink message by calling the cache specific message parser
910  * and adds the new element to the cache. If an old object with same key
911  * attributes is present in the cache, it is replaced with the new object.
912  * If the old object type supports an update operation, an update is
913  * attempted before a replace.
914  *
915  * @return 0 or a negative error code.
916  */
917 int nl_cache_parse_and_add(struct nl_cache *cache, struct nl_msg *msg)
918 {
919  struct nl_parser_param p = {
920  .pp_cb = pickup_cb,
921  .pp_arg = cache,
922  };
923 
924  return nl_cache_parse(cache->c_ops, NULL, nlmsg_hdr(msg), &p);
925 }
926 
927 /**
928  * (Re)fill a cache with the contents in the kernel.
929  * @arg sk Netlink socket.
930  * @arg cache cache to update
931  *
932  * Clears the specified cache and fills it with the current state in
933  * the kernel.
934  *
935  * @return 0 or a negative error code.
936  */
937 int nl_cache_refill(struct nl_sock *sk, struct nl_cache *cache)
938 {
939  struct nl_af_group *grp;
940  int err;
941 
942  nl_cache_clear(cache);
943  grp = cache->c_ops->co_groups;
944  do {
945  if (grp && grp->ag_group &&
946  (cache->c_flags & NL_CACHE_AF_ITER))
947  nl_cache_set_arg1(cache, grp->ag_family);
948 
949 restart:
950  err = nl_cache_request_full_dump(sk, cache);
951  if (err < 0)
952  return err;
953 
954  err = nl_cache_pickup(sk, cache);
955  if (err == -NLE_DUMP_INTR) {
956  NL_DBG(1, "dump interrupted, restarting!\n");
957  goto restart;
958  } else if (err < 0)
959  break;
960 
961  if (grp)
962  grp++;
963  } while (grp && grp->ag_group &&
964  (cache->c_flags & NL_CACHE_AF_ITER));
965 
966  NL_DBG(2, "Upading cache %p <%s>, request sent, waiting for dump...\n",
967  cache, nl_cache_name(cache));
968 
969  return err;
970 }
971 
972 /** @} */
973 
974 /**
975  * @name Utillities
976  * @{
977  */
978 static struct nl_object *__cache_fast_lookup(struct nl_cache *cache,
979  struct nl_object *needle)
980 {
981  struct nl_object *obj;
982 
983  obj = nl_hash_table_lookup(cache->hashtable, needle);
984  if (obj) {
985  nl_object_get(obj);
986  return obj;
987  }
988 
989  return NULL;
990 }
991 
992 /**
993  * Search object in cache
994  * @arg cache Cache
995  * @arg needle Object to look for.
996  *
997  * Searches the cache for an object which matches the object \p needle.
998  * The function nl_object_identical() is used to determine if the
999  * objects match. If a matching object is found, the reference counter
1000  * is incremented and the object is returned.
1001  *
1002  * Therefore, if an object is returned, the reference to the object
1003  * must be returned by calling nl_object_put() after usage.
1004  *
1005  * @return Reference to object or NULL if not found.
1006  */
1007 struct nl_object *nl_cache_search(struct nl_cache *cache,
1008  struct nl_object *needle)
1009 {
1010  struct nl_object *obj;
1011 
1012  if (cache->hashtable)
1013  return __cache_fast_lookup(cache, needle);
1014 
1015  nl_list_for_each_entry(obj, &cache->c_items, ce_list) {
1016  if (nl_object_identical(obj, needle)) {
1017  nl_object_get(obj);
1018  return obj;
1019  }
1020  }
1021 
1022  return NULL;
1023 }
1024 
1025 /**
1026  * Find object in cache
1027  * @arg cache Cache
1028  * @arg filter object acting as a filter
1029  *
1030  * Searches the cache for an object which matches the object filter.
1031  * If the filter attributes matches the object type id attributes,
1032  * and the cache supports hash lookups, a faster hashtable lookup
1033  * is used to return the object. Else, function nl_object_match_filter() is
1034  * used to determine if the objects match. If a matching object is
1035  * found, the reference counter is incremented and the object is returned.
1036  *
1037  * Therefore, if an object is returned, the reference to the object
1038  * must be returned by calling nl_object_put() after usage.
1039  *
1040  * @return Reference to object or NULL if not found.
1041  */
1042 struct nl_object *nl_cache_find(struct nl_cache *cache,
1043  struct nl_object *filter)
1044 {
1045  struct nl_object *obj;
1046 
1047  if (cache->c_ops == NULL)
1048  BUG();
1049 
1050  if ((nl_object_get_id_attrs(filter) == filter->ce_mask)
1051  && cache->hashtable)
1052  return __cache_fast_lookup(cache, filter);
1053 
1054  nl_list_for_each_entry(obj, &cache->c_items, ce_list) {
1055  if (nl_object_match_filter(obj, filter)) {
1056  nl_object_get(obj);
1057  return obj;
1058  }
1059  }
1060 
1061  return NULL;
1062 }
1063 
1064 /**
1065  * Mark all objects of a cache
1066  * @arg cache Cache
1067  *
1068  * Marks all objects of a cache by calling nl_object_mark() on each
1069  * object associated with the cache.
1070  */
1071 void nl_cache_mark_all(struct nl_cache *cache)
1072 {
1073  struct nl_object *obj;
1074 
1075  NL_DBG(2, "Marking all objects in cache %p <%s>...\n",
1076  cache, nl_cache_name(cache));
1077 
1078  nl_list_for_each_entry(obj, &cache->c_items, ce_list)
1079  nl_object_mark(obj);
1080 }
1081 
1082 /** @} */
1083 
1084 /**
1085  * @name Dumping
1086  * @{
1087  */
1088 
1089 /**
1090  * Dump all elements of a cache.
1091  * @arg cache cache to dump
1092  * @arg params dumping parameters
1093  *
1094  * Dumps all elements of the \a cache to the file descriptor \a fd.
1095  */
1096 void nl_cache_dump(struct nl_cache *cache, struct nl_dump_params *params)
1097 {
1098  nl_cache_dump_filter(cache, params, NULL);
1099 }
1100 
1101 /**
1102  * Dump all elements of a cache (filtered).
1103  * @arg cache cache to dump
1104  * @arg params dumping parameters (optional)
1105  * @arg filter filter object
1106  *
1107  * Dumps all elements of the \a cache to the file descriptor \a fd
1108  * given they match the given filter \a filter.
1109  */
1110 void nl_cache_dump_filter(struct nl_cache *cache,
1111  struct nl_dump_params *params,
1112  struct nl_object *filter)
1113 {
1114  int type = params ? params->dp_type : NL_DUMP_DETAILS;
1115  struct nl_object_ops *ops;
1116  struct nl_object *obj;
1117 
1118  NL_DBG(2, "Dumping cache %p <%s> filter %p\n",
1119  cache, nl_cache_name(cache), filter);
1120 
1121  if (type > NL_DUMP_MAX || type < 0)
1122  BUG();
1123 
1124  if (cache->c_ops == NULL)
1125  BUG();
1126 
1127  ops = cache->c_ops->co_obj_ops;
1128  if (!ops->oo_dump[type])
1129  return;
1130 
1131  if (params->dp_buf)
1132  memset(params->dp_buf, 0, params->dp_buflen);
1133 
1134  nl_list_for_each_entry(obj, &cache->c_items, ce_list) {
1135  if (filter && !nl_object_match_filter(obj, filter))
1136  continue;
1137 
1138  NL_DBG(4, "Dumping object %p...\n", obj);
1139  dump_from_ops(obj, params);
1140  }
1141 }
1142 
1143 /** @} */
1144 
1145 /**
1146  * @name Iterators
1147  * @{
1148  */
1149 
1150 /**
1151  * Call a callback on each element of the cache.
1152  * @arg cache cache to iterate on
1153  * @arg cb callback function
1154  * @arg arg argument passed to callback function
1155  *
1156  * Calls a callback function \a cb on each element of the \a cache.
1157  * The argument \a arg is passed on the callback function.
1158  */
1159 void nl_cache_foreach(struct nl_cache *cache,
1160  void (*cb)(struct nl_object *, void *), void *arg)
1161 {
1162  nl_cache_foreach_filter(cache, NULL, cb, arg);
1163 }
1164 
1165 /**
1166  * Call a callback on each element of the cache (filtered).
1167  * @arg cache cache to iterate on
1168  * @arg filter filter object
1169  * @arg cb callback function
1170  * @arg arg argument passed to callback function
1171  *
1172  * Calls a callback function \a cb on each element of the \a cache
1173  * that matches the \a filter. The argument \a arg is passed on
1174  * to the callback function.
1175  */
1176 void nl_cache_foreach_filter(struct nl_cache *cache, struct nl_object *filter,
1177  void (*cb)(struct nl_object *, void *), void *arg)
1178 {
1179  struct nl_object *obj, *tmp;
1180 
1181  if (cache->c_ops == NULL)
1182  BUG();
1183 
1184  nl_list_for_each_entry_safe(obj, tmp, &cache->c_items, ce_list) {
1185  if (filter) {
1186  int diff = nl_object_match_filter(obj, filter);
1187 
1188  NL_DBG(3, "%p<->%p object difference: %x\n",
1189  obj, filter, diff);
1190 
1191  if (!diff)
1192  continue;
1193  }
1194 
1195  /* Caller may hold obj for a long time */
1196  nl_object_get(obj);
1197 
1198  cb(obj, arg);
1199 
1200  nl_object_put(obj);
1201  }
1202 }
1203 
1204 /** @} */
1205 
1206 /** @} */