summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorThomas Graf <tgraf@suug.ch>2011-03-21 23:40:26 (GMT)
committerThomas Graf <tgraf@suug.ch>2011-03-21 23:40:26 (GMT)
commitc1073d6172223be9837141da149c8876ce46884b (patch)
treeb1bfcc1f25a97337fd60aa0ef7052132b756be86
parent55f803c64df6f742a00dd45a24a3d51f87f6365b (diff)
downloadlibnl-c1073d6172223be9837141da149c8876ce46884b.zip
libnl-c1073d6172223be9837141da149c8876ce46884b.tar.gz
libnl-c1073d6172223be9837141da149c8876ce46884b.tar.bz2
Documentation updates
Mostly killing doxygen warnings, some doc updates to caching
-rw-r--r--include/netlink/cache-api.h24
-rw-r--r--lib/cache.c211
-rw-r--r--lib/cache_mngr.c4
-rw-r--r--lib/fib_lookup/lookup.c3
-rw-r--r--lib/msg.c2
-rw-r--r--lib/object.c6
-rw-r--r--lib/route/class.c3
-rw-r--r--lib/route/link.c3
-rw-r--r--lib/route/neigh.c2
-rw-r--r--lib/route/pktloc.c3
-rw-r--r--lib/route/route.c3
-rw-r--r--lib/route/rule.c8
12 files changed, 198 insertions, 74 deletions
diff --git a/include/netlink/cache-api.h b/include/netlink/cache-api.h
index 22fc449..efae2ed 100644
--- a/include/netlink/cache-api.h
+++ b/include/netlink/cache-api.h
@@ -151,21 +151,40 @@ struct nl_af_group
#define END_OF_GROUP_LIST AF_UNSPEC, 0
+/**
+ * Parser parameters
+ *
+ * This structure is used to configure what kind of parser to use
+ * when parsing netlink messages to create objects.
+ */
struct nl_parser_param
{
+ /** Function to parse netlink messages into objects */
int (*pp_cb)(struct nl_object *, struct nl_parser_param *);
+
+ /** Arbitary argument to be passed to the parser */
void * pp_arg;
};
/**
* Cache Operations
+ *
+ * This structure defines the characterstics of a cache type. It contains
+ * pointers to functions which implement the specifics of the object type
+ * the cache can hold.
*/
struct nl_cache_ops
{
+ /** Name of cache type (must be unique) */
char * co_name;
+ /** Size of family specific netlink header */
int co_hdrsize;
+
+ /** Netlink protocol */
int co_protocol;
+
+ /** Group definition */
struct nl_af_group * co_groups;
/**
@@ -182,11 +201,16 @@ struct nl_cache_ops
int (*co_msg_parser)(struct nl_cache_ops *, struct sockaddr_nl *,
struct nlmsghdr *, struct nl_parser_param *);
+ /** Object operations */
struct nl_object_ops * co_obj_ops;
+ /** Internal, do not touch! */
struct nl_cache_ops *co_next;
+
struct nl_cache *co_major_cache;
struct genl_ops * co_genl;
+
+ /* Message type definition */
struct nl_msgtype co_msgtypes[];
};
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.
*/
diff --git a/lib/msg.c b/lib/msg.c
index 5c852c0..62f0911 100644
--- a/lib/msg.c
+++ b/lib/msg.c
@@ -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)