* License as published by the Free Software Foundation version 2.1
* of the License.
*
- * Copyright (c) 2003-2012 Thomas Graf <tgraf@suug.ch>
+ * Copyright (c) 2003-2013 Thomas Graf <tgraf@suug.ch>
*/
/**
*/
/**
- * 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)
{
}
/**
- * 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)
{
}
/**
- * 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)
{
}
/**
- * 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
* 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)
}
/**
- * 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)
{
* @{
*/
+/**
+ * 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++;
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)
}
/**
- * 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)
{
*/
/**
- * 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)
{
}
/**
- * 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)
{
/**
* 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)
{
}
/**
- * 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)
}
/**
- * 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)
{
* 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.
*
* @{
*/
+/**
+ * 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;
* @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)
{
/**
* 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)
{
/**
* 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)
{
projects / libnl / commitdiff