include/netlink/attr.h

   1 /*
   2  * netlink/attr.h               Netlink Attributes
   3  *
   4  *      This library is free software; you can redistribute it and/or
   5  *      modify it under the terms of the GNU Lesser General Public
   6  *      License as published by the Free Software Foundation version 2.1
   7  *      of the License.
   8  *
   9  * Copyright (c) 2003-2006 Thomas Graf <tgraf@suug.ch>
  10  */
  11
  12 #ifndef NETLINK_ATTR_H_
  13 #define NETLINK_ATTR_H_
  14
  15 #include <netlink/netlink.h>
  16 #include <netlink/object.h>
  17 #include <netlink/addr.h>
  18 #include <netlink/data.h>
  19
  20 struct nl_msg;
  21
  22 /**
  23  * @name Validation Policy Types
  24  * @{
  25  */
  26
  27  /**
  28   * @ingroup attr
  29   * Standard attribute types to specify validation policy
  30   */
  31 enum {
  32         NLA_UNSPEC,     /**< Unspecified type */
  33         NLA_U8,         /**< 8bit integer */
  34         NLA_U16,        /**< 16bit integer */
  35         NLA_U32,        /**< 32bit integer */
  36         NLA_U64,        /**< 64bit integer */
  37         NLA_STRING,     /**< character string */
  38         NLA_FLAG,       /**< flag */
  39         NLA_MSECS,      /**< micro seconds (64bit) */
  40         NLA_NESTED,     /**< nested attributes */
  41         __NLA_TYPE_MAX,
  42 };
  43
  44 /**
  45  * @ingroup attr
  46  * Maximum netlink validation policy type
  47  */
  48 #define NLA_TYPE_MAX (__NLA_TYPE_MAX - 1)
  49
  50 /** @} */
  51
  52 /**
  53  * @ingroup attr
  54  * attribute validation policy
  55  *
  56  * Policies are defined as arrays of this struct, the array must
  57  * be accessible by attribute type up to the highest identifier
  58  * to be expected.
  59  *
  60  * Example:
  61  * @code
  62  * static struct nla_policy my_policy[ATTR_MAX+1] __read_mostly = {
  63  *      [ATTR_FOO] = { .type = NLA_U16 },
  64  *      [ATTR_BAR] = { .type = NLA_STRING },
  65  *      [ATTR_BAZ] = { .minlen = sizeof(struct mystruct) },
  66  * };
  67  * @endcode
  68  */
  69 struct nla_policy {
  70         /** Type of attribute or NLA_UNSPEC */
  71         uint16_t        type;
  72
  73         /** Minimal length of payload required to be available */
  74         uint16_t        minlen;
  75
  76         /** Maximal length of payload required to be available */
  77         uint16_t        maxlen;
  78 };
  79
  80 /* size calculations */
  81 extern int              nla_attr_size(int payload);
  82 extern int              nla_total_size(int payload);
  83 extern int              nla_padlen(int payload);
  84
  85 /* payload access */
  86 extern void *           nla_data(const struct nlattr *);
  87 extern int              nla_len(const struct nlattr *);
  88
  89 /* attribute parsing */
  90 extern int              nla_ok(const struct nlattr *, int);
  91 extern struct nlattr *  nla_next(const struct nlattr *, int *);
  92 extern int              nla_parse(struct nlattr **, int, struct nlattr *,
  93                                   int, struct nla_policy *);
  94 extern int              nla_parse_nested(struct nlattr **, int, struct nlattr *,
  95                                          struct nla_policy *);
  96 extern int              nla_validate(struct nlattr *, int, int,
  97                                      struct nla_policy *);
  98 extern struct nlattr *  nla_find(struct nlattr *, int, int);
  99
 100 /* utilities */
 101 extern int              nla_memcpy(void *, struct nlattr *, int);
 102 extern size_t           nla_strlcpy(char *, const struct nlattr *, size_t);
 103 extern int              nla_memcmp(const struct nlattr *, const void *, size_t);
 104 extern int              nla_strcmp(const struct nlattr *, const char *);
 105
 106 /* attribute construction */
 107 extern struct nlattr *  nla_reserve(struct nl_msg *, int, int);
 108 extern int              nla_put(struct nl_msg *, int, int, const void *);
 109 extern int              nla_put_nested(struct nl_msg *, int, struct nl_msg *);
 110 extern int              nla_put_u8(struct nl_msg *, int, uint8_t);
 111 extern int              nla_put_u16(struct nl_msg *, int, uint16_t);
 112 extern int              nla_put_u32(struct nl_msg *, int, uint32_t);
 113 extern int              nla_put_u64(struct nl_msg *, int, uint64_t);
 114 extern int              nla_put_string(struct nl_msg *, int, const char *);
 115 extern int              nla_put_flag(struct nl_msg *, int);
 116 extern int              nla_put_msecs(struct nl_msg *, int, unsigned long);
 117 extern int              nla_put_data(struct nl_msg *, int, struct nl_data *);
 118 extern int              nla_put_addr(struct nl_msg *, int, struct nl_addr *);
 119
 120 /* attribute nesting */
 121 extern struct nlattr *  nla_nest_start(struct nl_msg *, int);
 122 extern int              nla_nest_end(struct nl_msg *, struct nlattr *);
 123
 124 /* attribute reading */
 125 extern uint8_t          nla_get_u8(struct nlattr *);
 126 extern uint16_t         nla_get_u16(struct nlattr *);
 127 extern uint32_t         nla_get_u32(struct nlattr *);
 128 extern uint64_t         nla_get_u64(struct nlattr *);
 129 extern int              nla_get_flag(struct nlattr *);
 130 extern unsigned long    nla_get_msecs(struct nlattr *);
 131 extern struct nl_data * nla_get_data(struct nlattr *);
 132 extern struct nl_addr * nla_get_addr(struct nlattr *, int);
 133
 134 /**
 135  * @name Attribute Construction (Exception Based)
 136  *
 137  * All these functions jump to nla_put_failure in case of a failure
 138  * instead of returning an error code.
 139  *
 140  * @{
 141  */
 142
 143 /**
 144  * @ingroup attr
 145  * Add a netlink attribute to a netlink message
 146  * @arg n               netlink message
 147  * @arg attrtype        attribute type
 148  * @arg attrlen         length of attribute payload
 149  * @arg data            head of attribute payload
 150  */
 151 #define NLA_PUT(n, attrtype, attrlen, data) \
 152         do { \
 153                 if (nla_put(n, attrtype, attrlen, data) < 0) \
 154                         goto nla_put_failure; \
 155         } while(0)
 156
 157 /**
 158  * @ingroup attr
 159  * Add a basic netlink attribute to a netlink message
 160  * @arg n               netlink message
 161  * @arg type            atomic type
 162  * @arg attrtype        attribute type
 163  * @arg value           head of attribute payload
 164  */
 165 #define NLA_PUT_TYPE(n, type, attrtype, value) \
 166         do { \
 167                 type __tmp = value; \
 168                 NLA_PUT(n, attrtype, sizeof(type), &__tmp); \
 169         } while(0)
 170
 171 /**
 172  * Add a u8 netlink attribute to a netlink message
 173  * @arg n               netlink message
 174  * @arg attrtype        attribute type
 175  * @arg value           numeric value
 176  */
 177 #define NLA_PUT_U8(n, attrtype, value) \
 178         NLA_PUT_TYPE(n, uint8_t, attrtype, value)
 179
 180 /**
 181  * Add a u16 netlink attribute to a netlink message
 182  * @arg n               netlink message
 183  * @arg attrtype        attribute type
 184  * @arg value           numeric value
 185  */
 186 #define NLA_PUT_U16(n, attrtype, value) \
 187         NLA_PUT_TYPE(n, uint16_t, attrtype, value)
 188
 189 /**
 190  * Add a u32 netlink attribute to a netlink message
 191  * @arg n               netlink message
 192  * @arg attrtype        attribute type
 193  * @arg value           numeric value
 194  */
 195 #define NLA_PUT_U32(n, attrtype, value) \
 196         NLA_PUT_TYPE(n, uint32_t, attrtype, value)
 197
 198 /**
 199  * Add a u64 netlink attribute to a netlink message
 200  * @arg n               netlink message
 201  * @arg attrtype        attribute type
 202  * @arg value           numeric value
 203  */
 204 #define NLA_PUT_U64(n, attrtype, value) \
 205         NLA_PUT_TYPE(n, uint64_t, attrtype, value)
 206
 207 /**
 208  * Add a character string netlink attribute to a netlink message
 209  * @arg n               netlink message
 210  * @arg attrtype        attribute type
 211  * @arg value           character string
 212  */
 213 #define NLA_PUT_STRING(n, attrtype, value) \
 214         NLA_PUT(n, attrtype, strlen(value) + 1, value)
 215
 216 /**
 217  * Add a flag netlink attribute to a netlink message
 218  * @arg n               netlink message
 219  * @arg attrtype        attribute type
 220  */
 221 #define NLA_PUT_FLAG(n, attrtype) \
 222         NLA_PUT(n, attrtype, 0, NULL)
 223
 224 /**
 225  * Add a msecs netlink attribute to a netlink message
 226  * @arg n               netlink message
 227  * @arg attrtype        attribute type
 228  * @arg msecs           numeric value in micro seconds
 229  */
 230 #define NLA_PUT_MSECS(n, attrtype, msecs) \
 231         NLA_PUT_U64(n, attrtype, msecs)
 232
 233 /**
 234  * Add a address attribute to a netlink message
 235  * @arg n               netlink message
 236  * @arg attrtype        attribute type
 237  * @arg addr            abstract address object
 238  */
 239 #define NLA_PUT_ADDR(n, attrtype, addr) \
 240         NLA_PUT(n, attrtype, nl_addr_get_len(addr), \
 241                 nl_addr_get_binary_addr(addr))
 242
 243 /** @} */
 244
 245 /**
 246  * @name Iterators
 247  * @{
 248  */
 249
 250 /**
 251  * @ingroup attr
 252  * iterate over a stream of attributes
 253  * @arg pos     loop counter, set to current attribute
 254  * @arg head    head of attribute stream
 255  * @arg len     length of attribute stream
 256  * @arg rem     initialized to len, holds bytes currently remaining in stream
 257  */
 258 #define nla_for_each_attr(pos, head, len, rem) \
 259         for (pos = head, rem = len; \
 260              nla_ok(pos, rem); \
 261              pos = nla_next(pos, &(rem)))
 262
 263 /** @} */
 264
 265 #endif