Documentation updates
Mostly killing doxygen warnings, some doc updates to caching
This commit is contained in:
parent
55f803c64d
commit
c1073d6172
12 changed files with 198 additions and 74 deletions
|
@ -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[];
|
||||
};
|
||||
|
||||
|
|
211
lib/cache.c
211
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
|
||||
*
|
||||
* Send a dumping request to the kernel causing it to dump all objects
|
||||
* related to the specified cache to the netlink socket.
|
||||
* 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.
|
||||
*
|
||||
* Use nl_cache_pickup() to read the objects from the socket and fill them
|
||||
* into a cache.
|
||||
* The behaviour of this function depends on the implemenation of
|
||||
* the \e request_update function of each individual type of 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)
|
||||
{
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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)
|
||||
{
|
||||
|
|
|
@ -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)
|
||||
|
|
|
@ -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.
|
||||
*/
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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)
|
||||
|
|
|
@ -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)
|
||||
|
|
Loading…
Add table
Reference in a new issue