diff options
author | Thomas Graf <tgraf@suug.ch> | 2011-03-21 23:40:26 (GMT) |
---|---|---|
committer | Thomas Graf <tgraf@suug.ch> | 2011-03-21 23:40:26 (GMT) |
commit | c1073d6172223be9837141da149c8876ce46884b (patch) | |
tree | b1bfcc1f25a97337fd60aa0ef7052132b756be86 /lib | |
parent | 55f803c64df6f742a00dd45a24a3d51f87f6365b (diff) | |
download | libnl-c1073d6172223be9837141da149c8876ce46884b.zip libnl-c1073d6172223be9837141da149c8876ce46884b.tar.gz libnl-c1073d6172223be9837141da149c8876ce46884b.tar.bz2 |
Documentation updates
Mostly killing doxygen warnings, some doc updates to caching
Diffstat (limited to 'lib')
-rw-r--r-- | lib/cache.c | 211 | ||||
-rw-r--r-- | lib/cache_mngr.c | 4 | ||||
-rw-r--r-- | lib/fib_lookup/lookup.c | 3 | ||||
-rw-r--r-- | lib/msg.c | 2 | ||||
-rw-r--r-- | lib/object.c | 6 | ||||
-rw-r--r-- | lib/route/class.c | 3 | ||||
-rw-r--r-- | lib/route/link.c | 3 | ||||
-rw-r--r-- | lib/route/neigh.c | 2 | ||||
-rw-r--r-- | lib/route/pktloc.c | 3 | ||||
-rw-r--r-- | lib/route/route.c | 3 | ||||
-rw-r--r-- | lib/route/rule.c | 8 |
11 files changed, 174 insertions, 74 deletions
diff --git a/lib/cache.c b/lib/cache.c index 601dadc..ece354c 100644 --- a/lib/cache.c +++ b/lib/cache.c @@ -160,15 +160,18 @@ struct nl_object *nl_cache_get_prev(struct nl_object *obj) /** @} */ /** - * @name Cache Creation/Deletion + * @name Cache Allocation/Deletion * @{ */ /** - * Allocate an empty cache - * @arg ops cache operations to base the cache on - * - * @return A newly allocated and initialized cache. + * Allocate new cache + * @arg ops Cache operations + * + * Allocate and initialize a new cache based on the cache operations + * provided. + * + * @return Allocated cache or NULL if allocation failed. */ struct nl_cache *nl_cache_alloc(struct nl_cache_ops *ops) { @@ -186,6 +189,22 @@ struct nl_cache *nl_cache_alloc(struct nl_cache_ops *ops) return cache; } +/** + * Allocate new cache and fill it + * @arg ops Cache operations + * @arg sock Netlink socket + * @arg result Result pointer + * + * Allocate new cache and fill it. Equivalent to calling: + * @code + * cache = nl_cache_alloc(ops); + * nl_cache_refill(sock, cache); + * @endcode + * + * @see nl_cache_alloc + * + * @return 0 on success or a negative error code. + */ int nl_cache_alloc_and_fill(struct nl_cache_ops *ops, struct nl_sock *sock, struct nl_cache **result) { @@ -205,9 +224,17 @@ int nl_cache_alloc_and_fill(struct nl_cache_ops *ops, struct nl_sock *sock, } /** - * Allocate an empty cache based on type name + * Allocate new cache based on type name * @arg kind Name of cache type - * @return A newly allocated and initialized cache. + * @arg result Result pointer + * + * Lookup cache ops via nl_cache_ops_lookup() and allocate the cache + * by calling nl_cache_alloc(). Stores the allocated cache in the + * result pointer provided. + * + * @see nl_cache_alloc + * + * @return 0 on success or a negative error code. */ int nl_cache_alloc_name(const char *kind, struct nl_cache **result) { @@ -226,9 +253,18 @@ int nl_cache_alloc_name(const char *kind, struct nl_cache **result) } /** - * Allocate a new cache containing a subset of a cache - * @arg orig Original cache to be based on - * @arg filter Filter defining the subset to be filled into new cache + * Allocate new cache containing a subset of an existing cache + * @arg orig Original cache to base new cache on + * @arg filter Filter defining the subset to be filled into the new cache + * + * Allocates a new cache matching the type of the cache specified by + * \p orig. Iterates over the \p orig cache applying the specified + * \p filter and copies all objects that match to the new cache. + * + * The copied objects are clones but do not contain a reference to each + * other. Later modifications to objects in the original cache will + * not affect objects in the new cache. + * * @return A newly allocated cache or NULL. */ struct nl_cache *nl_cache_subset(struct nl_cache *orig, @@ -258,10 +294,15 @@ struct nl_cache *nl_cache_subset(struct nl_cache *orig, } /** - * Clear a cache. - * @arg cache cache to clear + * Remove all objects of a cache. + * @arg cache Cache to clear * - * Removes all elements of a cache. + * The objects are unliked/removed from the cache by calling + * nl_cache_remove() on each object in the cache. If any of the objects + * to not contain any further references to them, those objects will + * be freed. + * + * Unlike with nl_cache_free(), the cache is not freed just emptied. */ void nl_cache_clear(struct nl_cache *cache) { @@ -277,9 +318,10 @@ void nl_cache_clear(struct nl_cache *cache) * Free a cache. * @arg cache Cache to free. * - * Removes all elements of a cache and frees all memory. + * Calls nl_cache_clear() to remove all objects associated with the + * cache and frees the cache afterwards. * - * @note Use this function if you are working with allocated caches. + * @see nl_cache_clear() */ void nl_cache_free(struct nl_cache *cache) { @@ -312,12 +354,24 @@ static int __cache_add(struct nl_cache *cache, struct nl_object *obj) } /** - * Add object to a cache. - * @arg cache Cache to add object to + * Add object to cache. + * @arg cache Cache * @arg obj Object to be added to the cache * - * Adds the given object to the specified cache. The object is cloned - * if it has been added to another cache already. + * Adds the object \p obj to the specified \p cache. In case the object + * is already associated with another cache, the object is cloned before + * adding it to the cache. In this case, the sole reference to the object + * will be the one of the cache. Therefore clearing/freeing the cache + * will result in the object being freed again. + * + * If the object has not been associated with a cache yet, the reference + * counter of the object is incremented to account for the additional + * reference. + * + * The type of the object and cache must match, otherwise an error is + * returned (-NLE_OBJ_MISMATCH). + * + * @see nl_cache_move() * * @return 0 or a negative error code. */ @@ -345,8 +399,16 @@ int nl_cache_add(struct nl_cache *cache, struct nl_object *obj) * @arg cache Cache to move object to. * @arg obj Object subject to be moved * - * Removes the given object from its associated cache if needed - * and adds it to the new cache. + * Removes the the specified object \p obj from its associated cache + * and moves it to another cache. + * + * If the object is not associated with a cache, the function behaves + * just like nl_cache_add(). + * + * The type of the object and cache must match, otherwise an error is + * returned (-NLE_OBJ_MISMATCH). + * + * @see nl_cache_add() * * @return 0 on success or a negative error code. */ @@ -368,12 +430,14 @@ int nl_cache_move(struct nl_cache *cache, struct nl_object *obj) } /** - * Removes an object from a cache. - * @arg obj Object to remove from its cache + * Remove object from cache. + * @arg obj Object to remove from cache * - * Removes the object \c obj from the cache it is assigned to, since - * an object can only be assigned to one cache at a time, the cache - * must ne be passed along with it. + * Removes the object \c obj from the cache it is associated with. The + * reference counter of the object will be decremented. If the reference + * to the object was the only one remaining, the object will be freed. + * + * If no cache is associated with the object, this function is a NOP. */ void nl_cache_remove(struct nl_object *obj) { @@ -391,33 +455,6 @@ void nl_cache_remove(struct nl_object *obj) obj, cache, nl_cache_name(cache)); } -/** - * Search for an object in a cache - * @arg cache Cache to search in. - * @arg needle Object to look for. - * - * Iterates over the cache and looks for an object with identical - * identifiers as the needle. - * - * @return Reference to object or NULL if not found. - * @note The returned object must be returned via nl_object_put(). - */ -struct nl_object *nl_cache_search(struct nl_cache *cache, - struct nl_object *needle) -{ - struct nl_object *obj; - - nl_list_for_each_entry(obj, &cache->c_items, ce_list) { - if (nl_object_identical(obj, needle)) { - nl_object_get(obj); - return obj; - } - } - - return NULL; -} - - /** @} */ /** @@ -426,15 +463,28 @@ struct nl_object *nl_cache_search(struct nl_cache *cache, */ /** - * Request a full dump from the kernel to fill a cache + * Invoke the request-update operation * @arg sk Netlink socket. - * @arg cache Cache subjected to be filled. + * @arg cache Cache + * + * This function causes the \e request-update function of the cache + * operations to be invoked. This usually causes a dump request to + * be sent over the netlink socket which triggers the kernel to dump + * all objects of a specific type to be dumped onto the netlink + * socket for pickup. * - * Send a dumping request to the kernel causing it to dump all objects - * related to the specified cache to the netlink socket. + * The behaviour of this function depends on the implemenation of + * the \e request_update function of each individual type of cache. * - * Use nl_cache_pickup() to read the objects from the socket and fill them - * into a cache. + * This function will not have any effects on the cache (unless the + * request_update implementation of the cache operations does so). + * + * Use nl_cache_pickup() to pick-up (read) the objects from the socket + * and fill them into the cache. + * + * @see nl_cache_pickup(), nl_cache_resync() + * + * @return 0 on success or a negative error code. */ int nl_cache_request_full_dump(struct nl_sock *sk, struct nl_cache *cache) { @@ -461,6 +511,12 @@ static int update_msg_parser(struct nl_msg *msg, void *arg) } /** @endcond */ +/** + * Pick-up a netlink request-update with your own parser + * @arg sk Netlink socket + * @arg cache Cache + * @arg param Parser parameters + */ int __cache_pickup(struct nl_sock *sk, struct nl_cache *cache, struct nl_parser_param *param) { @@ -707,8 +763,41 @@ int nl_cache_refill(struct nl_sock *sk, struct nl_cache *cache) */ /** - * Mark all objects in a cache - * @arg cache Cache to mark all objects in + * Search object in cache + * @arg cache Cache + * @arg needle Object to look for. + * + * Searches the cache for an object which matches the object \p needle. + * The function nl_object_identical() is used to determine if the + * objects match. If a matching object is found, the reference counter + * is incremented and the object is returned. + * + * Therefore, if an object is returned, the reference to the object + * must be returned by calling nl_object_put() after usage. + * + * @return Reference to object or NULL if not found. + */ +struct nl_object *nl_cache_search(struct nl_cache *cache, + struct nl_object *needle) +{ + struct nl_object *obj; + + nl_list_for_each_entry(obj, &cache->c_items, ce_list) { + if (nl_object_identical(obj, needle)) { + nl_object_get(obj); + return obj; + } + } + + return NULL; +} + +/** + * Mark all objects of a cache + * @arg cache Cache + * + * Marks all objects of a cache by calling nl_object_mark() on each + * object associated with the cache. */ void nl_cache_mark_all(struct nl_cache *cache) { diff --git a/lib/cache_mngr.c b/lib/cache_mngr.c index 81052aa..cfa676b 100644 --- a/lib/cache_mngr.c +++ b/lib/cache_mngr.c @@ -143,8 +143,9 @@ found: * @arg sk Netlink socket. * @arg protocol Netlink Protocol this manager is used for * @arg flags Flags + * @arg result Result pointer * - * @return Newly allocated cache manager or NULL on failure. + * @return 0 on success or a negative error code. */ int nl_cache_mngr_alloc(struct nl_sock *sk, int protocol, int flags, struct nl_cache_mngr **result) @@ -196,6 +197,7 @@ errout: * @arg mngr Cache manager. * @arg name Name of cache to keep track of * @arg cb Function to be called upon changes. + * @arg data Argument passed on to change callback * @arg result Pointer to store added cache. * * Allocates a new cache of the specified type and adds it to the manager. diff --git a/lib/fib_lookup/lookup.c b/lib/fib_lookup/lookup.c index ce9c027..61984c7 100644 --- a/lib/fib_lookup/lookup.c +++ b/lib/fib_lookup/lookup.c @@ -192,6 +192,7 @@ struct nl_cache *flnl_result_alloc_cache(void) * Builds a netlink request message to do a lookup * @arg req Requested match. * @arg flags additional netlink message flags + * @arg result Result pointer * * Builds a new netlink message requesting a change of link attributes. * The netlink message header isn't fully equipped with all relevant @@ -201,7 +202,7 @@ struct nl_cache *flnl_result_alloc_cache(void) * and \a tmpl must contain the attributes to be changed set via * \c rtnl_link_set_* functions. * - * @return New netlink message + * @return 0 on success or a negative error code. * @note Not all attributes can be changed, see * \ref link_changeable "Changeable Attributes" for more details. */ @@ -27,7 +27,7 @@ * Netlink header type \c NLMSG_DONE. * * @par - * The Netlink message header (\link nlmsghdr struct nlmsghdr\endlink) is shown below. + * The Netlink message header (struct nlmsghdr) is shown below. * @code * 0 1 2 3 * 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 diff --git a/lib/object.c b/lib/object.c index d881ac9..4a1b356 100644 --- a/lib/object.c +++ b/lib/object.c @@ -63,9 +63,11 @@ struct nl_object *nl_object_alloc(struct nl_object_ops *ops) } /** - * Allocate a new object of kind specified by the name + * Allocate new object of kind specified by the name * @arg kind name of object type - * @return The new object or nULL + * @arg result Result pointer + * + * @return 0 on success or a negative error code. */ int nl_object_alloc_name(const char *kind, struct nl_object **result) { diff --git a/lib/route/class.c b/lib/route/class.c index 47356e2..a0f3758 100644 --- a/lib/route/class.c +++ b/lib/route/class.c @@ -309,11 +309,12 @@ void rtnl_class_foreach_cls(struct rtnl_class *class, struct nl_cache *cache, * @arg sk Netlink socket. * @arg ifindex interface index of the link the classes are * attached to. + * @arg result Result pointer * * Allocates a new cache, initializes it properly and updates it to * include all classes attached to the specified interface. * - * @return The cache or NULL if an error has occured. + * @return 0 on success or a negative error code. */ int rtnl_class_alloc_cache(struct nl_sock *sk, int ifindex, struct nl_cache **result) diff --git a/lib/route/link.c b/lib/route/link.c index f9039a1..bfb4150 100644 --- a/lib/route/link.c +++ b/lib/route/link.c @@ -1036,6 +1036,7 @@ struct rtnl_link *rtnl_link_get_by_name(struct nl_cache *cache, * @arg old link to be changed * @arg tmpl template with requested changes * @arg flags additional netlink message flags + * @arg result Result pointer * * Builds a new netlink message requesting a change of link attributes. * The netlink message header isn't fully equipped with all relevant @@ -1045,7 +1046,7 @@ struct rtnl_link *rtnl_link_get_by_name(struct nl_cache *cache, * and \a tmpl must contain the attributes to be changed set via * \c rtnl_link_set_* functions. * - * @return New netlink message + * @return 0 on success or a negative error code. * @note Not all attributes can be changed, see * \ref link_changeable "Changeable Attributes" for more details. */ diff --git a/lib/route/neigh.c b/lib/route/neigh.c index aa19faa..0cd0366 100644 --- a/lib/route/neigh.c +++ b/lib/route/neigh.c @@ -408,7 +408,7 @@ void rtnl_neigh_put(struct rtnl_neigh *neigh) /** * Build a neighbour cache including all neighbours currently configured in the kernel. - * @arg sk Netlink socket. + * @arg sock Netlink socket. * @arg result Pointer to store resulting cache. * * Allocates a new neighbour cache, initializes it properly and updates it diff --git a/lib/route/pktloc.c b/lib/route/pktloc.c index 823a3c7..4d7d9dd 100644 --- a/lib/route/pktloc.c +++ b/lib/route/pktloc.c @@ -20,7 +20,7 @@ * library and provides a well defined set of definitions for most common * protocol fields. * - * @subsection pktloc_examples Examples + * @section pktloc_examples Examples * @par Example 1.1 Looking up a packet location * @code * struct rtnl_pktloc *loc; @@ -151,6 +151,7 @@ errout: /** * Lookup packet location alias * @arg name Name of packet location. + * @arg result Result pointer * * Tries to find a matching packet location alias for the supplied * packet location name. diff --git a/lib/route/route.c b/lib/route/route.c index c85c225..f684f96 100644 --- a/lib/route/route.c +++ b/lib/route/route.c @@ -64,13 +64,14 @@ static int route_request_update(struct nl_cache *c, struct nl_sock *h) * @arg sk Netlink socket. * @arg family Address family of routes to cover or AF_UNSPEC * @arg flags Flags + * @arg result Result pointer * * Allocates a new cache, initializes it properly and updates it to * contain all routes currently configured in the kernel. * * @note The caller is responsible for destroying and freeing the * cache after using it. - * @return The cache or NULL if an error has occured. + * @return 0 on success or a negative error code. */ int rtnl_route_alloc_cache(struct nl_sock *sk, int family, int flags, struct nl_cache **result) diff --git a/lib/route/rule.c b/lib/route/rule.c index 36672d3..8fa54e9 100644 --- a/lib/route/rule.c +++ b/lib/route/rule.c @@ -319,7 +319,7 @@ void rtnl_rule_put(struct rtnl_rule *rule) /** * Build a rule cache including all rules currently configured in the kernel. - * @arg sk Netlink socket. + * @arg sock Netlink socket. * @arg family Address family or AF_UNSPEC. * @arg result Pointer to store resulting cache. * @@ -421,6 +421,7 @@ nla_put_failure: * Build netlink request message to add a new rule * @arg tmpl template with data of new rule * @arg flags additional netlink message flags + * @arg result Result pointer * * Builds a new netlink message requesting a addition of a new * rule. The netlink message header isn't fully equipped with @@ -428,7 +429,7 @@ nla_put_failure: * or supplemented as needed. \a tmpl must contain the attributes of the new * address set via \c rtnl_rule_set_* functions. * - * @return The netlink message + * @return 0 on success or a negative error code. */ int rtnl_rule_build_add_request(struct rtnl_rule *tmpl, int flags, struct nl_msg **result) @@ -476,6 +477,7 @@ int rtnl_rule_add(struct nl_sock *sk, struct rtnl_rule *tmpl, int flags) * Build a netlink request message to delete a rule * @arg rule rule to delete * @arg flags additional netlink message flags + * @arg result Result pointer * * Builds a new netlink message requesting a deletion of a rule. * The netlink message header isn't fully equipped with all relevant @@ -483,7 +485,7 @@ int rtnl_rule_add(struct nl_sock *sk, struct rtnl_rule *tmpl, int flags) * or supplemented as needed. \a rule must point to an existing * address. * - * @return The netlink message + * @return 0 on success or a negative error code. */ int rtnl_rule_build_delete_request(struct rtnl_rule *rule, int flags, struct nl_msg **result) |