dict.h

Go to the documentation of this file.

#pragma once
/*
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
 */
 
/** Multi-protocol AVP dictionary API
 *
 * @file src/lib/util/dict.h
 *
 * @copyright 2015 The FreeRADIUS server project
 */
RCSIDH(dict_h, "$Id: 0ad1bda348c50556e9d12359321a6485794c017c $")
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <freeradius-devel/build.h>
#include <freeradius-devel/missing.h>
#include <freeradius-devel/util/dl.h>
#include <freeradius-devel/util/ext.h>
#include <freeradius-devel/util/rb.h>
#include <freeradius-devel/util/sbuff.h>
#include <freeradius-devel/util/table.h>
#include <freeradius-devel/util/talloc.h>
#include <freeradius-devel/util/types.h>
 
#include <stdbool.h>
#include <stdint.h>
 
/*
 *      Avoid circular type references.
 */
typedef struct dict_attr_s fr_dict_attr_t;
typedef struct fr_dict fr_dict_t;
 
typedef struct value_box_s fr_value_box_t;
 
/*
 *      Allow public and private versions of the same structures
 */
#ifdef _CONST
#  error _CONST can only be defined in the local header
#endif
#ifndef _DICT_PRIVATE
#  define _CONST const
#else
#  define _CONST
#endif
 
#ifdef WITH_VERIFY_PTR
#  define DA_VERIFY(_x)         fr_dict_attr_verify(__FILE__, __LINE__, _x)
#else
#  define DA_VERIFY(_x)         fr_cond_assert(_x)
#endif
 
typedef struct fr_dict_autoload_talloc_s fr_dict_autoload_talloc_t;
 
/** Values of the encryption flags
 */
typedef struct {
        unsigned int            is_root : 1;                    //!< Is root of a dictionary.
 
        unsigned int            is_unknown : 1;                 //!< This dictionary attribute is ephemeral
                                                                ///< and not part of the main dictionary.
 
        unsigned int            is_raw : 1;                     //!< This dictionary attribute was constructed
                                                                ///< from a known attribute to allow the user
                                                                ///< to assign octets values directly.
                                                                ///< See .is_unknown to determine if it is
                                                                ///< ephemeral.
        unsigned int            is_alias : 1;                   //!< This isn't a real attribute, it's a reference to
                                                                ///< to one.
        unsigned int            internal : 1;                   //!< Internal attribute, should not be received
                                                                ///< in protocol packets, should not be encoded.
        unsigned int            array : 1;                      //!< Pack multiples into 1 attr.
 
        unsigned int            is_known_width : 1;             //!< is treated as if it has a known width for structs
 
        unsigned int            has_value : 1;                  //!< Has a value.
 
        unsigned int            is_unsigned : 1;                //!< hackity hack for dates and time deltas
 
        unsigned int            counter : 1;                    //!< integer attribute is actually an impulse / counter
 
        unsigned int            name_only : 1;                  //!< this attribute should always be referred to by name, not by number
 
        unsigned int            secret : 1;                     //!< this attribute should be omitted in debug mode
 
        /*
         *      @todo - if we want to clean these fields up, make
         *      "subtype" and "type_size" both 4-bit bitfields.  That
         *      gives us an extra 8 bits for adding new flags, and we
         *      can likely get rid of "extra", in order to save one
         *      more bit.
         */
        unsigned int            extra : 1;                      //!< really "subtype is used by dict, not by protocol"
 
        unsigned int            local : 1;                      //!< is a local variable
 
        /*
         *      main: extra is set, then this field is is key, bit, or a uint16 length field.
         *      radius: is one of 9 options for flags
         *      dhcp v4/v6: DNS label, or partial DNS label
         */
        uint8_t                 subtype;                        //!< protocol-specific values, OR key fields
 
        /*
         *      Length in bytes for most attributes.
         *      Length in bits for da_is_bit_field(da)
         */
        uint8_t                 length;                         //!< length of the attribute
 
        /*
         *      TLVs: 1, 2, or 4.
         *      date / time types: fr_time_res_t, which has 4 possible values.
         *      bit fields: offset in the byte where this bit field ends, which is only
         *      used as a caching mechanism during parsing of the dictionaries.
         */
        uint8_t                 type_size;                      //!< For TLV2 and root attributes.
} fr_dict_attr_flags_t;
 
#define flag_time_res type_size
#define flag_byte_offset type_size
 
/** subtype values for the dictionary when extra=1
 *
 */
enum {
        FLAG_EXTRA_NONE = 0,                            //!< no extra meaning, should be invalid
        FLAG_KEY_FIELD,                                 //!< this is a key field for a subsequent struct
        FLAG_BIT_FIELD,                                 //!< bit field inside of a struct
        FLAG_LENGTH_UINT8,                              //!< string / octets type is prefixed by uint8 of length
        FLAG_LENGTH_UINT16,                             //!< string / octets type is prefixed by uint16 of length
};
 
#define fr_dict_attr_is_key_field(_da) ((_da)->flags.extra && ((_da)->flags.subtype == FLAG_KEY_FIELD))
#define da_is_bit_field(_da) ((_da)->flags.extra && ((_da)->flags.subtype == FLAG_BIT_FIELD))
#define da_is_length_field(_da) ((_da)->flags.extra && (((_da)->flags.subtype == FLAG_LENGTH_UINT8) || ((_da)->flags.subtype == FLAG_LENGTH_UINT16)))
#define da_length_offset(_da) ((_da)->flags.type_size)
 
 
/** Extension identifier
 *
 * @note New extension structures should also be added to the to the appropriate table in dict_ext.c
 */
typedef enum {
        FR_DICT_ATTR_EXT_NAME = 0,                              //!< Name of the attribute.
        FR_DICT_ATTR_EXT_CHILDREN,                              //!< Attribute has children.
        FR_DICT_ATTR_EXT_REF,                                   //!< Attribute references another
                                                                ///< attribute and/or dictionary.
        FR_DICT_ATTR_EXT_VENDOR,                                //!< Cached vendor pointer.
        FR_DICT_ATTR_EXT_DA_STACK,                              //!< Cached da stack.
        FR_DICT_ATTR_EXT_ENUMV,                                 //!< Enumeration values.
        FR_DICT_ATTR_EXT_NAMESPACE,                             //!< Attribute has its own namespace.
        FR_DICT_ATTR_EXT_PROTOCOL_SPECIFIC,                     //!< Protocol specific extensions
        FR_DICT_ATTR_EXT_MAX
} fr_dict_attr_ext_t;
 
/** Dictionary attribute
 */
struct dict_attr_s {
        fr_dict_t _CONST* _CONST dict;                          //!< Dict attribute belongs to.
 
        char const              *name;                          //!< Attribute name.
        size_t                  name_len;                       //!< Length of the name.
 
        unsigned int            attr;                           //!< Attribute number.
        unsigned int            depth;                          //!< Depth of nesting for this attribute.
 
        unsigned int            last_child_attr;                //!< highest value of last child attribute.
 
        fr_type_t               type;                           //!< Value type.
 
        fr_dict_attr_t const    *parent;                        //!< Immediate parent of this attribute.
        fr_dict_attr_t const    *next;                          //!< Next child in bin.
        fr_dict_attr_t          *fixup;                         //!< Attribute has been marked up for fixups.
 
        fr_dict_attr_flags_t    flags;                          //!< Flags.
 
        uint8_t                 ext[FR_DICT_ATTR_EXT_MAX];      //!< Extensions to the dictionary attribute.
} CC_HINT(aligned(FR_EXT_ALIGNMENT));
 
/** Extension identifier
 *
 * @note New extension structures should also be added to the appropriate table in dict_ext.c
 */
typedef enum {
        FR_DICT_ENUM_EXT_UNION_REF = 0,                         //!< Reference to a union/subs-struct.
        FR_DICT_ENUM_EXT_MAX
} fr_dict_enum_ext_t;
 
/** Value of an enumerated attribute
 *
 * Maps one of more string values to integers and vice versa.
 */
typedef struct {
        char const              *name;                          //!< Enum name.
        size_t                  name_len;                       //!< Allows for efficient name lookups when operating
                                                                ///< on partial buffers.
        fr_value_box_t const    *value;                         //!< Enum value (what name maps to).
 
        uint8_t                 ext[FR_DICT_ENUM_EXT_MAX];      //!< Extensions to the dictionary attribute.
 
        fr_dict_attr_t const    *child_struct[];                //!< for key fields
} fr_dict_enum_value_t CC_HINT(aligned(FR_EXT_ALIGNMENT));
 
/** Private enterprise
 *
 * Represents an IANA private enterprise allocation.
 *
 * The width of the private enterprise number must be the same for all protocols
 * so we can represent a vendor with a single struct.
 */
typedef struct {
        uint32_t                pen;                            //!< Private enterprise number.
        bool                    continuation;                   //!< we only have one flag for now, for WiMAX
        size_t                  type;                           //!< Length of type data
        size_t                  length;                         //!< Length of length data
        char const              *name;                          //!< Vendor name.
} fr_dict_vendor_t;
 
/** Specifies a value which must be present for the module to function
 *
 */
typedef struct {
        fr_value_box_t const    **out;                          //!< Enumeration value.
        fr_dict_attr_t const    **attr;                         //!< The protocol dictionary the attribute should
                                                                ///< be resolved in. ** so it's a compile time
                                                                ///< constant.
        char const              *name;                          //!< of the attribute.
} fr_dict_enum_autoload_t;
 
/** Specifies an attribute which must be present for the module to function
 *
 */
typedef struct {
        fr_dict_attr_t const    **out;                          //!< Where to write a pointer to the resolved
                                                                //!< #fr_dict_attr_t.
        fr_dict_t const         **dict;                         //!< The protocol dictionary the attribute should
                                                                ///< be resolved in. ** so it's a compile time
                                                                ///< constant.
        char const              *name;                          //!< of the attribute.
        fr_type_t               type;                           //!< of the attribute.  Mismatch is a fatal error.
} fr_dict_attr_autoload_t;
 
/** Specifies a dictionary which must be loaded/loadable for the module to function
 *
 */
typedef struct {
        fr_dict_t const         **out;                          //!< Where to write a pointer to the loaded/resolved
                                                                //!< #fr_dict_t.
        char const              *base_dir;                      //!< Directory structure beneath share.
        char const              *proto;                         //!< The protocol dictionary name.
} fr_dict_autoload_t;
 
/** Errors returned by attribute lookup functions
 *
 */
typedef enum {
        FR_DICT_ATTR_OK                 = 0,                    //!< No error.
        FR_DICT_ATTR_NOTFOUND           = -1,                   //!< Attribute couldn't be found.
        FR_DICT_ATTR_PROTOCOL_NOTFOUND  = -2,                   //!< Protocol couldn't be found.
        FR_DICT_ATTR_PARSE_ERROR        = -3,                   //!< Attribute string couldn't be parsed
        FR_DICT_ATTR_INTERNAL_ERROR     = -4,                   //!< Internal error occurred.
        FR_DICT_ATTR_OOM                = -5,                   //!< Memory allocation error.
        FR_DICT_ATTR_NOT_DESCENDENT     = -6,                   //!< Attribute is not a descendent of the parent
                                                                ///< attribute.
        FR_DICT_ATTR_NOT_ANCESTOR       = -7,                   //!< Attribute is not an ancestor of the child
                                                                ///< attribute.
        FR_DICT_ATTR_NO_CHILDREN        = -8,                   //!< Child lookup in attribute with no children.
        FR_DICT_ATTR_EINVAL             = -9                    //!< Invalid arguments.
 
} fr_dict_attr_err_t;
 
typedef bool (*fr_dict_attr_valid_func_t)(fr_dict_t *dict, fr_dict_attr_t const *parent,
                                          char const *name, int attr, fr_type_t type, fr_dict_attr_flags_t *flags);
 
/*
 *      Forward declarations to avoid circular references.
 */
typedef struct pair_list_s fr_pair_list_t;
typedef struct fr_dbuff_s fr_dbuff_t;
 
/** A generic interface for decoding packets to fr_pair_ts
 *
 * A decoding function should decode a single top level packet from wire format.
 *
 * Note that unlike #fr_tp_proto_decode_t, this function is NOT passed an encode_ctx.  That is because when we
 * do cross-protocol encoding, the "outer" protocol has no information it can share with the "inner" protocol.
 *
 * @param[in] ctx               to allocate new pairs in.
 * @param[in] vps               where new VPs will be added
 * @param[in] data              to decode.
 * @param[in] data_len          The length of the incoming data.
 * @return
 *      - <= 0 on error.  May be the offset (as a negative value) where the error occurred.
 *      - > 0 on success.  How many bytes were decoded.
 */
typedef ssize_t (*fr_dict_attr_decode_func_t)(TALLOC_CTX *ctx, fr_pair_list_t *vps,
                                              uint8_t const *data, size_t data_len);
 
/** A generic interface for encoding fr_pair_ts to packets
 *
 * An encoding function should encode multiple VPs to a wire format packet
 *
 * Note that unlike #fr_tp_proto_encode_t, this function is NOT passed an encode_ctx.  That is because when we
 * do cross-protocol encoding, the "outer" protocol has no information it can share with the "inner" protocol.
 *
 * @param[in] vps               vps to encode
 * @param[in] dbuff             buffer where data can be written
 * @return
 *      - <= 0 on error.  May be the offset (as a negative value) where the error occurred.
 *      - > 0 on success.  How many bytes were encoded
 */
typedef ssize_t(*fr_dict_attr_encode_func_t)(fr_dbuff_t *dbuff, fr_pair_list_t const *vps);
 
/** Init / free callbacks
 *
 *  Only for "autoref" usage.
 */
typedef int (*fr_dict_protocol_init_t)(void);
typedef void (*fr_dict_protocol_free_t)(void);
 
 
/** Protocol-specific callbacks in libfreeradius-PROTOCOL
 *
 */
typedef struct {
        char const              *name;                          //!< name of this protocol
        int                     default_type_size;              //!< how many octets are in "type" field
        int                     default_type_length;            //!< how many octets are in "length" field
        fr_table_num_ordered_t  const *subtype_table;           //!< for "encrypt=1", etc.
        size_t                  subtype_table_len;              //!< length of subtype_table
        fr_dict_attr_valid_func_t attr_valid;                   //!< validation function for new attributes
 
        fr_dict_protocol_init_t init;                           //!< initialize the library
        fr_dict_protocol_free_t free;                           //!< free the library
 
        fr_dict_attr_decode_func_t decode;                      //!< for decoding attributes
        fr_dict_attr_encode_func_t encode;                      //!< for encoding attributes
} fr_dict_protocol_t;
 
typedef struct fr_dict_gctx_s fr_dict_gctx_t;
 
/*
 *      Dictionary constants
 */
#define FR_DICT_PROTO_MAX_NAME_LEN      (128)                   //!< Maximum length of a protocol name.
#define FR_DICT_ENUM_MAX_NAME_LEN       (128)                   //!< Maximum length of a enum value.
#define FR_DICT_VENDOR_MAX_NAME_LEN     (128)                   //!< Maximum length of a vendor name.
#define FR_DICT_ATTR_MAX_NAME_LEN       (128)                   //!< Maximum length of a attribute name.
 
/** Maximum level of TLV nesting allowed
 */
#define FR_DICT_TLV_NEST_MAX            (24)
 
/** Maximum level of da stack caching
 */
#define FR_DICT_DA_STACK_CACHE_MAX      (5)
 
/** Maximum TLV stack size
 *
 * The additional attributes are to account for
 *
 * Root + Vendor + NULL (top frame).
 * Root + Embedded protocol + Root + Vendor + NULL.
 *
 * Code should ensure that it doesn't run off the end of the stack,
 * as this could be remotely exploitable, using odd nesting.
 */
#define FR_DICT_MAX_TLV_STACK           (FR_DICT_TLV_NEST_MAX + 5)
 
/** Characters that are allowed in dictionary attribute names
 *
 */
extern bool const       fr_dict_attr_allowed_chars[UINT8_MAX + 1];
 
/** Characters that are allowed in dictionary enumeration value names
 *
 */
extern bool const       fr_dict_enum_allowed_chars[UINT8_MAX + 1];
 
/** @name Dictionary structure extensions
 *
 * @{
 */
#include <freeradius-devel/util/dict_ext.h>
/** @} */
 
/** @name Programmatically create dictionary attributes and values
 *
 * @{
 */
int                     fr_dict_attr_add(fr_dict_t *dict, fr_dict_attr_t const *parent, char const *name, int attr,
                                         fr_type_t type, fr_dict_attr_flags_t const *flags) CC_HINT(nonnull(1,2,3));
 
int                     fr_dict_enum_add_name(fr_dict_attr_t *da, char const *name,
                                              fr_value_box_t const *value, bool coerce, bool replace);
 
int                     fr_dict_enum_add_name_next(fr_dict_attr_t *da, char const *name) CC_HINT(nonnull);
 
int                     fr_dict_str_to_argv(char *str, char **argv, int max_argc);
/** @} */
 
/** @name Unknown ephemeral attributes
 *
 * @{
 */
fr_dict_attr_t const    *fr_dict_unknown_add(fr_dict_t *dict, fr_dict_attr_t const *old) CC_HINT(nonnull);
 
void                    fr_dict_unknown_free(fr_dict_attr_t const **da);
 
fr_dict_attr_t          *fr_dict_unknown_afrom_da(TALLOC_CTX *ctx, fr_dict_attr_t const *da);
 
static inline fr_dict_attr_t *fr_dict_unknown_copy(TALLOC_CTX *ctx, fr_dict_attr_t const *da)
{
        fr_assert(da->flags.is_unknown);
 
        return fr_dict_unknown_afrom_da(ctx, da);
}
 
fr_dict_attr_t          *fr_dict_unknown_vendor_afrom_num(TALLOC_CTX *ctx,
                                                          fr_dict_attr_t const *parent, unsigned int vendor)
                                                          CC_HINT(nonnull(2));
 
fr_dict_attr_t          *fr_dict_unknown_tlv_afrom_num(TALLOC_CTX *ctx,
                                                       fr_dict_attr_t const *parent, unsigned int num)
                                                       CC_HINT(nonnull(2));
 
fr_dict_attr_t          *fr_dict_unknown_attr_afrom_num(TALLOC_CTX *ctx,
                                                        fr_dict_attr_t const *parent, unsigned int num)
                                                        CC_HINT(nonnull(2));
 
fr_dict_attr_t          *fr_dict_unknown_attr_afrom_da(TALLOC_CTX *ctx, fr_dict_attr_t const *da)
                                                       CC_HINT(nonnull(2));
 
 
fr_slen_t               fr_dict_unknown_afrom_oid_substr(TALLOC_CTX *ctx,
                                                         fr_dict_attr_t const **out,
                                                         fr_dict_attr_t const *parent,
                                                         fr_sbuff_t *in)
                                                         CC_HINT(nonnull(2,3,4));
 
int                     fr_dict_attr_unknown_parent_to_known(fr_dict_attr_t *da, fr_dict_attr_t const *parent);
 
fr_dict_attr_t const    *fr_dict_attr_unknown_resolve(fr_dict_t const *dict, fr_dict_attr_t const *da);
/** @} */
 
/** @name Attribute comparisons
 *
 * @{
 */
static inline  CC_HINT(nonnull) int8_t fr_dict_attr_cmp(fr_dict_attr_t const *a, fr_dict_attr_t const *b)
{
        int8_t ret;
 
        /*
         *      Comparing unknowns or raws is expensive
         *      because we need to check the lineage.
         */
        if (a->flags.is_unknown | a->flags.is_raw | b->flags.is_unknown | b->flags.is_raw) {
                ret = CMP(a->depth, b->depth);
                if (ret != 0) return ret;
 
                ret = CMP(a->attr, b->attr);
                if (ret != 0) return ret;
 
                ret = (a->parent == NULL) - (b->parent == NULL);
                if ((ret != 0) || !a->parent) return ret;
 
                return fr_dict_attr_cmp(a->parent, b->parent);
        }
 
        /*
         *      Comparing knowns is cheap because the
         *      DAs are unique.
         */
        return CMP(a, b);
}
/** @} */
 
/** @name Debugging functions
 *
 * @{
 */
void                    fr_dict_namespace_debug(fr_dict_attr_t const *da);
 
void                    fr_dict_attr_debug(fr_dict_attr_t const *da);
 
void                    fr_dict_debug(fr_dict_t const *dict);
 
void                    fr_dict_export(fr_dict_t const *dict);
/** @} */
 
/** @name Attribute lineage
 *
 * @{
 */
fr_dict_attr_t const    *fr_dict_attr_common_parent(fr_dict_attr_t const *a, fr_dict_attr_t const *b, bool is_ancestor);
 
int                     fr_dict_oid_component_legacy(unsigned int *out, char const **oid);
 
fr_slen_t               fr_dict_attr_flags_print(fr_sbuff_t *out, fr_dict_t const *dict,
                                                 fr_type_t type, fr_dict_attr_flags_t const *flags);
 
fr_slen_t               fr_dict_attr_oid_print(fr_sbuff_t *out,
                                               fr_dict_attr_t const *ancestor, fr_dict_attr_t const *da, bool numeric);
#define                 FR_DICT_ATTR_OID_PRINT_RETURN(...) FR_SBUFF_RETURN(fr_dict_attr_oid_print, ##__VA_ARGS__)
 
fr_slen_t               fr_dict_attr_by_oid_legacy(fr_dict_t const *dict, fr_dict_attr_t const **parent,
                                                   unsigned int *attr, char const *oid) CC_HINT(nonnull);
 
fr_slen_t               fr_dict_oid_component(fr_dict_attr_err_t *err,
                                              fr_dict_attr_t const **out, fr_dict_attr_t const *parent,
                                              fr_sbuff_t *in, fr_sbuff_term_t const *tt)
                                              CC_HINT(nonnull(2,3,4));
 
fr_slen_t               fr_dict_attr_by_oid_substr(fr_dict_attr_err_t *err,
                                                   fr_dict_attr_t const **out, fr_dict_attr_t const *parent,
                                                   fr_sbuff_t *in, fr_sbuff_term_t const *tt)
                                                   CC_HINT(nonnull(2,3,4));
 
fr_dict_attr_t const    *fr_dict_attr_by_oid(fr_dict_attr_err_t *err,
                                             fr_dict_attr_t const *parent, char const *oid)
                                             CC_HINT(nonnull(2,3));
 
bool                    fr_dict_attr_can_contain(fr_dict_attr_t const *parent, fr_dict_attr_t const *child) CC_HINT(nonnull);
 
/** @} */
 
/** @name Attribute, vendor and dictionary lookup
 *
 * @{
 */
 
/** @hidecallergraph */
fr_dict_attr_t const    *fr_dict_root(fr_dict_t const *dict) CC_HINT(nonnull);
 
bool                    fr_dict_is_read_only(fr_dict_t const *dict);
 
dl_t                    *fr_dict_dl(fr_dict_t const *dict);
 
fr_slen_t               fr_dict_by_protocol_substr(fr_dict_attr_err_t *err,
                                                   fr_dict_t const **out, fr_sbuff_t *name, fr_dict_t const *dict_def);
 
fr_dict_t const         *fr_dict_by_protocol_name(char const *name);
 
fr_dict_t const         *fr_dict_by_protocol_num(unsigned int num);
 
fr_dict_protocol_t const *fr_dict_protocol(fr_dict_t const *dict);
 
fr_dict_t const         *fr_dict_by_da(fr_dict_attr_t const *da) CC_HINT(nonnull);
 
fr_dict_t const         *fr_dict_by_attr_name(fr_dict_attr_t const **found, char const *name);
 
bool                    fr_dict_compatible(fr_dict_t const *dict1, fr_dict_t const *dict2) CC_HINT(nonnull);
 
/** Return true if this attribute is parented directly off the dictionary root
 *
 * @param[in] da                to check.
 * @return
 *      - true if attribute is top level.
 *      - false if attribute is not top level.
 */
static inline bool fr_dict_attr_is_top_level(fr_dict_attr_t const *da)
{
        if (unlikely(!da) || unlikely(!da->parent)) return false;
        return da->parent->flags.is_root;
}
 
fr_dict_vendor_t const  *fr_dict_vendor_by_da(fr_dict_attr_t const *da);
 
fr_dict_vendor_t const  *fr_dict_vendor_by_name(fr_dict_t const *dict, char const *name);
 
fr_dict_vendor_t const  *fr_dict_vendor_by_num(fr_dict_t const *dict, uint32_t vendor_pen);
 
fr_dict_attr_t const    *fr_dict_vendor_da_by_num(fr_dict_attr_t const *vendor_root, uint32_t vendor_pen);
 
fr_slen_t               fr_dict_attr_search_by_qualified_name_substr(fr_dict_attr_err_t *err, fr_dict_attr_t const **out,
                                                                     fr_dict_t const *dict_def,
                                                                     fr_sbuff_t *name, fr_sbuff_term_t const *tt,
                                                                     bool internal, bool foreign)
                                                                     CC_HINT(nonnull(2, 4));
 
fr_slen_t               fr_dict_attr_search_by_name_substr(fr_dict_attr_err_t *err, fr_dict_attr_t const **out,
                                                           fr_dict_t const *dict_def,
                                                           fr_sbuff_t *name, fr_sbuff_term_t const *tt,
                                                           bool internal, bool foreign)
                                                           CC_HINT(nonnull(2, 4));
 
fr_slen_t               fr_dict_attr_search_by_qualified_oid_substr(fr_dict_attr_err_t *err, fr_dict_attr_t const **out,
                                                                    fr_dict_t const *dict_def,
                                                                    fr_sbuff_t *in, fr_sbuff_term_t const *tt,
                                                                    bool internal, bool foreign)
                                                                    CC_HINT(nonnull(2, 4));
 
fr_dict_attr_t const    *fr_dict_attr_search_by_qualified_oid(fr_dict_attr_err_t *err,
                                                              fr_dict_t const *dict_def, char const *attr,
                                                              bool internal, bool foreign)
                                                              CC_HINT(nonnull(3));
 
fr_slen_t               fr_dict_attr_search_by_oid_substr(fr_dict_attr_err_t *err, fr_dict_attr_t const **out,
                                                          fr_dict_t const *dict_def,
                                                          fr_sbuff_t *in, fr_sbuff_term_t const *tt,
                                                          bool internal, bool foreign)
                                                          CC_HINT(nonnull(2, 4));
 
fr_slen_t               fr_dict_attr_by_name_substr(fr_dict_attr_err_t *err, fr_dict_attr_t const **out,
                                                    fr_dict_attr_t const *parent,
                                                    fr_sbuff_t *name, fr_sbuff_term_t const *tt)
                                                    CC_HINT(nonnull(2,3,4));
 
fr_dict_attr_t const    *fr_dict_attr_by_name(fr_dict_attr_err_t *err, fr_dict_attr_t const *parent,
                                              char const *attr)
                                              CC_HINT(nonnull(2,3));
 
fr_dict_attr_t const    *fr_dict_attr_child_by_num(fr_dict_attr_t const *parent, unsigned int attr);
 
fr_dict_enum_value_t            *fr_dict_enum_by_value(fr_dict_attr_t const *da, fr_value_box_t const *value);
 
char const              *fr_dict_enum_name_by_value(fr_dict_attr_t const *da, fr_value_box_t const *value);
 
fr_dict_enum_value_t            *fr_dict_enum_by_name(fr_dict_attr_t const *da, char const *name, ssize_t len);
 
fr_slen_t               fr_dict_enum_by_name_substr(fr_dict_enum_value_t **out, fr_dict_attr_t const *da, fr_sbuff_t *in);
 
fr_slen_t               fr_dict_enum_name_from_substr(fr_sbuff_t *out, fr_sbuff_parse_error_t *err,
                                                      fr_sbuff_t *in, fr_sbuff_term_t const *tt);
 
static inline fr_slen_t fr_dict_enum_name_afrom_substr(TALLOC_CTX *ctx, char **out, fr_sbuff_parse_error_t *err,
                                                       fr_sbuff_t *in, fr_sbuff_term_t const *tt)
                        SBUFF_OUT_TALLOC_FUNC_NO_LEN_DEF(fr_dict_enum_name_from_substr, err, in, tt)
/** @} */
 
/** @name Dictionary and protocol loading
 *
 * @{
 */
int                     fr_dict_internal_afrom_file(fr_dict_t **out, char const *internal_name,
                                                    char const *dependent);
 
int                     fr_dict_protocol_afrom_file(fr_dict_t **out, char const *proto_name, char const *proto_dir,
                                                    char const *dependent);
 
fr_dict_t               *fr_dict_protocol_alloc(fr_dict_t const *parent);
 
int                     fr_dict_read(fr_dict_t *dict, char const *dict_dir, char const *filename);
/** @} */
 
/** @name Autoloader interface
 *
 * @{
 */
int                     fr_dict_enum_autoload(fr_dict_enum_autoload_t const *to_load);
 
int                     fr_dict_attr_autoload(fr_dict_attr_autoload_t const *to_load);
 
#define                 fr_dict_autoload(_to_load) _fr_dict_autoload(_to_load, __FILE__)
int                     _fr_dict_autoload(fr_dict_autoload_t const *to_load, char const *dependent);
 
#define                 fr_dict_autofree(_to_free) _fr_dict_autofree(_to_free, __FILE__)
int                     _fr_dict_autofree(fr_dict_autoload_t const *to_free, char const *dependent);
 
#define                 fr_dict_autoload_talloc(_ctx, _dict_out, _proto) _fr_dict_autoload_talloc(_ctx, _dict_out, _proto, __FILE__)
fr_dict_autoload_talloc_t *_fr_dict_autoload_talloc(TALLOC_CTX *ctx, fr_dict_t const **out, char const *proto, char const *dependent);
 
int                     fr_dl_dict_enum_autoload(dl_t const *module, void *symbol, void *user_ctx);
 
int                     fr_dl_dict_attr_autoload(dl_t const *module, void *symbol, void *user_ctx);
 
int                     fr_dl_dict_autoload(dl_t const *module, void *symbol, void *user_ctx);
 
void                    fr_dl_dict_autofree(dl_t const *module, void *symbol, void *user_ctx);
/** @} */
 
/** @name Allocating and freeing
 *
 * @{
 */
fr_dict_t               *fr_dict_alloc(char const *proto_name, unsigned int proto_number) CC_HINT(nonnull);
 
int                     fr_dict_dependent_add(fr_dict_t const *dict, char const *dependent) CC_HINT(nonnull);
 
int                     fr_dict_free(fr_dict_t **dict, char const *dependent) CC_HINT(nonnull);
 
int                     fr_dict_const_free(fr_dict_t const **dict, char const *dependent) CC_HINT(nonnull);
/** @} */
 
/** @name Global dictionary management
 *
 * @{
 */
fr_dict_gctx_t          *fr_dict_global_ctx_init(TALLOC_CTX *ctx, bool free_at_exit, char const *dict_dir);
 
void                    fr_dict_global_ctx_perm_check(fr_dict_gctx_t *gctx, bool enable);
 
void                    fr_dict_global_ctx_set(fr_dict_gctx_t const *gctx);
 
int                     fr_dict_global_ctx_free(fr_dict_gctx_t const *gctx);
 
int                     fr_dict_global_ctx_dir_set(char const *dict_dir);
 
void                    fr_dict_global_ctx_read_only(void);
 
void                    fr_dict_global_ctx_debug(fr_dict_gctx_t const *gctx);
 
char const              *fr_dict_global_ctx_dir(void);
 
typedef struct fr_hash_iter_s fr_dict_global_ctx_iter_t;
 
fr_dict_t               *fr_dict_global_ctx_iter_init(fr_dict_global_ctx_iter_t *iter) CC_HINT(nonnull);
 
fr_dict_t               *fr_dict_global_ctx_iter_next(fr_dict_global_ctx_iter_t *iter) CC_HINT(nonnull);
 
fr_dict_t               *fr_dict_unconst(fr_dict_t const *dict);
 
fr_dict_attr_t          *fr_dict_attr_unconst(fr_dict_attr_t const *da);
 
fr_dict_t const         *fr_dict_internal(void);
 
/** @} */
 
/** @name Dictionary testing and validation
 *
 * @{
 */
int                     fr_dict_parse_str(fr_dict_t *dict, char *buf,
                                          fr_dict_attr_t const *parent);
 
ssize_t                 fr_dict_valid_name(char const *name, ssize_t len);
 
ssize_t                 fr_dict_valid_oid_str(char const *name, ssize_t len);
 
fr_dict_attr_t const    *fr_dict_attr_iterate_children(fr_dict_attr_t const *parent, fr_dict_attr_t const **prev);
 
typedef int             (*fr_dict_walk_t)(fr_dict_attr_t const *da, void *uctx);
 
int                     fr_dict_walk(fr_dict_attr_t const *da, fr_dict_walk_t callback, void *uctx);
 
void                    fr_dict_attr_verify(char const *file, int line, fr_dict_attr_t const *da);
/** @} */
 
#undef _CONST
 
#ifdef __cplusplus
}
#endif