From 88527534ba08bf8946dcf9f61c725133facb97af Mon Sep 17 00:00:00 2001 From: Thomas Graf Date: Thu, 14 Mar 2013 15:37:46 +0100 Subject: addr: improve API reference documentation for nl_addr_*() Signed-off-by: Thomas Graf --- include/netlink/addr.h | 4 +- lib/addr.c | 204 +++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 166 insertions(+), 42 deletions(-) diff --git a/include/netlink/addr.h b/include/netlink/addr.h index 794c4ff..db3e4c2 100644 --- a/include/netlink/addr.h +++ b/include/netlink/addr.h @@ -6,7 +6,7 @@ * License as published by the Free Software Foundation version 2.1 * of the License. * - * Copyright (c) 2003-2010 Thomas Graf + * Copyright (c) 2003-2013 Thomas Graf */ #ifndef NETLINK_ADDR_H_ @@ -40,7 +40,7 @@ extern int nl_addr_guess_family(struct nl_addr *); extern int nl_addr_fill_sockaddr(struct nl_addr *, struct sockaddr *, socklen_t *); extern int nl_addr_info(struct nl_addr *, struct addrinfo **); -extern int nl_addr_resolve(struct nl_addr *addr, char *host, size_t hostlen); +extern int nl_addr_resolve(struct nl_addr *, char *, size_t); /* Access Functions */ extern void nl_addr_set_family(struct nl_addr *, int); diff --git a/lib/addr.c b/lib/addr.c index e75ef70..3db30ee 100644 --- a/lib/addr.c +++ b/lib/addr.c @@ -6,7 +6,7 @@ * License as published by the Free Software Foundation version 2.1 * of the License. * - * Copyright (c) 2003-2012 Thomas Graf + * Copyright (c) 2003-2013 Thomas Graf */ /** @@ -170,9 +170,17 @@ static void addr_destroy(struct nl_addr *addr) */ /** - * Allocate new abstract address object. - * @arg maxsize Maximum size of the binary address. - * @return Newly allocated address object or NULL + * Allocate empty abstract address + * @arg maxsize Upper limit of the binary address to be stored + * + * The new address object will be empty with a prefix length of 0 and will + * be capable of holding binary addresses up to the specified limit. + * + * @see nl_addr_build() + * @see nl_addr_parse() + * @see nl_addr_put() + * + * @return Allocated address object or NULL upon failure. */ struct nl_addr *nl_addr_alloc(size_t maxsize) { @@ -189,11 +197,21 @@ struct nl_addr *nl_addr_alloc(size_t maxsize) } /** - * Allocate new abstract address object based on a binary address. - * @arg family Address family. - * @arg buf Buffer containing the binary address. - * @arg size Length of binary address buffer. - * @return Newly allocated address handle or NULL + * Allocate abstract address based on a binary address. + * @arg family Address family + * @arg buf Binary address + * @arg size Length of binary address + * + * This function will allocate an abstract address capable of holding the + * binary address specified. The prefix length will be set to the full + * length of the binary address provided. + * + * @see nl_addr_alloc() + * @see nl_addr_alloc_attr() + * @see nl_addr_parse() + * @see nl_addr_put() + * + * @return Allocated address object or NULL upon failure. */ struct nl_addr *nl_addr_build(int family, void *buf, size_t size) { @@ -214,14 +232,25 @@ struct nl_addr *nl_addr_build(int family, void *buf, size_t size) } /** - * Allocate abstract address based on netlink attribute. - * @arg nla Netlink attribute of unspecific type. + * Allocate abstract address based on Netlink attribute. + * @arg nla Netlink attribute * @arg family Address family. * - * Considers the netlink attribute payload a address of the specified - * family and allocates a new abstract address based on it. + * Allocates an abstract address based on the specified Netlink attribute + * by interpreting the payload of the Netlink attribute as the binary + * address. * - * @return Newly allocated address handle or NULL. + * This function is identical to: + * @code + * nl_addr_build(family, nla_data(nla), nla_len(nla)); + * @endcode + * + * @see nl_addr_alloc() + * @see nl_addr_build() + * @see nl_addr_parse() + * @see nl_addr_put() + * + * @return Allocated address object or NULL upon failure. */ struct nl_addr *nl_addr_alloc_attr(struct nlattr *nla, int family) { @@ -229,13 +258,13 @@ struct nl_addr *nl_addr_alloc_attr(struct nlattr *nla, int family) } /** - * Allocate abstract address object based on a character string + * Allocate abstract address based on character string * @arg addrstr Address represented as character string. * @arg hint Address family hint or AF_UNSPEC. * @arg result Pointer to store resulting address. * * Regognizes the following address formats: - *@code + * @code * Format Len Family * ---------------------------------------------------------------- * IPv6 address format 16 AF_INET6 @@ -253,6 +282,10 @@ struct nl_addr *nl_addr_alloc_attr(struct nlattr *nla, int family) * The prefix length may be appened at the end prefixed with a * slash, e.g. 10.0.0.0/8. * + * @see nl_addr_alloc() + * @see nl_addr_build() + * @see nl_addr_put() + * * @return 0 on success or a negative error code. */ int nl_addr_parse(const char *addrstr, int hint, struct nl_addr **result) @@ -424,10 +457,16 @@ errout: } /** - * Clone existing abstract address object. - * @arg addr Abstract address object. - * @return Newly allocated abstract address object being a duplicate of the - * specified address object or NULL if a failure occured. + * Clone existing abstract address object + * @arg addr Abstract address object + * + * Allocates new abstract address representing an identical clone of an + * existing address. + * + * @see nl_addr_alloc() + * @see nl_addr_put() + * + * @return Allocated abstract address or NULL upon failure. */ struct nl_addr *nl_addr_clone(struct nl_addr *addr) { @@ -447,6 +486,18 @@ struct nl_addr *nl_addr_clone(struct nl_addr *addr) * @{ */ +/** + * Increase the reference counter of an abstract address + * @arg addr Abstract address + * + * Increases the reference counter of the address and thus prevents the + * release of the memory resources until the reference is given back + * using the function nl_addr_put(). + * + * @see nl_addr_put() + * + * @return Pointer to the existing abstract address + */ struct nl_addr *nl_addr_get(struct nl_addr *addr) { addr->a_refcnt++; @@ -454,6 +505,15 @@ struct nl_addr *nl_addr_get(struct nl_addr *addr) return addr; } +/** + * Decrease the reference counter of an abstract address + * @arg addr Abstract addr + * + * @note The resources of the abstract address will be freed after the + * last reference to the address has been returned. + * + * @see nl_addr_get() + */ void nl_addr_put(struct nl_addr *addr) { if (!addr) @@ -466,9 +526,10 @@ void nl_addr_put(struct nl_addr *addr) } /** - * Check whether an abstract address object is shared. + * Check whether an abstract address is shared. * @arg addr Abstract address object. - * @return Non-zero if the abstract address object is shared, otherwise 0. + * + * @return Non-zero if the abstract address is shared, otherwise 0. */ int nl_addr_shared(struct nl_addr *addr) { @@ -483,12 +544,21 @@ int nl_addr_shared(struct nl_addr *addr) */ /** - * Compares two abstract address objects. - * @arg a A abstract address object. - * @arg b Another abstract address object. + * Compare abstract addresses + * @arg a An abstract address + * @arg b Another abstract address + * + * Verifies whether the address family, address length, prefix length, and + * binary addresses of two abstract addresses matches. + * + * @note This function will *not* respect the prefix length in the sense + * that only the actual prefix will be compared. Please refer to the + * nl_addr_cmp_prefix() function if you require this functionality. * - * @return Integer less than, equal to or greather than zero if \c is found, - * respectively to be less than, to, or be greater than \c b. + * @see nl_addr_cmp_prefix() + * + * @return Integer less than, equal to or greather than zero if the two + * addresses match. */ int nl_addr_cmp(struct nl_addr *a, struct nl_addr *b) { @@ -509,12 +579,17 @@ int nl_addr_cmp(struct nl_addr *a, struct nl_addr *b) } /** - * Compares the prefix of two abstract address objects. - * @arg a A abstract address object. - * @arg b Another abstract address object. + * Compare the prefix of two abstract addresses + * @arg a An abstract address + * @arg b Another abstract address + * + * Verifies whether the address family and the binary address covered by + * the smaller prefix length of the two abstract addresses matches. * - * @return Integer less than, equal to or greather than zero if \c is found, - * respectively to be less than, to, or be greater than \c b. + * @see nl_addr_cmp() + * + * @return Integer less than, equal to or greather than zero if the two + * addresses match. */ int nl_addr_cmp_prefix(struct nl_addr *a, struct nl_addr *b) { @@ -538,7 +613,9 @@ int nl_addr_cmp_prefix(struct nl_addr *a, struct nl_addr *b) /** * Returns true if the address consists of all zeros - * @arg addr Address to look at. + * @arg addr Abstract address + * + * @return 1 if the binary address consists of all zeros, 0 otherwise. */ int nl_addr_iszero(struct nl_addr *addr) { @@ -552,11 +629,11 @@ int nl_addr_iszero(struct nl_addr *addr) } /** - * Check if an address matches a certain family. + * Check if address string is parseable for a specific address family * @arg addr Address represented as character string. * @arg family Desired address family. * - * @return 1 if the address is of the desired address family, + * @return 1 if the address is parseable assuming the specified address family, * otherwise 0 is returned. */ int nl_addr_valid(char *addr, int family) @@ -588,9 +665,10 @@ int nl_addr_valid(char *addr, int family) } /** - * Guess address family of an abstract address object based on address size. + * Guess address family of abstract address based on address size * @arg addr Abstract address object. - * @return Address family or AF_UNSPEC if guessing wasn't successful. + * + * @return Numeric address family or AF_UNSPEC */ int nl_addr_guess_family(struct nl_addr *addr) { @@ -666,7 +744,7 @@ int nl_addr_fill_sockaddr(struct nl_addr *addr, struct sockaddr *sa, * Call getaddrinfo() for an abstract address object. * @arg addr Abstract address object. * @arg result Pointer to store resulting address list. - * + * * Calls getaddrinfo() for the specified abstract address in AI_NUMERICHOST * mode. * @@ -744,11 +822,26 @@ int nl_addr_resolve(struct nl_addr *addr, char *host, size_t hostlen) * @{ */ +/** + * Set address family + * @arg addr Abstract address object + * @arg family Address family + * + * @see nl_addr_get_family() + */ void nl_addr_set_family(struct nl_addr *addr, int family) { addr->a_family = family; } +/** + * Return address family + * @arg addr Abstract address object + * + * @see nl_addr_set_family() + * + * @return The numeric address family or `AF_UNSPEC` + */ int nl_addr_get_family(struct nl_addr *addr) { return addr->a_family; @@ -759,6 +852,20 @@ int nl_addr_get_family(struct nl_addr *addr) * @arg addr Abstract address object. * @arg buf Buffer containing binary address. * @arg len Length of buffer containing binary address. + * + * Modifies the binary address portion of the abstract address. The + * abstract address must be capable of holding the required amount + * or this function will fail. + * + * @note This function will *not* modify the prefix length. It is within + * the responsibility of the caller to set the prefix length to the + * desirable length. + * + * @see nl_addr_alloc() + * @see nl_addr_get_binary_addr() + * @see nl_addr_get_len() + * + * @return 0 on success or a negative error code. */ int nl_addr_set_binary_addr(struct nl_addr *addr, void *buf, size_t len) { @@ -777,6 +884,11 @@ int nl_addr_set_binary_addr(struct nl_addr *addr, void *buf, size_t len) /** * Get binary address of abstract address object. * @arg addr Abstract address object. + * + * @see nl_addr_set_binary_addr() + * @see nl_addr_get_len() + * + * @return Pointer to binary address of length nl_addr_get_len() */ void *nl_addr_get_binary_addr(struct nl_addr *addr) { @@ -786,20 +898,32 @@ void *nl_addr_get_binary_addr(struct nl_addr *addr) /** * Get length of binary address of abstract address object. * @arg addr Abstract address object. + * + * @see nl_addr_get_binary_addr() + * @see nl_addr_set_binary_addr() */ unsigned int nl_addr_get_len(struct nl_addr *addr) { return addr->a_len; } +/** + * Set the prefix length of an abstract address + * @arg addr Abstract address object + * @arg prefixlen New prefix length + * + * @see nl_addr_get_prefixlen() + */ void nl_addr_set_prefixlen(struct nl_addr *addr, int prefixlen) { addr->a_prefixlen = prefixlen; } /** - * Get prefix length of abstract address object. - * @arg addr Abstract address object. + * Return prefix length of abstract address object. + * @arg addr Abstract address object + * + * @see nl_addr_set_prefixlen() */ unsigned int nl_addr_get_prefixlen(struct nl_addr *addr) { -- cgit v0.12