Detailed attribute documentation
This patch extends and reorganizes the existing attribute documentation and includes various verbose examples.
This commit is contained in:
Thomas Graf
parent
0fa6756cca
commit
dbcdf91a99
3 changed files with 870 additions and 485 deletions
|
|
@ -341,6 +341,7 @@ static inline int nl_cb_call(struct nl_cb *cb, int type, struct nl_msg *msg)
|
|||
|
||||
#define __init __attribute__ ((constructor))
|
||||
#define __exit __attribute__ ((destructor))
|
||||
#define __deprecated __attribute__ ((deprecated))
|
||||
|
||||
#define P_ACCEPT 0
|
||||
#define P_IGNORE 0
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
* License as published by the Free Software Foundation version 2.1
|
||||
* of the License.
|
||||
*
|
||||
* Copyright (c) 2003-2006 Thomas Graf <tgraf@suug.ch>
|
||||
* Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch>
|
||||
*/
|
||||
|
||||
#ifndef NETLINK_ATTR_H_
|
||||
|
|
@ -24,226 +24,215 @@ extern "C" {
|
|||
struct nl_msg;
|
||||
|
||||
/**
|
||||
* @name Validation Policy Types
|
||||
* @name Basic Attribute Data Types
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* @ingroup attr
|
||||
* Standard attribute types to specify validation policy
|
||||
* Basic attribute data types
|
||||
*
|
||||
* See \ref attr_datatypes for more details.
|
||||
*/
|
||||
enum {
|
||||
NLA_UNSPEC, /**< Unspecified type */
|
||||
NLA_U8, /**< 8bit integer */
|
||||
NLA_U16, /**< 16bit integer */
|
||||
NLA_U32, /**< 32bit integer */
|
||||
NLA_U64, /**< 64bit integer */
|
||||
NLA_STRING, /**< character string */
|
||||
NLA_FLAG, /**< flag */
|
||||
NLA_MSECS, /**< micro seconds (64bit) */
|
||||
NLA_NESTED, /**< nested attributes */
|
||||
NLA_UNSPEC, /**< Unspecified type, binary data chunk */
|
||||
NLA_U8, /**< 8 bit integer */
|
||||
NLA_U16, /**< 16 bit integer */
|
||||
NLA_U32, /**< 32 bit integer */
|
||||
NLA_U64, /**< 64 bit integer */
|
||||
NLA_STRING, /**< NUL terminated character string */
|
||||
NLA_FLAG, /**< Flag */
|
||||
NLA_MSECS, /**< Micro seconds (64bit) */
|
||||
NLA_NESTED, /**< Nested attributes */
|
||||
__NLA_TYPE_MAX,
|
||||
};
|
||||
|
||||
/**
|
||||
* @ingroup attr
|
||||
* Maximum netlink validation policy type
|
||||
*/
|
||||
#define NLA_TYPE_MAX (__NLA_TYPE_MAX - 1)
|
||||
|
||||
/** @} */
|
||||
|
||||
/**
|
||||
* @ingroup attr
|
||||
* attribute validation policy
|
||||
* Attribute validation policy.
|
||||
*
|
||||
* Policies are defined as arrays of this struct, the array must
|
||||
* be accessible by attribute type up to the highest identifier
|
||||
* to be expected.
|
||||
*
|
||||
* Example:
|
||||
* @code
|
||||
* static struct nla_policy my_policy[ATTR_MAX+1] __read_mostly = {
|
||||
* [ATTR_FOO] = { .type = NLA_U16 },
|
||||
* [ATTR_BAR] = { .type = NLA_STRING },
|
||||
* [ATTR_BAZ] = { .minlen = sizeof(struct mystruct) },
|
||||
* };
|
||||
* @endcode
|
||||
* See \ref attr_datatypes for more details.
|
||||
*/
|
||||
struct nla_policy {
|
||||
/** Type of attribute or NLA_UNSPEC */
|
||||
uint16_t type;
|
||||
|
||||
/** Minimal length of payload required to be available */
|
||||
/** Minimal length of payload required */
|
||||
uint16_t minlen;
|
||||
|
||||
/** Maximal length of payload required to be available */
|
||||
/** Maximal length of payload allowed */
|
||||
uint16_t maxlen;
|
||||
};
|
||||
|
||||
/* size calculations */
|
||||
/* Size calculations */
|
||||
extern int nla_attr_size(int payload);
|
||||
extern int nla_total_size(int payload);
|
||||
extern int nla_padlen(int payload);
|
||||
|
||||
/* payload access */
|
||||
/* Attribute parsing */
|
||||
extern int nla_type(const struct nlattr *);
|
||||
extern void * nla_data(const struct nlattr *);
|
||||
extern int nla_len(const struct nlattr *);
|
||||
|
||||
/* attribute parsing */
|
||||
extern int nla_ok(const struct nlattr *, int);
|
||||
extern struct nlattr * nla_next(const struct nlattr *, int *);
|
||||
extern int nla_parse(struct nlattr **, int, struct nlattr *,
|
||||
int, struct nla_policy *);
|
||||
extern int nla_parse_nested(struct nlattr **, int, struct nlattr *,
|
||||
struct nla_policy *);
|
||||
extern int nla_validate(struct nlattr *, int, int,
|
||||
struct nla_policy *);
|
||||
extern struct nlattr * nla_find(struct nlattr *, int, int);
|
||||
|
||||
/* utilities */
|
||||
/* Helper Functions */
|
||||
extern int nla_memcpy(void *, struct nlattr *, int);
|
||||
extern size_t nla_strlcpy(char *, const struct nlattr *, size_t);
|
||||
extern int nla_memcmp(const struct nlattr *, const void *, size_t);
|
||||
extern int nla_strcmp(const struct nlattr *, const char *);
|
||||
|
||||
/* attribute construction */
|
||||
/* Unspecific attribute */
|
||||
extern struct nlattr * nla_reserve(struct nl_msg *, int, int);
|
||||
extern int nla_put(struct nl_msg *, int, int, const void *);
|
||||
extern int nla_put_nested(struct nl_msg *, int, struct nl_msg *);
|
||||
extern int nla_put_u8(struct nl_msg *, int, uint8_t);
|
||||
extern int nla_put_u16(struct nl_msg *, int, uint16_t);
|
||||
extern int nla_put_u32(struct nl_msg *, int, uint32_t);
|
||||
extern int nla_put_u64(struct nl_msg *, int, uint64_t);
|
||||
extern int nla_put_string(struct nl_msg *, int, const char *);
|
||||
extern int nla_put_flag(struct nl_msg *, int);
|
||||
extern int nla_put_msecs(struct nl_msg *, int, unsigned long);
|
||||
extern int nla_put_data(struct nl_msg *, int, struct nl_data *);
|
||||
extern int nla_put_addr(struct nl_msg *, int, struct nl_addr *);
|
||||
|
||||
/* attribute nesting */
|
||||
/* Integer attribute */
|
||||
extern uint8_t nla_get_u8(struct nlattr *);
|
||||
extern int nla_put_u8(struct nl_msg *, int, uint8_t);
|
||||
extern uint16_t nla_get_u16(struct nlattr *);
|
||||
extern int nla_put_u16(struct nl_msg *, int, uint16_t);
|
||||
extern uint32_t nla_get_u32(struct nlattr *);
|
||||
extern int nla_put_u32(struct nl_msg *, int, uint32_t);
|
||||
extern uint64_t nla_get_u64(struct nlattr *);
|
||||
extern int nla_put_u64(struct nl_msg *, int, uint64_t);
|
||||
|
||||
/* String attribute */
|
||||
extern char * nla_get_string(struct nlattr *);
|
||||
extern int nla_put_string(struct nl_msg *, int, const char *);
|
||||
|
||||
/* Flag attribute */
|
||||
extern int nla_get_flag(struct nlattr *);
|
||||
extern int nla_put_flag(struct nl_msg *, int);
|
||||
|
||||
/* Msec attribute */
|
||||
extern unsigned long nla_get_msecs(struct nlattr *);
|
||||
extern int nla_put_msecs(struct nl_msg *, int, unsigned long);
|
||||
|
||||
/* Attribute nesting */
|
||||
extern int nla_put_nested(struct nl_msg *, int, struct nl_msg *);
|
||||
extern struct nlattr * nla_nest_start(struct nl_msg *, int);
|
||||
extern int nla_nest_end(struct nl_msg *, struct nlattr *);
|
||||
extern int nla_parse_nested(struct nlattr **, int, struct nlattr *,
|
||||
struct nla_policy *);
|
||||
|
||||
/* attribute reading */
|
||||
extern uint8_t nla_get_u8(struct nlattr *);
|
||||
extern uint16_t nla_get_u16(struct nlattr *);
|
||||
extern uint32_t nla_get_u32(struct nlattr *);
|
||||
extern uint64_t nla_get_u64(struct nlattr *);
|
||||
extern char * nla_get_string(struct nlattr *);
|
||||
extern int nla_get_flag(struct nlattr *);
|
||||
extern unsigned long nla_get_msecs(struct nlattr *);
|
||||
/* DEPRECATED! */
|
||||
extern struct nl_data * nla_get_data(struct nlattr *);
|
||||
extern struct nl_addr * nla_get_addr(struct nlattr *, int);
|
||||
|
||||
/**
|
||||
* @name Attribute Construction (Exception Based)
|
||||
*
|
||||
* All these functions jump to nla_put_failure in case of a failure
|
||||
* instead of returning an error code.
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* @ingroup attr
|
||||
* Add a netlink attribute to a netlink message
|
||||
* @arg n netlink message
|
||||
* @arg attrtype attribute type
|
||||
* @arg attrlen length of attribute payload
|
||||
* @arg data head of attribute payload
|
||||
* Add unspecific attribute to netlink message.
|
||||
* @arg msg Netlink message.
|
||||
* @arg attrtype Attribute type.
|
||||
* @arg attrlen Length of attribute payload.
|
||||
* @arg data Head of attribute payload.
|
||||
*/
|
||||
#define NLA_PUT(n, attrtype, attrlen, data) \
|
||||
#define NLA_PUT(msg, attrtype, attrlen, data) \
|
||||
do { \
|
||||
if (nla_put(n, attrtype, attrlen, data) < 0) \
|
||||
if (nla_put(msg, attrtype, attrlen, data) < 0) \
|
||||
goto nla_put_failure; \
|
||||
} while(0)
|
||||
|
||||
/**
|
||||
* @ingroup attr
|
||||
* Add a basic netlink attribute to a netlink message
|
||||
* @arg n netlink message
|
||||
* @arg type atomic type
|
||||
* @arg attrtype attribute type
|
||||
* @arg value head of attribute payload
|
||||
* Add atomic type attribute to netlink message.
|
||||
* @arg msg Netlink message.
|
||||
* @arg type Atomic type.
|
||||
* @arg attrtype Attribute type.
|
||||
* @arg value Head of attribute payload.
|
||||
*/
|
||||
#define NLA_PUT_TYPE(n, type, attrtype, value) \
|
||||
#define NLA_PUT_TYPE(msg, type, attrtype, value) \
|
||||
do { \
|
||||
type __tmp = value; \
|
||||
NLA_PUT(n, attrtype, sizeof(type), &__tmp); \
|
||||
NLA_PUT(msg, attrtype, sizeof(type), &__tmp); \
|
||||
} while(0)
|
||||
|
||||
/**
|
||||
* Add a u8 netlink attribute to a netlink message
|
||||
* @arg n netlink message
|
||||
* @arg attrtype attribute type
|
||||
* @arg value numeric value
|
||||
* Add 8 bit integer attribute to netlink message.
|
||||
* @arg msg Netlink message.
|
||||
* @arg attrtype Attribute type.
|
||||
* @arg value Numeric value.
|
||||
*/
|
||||
#define NLA_PUT_U8(n, attrtype, value) \
|
||||
NLA_PUT_TYPE(n, uint8_t, attrtype, value)
|
||||
#define NLA_PUT_U8(msg, attrtype, value) \
|
||||
NLA_PUT_TYPE(msg, uint8_t, attrtype, value)
|
||||
|
||||
/**
|
||||
* Add a u16 netlink attribute to a netlink message
|
||||
* @arg n netlink message
|
||||
* @arg attrtype attribute type
|
||||
* @arg value numeric value
|
||||
* Add 16 bit integer attribute to netlink message.
|
||||
* @arg msg Netlink message.
|
||||
* @arg attrtype Attribute type.
|
||||
* @arg value Numeric value.
|
||||
*/
|
||||
#define NLA_PUT_U16(n, attrtype, value) \
|
||||
NLA_PUT_TYPE(n, uint16_t, attrtype, value)
|
||||
#define NLA_PUT_U16(msg, attrtype, value) \
|
||||
NLA_PUT_TYPE(msg, uint16_t, attrtype, value)
|
||||
|
||||
/**
|
||||
* Add a u32 netlink attribute to a netlink message
|
||||
* @arg n netlink message
|
||||
* @arg attrtype attribute type
|
||||
* @arg value numeric value
|
||||
* Add 32 bit integer attribute to netlink message.
|
||||
* @arg msg Netlink message.
|
||||
* @arg attrtype Attribute type.
|
||||
* @arg value Numeric value.
|
||||
*/
|
||||
#define NLA_PUT_U32(n, attrtype, value) \
|
||||
NLA_PUT_TYPE(n, uint32_t, attrtype, value)
|
||||
#define NLA_PUT_U32(msg, attrtype, value) \
|
||||
NLA_PUT_TYPE(msg, uint32_t, attrtype, value)
|
||||
|
||||
/**
|
||||
* Add a u64 netlink attribute to a netlink message
|
||||
* @arg n netlink message
|
||||
* @arg attrtype attribute type
|
||||
* @arg value numeric value
|
||||
* Add 64 bit integer attribute to netlink message.
|
||||
* @arg msg Netlink message.
|
||||
* @arg attrtype Attribute type.
|
||||
* @arg value Numeric value.
|
||||
*/
|
||||
#define NLA_PUT_U64(n, attrtype, value) \
|
||||
NLA_PUT_TYPE(n, uint64_t, attrtype, value)
|
||||
#define NLA_PUT_U64(msg, attrtype, value) \
|
||||
NLA_PUT_TYPE(msg, uint64_t, attrtype, value)
|
||||
|
||||
/**
|
||||
* Add a character string netlink attribute to a netlink message
|
||||
* @arg n netlink message
|
||||
* @arg attrtype attribute type
|
||||
* @arg value character string
|
||||
* Add string attribute to netlink message.
|
||||
* @arg msg Netlink message.
|
||||
* @arg attrtype Attribute type.
|
||||
* @arg value NUL terminated character string.
|
||||
*/
|
||||
#define NLA_PUT_STRING(n, attrtype, value) \
|
||||
NLA_PUT(n, attrtype, strlen(value) + 1, value)
|
||||
#define NLA_PUT_STRING(msg, attrtype, value) \
|
||||
NLA_PUT(msg, attrtype, strlen(value) + 1, value)
|
||||
|
||||
/**
|
||||
* Add a flag netlink attribute to a netlink message
|
||||
* @arg n netlink message
|
||||
* @arg attrtype attribute type
|
||||
* Add flag attribute to netlink message.
|
||||
* @arg msg Netlink message.
|
||||
* @arg attrtype Attribute type.
|
||||
*/
|
||||
#define NLA_PUT_FLAG(n, attrtype) \
|
||||
NLA_PUT(n, attrtype, 0, NULL)
|
||||
#define NLA_PUT_FLAG(msg, attrtype) \
|
||||
NLA_PUT(msg, attrtype, 0, NULL)
|
||||
|
||||
/**
|
||||
* Add a msecs netlink attribute to a netlink message
|
||||
* @arg n netlink message
|
||||
* @arg attrtype attribute type
|
||||
* @arg msecs numeric value in micro seconds
|
||||
* Add msecs attribute to netlink message.
|
||||
* @arg msg Netlink message.
|
||||
* @arg attrtype Attribute type.
|
||||
* @arg msecs Numeric value in micro seconds.
|
||||
*/
|
||||
#define NLA_PUT_MSECS(n, attrtype, msecs) \
|
||||
NLA_PUT_U64(n, attrtype, msecs)
|
||||
#define NLA_PUT_MSECS(msg, attrtype, msecs) \
|
||||
NLA_PUT_U64(msg, attrtype, msecs)
|
||||
|
||||
/**
|
||||
* Add a address attribute to a netlink message
|
||||
* @arg n netlink message
|
||||
* @arg attrtype attribute type
|
||||
* @arg addr abstract address object
|
||||
* Add address attribute to netlink message.
|
||||
* @arg msg Netlink message.
|
||||
* @arg attrtype Attribute type.
|
||||
* @arg addr Abstract address object.
|
||||
*/
|
||||
#define NLA_PUT_ADDR(n, attrtype, addr) \
|
||||
NLA_PUT(n, attrtype, nl_addr_get_len(addr), \
|
||||
#define NLA_PUT_ADDR(msg, attrtype, addr) \
|
||||
NLA_PUT(msg, attrtype, nl_addr_get_len(addr), \
|
||||
nl_addr_get_binary_addr(addr))
|
||||
|
||||
/** @} */
|
||||
|
|
@ -255,7 +244,7 @@ extern struct nl_addr * nla_get_addr(struct nlattr *, int);
|
|||
|
||||
/**
|
||||
* @ingroup attr
|
||||
* iterate over a stream of attributes
|
||||
* Iterate over a stream of attributes
|
||||
* @arg pos loop counter, set to current attribute
|
||||
* @arg head head of attribute stream
|
||||
* @arg len length of attribute stream
|
||||
|
|
@ -268,7 +257,7 @@ extern struct nl_addr * nla_get_addr(struct nlattr *, int);
|
|||
|
||||
/**
|
||||
* @ingroup attr
|
||||
* iterate over a stream of nested attributes
|
||||
* Iterate over a stream of nested attributes
|
||||
* @arg pos loop counter, set to current attribute
|
||||
* @arg nla attribute containing the nested attributes
|
||||
* @arg rem initialized to len, holds bytes currently remaining in stream
|
||||
|
|
|
|||
1119
lib/attr.c
1119
lib/attr.c
File diff suppressed because it is too large
Load diff
Loading…
Add table
Reference in a new issue