libnl  3.2.3
/build/buildd/libnl3-3.2.3/lib/attr.c
00001 /*
00002  * lib/attr.c           Netlink Attributes
00003  *
00004  *      This library is free software; you can redistribute it and/or
00005  *      modify it under the terms of the GNU Lesser General Public
00006  *      License as published by the Free Software Foundation version 2.1
00007  *      of the License.
00008  *
00009  * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch>
00010  */
00011 
00012 #include <netlink-local.h>
00013 #include <netlink/netlink.h>
00014 #include <netlink/utils.h>
00015 #include <netlink/addr.h>
00016 #include <netlink/attr.h>
00017 #include <netlink/msg.h>
00018 #include <linux/socket.h>
00019 
00020 /**
00021  * @ingroup msg
00022  * @defgroup attr Attributes
00023  * Netlink Attributes Construction/Parsing Interface
00024  *
00025  * \section attr_sec Netlink Attributes
00026  * Netlink attributes allow for data chunks of arbitary length to be
00027  * attached to a netlink message. Each attribute is encoded with a
00028  * type and length field, both 16 bits, stored in the attribute header
00029  * preceding the attribute data. The main advantage of using attributes
00030  * over packing everything into the family header is that the interface
00031  * stays extendable as new attributes can supersede old attributes while
00032  * remaining backwards compatible. Also attributes can be defined optional
00033  * thus avoiding the transmission of unnecessary empty data blocks.
00034  * Special nested attributes allow for more complex data structures to
00035  * be transmitted, e.g. trees, lists, etc.
00036  *
00037  * While not required, netlink attributes typically follow the family
00038  * header of a netlink message and must be properly aligned to NLA_ALIGNTO:
00039  * @code
00040  *   +----------------+- - -+---------------+- - -+------------+- - -+
00041  *   | Netlink Header | Pad | Family Header | Pad | Attributes | Pad |
00042  *   +----------------+- - -+---------------+- - -+------------+- - -+
00043  * @endcode
00044  *
00045  * The actual attributes are chained together each separately aligned to
00046  * NLA_ALIGNTO. The position of an attribute is defined based on the
00047  * length field of the preceding attributes:
00048  * @code
00049  *   +-------------+- - -+-------------+- - -+------
00050  *   | Attribute 1 | Pad | Attribute 2 | Pad | ...
00051  *   +-------------+- - -+-------------+- - -+------
00052  *   nla_next(attr1)------^
00053  * @endcode
00054  *
00055  * The attribute itself consists of the attribute header followed by
00056  * the actual payload also aligned to NLA_ALIGNTO. The function nla_data()
00057  * returns a pointer to the start of the payload while nla_len() returns
00058  * the length of the payload in bytes.
00059  *
00060  * \b Note: Be aware, NLA_ALIGNTO equals to 4 bytes, therefore it is not
00061  * safe to dereference any 64 bit data types directly.
00062  *
00063  * @code
00064  *    <----------- nla_total_size(payload) ----------->
00065  *    <-------- nla_attr_size(payload) --------->
00066  *   +------------------+- - -+- - - - - - - - - +- - -+
00067  *   | Attribute Header | Pad |     Payload      | Pad |
00068  *   +------------------+- - -+- - - - - - - - - +- - -+
00069  *   nla_data(nla)-------------^
00070  *                             <- nla_len(nla) ->
00071  * @endcode
00072  *
00073  * @subsection attr_datatypes Attribute Data Types
00074  * A number of basic data types are supported to simplify access and
00075  * validation of netlink attributes. This data type information is
00076  * not encoded in the attribute, both the kernel and userspace part
00077  * are required to share this information on their own.
00078  *
00079  * One of the major advantages of these basic types is the automatic
00080  * validation of each attribute based on an attribute policy. The
00081  * validation covers most of the checks required to safely use
00082  * attributes and thus keeps the individual sanity check to a minimum.
00083  *
00084  * Never access attribute payload without ensuring basic validation
00085  * first, attributes may:
00086  * - not be present even though required
00087  * - contain less actual payload than expected
00088  * - fake a attribute length which exceeds the end of the message
00089  * - contain unterminated character strings
00090  *
00091  * Policies are defined as array of the struct nla_policy. The array is
00092  * indexed with the attribute type, therefore the array must be sized
00093  * accordingly.
00094  * @code
00095  * static struct nla_policy my_policy[ATTR_MAX+1] = {
00096  *      [ATTR_FOO] = { .type = ..., .minlen = ..., .maxlen = ... },
00097  * };
00098  *
00099  * err = nla_validate(attrs, attrlen, ATTR_MAX, &my_policy);
00100  * @endcode
00101  *
00102  * Some basic validations are performed on every attribute, regardless of type.
00103  * - If the attribute type exceeds the maximum attribute type specified or
00104  *   the attribute type is lesser-or-equal than zero, the attribute will
00105  *   be silently ignored.
00106  * - If the payload length falls below the \a minlen value the attribute
00107  *   will be rejected.
00108  * - If \a maxlen is non-zero and the payload length exceeds the \a maxlen
00109  *   value the attribute will be rejected.
00110  *
00111  *
00112  * @par Unspecific Attribute (NLA_UNSPEC)
00113  * This is the standard type if no type is specified. It is used for
00114  * binary data of arbitary length. Typically this attribute carries
00115  * a binary structure or a stream of bytes.
00116  * @par
00117  * @code
00118  * // In this example, we will assume a binary structure requires to
00119  * // be transmitted. The definition of the structure will typically
00120  * // go into a header file available to both the kernel and userspace
00121  * // side.
00122  * //
00123  * // Note: Be careful when putting 64 bit data types into a structure.
00124  * // The attribute payload is only aligned to 4 bytes, dereferencing
00125  * // the member may fail.
00126  * struct my_struct {
00127  *     int a;
00128  *     int b;
00129  * };
00130  *
00131  * // The validation function will not enforce an exact length match to
00132  * // allow structures to grow as required. Note: While it is allowed
00133  * // to add members to the end of the structure, changing the order or
00134  * // inserting members in the middle of the structure will break your
00135  * // binary interface.
00136  * static struct nla_policy my_policy[ATTR_MAX+1] = {
00137  *     [ATTR_MY_STRICT] = { .type = NLA_UNSPEC,
00138  *                          .minlen = sizeof(struct my_struct) },
00139  *
00140  * // The binary structure is appened to the message using nla_put()
00141  * struct my_struct foo = { .a = 1, .b = 2 };
00142  * nla_put(msg, ATTR_MY_STRUCT, sizeof(foo), &foo);
00143  *
00144  * // On the receiving side, a pointer to the structure pointing inside
00145  * // the message payload is returned by nla_get().
00146  * if (attrs[ATTR_MY_STRUCT])
00147  *     struct my_struct *foo = nla_get(attrs[ATTR_MY_STRUCT]);
00148  * @endcode
00149  *
00150  * @par Integers (NLA_U8, NLA_U16, NLA_U32, NLA_U64)
00151  * Integers come in different sizes from 8 bit to 64 bit. However, since the
00152  * payload length is aligned to 4 bytes, integers smaller than 32 bit are
00153  * only useful to enforce the maximum range of values.
00154  * @par
00155  * \b Note: There is no difference made between signed and unsigned integers.
00156  * The validation only enforces the minimal payload length required to store
00157  * an integer of specified type.
00158  * @par
00159  * @code
00160  * // Even though possible, it does not make sense to specify .minlen or
00161  * // .maxlen for integer types. The data types implies the corresponding
00162  * // minimal payload length.
00163  * static struct nla_policy my_policy[ATTR_MAX+1] = {
00164  *     [ATTR_FOO] = { .type = NLA_U32 },
00165  *
00166  * // Numeric values can be appended directly using the respective
00167  * // nla_put_uxxx() function
00168  * nla_put_u32(msg, ATTR_FOO, 123);
00169  *
00170  * // Same for the receiving side.
00171  * if (attrs[ATTR_FOO])
00172  *     uint32_t foo = nla_get_u32(attrs[ATTR_FOO]);
00173  * @endcode
00174  *
00175  * @par Character string (NLA_STRING)
00176  * This data type represents a NUL terminated character string of variable
00177  * length. For binary data streams the type NLA_UNSPEC is recommended.
00178  * @par
00179  * @code
00180  * // Enforce a NUL terminated character string of at most 4 characters
00181  * // including the NUL termination.
00182  * static struct nla_policy my_policy[ATTR_MAX+1] = {
00183  *     [ATTR_BAR] = { .type = NLA_STRING, maxlen = 4 },
00184  *
00185  * // nla_put_string() creates a string attribute of the necessary length
00186  * // and appends it to the message including the NUL termination.
00187  * nla_put_string(msg, ATTR_BAR, "some text");
00188  *
00189  * // It is safe to use the returned character string directly if the
00190  * // attribute has been validated as the validation enforces the proper
00191  * // termination of the string.
00192  * if (attrs[ATTR_BAR])
00193  *     char *text = nla_get_string(attrs[ATTR_BAR]);
00194  * @endcode
00195  *
00196  * @par Flag (NLA_FLAG)
00197  * This attribute type may be used to indicate the presence of a flag. The
00198  * attribute is only valid if the payload length is zero. The presence of
00199  * the attribute header indicates the presence of the flag.
00200  * @par
00201  * @code
00202  * // This attribute type is special as .minlen and .maxlen have no effect.
00203  * static struct nla_policy my_policy[ATTR_MAX+1] = {
00204  *     [ATTR_FLAG] = { .type = NLA_FLAG },
00205  *
00206  * // nla_put_flag() appends a zero sized attribute to the message.
00207  * nla_put_flag(msg, ATTR_FLAG);
00208  *
00209  * // There is no need for a receival function, the presence is the value.
00210  * if (attrs[ATTR_FLAG])
00211  *     // flag is present
00212  * @endcode
00213  *
00214  * @par Micro Seconds (NLA_MSECS)
00215  *
00216  * @par Nested Attribute (NLA_NESTED)
00217  * Attributes can be nested and put into a container to create groups, lists
00218  * or to construct trees of attributes. Nested attributes are often used to
00219  * pass attributes to a subsystem where the top layer has no knowledge of the
00220  * configuration possibilities of each subsystem.
00221  * @par
00222  * \b Note: When validating the attributes using nlmsg_validate() or
00223  * nlmsg_parse() it will only affect the top level attributes. Each
00224  * level of nested attributes must be validated seperately using
00225  * nla_parse_nested() or nla_validate().
00226  * @par
00227  * @code
00228  * // The minimal length policy may be used to enforce the presence of at
00229  * // least one attribute.
00230  * static struct nla_policy my_policy[ATTR_MAX+1] = {
00231  *     [ATTR_OPTS] = { .type = NLA_NESTED, minlen = NLA_HDRLEN },
00232  *
00233  * // Nested attributes are constructed by enclosing the attributes
00234  * // to be nested with calls to nla_nest_start() respetively nla_nest_end().
00235  * struct nlattr *opts = nla_nest_start(msg, ATTR_OPTS);
00236  * nla_put_u32(msg, ATTR_FOO, 123);
00237  * nla_put_string(msg, ATTR_BAR, "some text");
00238  * nla_nest_end(msg, opts);
00239  *
00240  * // Various methods exist to parse nested attributes, the easiest being
00241  * // nla_parse_nested() which also allows validation in the same step.
00242  * if (attrs[ATTR_OPTS]) {
00243  *     struct nlattr *nested[ATTR_MAX+1];
00244  *
00245  *     nla_parse_nested(nested, ATTR_MAX, attrs[ATTR_OPTS], &policy);
00246  *
00247  *     if (nested[ATTR_FOO])
00248  *         uint32_t foo = nla_get_u32(nested[ATTR_FOO]);
00249  * }
00250  * @endcode
00251  *
00252  * @subsection attr_exceptions Exception Based Attribute Construction
00253  * Often a large number of attributes are added to a message in a single
00254  * function. In order to simplify error handling, a second set of
00255  * construction functions exist which jump to a error label when they
00256  * fail instead of returning an error code. This second set consists
00257  * of macros which are named after their error code based counterpart
00258  * except that the name is written all uppercase.
00259  *
00260  * All of the macros jump to the target \c nla_put_failure if they fail.
00261  * @code
00262  * void my_func(struct nl_msg *msg)
00263  * {
00264  *     NLA_PUT_U32(msg, ATTR_FOO, 10);
00265  *     NLA_PUT_STRING(msg, ATTR_BAR, "bar");
00266  *
00267  *     return 0;
00268  *
00269  * nla_put_failure:
00270  *     return -NLE_NOMEM;
00271  * }
00272  * @endcode
00273  *
00274  * @subsection attr_examples Examples
00275  * @par Example 1.1 Constructing a netlink message with attributes.
00276  * @code
00277  * struct nl_msg *build_msg(int ifindex, struct nl_addr *lladdr, int mtu)
00278  * {
00279  *     struct nl_msg *msg;
00280  *     struct nlattr *info, *vlan;
00281  *     struct ifinfomsg ifi = {
00282  *         .ifi_family = AF_INET,
00283  *         .ifi_index = ifindex,
00284  *     };
00285  *
00286  *     // Allocate a new netlink message, type=RTM_SETLINK, flags=NLM_F_ECHO
00287  *     if (!(msg = nlmsg_alloc_simple(RTM_SETLINK, NLM_F_ECHO)))
00288  *         return NULL;
00289  *
00290  *     // Append the family specific header (struct ifinfomsg)
00291  *     if (nlmsg_append(msg, &ifi, sizeof(ifi), NLMSG_ALIGNTO) < 0)
00292  *         goto nla_put_failure
00293  *
00294  *     // Append a 32 bit integer attribute to carry the MTU
00295  *     NLA_PUT_U32(msg, IFLA_MTU, mtu);
00296  *
00297  *     // Append a unspecific attribute to carry the link layer address
00298  *     NLA_PUT_ADDR(msg, IFLA_ADDRESS, lladdr);
00299  *
00300  *     // Append a container for nested attributes to carry link information
00301  *     if (!(info = nla_nest_start(msg, IFLA_LINKINFO)))
00302  *         goto nla_put_failure;
00303  *
00304  *     // Put a string attribute into the container
00305  *     NLA_PUT_STRING(msg, IFLA_INFO_KIND, "vlan");
00306  *
00307  *     // Append another container inside the open container to carry
00308  *     // vlan specific attributes
00309  *     if (!(vlan = nla_nest_start(msg, IFLA_INFO_DATA)))
00310  *         goto nla_put_failure;
00311  *
00312  *     // add vlan specific info attributes here...
00313  *
00314  *     // Finish nesting the vlan attributes and close the second container.
00315  *     nla_nest_end(msg, vlan);
00316  *
00317  *     // Finish nesting the link info attribute and close the first container.
00318  *     nla_nest_end(msg, info);
00319  *
00320  *     return msg;
00321  *
00322  * // If any of the construction macros fails, we end up here.
00323  * nla_put_failure:
00324  *     nlmsg_free(msg);
00325  *     return NULL;
00326  * }
00327  * @endcode
00328  *
00329  * @par Example 2.1 Parsing a netlink message with attributes.
00330  * @code
00331  * int parse_message(struct nl_msg *msg)
00332  * {
00333  *     // The policy defines two attributes: a 32 bit integer and a container
00334  *     // for nested attributes.
00335  *     struct nla_policy attr_policy[ATTR_MAX+1] = {
00336  *         [ATTR_FOO] = { .type = NLA_U32 },
00337  *         [ATTR_BAR] = { .type = NLA_NESTED },
00338  *     };
00339  *     struct nlattr *attrs[ATTR_MAX+1];
00340  *     int err;
00341  *
00342  *     // The nlmsg_parse() function will make sure that the message contains
00343  *     // enough payload to hold the header (struct my_hdr), validates any
00344  *     // attributes attached to the messages and stores a pointer to each
00345  *     // attribute in the attrs[] array accessable by attribute type.
00346  *     if ((err = nlmsg_parse(nlmsg_hdr(msg), sizeof(struct my_hdr), attrs,
00347  *                            ATTR_MAX, attr_policy)) < 0)
00348  *         goto errout;
00349  *
00350  *     if (attrs[ATTR_FOO]) {
00351  *         // It is safe to directly access the attribute payload without
00352  *         // any further checks since nlmsg_parse() enforced the policy.
00353  *         uint32_t foo = nla_get_u32(attrs[ATTR_FOO]);
00354  *     }
00355  *
00356  *     if (attrs[ATTR_BAR]) {
00357  *         struct nlattr *nested[NESTED_MAX+1];
00358  *
00359  *         // Attributes nested in a container can be parsed the same way
00360  *         // as top level attributes.
00361  *         if ((err = nla_parse_nested(nested, NESTED_MAX, attrs[ATTR_BAR],
00362  *                                     nested_policy)) < 0)
00363  *             goto errout;
00364  *
00365  *         // Process nested attributes here.
00366  *     }
00367  *
00368  *     err = 0;
00369  * errout:
00370  *     return err;
00371  * }
00372  * @endcode
00373  *
00374  * @{
00375  */
00376 
00377 /**
00378  * @name Attribute Size Calculation
00379  * @{
00380  */
00381 
00382 /**
00383  * Return size of attribute whithout padding.
00384  * @arg payload         Payload length of attribute.
00385  *
00386  * @code
00387  *    <-------- nla_attr_size(payload) --------->
00388  *   +------------------+- - -+- - - - - - - - - +- - -+
00389  *   | Attribute Header | Pad |     Payload      | Pad |
00390  *   +------------------+- - -+- - - - - - - - - +- - -+
00391  * @endcode
00392  *
00393  * @return Size of attribute in bytes without padding.
00394  */
00395 int nla_attr_size(int payload)
00396 {
00397         return NLA_HDRLEN + payload;
00398 }
00399 
00400 /**
00401  * Return size of attribute including padding.
00402  * @arg payload         Payload length of attribute.
00403  *
00404  * @code
00405  *    <----------- nla_total_size(payload) ----------->
00406  *   +------------------+- - -+- - - - - - - - - +- - -+
00407  *   | Attribute Header | Pad |     Payload      | Pad |
00408  *   +------------------+- - -+- - - - - - - - - +- - -+
00409  * @endcode
00410  *
00411  * @return Size of attribute in bytes.
00412  */
00413 int nla_total_size(int payload)
00414 {
00415         return NLA_ALIGN(nla_attr_size(payload));
00416 }
00417 
00418 /**
00419  * Return length of padding at the tail of the attribute.
00420  * @arg payload         Payload length of attribute.
00421  *
00422  * @code
00423  *   +------------------+- - -+- - - - - - - - - +- - -+
00424  *   | Attribute Header | Pad |     Payload      | Pad |
00425  *   +------------------+- - -+- - - - - - - - - +- - -+
00426  *                                                <--->  
00427  * @endcode
00428  *
00429  * @return Length of padding in bytes.
00430  */
00431 int nla_padlen(int payload)
00432 {
00433         return nla_total_size(payload) - nla_attr_size(payload);
00434 }
00435 
00436 /** @} */
00437 
00438 /**
00439  * @name Parsing Attributes
00440  * @{
00441  */
00442 
00443 /**
00444  * Return type of the attribute.
00445  * @arg nla             Attribute.
00446  *
00447  * @return Type of attribute.
00448  */
00449 int nla_type(const struct nlattr *nla)
00450 {
00451         return nla->nla_type & NLA_TYPE_MASK;
00452 }
00453 
00454 /**
00455  * Return pointer to the payload section.
00456  * @arg nla             Attribute.
00457  *
00458  * @return Pointer to start of payload section.
00459  */
00460 void *nla_data(const struct nlattr *nla)
00461 {
00462         return (char *) nla + NLA_HDRLEN;
00463 }
00464 
00465 /**
00466  * Return length of the payload .
00467  * @arg nla             Attribute
00468  *
00469  * @return Length of payload in bytes.
00470  */
00471 int nla_len(const struct nlattr *nla)
00472 {
00473         return nla->nla_len - NLA_HDRLEN;
00474 }
00475 
00476 /**
00477  * Check if the attribute header and payload can be accessed safely.
00478  * @arg nla             Attribute of any kind.
00479  * @arg remaining       Number of bytes remaining in attribute stream.
00480  *
00481  * Verifies that the header and payload do not exceed the number of
00482  * bytes left in the attribute stream. This function must be called
00483  * before access the attribute header or payload when iterating over
00484  * the attribute stream using nla_next().
00485  *
00486  * @return True if the attribute can be accessed safely, false otherwise.
00487  */
00488 int nla_ok(const struct nlattr *nla, int remaining)
00489 {
00490         return remaining >= sizeof(*nla) &&
00491                nla->nla_len >= sizeof(*nla) &&
00492                nla->nla_len <= remaining;
00493 }
00494 
00495 /**
00496  * Return next attribute in a stream of attributes.
00497  * @arg nla             Attribute of any kind.
00498  * @arg remaining       Variable to count remaining bytes in stream.
00499  *
00500  * Calculates the offset to the next attribute based on the attribute
00501  * given. The attribute provided is assumed to be accessible, the
00502  * caller is responsible to use nla_ok() beforehand. The offset (length
00503  * of specified attribute including padding) is then subtracted from
00504  * the remaining bytes variable and a pointer to the next attribute is
00505  * returned.
00506  *
00507  * nla_next() can be called as long as remainig is >0.
00508  *
00509  * @return Pointer to next attribute.
00510  */
00511 struct nlattr *nla_next(const struct nlattr *nla, int *remaining)
00512 {
00513         int totlen = NLA_ALIGN(nla->nla_len);
00514 
00515         *remaining -= totlen;
00516         return (struct nlattr *) ((char *) nla + totlen);
00517 }
00518 
00519 static uint16_t nla_attr_minlen[NLA_TYPE_MAX+1] = {
00520         [NLA_U8]        = sizeof(uint8_t),
00521         [NLA_U16]       = sizeof(uint16_t),
00522         [NLA_U32]       = sizeof(uint32_t),
00523         [NLA_U64]       = sizeof(uint64_t),
00524         [NLA_STRING]    = 1,
00525 };
00526 
00527 static int validate_nla(struct nlattr *nla, int maxtype,
00528                         struct nla_policy *policy)
00529 {
00530         struct nla_policy *pt;
00531         int minlen = 0, type = nla_type(nla);
00532 
00533         if (type <= 0 || type > maxtype)
00534                 return 0;
00535 
00536         pt = &policy[type];
00537 
00538         if (pt->type > NLA_TYPE_MAX)
00539                 BUG();
00540 
00541         if (pt->minlen)
00542                 minlen = pt->minlen;
00543         else if (pt->type != NLA_UNSPEC)
00544                 minlen = nla_attr_minlen[pt->type];
00545 
00546         if (pt->type == NLA_FLAG && nla_len(nla) > 0)
00547                 return -NLE_RANGE;
00548 
00549         if (nla_len(nla) < minlen)
00550                 return -NLE_RANGE;
00551 
00552         if (pt->maxlen && nla_len(nla) > pt->maxlen)
00553                 return -NLE_RANGE;
00554 
00555         if (pt->type == NLA_STRING) {
00556                 char *data = nla_data(nla);
00557                 if (data[nla_len(nla) - 1] != '\0')
00558                         return -NLE_INVAL;
00559         }
00560 
00561         return 0;
00562 }
00563 
00564 
00565 /**
00566  * Create attribute index based on a stream of attributes.
00567  * @arg tb              Index array to be filled (maxtype+1 elements).
00568  * @arg maxtype         Maximum attribute type expected and accepted.
00569  * @arg head            Head of attribute stream.
00570  * @arg len             Length of attribute stream.
00571  * @arg policy          Attribute validation policy.
00572  *
00573  * Iterates over the stream of attributes and stores a pointer to each
00574  * attribute in the index array using the attribute type as index to
00575  * the array. Attribute with a type greater than the maximum type
00576  * specified will be silently ignored in order to maintain backwards
00577  * compatibility. If \a policy is not NULL, the attribute will be
00578  * validated using the specified policy.
00579  *
00580  * @see nla_validate
00581  * @return 0 on success or a negative error code.
00582  */
00583 int nla_parse(struct nlattr *tb[], int maxtype, struct nlattr *head, int len,
00584               struct nla_policy *policy)
00585 {
00586         struct nlattr *nla;
00587         int rem, err;
00588 
00589         memset(tb, 0, sizeof(struct nlattr *) * (maxtype + 1));
00590 
00591         nla_for_each_attr(nla, head, len, rem) {
00592                 int type = nla_type(nla);
00593 
00594                 if (type == 0) {
00595                         fprintf(stderr, "Illegal nla->nla_type == 0\n");
00596                         continue;
00597                 }
00598 
00599                 if (type <= maxtype) {
00600                         if (policy) {
00601                                 err = validate_nla(nla, maxtype, policy);
00602                                 if (err < 0)
00603                                         goto errout;
00604                         }
00605 
00606                         tb[type] = nla;
00607                 }
00608         }
00609 
00610         if (rem > 0)
00611                 fprintf(stderr, "netlink: %d bytes leftover after parsing "
00612                        "attributes.\n", rem);
00613 
00614         err = 0;
00615 errout:
00616         return err;
00617 }
00618 
00619 /**
00620  * Validate a stream of attributes.
00621  * @arg head            Head of attributes stream.
00622  * @arg len             Length of attributes stream.
00623  * @arg maxtype         Maximum attribute type expected and accepted.
00624  * @arg policy          Validation policy.
00625  *
00626  * Iterates over the stream of attributes and validates each attribute
00627  * one by one using the specified policy. Attributes with a type greater
00628  * than the maximum type specified will be silently ignored in order to
00629  * maintain backwards compatibility.
00630  *
00631  * See \ref attr_datatypes for more details on what kind of validation
00632  * checks are performed on each attribute data type.
00633  *
00634  * @return 0 on success or a negative error code.
00635  */
00636 int nla_validate(struct nlattr *head, int len, int maxtype,
00637                  struct nla_policy *policy)
00638 {
00639         struct nlattr *nla;
00640         int rem, err;
00641 
00642         nla_for_each_attr(nla, head, len, rem) {
00643                 err = validate_nla(nla, maxtype, policy);
00644                 if (err < 0)
00645                         goto errout;
00646         }
00647 
00648         err = 0;
00649 errout:
00650         return err;
00651 }
00652 
00653 /**
00654  * Find a single attribute in a stream of attributes.
00655  * @arg head            Head of attributes stream.
00656  * @arg len             Length of attributes stream.
00657  * @arg attrtype        Attribute type to look for.
00658  *
00659  * Iterates over the stream of attributes and compares each type with
00660  * the type specified. Returns the first attribute which matches the
00661  * type.
00662  *
00663  * @return Pointer to attribute found or NULL.
00664  */
00665 struct nlattr *nla_find(struct nlattr *head, int len, int attrtype)
00666 {
00667         struct nlattr *nla;
00668         int rem;
00669 
00670         nla_for_each_attr(nla, head, len, rem)
00671                 if (nla_type(nla) == attrtype)
00672                         return nla;
00673 
00674         return NULL;
00675 }
00676 
00677 /** @} */
00678 
00679 /**
00680  * @name Helper Functions
00681  * @{
00682  */
00683 
00684 /**
00685  * Copy attribute payload to another memory area.
00686  * @arg dest            Pointer to destination memory area.
00687  * @arg src             Attribute
00688  * @arg count           Number of bytes to copy at most.
00689  *
00690  * Note: The number of bytes copied is limited by the length of
00691  *       the attribute payload.
00692  *
00693  * @return The number of bytes copied to dest.
00694  */
00695 int nla_memcpy(void *dest, struct nlattr *src, int count)
00696 {
00697         int minlen;
00698 
00699         if (!src)
00700                 return 0;
00701         
00702         minlen = min_t(int, count, nla_len(src));
00703         memcpy(dest, nla_data(src), minlen);
00704 
00705         return minlen;
00706 }
00707 
00708 /**
00709  * Copy string attribute payload to a buffer.
00710  * @arg dst             Pointer to destination buffer.
00711  * @arg nla             Attribute of type NLA_STRING.
00712  * @arg dstsize         Size of destination buffer in bytes.
00713  *
00714  * Copies at most dstsize - 1 bytes to the destination buffer.
00715  * The result is always a valid NUL terminated string. Unlike
00716  * strlcpy the destination buffer is always padded out.
00717  *
00718  * @return The length of string attribute without the terminating NUL.
00719  */
00720 size_t nla_strlcpy(char *dst, const struct nlattr *nla, size_t dstsize)
00721 {
00722         size_t srclen = nla_len(nla);
00723         char *src = nla_data(nla);
00724 
00725         if (srclen > 0 && src[srclen - 1] == '\0')
00726                 srclen--;
00727 
00728         if (dstsize > 0) {
00729                 size_t len = (srclen >= dstsize) ? dstsize - 1 : srclen;
00730 
00731                 memset(dst, 0, dstsize);
00732                 memcpy(dst, src, len);
00733         }
00734 
00735         return srclen;
00736 }
00737 
00738 /**
00739  * Compare attribute payload with memory area.
00740  * @arg nla             Attribute.
00741  * @arg data            Memory area to compare to.
00742  * @arg size            Number of bytes to compare.
00743  *
00744  * @see memcmp(3)
00745  * @return An integer less than, equal to, or greater than zero.
00746  */
00747 int nla_memcmp(const struct nlattr *nla, const void *data, size_t size)
00748 {
00749         int d = nla_len(nla) - size;
00750 
00751         if (d == 0)
00752                 d = memcmp(nla_data(nla), data, size);
00753 
00754         return d;
00755 }
00756 
00757 /**
00758  * Compare string attribute payload with string
00759  * @arg nla             Attribute of type NLA_STRING.
00760  * @arg str             NUL terminated string.
00761  *
00762  * @see strcmp(3)
00763  * @return An integer less than, equal to, or greater than zero.
00764  */
00765 int nla_strcmp(const struct nlattr *nla, const char *str)
00766 {
00767         int len = strlen(str) + 1;
00768         int d = nla_len(nla) - len;
00769 
00770         if (d == 0)
00771                 d = memcmp(nla_data(nla), str, len);
00772 
00773         return d;
00774 }
00775 
00776 /** @} */
00777 
00778 /**
00779  * @name Unspecific Attribute
00780  * @{
00781  */
00782 
00783 /**
00784  * Reserve space for a attribute.
00785  * @arg msg             Netlink Message.
00786  * @arg attrtype        Attribute Type.
00787  * @arg attrlen         Length of payload.
00788  *
00789  * Reserves room for a attribute in the specified netlink message and
00790  * fills in the attribute header (type, length). Returns NULL if there
00791  * is unsuficient space for the attribute.
00792  *
00793  * Any padding between payload and the start of the next attribute is
00794  * zeroed out.
00795  *
00796  * @return Pointer to start of attribute or NULL on failure.
00797  */
00798 struct nlattr *nla_reserve(struct nl_msg *msg, int attrtype, int attrlen)
00799 {
00800         struct nlattr *nla;
00801         int tlen;
00802         
00803         tlen = NLMSG_ALIGN(msg->nm_nlh->nlmsg_len) + nla_total_size(attrlen);
00804 
00805         if ((tlen + msg->nm_nlh->nlmsg_len) > msg->nm_size)
00806                 return NULL;
00807 
00808         nla = (struct nlattr *) nlmsg_tail(msg->nm_nlh);
00809         nla->nla_type = attrtype;
00810         nla->nla_len = nla_attr_size(attrlen);
00811 
00812         if (attrlen)
00813                 memset((unsigned char *) nla + nla->nla_len, 0, nla_padlen(attrlen));
00814         msg->nm_nlh->nlmsg_len = tlen;
00815 
00816         NL_DBG(2, "msg %p: attr <%p> %d: Reserved %d (%d) bytes at offset +%td "
00817                   "nlmsg_len=%d\n", msg, nla, nla->nla_type,
00818                   nla_total_size(attrlen), attrlen,
00819                   (void *) nla - nlmsg_data(msg->nm_nlh),
00820                   msg->nm_nlh->nlmsg_len);
00821 
00822         return nla;
00823 }
00824 
00825 /**
00826  * Add a unspecific attribute to netlink message.
00827  * @arg msg             Netlink message.
00828  * @arg attrtype        Attribute type.
00829  * @arg datalen         Length of data to be used as payload.
00830  * @arg data            Pointer to data to be used as attribute payload.
00831  *
00832  * Reserves room for a unspecific attribute and copies the provided data
00833  * into the message as payload of the attribute. Returns an error if there
00834  * is insufficient space for the attribute.
00835  *
00836  * @see nla_reserve
00837  * @return 0 on success or a negative error code.
00838  */
00839 int nla_put(struct nl_msg *msg, int attrtype, int datalen, const void *data)
00840 {
00841         struct nlattr *nla;
00842 
00843         nla = nla_reserve(msg, attrtype, datalen);
00844         if (!nla)
00845                 return -NLE_NOMEM;
00846 
00847         if (datalen > 0) {
00848                 memcpy(nla_data(nla), data, datalen);
00849                 NL_DBG(2, "msg %p: attr <%p> %d: Wrote %d bytes at offset +%td\n",
00850                        msg, nla, nla->nla_type, datalen,
00851                        (void *) nla - nlmsg_data(msg->nm_nlh));
00852         }
00853 
00854         return 0;
00855 }
00856 
00857 /**
00858  * Add abstract data as unspecific attribute to netlink message.
00859  * @arg msg             Netlink message.
00860  * @arg attrtype        Attribute type.
00861  * @arg data            Abstract data object.
00862  *
00863  * Equivalent to nla_put() except that the length of the payload is
00864  * derived from the abstract data object.
00865  *
00866  * @see nla_put
00867  * @return 0 on success or a negative error code.
00868  */
00869 int nla_put_data(struct nl_msg *msg, int attrtype, struct nl_data *data)
00870 {
00871         return nla_put(msg, attrtype, nl_data_get_size(data),
00872                        nl_data_get(data));
00873 }
00874 
00875 /**
00876  * Add abstract address as unspecific attribute to netlink message.
00877  * @arg msg             Netlink message.
00878  * @arg attrtype        Attribute type.
00879  * @arg addr            Abstract address object.
00880  *
00881  * @see nla_put
00882  * @return 0 on success or a negative error code.
00883  */
00884 int nla_put_addr(struct nl_msg *msg, int attrtype, struct nl_addr *addr)
00885 {
00886         return nla_put(msg, attrtype, nl_addr_get_len(addr),
00887                        nl_addr_get_binary_addr(addr));
00888 }
00889 
00890 /** @} */
00891 
00892 /**
00893  * @name Integer Attributes
00894  */
00895 
00896 /**
00897  * Add 8 bit integer attribute to netlink message.
00898  * @arg msg             Netlink message.
00899  * @arg attrtype        Attribute type.
00900  * @arg value           Numeric value to store as payload.
00901  *
00902  * @see nla_put
00903  * @return 0 on success or a negative error code.
00904  */
00905 int nla_put_u8(struct nl_msg *msg, int attrtype, uint8_t value)
00906 {
00907         return nla_put(msg, attrtype, sizeof(uint8_t), &value);
00908 }
00909 
00910 /**
00911  * Return value of 8 bit integer attribute.
00912  * @arg nla             8 bit integer attribute
00913  *
00914  * @return Payload as 8 bit integer.
00915  */
00916 uint8_t nla_get_u8(struct nlattr *nla)
00917 {
00918         return *(uint8_t *) nla_data(nla);
00919 }
00920 
00921 /**
00922  * Add 16 bit integer attribute to netlink message.
00923  * @arg msg             Netlink message.
00924  * @arg attrtype        Attribute type.
00925  * @arg value           Numeric value to store as payload.
00926  *
00927  * @see nla_put
00928  * @return 0 on success or a negative error code.
00929  */
00930 int nla_put_u16(struct nl_msg *msg, int attrtype, uint16_t value)
00931 {
00932         return nla_put(msg, attrtype, sizeof(uint16_t), &value);
00933 }
00934 
00935 /**
00936  * Return payload of 16 bit integer attribute.
00937  * @arg nla             16 bit integer attribute
00938  *
00939  * @return Payload as 16 bit integer.
00940  */
00941 uint16_t nla_get_u16(struct nlattr *nla)
00942 {
00943         return *(uint16_t *) nla_data(nla);
00944 }
00945 
00946 /**
00947  * Add 32 bit integer attribute to netlink message.
00948  * @arg msg             Netlink message.
00949  * @arg attrtype        Attribute type.
00950  * @arg value           Numeric value to store as payload.
00951  *
00952  * @see nla_put
00953  * @return 0 on success or a negative error code.
00954  */
00955 int nla_put_u32(struct nl_msg *msg, int attrtype, uint32_t value)
00956 {
00957         return nla_put(msg, attrtype, sizeof(uint32_t), &value);
00958 }
00959 
00960 /**
00961  * Return payload of 32 bit integer attribute.
00962  * @arg nla             32 bit integer attribute.
00963  *
00964  * @return Payload as 32 bit integer.
00965  */
00966 uint32_t nla_get_u32(struct nlattr *nla)
00967 {
00968         return *(uint32_t *) nla_data(nla);
00969 }
00970 
00971 /**
00972  * Add 64 bit integer attribute to netlink message.
00973  * @arg msg             Netlink message.
00974  * @arg attrtype        Attribute type.
00975  * @arg value           Numeric value to store as payload.
00976  *
00977  * @see nla_put
00978  * @return 0 on success or a negative error code.
00979  */
00980 int nla_put_u64(struct nl_msg *msg, int attrtype, uint64_t value)
00981 {
00982         return nla_put(msg, attrtype, sizeof(uint64_t), &value);
00983 }
00984 
00985 /**
00986  * Return payload of u64 attribute
00987  * @arg nla             u64 netlink attribute
00988  *
00989  * @return Payload as 64 bit integer.
00990  */
00991 uint64_t nla_get_u64(struct nlattr *nla)
00992 {
00993         uint64_t tmp;
00994 
00995         nla_memcpy(&tmp, nla, sizeof(tmp));
00996 
00997         return tmp;
00998 }
00999 
01000 /** @} */
01001 
01002 /**
01003  * @name String Attribute
01004  */
01005 
01006 /**
01007  * Add string attribute to netlink message.
01008  * @arg msg             Netlink message.
01009  * @arg attrtype        Attribute type.
01010  * @arg str             NUL terminated string.
01011  *
01012  * @see nla_put
01013  * @return 0 on success or a negative error code.
01014  */
01015 int nla_put_string(struct nl_msg *msg, int attrtype, const char *str)
01016 {
01017         return nla_put(msg, attrtype, strlen(str) + 1, str);
01018 }
01019 
01020 /**
01021  * Return payload of string attribute.
01022  * @arg nla             String attribute.
01023  *
01024  * @return Pointer to attribute payload.
01025  */
01026 char *nla_get_string(struct nlattr *nla)
01027 {
01028         return (char *) nla_data(nla);
01029 }
01030 
01031 char *nla_strdup(struct nlattr *nla)
01032 {
01033         return strdup(nla_get_string(nla));
01034 }
01035 
01036 /** @} */
01037 
01038 /**
01039  * @name Flag Attribute
01040  */
01041 
01042 /**
01043  * Add flag netlink attribute to netlink message.
01044  * @arg msg             Netlink message.
01045  * @arg attrtype        Attribute type.
01046  *
01047  * @see nla_put
01048  * @return 0 on success or a negative error code.
01049  */
01050 int nla_put_flag(struct nl_msg *msg, int attrtype)
01051 {
01052         return nla_put(msg, attrtype, 0, NULL);
01053 }
01054 
01055 /**
01056  * Return true if flag attribute is set.
01057  * @arg nla             Flag netlink attribute.
01058  *
01059  * @return True if flag is set, otherwise false.
01060  */
01061 int nla_get_flag(struct nlattr *nla)
01062 {
01063         return !!nla;
01064 }
01065 
01066 /** @} */
01067 
01068 /**
01069  * @name Microseconds Attribute
01070  */
01071 
01072 /**
01073  * Add a msecs netlink attribute to a netlink message
01074  * @arg n               netlink message
01075  * @arg attrtype        attribute type
01076  * @arg msecs           number of msecs
01077  */
01078 int nla_put_msecs(struct nl_msg *n, int attrtype, unsigned long msecs)
01079 {
01080         return nla_put_u64(n, attrtype, msecs);
01081 }
01082 
01083 /**
01084  * Return payload of msecs attribute
01085  * @arg nla             msecs netlink attribute
01086  *
01087  * @return the number of milliseconds.
01088  */
01089 unsigned long nla_get_msecs(struct nlattr *nla)
01090 {
01091         return nla_get_u64(nla);
01092 }
01093 
01094 /** @} */
01095 
01096 /**
01097  * @name Nested Attribute
01098  */
01099 
01100 /**
01101  * Add nested attributes to netlink message.
01102  * @arg msg             Netlink message.
01103  * @arg attrtype        Attribute type.
01104  * @arg nested          Message containing attributes to be nested.
01105  *
01106  * Takes the attributes found in the \a nested message and appends them
01107  * to the message \a msg nested in a container of the type \a attrtype.
01108  * The \a nested message may not have a family specific header.
01109  *
01110  * @see nla_put
01111  * @return 0 on success or a negative error code.
01112  */
01113 int nla_put_nested(struct nl_msg *msg, int attrtype, struct nl_msg *nested)
01114 {
01115         NL_DBG(2, "msg %p: attr <> %d: adding msg %p as nested attribute\n",
01116                 msg, attrtype, nested);
01117 
01118         return nla_put(msg, attrtype, nlmsg_datalen(nested->nm_nlh),
01119                        nlmsg_data(nested->nm_nlh));
01120 }
01121 
01122 
01123 /**
01124  * Start a new level of nested attributes.
01125  * @arg msg             Netlink message.
01126  * @arg attrtype        Attribute type of container.
01127  *
01128  * @return Pointer to container attribute.
01129  */
01130 struct nlattr *nla_nest_start(struct nl_msg *msg, int attrtype)
01131 {
01132         struct nlattr *start = (struct nlattr *) nlmsg_tail(msg->nm_nlh);
01133 
01134         if (nla_put(msg, attrtype, 0, NULL) < 0)
01135                 return NULL;
01136 
01137         NL_DBG(2, "msg %p: attr <%p> %d: starting nesting\n",
01138                 msg, start, start->nla_type);
01139 
01140         return start;
01141 }
01142 
01143 /**
01144  * Finalize nesting of attributes.
01145  * @arg msg             Netlink message.
01146  * @arg start           Container attribute as returned from nla_nest_start().
01147  *
01148  * Corrects the container attribute header to include the appeneded attributes.
01149  *
01150  * @return 0
01151  */
01152 int nla_nest_end(struct nl_msg *msg, struct nlattr *start)
01153 {
01154         size_t pad, len;
01155 
01156         len = (void *) nlmsg_tail(msg->nm_nlh) - (void *) start;
01157 
01158         if (len == NLA_HDRLEN) {
01159                 /*
01160                  * Kernel can't handle empty nested attributes, trim the
01161                  * attribute header again
01162                  */
01163                 msg->nm_nlh->nlmsg_len -= NLA_HDRLEN;
01164                 memset(nlmsg_tail(msg->nm_nlh), 0, NLA_HDRLEN);
01165 
01166                 return 0;
01167         }
01168 
01169         start->nla_len = len;
01170 
01171         pad = NLMSG_ALIGN(msg->nm_nlh->nlmsg_len) - msg->nm_nlh->nlmsg_len;
01172         if (pad > 0) {
01173                 /*
01174                  * Data inside attribute does not end at a alignment boundry.
01175                  * Pad accordingly and accoun for the additional space in
01176                  * the message. nlmsg_reserve() may never fail in this situation,
01177                  * the allocate message buffer must be a multiple of NLMSG_ALIGNTO.
01178                  */
01179                 if (!nlmsg_reserve(msg, pad, 0))
01180                         BUG();
01181 
01182                 NL_DBG(2, "msg %p: attr <%p> %d: added %zu bytes of padding\n",
01183                         msg, start, start->nla_type, pad);
01184         }
01185 
01186         NL_DBG(2, "msg %p: attr <%p> %d: closing nesting, len=%u\n",
01187                 msg, start, start->nla_type, start->nla_len);
01188 
01189         return 0;
01190 }
01191 
01192 /**
01193  * Create attribute index based on nested attribute
01194  * @arg tb              Index array to be filled (maxtype+1 elements).
01195  * @arg maxtype         Maximum attribute type expected and accepted.
01196  * @arg nla             Nested Attribute.
01197  * @arg policy          Attribute validation policy.
01198  *
01199  * Feeds the stream of attributes nested into the specified attribute
01200  * to nla_parse().
01201  *
01202  * @see nla_parse
01203  * @return 0 on success or a negative error code.
01204  */
01205 int nla_parse_nested(struct nlattr *tb[], int maxtype, struct nlattr *nla,
01206                      struct nla_policy *policy)
01207 {
01208         return nla_parse(tb, maxtype, nla_data(nla), nla_len(nla), policy);
01209 }
01210 
01211 /** @} */
01212 
01213 /** @} */