Private Multi-protocol AVP dictionary API. More...

#include <freeradius-devel/protocol/base.h>
#include <freeradius-devel/util/dict.h>
#include <freeradius-devel/util/dict_ext_priv.h>
#include <freeradius-devel/util/dl.h>
#include <freeradius-devel/util/hash.h>
#include <freeradius-devel/util/value.h>

Include dependency graph for dict_priv.h:

Go to the source code of this file.

Data Structures
struct	dict_attr_args_t
	Optional arguments for initialising/allocating attributes. More...

struct	fr_dict
	Vendors and attribute names. More...

struct	fr_dict_dependent_t
	Entry recording dictionary reference holders by file. More...

struct	fr_dict_gctx_s

Macros
#define	_DICT_PRIVATE 1

#define	DICT_FIXUP_POOL_SIZE (1024)

#define	DICT_POOL_SIZE (1024 * 1024 * 2)

#define	INTERNAL_IF_NULL(_dict, _ret)
	Set the internal dictionary if none was provided. More...

Functions
fr_dict_t *	dict_alloc (TALLOC_CTX *ctx)
	Allocate a new dictionary. More...

fr_dict_attr_t *	dict_attr_acopy (TALLOC_CTX ctx, fr_dict_attr_t const in, char const *new_name)
	Copy a an existing attribute. More...

int	dict_attr_acopy_children (fr_dict_t dict, fr_dict_attr_t dst, fr_dict_attr_t const *src)
	Copy the children of an existing attribute. More...

int	dict_attr_acopy_enumv (fr_dict_attr_t dst, fr_dict_attr_t const src)
	Copy the VALUEs of an existing attribute, by casting them. More...

int	dict_attr_add_to_namespace (fr_dict_attr_t const parent, fr_dict_attr_t da)
	Add an attribute to the name table for an attribute. More...

fr_dict_attr_t *	dict_attr_alloc (TALLOC_CTX ctx, fr_dict_attr_t const parent, char const name, int attr, fr_type_t type, dict_attr_args_t const args)
	Allocate a dictionary attribute on the heap. More...

fr_dict_attr_t *	dict_attr_alloc_null (TALLOC_CTX *ctx)
	Allocate a partially completed attribute. More...

fr_dict_attr_t *	dict_attr_by_name (fr_dict_attr_err_t err, fr_dict_attr_t const parent, char const *name)

bool	dict_attr_can_have_children (fr_dict_attr_t const *da)
	See if a fr_dict_attr_t can have children. More...

int	dict_attr_child_add (fr_dict_attr_t parent, fr_dict_attr_t child)
	Add a child to a parent. More...

fr_dict_attr_t *	dict_attr_child_by_num (fr_dict_attr_t const *parent, unsigned int attr)
	Internal version of fr_dict_attr_child_by_num. More...

int	dict_attr_enum_add_name (fr_dict_attr_t da, char const name, fr_value_box_t const value, bool coerce, bool replace, fr_dict_attr_t const child_struct)

bool	dict_attr_fields_valid (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)
	Validate a new attribute definition. More...

bool	dict_attr_flags_valid (fr_dict_t dict, fr_dict_attr_t const parent, UNUSED char const name, int attr, fr_type_t type, fr_dict_attr_flags_t *flags))

int	dict_attr_init (fr_dict_attr_t *da_p, fr_dict_attr_t const parent, char const name, int attr, fr_type_t type, dict_attr_args_t const args)
	Initialise fields in a dictionary attribute structure. More...

fr_dict_t *	dict_by_da (fr_dict_attr_t const *da)
	Internal version of fr_dict_by_da. More...

fr_dict_t *	dict_by_protocol_name (char const *name)
	Internal version of fr_dict_by_protocol_name. More...

fr_dict_t *	dict_by_protocol_num (unsigned int num)
	Internal version of fr_dict_by_protocol_num. More...

fr_slen_t	dict_by_protocol_substr (fr_dict_attr_err_t err, fr_dict_t out, fr_sbuff_t name, fr_dict_t const *dict_def)

int	dict_dependent_add (fr_dict_t dict, char const dependent)
	Record a new dependency on a dictionary. More...

int	dict_dependent_remove (fr_dict_t dict, char const dependent)
	Decrement ref count for a dependent in a dictionary. More...

int	dict_dlopen (fr_dict_t dict, char const name)

bool	dict_has_dependents (fr_dict_t *dict)
	Check if a dictionary still has dependents. More...

int	dict_protocol_add (fr_dict_t *dict)
	Add a protocol to the global protocol table. More...

int	dict_vendor_add (fr_dict_t dict, char const name, unsigned int num)
	Add a vendor to the dictionary. More...

Variables
fr_dict_gctx_t *	dict_gctx
	Top level structure containing global dictionary state. More...

Detailed Description

Private Multi-protocol AVP dictionary API.

Copyright: 2019 The FreeRADIUS server project

Definition in file dict_priv.h.

Data Structure Documentation

◆ dict_attr_args_t

struct dict_attr_args_t

Optional arguments for initialising/allocating attributes.

Definition at line 167 of file dict_priv.h.

Collaboration diagram for dict_attr_args_t:

Data Fields
fr_dict_attr_flags_t const *	flags	Any flags to assign to the attribute.
fr_dict_attr_t const *	ref	This attribute is a reference to another attribute.

◆ fr_dict

struct fr_dict

Vendors and attribute names.

It's very likely that the same vendors will operate in multiple protocol spaces, but number their attributes differently, so we need per protocol dictionaries.

There would also be conflicts for DHCP(v6)/RADIUS attributes etc...

Definition at line 73 of file dict_priv.h.

Collaboration diagram for fr_dict:

Data Fields
fr_dict_attr_valid_func_t	attr_valid	validation function for new attributes
fr_hash_table_t *	autoref	other dictionaries that we loaded via references
int	default_type_length	for TLVs and VSAs
int	default_type_size	for TLVs and VSAs
fr_rb_tree_t *	dependents	Which files are using this dictionary.
dl_t *	dl	for validation
fr_dict_attr_t **	fixups	Attributes that need fixing up.
fr_dict_gctx_t *	gctx	Global dictionary context this dictionary was allocated in.
bool	in_protocol_by_name	Whether the dictionary has been inserted into the protocol_by_name hash.
bool	in_protocol_by_num	Whether the dictionary has been inserted into the protocol_by_num table.
bool	loaded	from fr_dict_protocol_afrom_file();
bool	loading	from fr_dict_protocol_afrom_file();
fr_dict_t const *	next	for attribute overloading
TALLOC_CTX *	pool	Talloc memory pool to reduce allocs. in the dictionary.
fr_dict_protocol_t const *	proto	protocol-specific validation functions
bool	read_only	If true, disallow modifications.
fr_dict_attr_t *	root	Root attribute of this dictionary.
bool	string_based	TACACS, etc.
fr_table_num_ordered_t const *	subtype_table	table of subtypes for this protocol
size_t	subtype_table_len	length of table of subtypes for this protocol
fr_hash_table_t *	vendors_by_name	Lookup vendor by name.
fr_hash_table_t *	vendors_by_num	Lookup vendor by PEN.
unsigned int	vsa_parent	varies with different protocols

◆ fr_dict_dependent_t

struct fr_dict_dependent_t

Entry recording dictionary reference holders by file.

Definition at line 58 of file dict_priv.h.

Collaboration diagram for fr_dict_dependent_t:

Data Fields
int	count	How many references are held by this file. Signed to help figure out when things go wrong...
char const *	dependent	File holding the reference.
fr_rb_node_t	node

◆ fr_dict_gctx_s

struct fr_dict_gctx_s

Definition at line 119 of file dict_priv.h.

Collaboration diagram for fr_dict_gctx_s:

Data Fields
fr_dict_attr_t const *	attr_protocol_encapsulation
char *	dict_dir_default	The default location for loading dictionaries if one wasn't provided.
dl_loader_t *	dict_loader	for protocol validation
bool	free_at_exit	This gctx will be freed on exit.
fr_dict_t *	internal	Magic internal dictionary. Internal dictionary is checked in addition to the protocol dictionary when resolving attribute names. This is because internal attributes are valid for every protocol.
bool	perm_check	Whether we should check dictionary file permissions as they're loaded.
fr_hash_table_t *	protocol_by_name	Hash containing names of all the registered protocols.
fr_hash_table_t *	protocol_by_num	Hash containing numbers of all the registered protocols.
bool	read_only

Macro Definition Documentation

◆ _DICT_PRIVATE

#define _DICT_PRIVATE 1

Definition at line 28 of file dict_priv.h.

◆ DICT_FIXUP_POOL_SIZE

#define DICT_FIXUP_POOL_SIZE (1024)

Definition at line 38 of file dict_priv.h.

◆ DICT_POOL_SIZE

#define DICT_POOL_SIZE (1024 * 1024 * 2)

Definition at line 37 of file dict_priv.h.

◆ INTERNAL_IF_NULL

#define INTERNAL_IF_NULL	(	_dict,
		_ret
	)

Value:

        do { \
                if (!(_dict)) { \
                        _dict = dict_gctx ? dict_gctx->internal : NULL; \
                        if (unlikely(!(_dict))) { \
                                fr_strerror_const("No dictionaries available for attribute resolution"); \
                                return (_ret); \
                        } \
                } \
        } while (0)

Set the internal dictionary if none was provided.

Parameters

_dict	Dict pointer to check/set.
_ret	Value to return if no dictionaries are available.

Definition at line 45 of file dict_priv.h.

Function Documentation

◆ dict_alloc()

fr_dict_t* dict_alloc ( TALLOC_CTX * ctx )

Allocate a new dictionary.

Parameters

[in] ctx to allocate dictionary in.

Returns

NULL on memory allocation error.

Definition at line 3428 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_attr_acopy()

fr_dict_attr_t* dict_attr_acopy	(	TALLOC_CTX *	ctx,
		fr_dict_attr_t const *	in,
		char const *	new_name
	)

Copy a an existing attribute.

Parameters

[in]	ctx	to allocate new attribute in.
[in]	in	attribute to copy.
[in]	new_name	to assign to the attribute. If NULL the existing name will be used.

Returns

A copy of the input fr_dict_attr_t on success.
NULL on failure.

Definition at line 725 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_attr_acopy_children()

int dict_attr_acopy_children	(	fr_dict_t *	dict,
		fr_dict_attr_t *	dst,
		fr_dict_attr_t const *	src
	)

Copy the children of an existing attribute.

Parameters

[in]	dict	to allocate the children in
[in]	dst	where to copy the children to
[in]	src	where to copy the children from

Returns

0 on success
<0 on error

Definition at line 751 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_attr_acopy_enumv()

int dict_attr_acopy_enumv	(	fr_dict_attr_t *	dst,
		fr_dict_attr_t const *	src
	)

Copy the VALUEs of an existing attribute, by casting them.

Parameters

[in]	dst	where to cast the VALUEs to
[in]	src	where to cast the VALUEs from

Returns

0 on success (but copied no values)
1 on success (but copied at least one value)
<0 on error

Definition at line 804 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_attr_add_to_namespace()

int dict_attr_add_to_namespace	(	fr_dict_attr_t const *	parent,
		fr_dict_attr_t *	da
	)

Add an attribute to the name table for an attribute.

Parameters

[in]	parent	containing the namespace to add this attribute to.
[in]	da	to add to the name lookup tables.

Returns

0 on success.
-1 on failure.

Definition at line 1145 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_attr_alloc()

fr_dict_attr_t* dict_attr_alloc	(	TALLOC_CTX *	ctx,
		fr_dict_attr_t const *	parent,
		char const *	name,
		int	attr,
		fr_type_t	type,
		dict_attr_args_t const *	args
	)

Allocate a dictionary attribute on the heap.

Parameters

[in]	ctx	to allocate the attribute in.
[in]	parent	of the attribute, if none, should be the dictionary root.
[in]	name	of the attribute. If NULL an OID string will be created and set as the name.
[in]	attr	number.
[in]	type	of the attribute.
[in]	args	optional initialisation arguments.

Returns

A new fr_dict_attr_t on success.
NULL on failure.

Definition at line 697 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_attr_alloc_null()

fr_dict_attr_t* dict_attr_alloc_null ( TALLOC_CTX * ctx )

Allocate a partially completed attribute.

This is useful in some instances where we need to pre-allocate the attribute for talloc hierarchy reasons, but want to finish initialising it with dict_attr_init later.

Parameters

[in] ctx to allocate attribute in.

Returns

A new, partially completed, fr_dict_attr_t on success.
NULL on failure (memory allocation error).

Definition at line 657 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_attr_by_name()

fr_dict_attr_t* dict_attr_by_name	(	fr_dict_attr_err_t *	err,
		fr_dict_attr_t const *	parent,
		char const *	name
	)

Definition at line 2814 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_attr_can_have_children()

bool dict_attr_can_have_children ( fr_dict_attr_t const * da )

See if a fr_dict_attr_t can have children.

The check for children is complicated by the need for "int" types to have children, when they are key fields in a struct. This situation occurs when a struct has multiple sub-structures, which are selected based on a key field.

There is no other place for the sub-structures to go. In the future, we may extend the functionality of the key field, by allowing non-integer data types. That would require storing keys as fr_dict_enum_value_t, and then placing the child (i.e. sub) structures there. But that would involve adding children to enums, which is currently not supported.

Parameters

da	the dictionary attribute to check.

Definition at line 1012 of file dict_util.c.

Here is the caller graph for this function:

◆ dict_attr_child_add()

int dict_attr_child_add	(	fr_dict_attr_t *	parent,
		fr_dict_attr_t *	child
	)

Add a child to a parent.

Parameters

[in]	parent	we're adding a child to.
[in]	child	to add to parent.

Returns

0 on success.
-1 on failure (memory allocation error).

Definition at line 1046 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_attr_child_by_num()

fr_dict_attr_t* dict_attr_child_by_num	(	fr_dict_attr_t const *	parent,
		unsigned int	attr
	)

Internal version of fr_dict_attr_child_by_num.

Definition at line 2878 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_attr_enum_add_name()

int dict_attr_enum_add_name	(	fr_dict_attr_t *	da,
		char const *	name,
		fr_value_box_t const *	value,
		bool	coerce,
		bool	replace,
		fr_dict_attr_t const *	child_struct
	)

Definition at line 1346 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_attr_fields_valid()

bool dict_attr_fields_valid	(	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
	)

Validate a new attribute definition.

Todo:: we need to check length of none vendor attributes.

Parameters

[in]	dict	of protocol context we're operating in. If NULL the internal dictionary will be used.
[in]	parent	to add attribute under.
[in]	name	of the attribute.
[in]	attr	number.
[in]	type	of attribute.
[in]	flags	to set in the attribute.

Returns

true if attribute definition is valid.
false if attribute definition is not valid.

Definition at line 599 of file dict_validate.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_attr_flags_valid()

bool dict_attr_flags_valid	(	fr_dict_t *	dict,
		fr_dict_attr_t const *	parent,
		UNUSED char const *	name,
		int *	attr,
		fr_type_t	type,
		fr_dict_attr_flags_t *	flags
	)

Here is the caller graph for this function:

◆ dict_attr_init()

int dict_attr_init	(	fr_dict_attr_t **	da_p,
		fr_dict_attr_t const *	parent,
		char const *	name,
		int	attr,
		fr_type_t	type,
		dict_attr_args_t const *	args
	)

Initialise fields in a dictionary attribute structure.

Note: This function can only be used before the attribute is inserted into the dictionary.

Parameters

[in]	da_p	to initialise.
[in]	parent	of the attribute, if none, should be the dictionary root.
[in]	name	of attribute. Pass NULL for auto-generated name.
[in]	attr	number.
[in]	type	of the attribute.
[in]	args	optional initialisation arguments.

Definition at line 521 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_by_da()

fr_dict_t* dict_by_da ( fr_dict_attr_t const * da )

Internal version of fr_dict_by_da.

Note: For internal use by the dictionary API only.

Attempt to locate the protocol dictionary containing an attribute.

Definition at line 2133 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_by_protocol_name()

fr_dict_t* dict_by_protocol_name ( char const * name )

Internal version of fr_dict_by_protocol_name.

Note: For internal use by the dictionary API only.

Lookup a protocol by its name.

Definition at line 2105 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_by_protocol_num()

fr_dict_t* dict_by_protocol_num ( unsigned int num )

Internal version of fr_dict_by_protocol_num.

Note: For internal use by the dictionary API only.

Lookup a protocol by its number.

Definition at line 2119 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_by_protocol_substr()

fr_slen_t dict_by_protocol_substr	(	fr_dict_attr_err_t *	err,
		fr_dict_t **	out,
		fr_sbuff_t *	name,
		fr_dict_t const *	dict_def
	)

Definition at line 2012 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_dependent_add()

int dict_dependent_add	(	fr_dict_t *	dict,
		char const *	dependent
	)

Record a new dependency on a dictionary.

These are used to determine what is currently depending on a dictionary.

Parameters

[in]	dict	to record dependency on.
[in]	dependent	Either C src file, or another dictionary.

Returns

0 on success.
-1 on failure.

Definition at line 3203 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_dependent_remove()

int dict_dependent_remove	(	fr_dict_t *	dict,
		char const *	dependent
	)

Decrement ref count for a dependent in a dictionary.

Parameters

[in]	dict	to remove dependency from.
[in]	dependent	Either C src, or another dictionary dependent. What depends on this dictionary.

Definition at line 3262 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_dlopen()

int dict_dlopen	(	fr_dict_t *	dict,
		char const *	name
	)

Definition at line 3152 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_has_dependents()

bool dict_has_dependents ( fr_dict_t * dict )

Check if a dictionary still has dependents.

Parameters

[in] dict to check

Returns

true if there's still at least one dependent.
false if there are no dependents.

Definition at line 3294 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_protocol_add()

int dict_protocol_add ( fr_dict_t * dict )

Add a protocol to the global protocol table.

Inserts a protocol into the global protocol table. Uses the root attributes of the dictionary for comparisons.

Parameters

[in] dict of protocol we're inserting.

Returns

0 on success.
-1 on failure.

Definition at line 858 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dict_vendor_add()

int dict_vendor_add	(	fr_dict_t *	dict,
		char const *	name,
		unsigned int	num
	)

Add a vendor to the dictionary.

Inserts a vendor entry into the vendor hash table. This must be done before adding attributes under a VSA.

Parameters

[in]	dict	of protocol context we're operating in. If NULL the internal dictionary will be used.
[in]	name	of the vendor.
[in]	num	Vendor's Private Enterprise Number.

Returns

0 on success.
-1 on failure.

Definition at line 930 of file dict_util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ dict_gctx

fr_dict_gctx_t* dict_gctx

extern

Top level structure containing global dictionary state.

Definition at line 40 of file dict_util.c.

Data Structures

Macros

Functions

Variables

Detailed Description

Data Structure Documentation

◆ dict_attr_args_t

◆ fr_dict

◆ fr_dict_dependent_t

◆ fr_dict_gctx_s

Macro Definition Documentation

◆ _DICT_PRIVATE

◆ DICT_FIXUP_POOL_SIZE

◆ DICT_POOL_SIZE

◆ INTERNAL_IF_NULL

Function Documentation

◆ dict_alloc()

◆ dict_attr_acopy()

◆ dict_attr_acopy_children()

◆ dict_attr_acopy_enumv()

◆ dict_attr_add_to_namespace()

◆ dict_attr_alloc()

◆ dict_attr_alloc_null()

◆ dict_attr_by_name()

◆ dict_attr_can_have_children()

◆ dict_attr_child_add()

◆ dict_attr_child_by_num()

◆ dict_attr_enum_add_name()

◆ dict_attr_fields_valid()

◆ dict_attr_flags_valid()

◆ dict_attr_init()

◆ dict_by_da()

◆ dict_by_protocol_name()

◆ dict_by_protocol_num()

◆ dict_by_protocol_substr()

◆ dict_dependent_add()

◆ dict_dependent_remove()

◆ dict_dlopen()

◆ dict_has_dependents()

◆ dict_protocol_add()

◆ dict_vendor_add()

Variable Documentation

◆ dict_gctx