All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Variables
tmpl.c File Reference

VALUE_PAIR template functions More...

#include <freeradius-devel/radiusd.h>
#include <freeradius-devel/rad_assert.h>
#include <ctype.h>
+ Include dependency graph for tmpl.c:

Go to the source code of this file.

Functions

Parse list and request qualifiers to #pair_lists_t and #request_refs_t values

These functions also resolve pair_lists_t and request_refs_t values to REQUEST structs and the head of VALUE_PAIR lists in those structs.

For adding new VALUE_PAIR to the lists, the radius_list_ctx function can be used to obtain the appropriate TALLOC_CTX pointer.

Note
These don't really have much to do with vp_tmpl_t. They're in the same file as they're used almost exclusively by the tmpl_* functions.
size_t radius_list_name (pair_lists_t *out, char const *name, pair_lists_t def)
 Resolve attribute name to a pair_lists_t value. More...
 
VALUE_PAIR ** radius_list (REQUEST *request, pair_lists_t list)
 Resolve attribute pair_lists_t value to an attribute list. More...
 
RADIUS_PACKETradius_packet (REQUEST *request, pair_lists_t list)
 Resolve a list to the RADIUS_PACKET holding the HEAD pointer for a VALUE_PAIR list. More...
 
TALLOC_CTX * radius_list_ctx (REQUEST *request, pair_lists_t list)
 Return the correct TALLOC_CTX to alloc VALUE_PAIR in, for a list. More...
 
size_t radius_request_name (request_refs_t *out, char const *name, request_refs_t def)
 Resolve attribute name to a request_refs_t value. More...
 
int radius_request (REQUEST **context, request_refs_t name)
 Resolve a request_refs_t to a REQUEST. More...
 
Alloc or initialise #vp_tmpl_t
Note
Should not usually be called outside of tmpl_* functions, use one of the tmpl_*from_* functions instead.
vp_tmpl_ttmpl_init (vp_tmpl_t *vpt, tmpl_type_t type, char const *name, ssize_t len, FR_TOKEN quote)
 Initialise stack allocated vp_tmpl_t. More...
 
vp_tmpl_ttmpl_alloc (TALLOC_CTX *ctx, tmpl_type_t type, char const *name, ssize_t len, FR_TOKEN quote)
 Create a new heap allocated vp_tmpl_t. More...
 
Create new #vp_tmpl_t from a string
void tmpl_from_da (vp_tmpl_t *vpt, fr_dict_attr_t const *da, int8_t tag, int num, request_refs_t request, pair_lists_t list)
 Initialise a vp_tmpl_t to search for, or create attributes. More...
 
int tmpl_afrom_value_data (TALLOC_CTX *ctx, vp_tmpl_t **out, value_data_t *data, PW_TYPE type, fr_dict_attr_t const *enumv, bool steal)
 Create a vp_tmpl_t from a value_data_t. More...
 
ssize_t tmpl_from_attr_substr (vp_tmpl_t *vpt, char const *name, request_refs_t request_def, pair_lists_t list_def, bool allow_unknown, bool allow_undefined)
 Parse a string into a TMPL_TYPE_ATTR_* or TMPL_TYPE_LIST type vp_tmpl_t. More...
 
ssize_t tmpl_from_attr_str (vp_tmpl_t *vpt, char const *name, request_refs_t request_def, pair_lists_t list_def, bool allow_unknown, bool allow_undefined)
 Parse a string into a TMPL_TYPE_ATTR_* or TMPL_TYPE_LIST type vp_tmpl_t. More...
 
ssize_t tmpl_afrom_attr_substr (TALLOC_CTX *ctx, vp_tmpl_t **out, char const *name, request_refs_t request_def, pair_lists_t list_def, bool allow_unknown, bool allow_undefined)
 Parse a string into a TMPL_TYPE_ATTR_* or TMPL_TYPE_LIST type vp_tmpl_t. More...
 
ssize_t tmpl_afrom_attr_str (TALLOC_CTX *ctx, vp_tmpl_t **out, char const *name, request_refs_t request_def, pair_lists_t list_def, bool allow_unknown, bool allow_undefined)
 Parse a string into a TMPL_TYPE_ATTR_* or TMPL_TYPE_LIST type vp_tmpl_t. More...
 
ssize_t tmpl_afrom_str (TALLOC_CTX *ctx, vp_tmpl_t **out, char const *in, size_t inlen, FR_TOKEN type, request_refs_t request_def, pair_lists_t list_def, bool do_unescape)
 Convert an arbitrary string into a vp_tmpl_t. More...
 
Cast or convert #vp_tmpl_t

tmpl_cast_in_place can be used to convert TMPL_TYPE_UNPARSED to a TMPL_TYPE_DATA of a specified PW_TYPE.

tmpl_cast_in_place_str does the same as tmpl_cast_in_place, but will always convert to PW_TYPE PW_TYPE_STRING.

tmpl_cast_to_vp does the same as tmpl_cast_in_place, but outputs a VALUE_PAIR.

tmpl_define_unknown_attr converts a TMPL_TYPE_ATTR with an unknown fr_dict_attr_t to a TMPL_TYPE_ATTR with a known fr_dict_attr_t, by adding the unknown fr_dict_attr_t to the main dictionary, and updating the tmpl_da pointer.

int tmpl_cast_in_place (vp_tmpl_t *vpt, PW_TYPE type, fr_dict_attr_t const *enumv)
 Convert vp_tmpl_t of type TMPL_TYPE_UNPARSED or TMPL_TYPE_DATA to TMPL_TYPE_DATA of type specified. More...
 
void tmpl_cast_in_place_str (vp_tmpl_t *vpt)
 Convert vp_tmpl_t of type TMPL_TYPE_UNPARSED to TMPL_TYPE_DATA of type PW_TYPE_STRING. More...
 
int tmpl_cast_to_vp (VALUE_PAIR **out, REQUEST *request, vp_tmpl_t const *vpt, fr_dict_attr_t const *cast)
 Expand a vp_tmpl_t to a string, parse it as an attribute of type cast, create a VALUE_PAIR from the result. More...
 
int tmpl_define_unknown_attr (vp_tmpl_t *vpt)
 Add an unknown fr_dict_attr_t specified by a vp_tmpl_t to the main dictionary. More...
 
int tmpl_define_undefined_attr (vp_tmpl_t *vpt, PW_TYPE type, fr_dict_attr_flags_t const *flags)
 Add an undefined fr_dict_attr_t specified by a vp_tmpl_t to the main dictionary. More...
 
Resolve a #vp_tmpl_t outputting the result in various formats
ssize_t tmpl_expand (char const **out, char *buff, size_t bufflen, REQUEST *request, vp_tmpl_t const *vpt, xlat_escape_t escape, void *escape_ctx)
 Expand a vp_tmpl_t to a string writing the result to a buffer. More...
 
ssize_t tmpl_aexpand (TALLOC_CTX *ctx, char **out, REQUEST *request, vp_tmpl_t const *vpt, xlat_escape_t escape, void *escape_ctx)
 Expand a template to a string, allocing a new buffer to hold the string. More...
 
size_t tmpl_snprint (char *out, size_t outlen, vp_tmpl_t const *vpt, fr_dict_attr_t const *values)
 Print a vp_tmpl_t to a string. More...
 
VALUE_PAIRtmpl_cursor_init (int *err, vp_cursor_t *cursor, REQUEST *request, vp_tmpl_t const *vpt)
 Initialise a vp_cursor_t to the VALUE_PAIR specified by a vp_tmpl_t. More...
 
VALUE_PAIRtmpl_cursor_next (vp_cursor_t *cursor, vp_tmpl_t const *vpt)
 Returns the next VALUE_PAIR specified by vpt. More...
 
int tmpl_copy_vps (TALLOC_CTX *ctx, VALUE_PAIR **out, REQUEST *request, vp_tmpl_t const *vpt)
 Copy pairs matching a vp_tmpl_t in the current REQUEST. More...
 
int tmpl_find_vp (VALUE_PAIR **out, REQUEST *request, vp_tmpl_t const *vpt)
 Returns the first VP matching a vp_tmpl_t. More...
 
int tmpl_find_or_add_vp (VALUE_PAIR **out, REQUEST *request, vp_tmpl_t const *vpt)
 Returns the first VP matching a vp_tmpl_t, or if no VPs match, creates a new one. More...
 

Variables

const FR_NAME_NUMBER pair_lists []
 Map keywords to pair_lists_t values. More...
 
const FR_NAME_NUMBER request_refs []
 Map keywords to request_refs_t values. More...
 
FR_NAME_NUMBER const tmpl_names []
 Map tmpl_type_t values to descriptive strings. More...
 

Detailed Description

VALUE_PAIR template functions

Id:
6769d5a08663f1efbddab110468dd57147bb33dd

Definition in file tmpl.c.

Function Documentation

VALUE_PAIR** radius_list ( REQUEST request,
pair_lists_t  list 
)

Resolve attribute pair_lists_t value to an attribute list.

The value returned is a pointer to the pointer of the HEAD of a VALUE_PAIR list in the REQUEST. If the head of the list changes, the pointer will still be valid.

Parameters
[in]requestcontaining the target lists.
[in]listpair_lists_t value to resolve to VALUE_PAIR list. Will be NULL if list name couldn't be resolved.
Returns
a pointer to the HEAD of a list in the REQUEST.
See Also
tmpl_cursor_init
fr_cursor_init

Definition at line 195 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

TALLOC_CTX* radius_list_ctx ( REQUEST request,
pair_lists_t  list 
)

Return the correct TALLOC_CTX to alloc VALUE_PAIR in, for a list.

Allocating new VALUE_PAIR in the context of a REQUEST is usually wrong. VALUE_PAIR should be allocated in the context of a RADIUS_PACKET, so that if the RADIUS_PACKET is freed before the REQUEST, the associated VALUE_PAIR lists are freed too.

Parameters
[in]requestcontaining the target lists.
[in]listpair_lists_t value to resolve to TALLOC_CTX.
Returns
  • TALLOC_CTX on success.
  • NULL on failure.
See Also
radius_list

Definition at line 331 of file tmpl.c.

+ Here is the caller graph for this function:

size_t radius_list_name ( pair_lists_t out,
char const *  name,
pair_lists_t  def 
)

Resolve attribute name to a pair_lists_t value.

Check the name string for pair_lists qualifiers and write a pair_lists_t value for that list to out. This value may be passed to radius_list, along with the current REQUEST, to get a pointer to the actual list in the REQUEST.

If we're sure we've definitely found a list qualifier token delimiter (:) but the string doesn't match a radius_list qualifier, return 0 and write PAIR_LIST_UNKNOWN to out.

If we can't find a string that looks like a request qualifier, set out to def, and return 0.

Note
radius_list_name should be called before passing a name string that may contain qualifiers to fr_dict_attr_by_name.
Parameters
[out]outWhere to write the list qualifier.
[in]nameString containing list qualifiers to parse.
[in]defthe list to return if no qualifiers were found.
Returns
0 if no valid list qualifier could be found, else the number of bytes consumed. The caller may then advanced the name pointer by the value returned, to get the start of the attribute name (if any).
See Also
pair_list
radius_list

Definition at line 120 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

RADIUS_PACKET* radius_packet ( REQUEST request,
pair_lists_t  list 
)

Resolve a list to the RADIUS_PACKET holding the HEAD pointer for a VALUE_PAIR list.

Returns a pointer to the RADIUS_PACKET that holds the HEAD pointer of a given list, for the current REQUEST.

Parameters
[in]requestTo resolve list in.
[in]listpair_lists_t value to resolve to RADIUS_PACKET.
Returns
See Also
radius_list

Definition at line 279 of file tmpl.c.

+ Here is the caller graph for this function:

int radius_request ( REQUEST **  context,
request_refs_t  name 
)

Resolve a request_refs_t to a REQUEST.

Sometimes REQUEST structs may be chained to each other, as is the case when internally proxying EAP. This function resolves a request_refs_t to a REQUEST higher in the chain than the current REQUEST.

See Also
radius_list
Parameters
[in,out]contextREQUEST to start resolving from, and where to write a pointer to the resolved REQUEST back to.
[in]name(request) to resolve.
Returns
  • 0 if request is valid in this context.
  • -1 if request is not valid in this context.

Definition at line 451 of file tmpl.c.

+ Here is the caller graph for this function:

size_t radius_request_name ( request_refs_t out,
char const *  name,
request_refs_t  def 
)

Resolve attribute name to a request_refs_t value.

Check the name string for qualifiers that reference a parent REQUEST.

If we find a string that matches a request_refs qualifier, return the number of chars we consumed.

If we're sure we've definitely found a list qualifier token delimiter (*) but the qualifier doesn't match one of the request_refs qualifiers, return 0 and set out to REQUEST_UNKNOWN.

If we can't find a string that looks like a request qualifier, set out to def, and return 0.

Parameters
[out]outThe request_refs_t value the name resolved to (or REQUEST_UNKNOWN).
[in]nameof attribute.
[in]defdefault request ref to return if no request qualifier is present.
Returns
0 if no valid request qualifier could be found, else the number of bytes consumed. The caller may then advanced the name pointer by the value returned, to get the start of the attribute list or attribute name(if any).
See Also
radius_list_name
request_refs

Definition at line 413 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

ssize_t tmpl_aexpand ( TALLOC_CTX *  ctx,
char **  out,
REQUEST request,
vp_tmpl_t const *  vpt,
xlat_escape_t  escape,
void *  escape_ctx 
)

Expand a template to a string, allocing a new buffer to hold the string.

The intended use of tmpl_expand and tmpl_aexpand is for modules to easily convert a vp_tmpl_t provided by the conf parser, into a usable value. The value returned should be raw and undoctored for PW_TYPE_STRING and PW_TYPE_OCTETS types, and the printable (string) version of the data for all others.

This function will always duplicate values, whereas tmpl_expand may return a pointer to an existing buffer.

Note
This function is used where raw string values are needed, which may mean the string returned may be binary data or contain unprintable chars. fr_snprint or fr_asprint should be used before using these values in debug statements. is_printable can be used to check if the string only contains printable chars.
The type (char or uint8_t) can be obtained with talloc_get_type, and may be used as a hint as to how to process or print the data.
Parameters
ctxto allocate new buffer in.
outWhere to write pointer to the new buffer.
requestCurrent request.
vptto expand. Must be one of the following types:
escapexlat escape function (only used for xlat types).
escape_ctxxlat escape function data (only used for xlat types).
Returns
  • -1 on failure.
  • The length of data written to buff, or pointed to by out.

Definition at line 1653 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

ssize_t tmpl_afrom_attr_str ( TALLOC_CTX *  ctx,
vp_tmpl_t **  out,
char const *  name,
request_refs_t  request_def,
pair_lists_t  list_def,
bool  allow_unknown,
bool  allow_undefined 
)

Parse a string into a TMPL_TYPE_ATTR_* or TMPL_TYPE_LIST type vp_tmpl_t.

Note
Unlike tmpl_afrom_attr_substr this function will error out if the entire name string isn't parsed.
Parameters
[in,out]ctxto allocate vp_tmpl_t in.
[out]outWhere to write pointer to new vp_tmpl_t.
[in]nameof attribute including request_refs and pair_lists qualifiers. If only request_refs pair_lists qualifiers are found, a TMPL_TYPE_LIST vp_tmpl_t will be produced.
[in]request_defThe default REQUEST to set if no request_refs qualifiers are found in name.
[in]list_defThe default list to set if no pair_lists qualifiers are found in name.
[in]allow_unknownIf true attributes in the format accepted by fr_dict_unknown_from_suboid will be allowed, even if they're not in the main dictionaries. If an unknown attribute is found a TMPL_TYPE_ATTR vp_tmpl_t will be produced with the unknown fr_dict_attr_t stored in the unknown.da buffer. This fr_dict_attr_t will have its flags.is_unknown field set to true. If tmpl_from_attr_substr is being called on startup, the vp_tmpl_t may be passed to tmpl_define_unknown_attr to add the unknown attribute to the main dictionary. If the unknown attribute is not added to the main dictionary the vp_tmpl_t cannot be used to search for a VALUE_PAIR in a REQUEST.
[in]allow_undefinedIf true, we don't generate a parse error on unknown attributes. If an unknown attribute is found a TMPL_TYPE_ATTR_UNDEFINED vp_tmpl_t will be produced.
Returns
<= 0 on error (offset as negative integer), > 0 on success (number of bytes parsed).
See Also
REMARKER to produce pretty error markers from the return value.

Definition at line 956 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

ssize_t tmpl_afrom_attr_substr ( TALLOC_CTX *  ctx,
vp_tmpl_t **  out,
char const *  name,
request_refs_t  request_def,
pair_lists_t  list_def,
bool  allow_unknown,
bool  allow_undefined 
)

Parse a string into a TMPL_TYPE_ATTR_* or TMPL_TYPE_LIST type vp_tmpl_t.

Parameters
[in,out]ctxto allocate vp_tmpl_t in.
[out]outWhere to write pointer to new vp_tmpl_t.
[in]nameof attribute including request_refs and pair_lists qualifiers. If only request_refs pair_lists qualifiers are found, a TMPL_TYPE_LIST vp_tmpl_t will be produced.
[in]request_defThe default REQUEST to set if no request_refs qualifiers are found in name.
[in]list_defThe default list to set if no pair_lists qualifiers are found in name.
[in]allow_unknownIf true attributes in the format accepted by fr_dict_unknown_from_suboid will be allowed, even if they're not in the main dictionaries. If an unknown attribute is found a TMPL_TYPE_ATTR vp_tmpl_t will be produced with the unknown fr_dict_attr_t stored in the unknown.da buffer. This fr_dict_attr_t will have its flags.is_unknown field set to true. If tmpl_from_attr_substr is being called on startup, the vp_tmpl_t may be passed to tmpl_define_unknown_attr to add the unknown attribute to the main dictionary. If the unknown attribute is not added to the main dictionary the vp_tmpl_t cannot be used to search for a VALUE_PAIR in a REQUEST.
[in]allow_undefinedIf true, we don't generate a parse error on unknown attributes. If an unknown attribute is found a TMPL_TYPE_ATTR_UNDEFINED vp_tmpl_t will be produced.
Returns
<= 0 on error (offset as negative integer), > 0 on success (number of bytes parsed).
See Also
REMARKER to produce pretty error markers from the return value.

Definition at line 926 of file tmpl.c.

+ Here is the call graph for this function:

ssize_t tmpl_afrom_str ( TALLOC_CTX *  ctx,
vp_tmpl_t **  out,
char const *  in,
size_t  inlen,
FR_TOKEN  type,
request_refs_t  request_def,
pair_lists_t  list_def,
bool  do_unescape 
)

Convert an arbitrary string into a vp_tmpl_t.

Note
Unlike tmpl_afrom_attr_str return code 0 doesn't necessarily indicate failure, may just mean a 0 length string was parsed.
xlats and regexes are left uncompiled. This is to support the two pass parsing done by the modcall code. Compilation on pass1 of that code could fail, as attributes or xlat functions registered by modules may not be available (yet).
For details of attribute parsing see tmpl_from_attr_substr.
Parameters
[in,out]ctxTo allocate vp_tmpl_t in.
[out]outWhere to write the pointer to the new vp_tmpl_t.
[in]inString to convert to a vp_tmpl_t.
[in]inlenlength of string to convert.
[in]typeof quoting around value. May be one of:
[in]request_defThe default REQUEST to set if no request_refs qualifiers are found in name.
[in]list_defThe default list to set if no pair_lists qualifiers are found in name.
[in]do_unescapewhether or not we should do unescaping. Should be false if the caller already did it.
Returns
<= 0 on error (offset as negative integer), > 0 on success (number of bytes parsed).
See Also
REMARKER to produce pretty error markers from the return value.
tmpl_from_attr_substr

Definition at line 1022 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

int tmpl_afrom_value_data ( TALLOC_CTX *  ctx,
vp_tmpl_t **  out,
value_data_t data,
PW_TYPE  type,
fr_dict_attr_t const *  enumv,
bool  steal 
)

Create a vp_tmpl_t from a value_data_t.

Parameters
[in,out]ctxto allocate vp_tmpl_t in.
[out]outWhere to write pointer to new vp_tmpl_t.
[in]datato convert.
[in]typeof data.
[in]enumvUsed to convert integers to string types for printing. May be NULL.
[in]stealIf true, any buffers are moved to the new ctx instead of being duplicated.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 595 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

vp_tmpl_t* tmpl_alloc ( TALLOC_CTX *  ctx,
tmpl_type_t  type,
char const *  name,
ssize_t  len,
FR_TOKEN  quote 
)

Create a new heap allocated vp_tmpl_t.

Parameters
[in,out]ctxto allocate in.
[in]typeto set in the vp_tmpl_t.
[in]nameof the vp_tmpl_t (will be copied to a new talloc buffer parented by the vp_tmpl_t).
[in]lenThe length of the buffer (or a substring of the buffer) pointed to by name. If < 0 strlen will be used to determine the length.
[in]quoteThe type of quoting around the template name.
Returns
the newly allocated vp_tmpl_t.

Definition at line 526 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

int tmpl_cast_in_place ( vp_tmpl_t vpt,
PW_TYPE  type,
fr_dict_attr_t const *  enumv 
)

Convert vp_tmpl_t of type TMPL_TYPE_UNPARSED or TMPL_TYPE_DATA to TMPL_TYPE_DATA of type specified.

Note
Conversion is done in place.
Irrespective of whether the vp_tmpl_t was TMPL_TYPE_UNPARSED or TMPL_TYPE_DATA, on successful cast it will be TMPL_TYPE_DATA.
Parameters
[in,out]vptThe template to modify. Must be of type TMPL_TYPE_UNPARSED or TMPL_TYPE_DATA.
[in]typeto cast to.
[in]enumvEnumerated dictionary values associated with a fr_dict_attr_t.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 1212 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

void tmpl_cast_in_place_str ( vp_tmpl_t vpt)

Convert vp_tmpl_t of type TMPL_TYPE_UNPARSED to TMPL_TYPE_DATA of type PW_TYPE_STRING.

Note
Conversion is done in place.
Parameters
[in,out]vptThe template to modify. Must be of type TMPL_TYPE_UNPARSED.

Definition at line 1273 of file tmpl.c.

+ Here is the call graph for this function:

int tmpl_cast_to_vp ( VALUE_PAIR **  out,
REQUEST request,
vp_tmpl_t const *  vpt,
fr_dict_attr_t const *  cast 
)

Expand a vp_tmpl_t to a string, parse it as an attribute of type cast, create a VALUE_PAIR from the result.

Note
Like tmpl_expand, but produces a VALUE_PAIR.
Parameters
outWhere to write pointer to the new VALUE_PAIR.
requestThe current REQUEST.
vptto cast. Must be one of the following types:
casttype of VALUE_PAIR to create.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 1304 of file tmpl.c.

+ Here is the call graph for this function:

int tmpl_copy_vps ( TALLOC_CTX *  ctx,
VALUE_PAIR **  out,
REQUEST request,
vp_tmpl_t const *  vpt 
)

Copy pairs matching a vp_tmpl_t in the current REQUEST.

Parameters
ctxto allocate new VALUE_PAIR in.
outWhere to write the copied VALUE_PAIR (s).
requestThe current REQUEST.
vptspecifying the VALUE_PAIR type/tag or list to copy. Must be one of the following types:
Returns
  • -1 if no matching VALUE_PAIR could be found.
  • -2 if list could not be found (doesn't exist in current REQUEST).
  • -3 if context could not be found (no parent REQUEST available).
  • -4 on memory allocation error.

Definition at line 2181 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

VALUE_PAIR* tmpl_cursor_init ( int *  err,
vp_cursor_t cursor,
REQUEST request,
vp_tmpl_t const *  vpt 
)

Initialise a vp_cursor_t to the VALUE_PAIR specified by a vp_tmpl_t.

This makes iterating over the one or more VALUE_PAIR specified by a vp_tmpl_t significantly easier.

Parameters
errMay be NULL if no error code is required. Will be set to:
  • 0 on success.
  • -1 if no matching VALUE_PAIR could be found.
  • -2 if list could not be found (doesn't exist in current REQUEST).
  • -3 if context could not be found (no parent REQUEST available).
cursorto store iterator state.
requestThe current REQUEST.
vptspecifying the VALUE_PAIR type/tag or list to iterate over.
Returns
See Also
tmpl_cursor_next

Definition at line 1990 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

VALUE_PAIR* tmpl_cursor_next ( vp_cursor_t cursor,
vp_tmpl_t const *  vpt 
)

Returns the next VALUE_PAIR specified by vpt.

Parameters
cursorinitialised with tmpl_cursor_init.
vptspecifying the VALUE_PAIR type/tag to iterate over. Must be one of the following types:
Returns

Definition at line 2128 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

int tmpl_define_undefined_attr ( vp_tmpl_t vpt,
PW_TYPE  type,
fr_dict_attr_flags_t const *  flags 
)

Add an undefined fr_dict_attr_t specified by a vp_tmpl_t to the main dictionary.

Note
fr_dict_attr_add will not return an error if the attribute already exists meaning that multiple vp_tmpl_t specifying the same attribute can be passed to this function to be fixed up, so long as the type and flags are identical.
Parameters
vptspecifying undefined attribute to add. tmpl_da pointer will be updated to point to the fr_dict_attr_t inserted into the dictionary. Lists and requests will be preserved.
typeto define undefined attribute as.
flagsto define undefined attribute with.
Returns
  • 1 noop (did nothing) - Not possible to convert tmpl.
  • 0 on success.
  • -1 on failure.

Definition at line 1396 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

int tmpl_define_unknown_attr ( vp_tmpl_t vpt)

Add an unknown fr_dict_attr_t specified by a vp_tmpl_t to the main dictionary.

Parameters
vptto add. tmpl_da pointer will be updated to point to the fr_dict_attr_t inserted into the dictionary.
Returns
  • 1 noop (did nothing) - Not possible to convert tmpl.
  • 0 on success.
  • -1 on failure.

Definition at line 1360 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

ssize_t tmpl_expand ( char const **  out,
char *  buff,
size_t  bufflen,
REQUEST request,
vp_tmpl_t const *  vpt,
xlat_escape_t  escape,
void *  escape_ctx 
)

Expand a vp_tmpl_t to a string writing the result to a buffer.

The intended use of tmpl_expand and tmpl_aexpand is for modules to easily convert a vp_tmpl_t provided by the conf parser, into a usable value. The value returned should be raw and undoctored for PW_TYPE_STRING and PW_TYPE_OCTETS types, and the printable (string) version of the data for all others.

Depending what arguments are passed, either copies the value to buff, or writes a pointer to a string buffer to out. This allows the most efficient access to the value resolved by the vp_tmpl_t, avoiding unecessary string copies.

Note
This function is used where raw string values are needed, which may mean the string returned may be binary data or contain unprintable chars. fr_snprint or fr_asprint should be used before using these values in debug statements. is_printable can be used to check if the string only contains printable chars.
Parameters
outWhere to write a pointer to the string buffer. On return may point to buff if buff was used to store the value. Otherwise will point to a value_data_t buffer, or the name of the template. To force copying to buff, out should be NULL.
buffExpansion buffer, may be NULL if out is not NULL, and processing TMPL_TYPE_UNPARSED or string types.
bufflenLength of expansion buffer.
requestCurrent request.
vptto expand. Must be one of the following types:
escapexlat escape function (only used for xlat types).
escape_ctxxlat escape function data.
Returns
  • -1 on failure.
  • The length of data written to buff, or pointed to by out.
Todo:
tmpl_expand should accept an enumv da from the lhs of the map.

Definition at line 1479 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

int tmpl_find_or_add_vp ( VALUE_PAIR **  out,
REQUEST request,
vp_tmpl_t const *  vpt 
)

Returns the first VP matching a vp_tmpl_t, or if no VPs match, creates a new one.

Parameters
[out]outwhere to write the retrieved or created vp.
[in]requestThe current REQUEST.
[in]vptspecifying the VALUE_PAIR type/tag to retrieve or create. Must be TMPL_TYPE_ATTR.
Returns
  • 1 on success a pair was created.
  • 0 on success a pair was found.
  • -1 if a new VALUE_PAIR couldn't be found or created.
  • -2 if list could not be found (doesn't exist in current REQUEST).
  • -3 if context could not be found (no parent REQUEST available).

Definition at line 2251 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

int tmpl_find_vp ( VALUE_PAIR **  out,
REQUEST request,
vp_tmpl_t const *  vpt 
)

Returns the first VP matching a vp_tmpl_t.

Parameters
[out]outwhere to write the retrieved vp.
[in]requestThe current REQUEST.
[in]vptspecifying the VALUE_PAIR type/tag to find. Must be one of the following types:
Returns
  • 0 on success (found matching VALUE_PAIR).
  • -1 if no matching VALUE_PAIR could be found.
  • -2 if list could not be found (doesn't exist in current REQUEST).
  • -3 if context could not be found (no parent REQUEST available).

Definition at line 2224 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

ssize_t tmpl_from_attr_str ( vp_tmpl_t vpt,
char const *  name,
request_refs_t  request_def,
pair_lists_t  list_def,
bool  allow_unknown,
bool  allow_undefined 
)

Parse a string into a TMPL_TYPE_ATTR_* or TMPL_TYPE_LIST type vp_tmpl_t.

Note
Unlike tmpl_from_attr_substr this function will error out if the entire name string isn't parsed.
The name field is just a copy of the input pointer, if you know that string might be freed before you're done with the vp_tmpl_t use tmpl_afrom_attr_str instead.
Parameters
[out]vptto modify.
[in]nameof attribute including request_refs and pair_lists qualifiers. If only request_refs and pair_lists qualifiers are found, a TMPL_TYPE_LIST vp_tmpl_t will be produced.
[in]request_defThe default REQUEST to set if no request_refs qualifiers are found in name.
[in]list_defThe default list to set if no pair_lists qualifiers are found in name.
[in]allow_unknownIf true attributes in the format accepted by fr_dict_unknown_from_suboid will be allowed, even if they're not in the main dictionaries. If an unknown attribute is found a TMPL_TYPE_ATTR vp_tmpl_t will be produced with the unknown fr_dict_attr_t stored in the unknown.da buffer. This fr_dict_attr_t will have its flags.is_unknown field set to true. If tmpl_from_attr_substr is being called on startup, the vp_tmpl_t may be passed to tmpl_define_unknown_attr to add the unknown attribute to the main dictionary. If the unknown attribute is not added to the main dictionary the vp_tmpl_t cannot be used to search for a VALUE_PAIR in a REQUEST.
[in]allow_undefinedIf true, we don't generate a parse error on unknown attributes. If an unknown attribute is found a TMPL_TYPE_ATTR_UNDEFINED vp_tmpl_t will be produced. A vp_tmpl_t of this type can be passed to tmpl_define_undefined_attr which will add the attribute to the global dictionary, and fixup the vp_tmpl_t, changing it to a TMPL_TYPE_ATTR with a pointer to the new fr_dict_attr_t.
Returns
  • <= 0 on error (parse failure offset as negative integer).
  • > 0 on success (number of bytes parsed).
See Also
REMARKER to produce pretty error markers from the return value.

Definition at line 877 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

ssize_t tmpl_from_attr_substr ( vp_tmpl_t vpt,
char const *  name,
request_refs_t  request_def,
pair_lists_t  list_def,
bool  allow_unknown,
bool  allow_undefined 
)

Parse a string into a TMPL_TYPE_ATTR_* or TMPL_TYPE_LIST type vp_tmpl_t.

Note
The name field is just a copy of the input pointer, if you know that string might be freed before you're done with the vp_tmpl_t use tmpl_afrom_attr_str instead.
Parameters
[out]vptto modify.
[in]nameof attribute including request_refs and pair_lists qualifiers. If only request_refs and pair_lists qualifiers are found, a TMPL_TYPE_LIST vp_tmpl_t will be produced.
[in]request_defThe default REQUEST to set if no request_refs qualifiers are found in name.
[in]list_defThe default list to set if no pair_lists qualifiers are found in name.
[in]allow_unknownIf true attributes in the format accepted by fr_dict_unknown_from_suboid will be allowed, even if they're not in the main dictionaries. If an unknown attribute is found a TMPL_TYPE_ATTR vp_tmpl_t will be produced with the unknown fr_dict_attr_t stored in the unknown.da buffer. This fr_dict_attr_t will have its flags.is_unknown field set to true. If tmpl_from_attr_substr is being called on startup, the vp_tmpl_t may be passed to tmpl_define_unknown_attr to add the unknown attribute to the main dictionary. If the unknown attribute is not added to the main dictionary the vp_tmpl_t cannot be used to search for a VALUE_PAIR in a REQUEST.
[in]allow_undefinedIf true, we don't generate a parse error on unknown attributes. If an unknown attribute is found a TMPL_TYPE_ATTR_UNDEFINED vp_tmpl_t will be produced. A vp_tmpl_t of this type can be passed to tmpl_define_undefined_attr which will add the attribute to the global dictionary, and fixup the vp_tmpl_t, changing it to a TMPL_TYPE_ATTR with a pointer to the new fr_dict_attr_t.
Returns
  • <= 0 on error (parse failure offset as negative integer).
  • > 0 on success (number of bytes parsed).
See Also
REMARKER to produce pretty error markers from the return value.

Definition at line 661 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

void tmpl_from_da ( vp_tmpl_t vpt,
fr_dict_attr_t const *  da,
int8_t  tag,
int  num,
request_refs_t  request,
pair_lists_t  list 
)

Initialise a vp_tmpl_t to search for, or create attributes.

Parameters
vptto initialise.
daof VALUE_PAIR type to operate on.
tagMust be one of:
  • A positive integer specifying a specific tag.
  • TAG_ANY - Attribute with no specific tag value.
  • TAG_NONE - No tag.
numSpecific instance, or all instances. Must be one of:
  • A positive integer specifying an instance.
  • NUM_ALL - All instances.
  • NUM_ANY - The first instance found.
  • NUM_LAST - The last instance found.
requestto operate on.
listto operate on.

Definition at line 567 of file tmpl.c.

+ Here is the call graph for this function:

vp_tmpl_t* tmpl_init ( vp_tmpl_t vpt,
tmpl_type_t  type,
char const *  name,
ssize_t  len,
FR_TOKEN  quote 
)

Initialise stack allocated vp_tmpl_t.

Note
Name is not strdupe'd or memcpy'd so must be available, and must not change for the lifetime of the vp_tmpl_t.
Parameters
[out]vptto initialise.
[in]typeto set in the vp_tmpl_t.
[in]nameof the vp_tmpl_t.
[in]lenThe length of the buffer (or a substring of the buffer) pointed to by name. If < 0 strlen will be used to determine the length.
[in]quoteThe type of quoting around the template name.
Returns
a pointer to the initialised vp_tmpl_t. The same value as vpt.

Definition at line 497 of file tmpl.c.

+ Here is the caller graph for this function:

size_t tmpl_snprint ( char *  out,
size_t  outlen,
vp_tmpl_t const *  vpt,
fr_dict_attr_t const *  values 
)

Print a vp_tmpl_t to a string.

Parameters
[out]outWhere to write the presentation format vp_tmpl_t string.
[in]outlenSize of output buffer.
[in]vptto print.
[in]valuesUsed for TMPL_TYPE_DATA only. fr_dict_attr_t to use when mapping integer values to strings.
Returns
  • The number of bytes written to the out buffer.
  • A number >= outlen if truncation has occurred.

Definition at line 1822 of file tmpl.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

Variable Documentation

Initial value:
= {
{ "request", PAIR_LIST_REQUEST },
{ "reply", PAIR_LIST_REPLY },
{ "control", PAIR_LIST_CONTROL },
{ "config", PAIR_LIST_CONTROL },
{ "session-state", PAIR_LIST_STATE },
{ "proxy-request", PAIR_LIST_PROXY_REQUEST },
{ "proxy-reply", PAIR_LIST_PROXY_REPLY },
{ "coa", PAIR_LIST_COA },
{ "coa-reply", PAIR_LIST_COA_REPLY },
{ "disconnect", PAIR_LIST_DM },
{ "disconnect-reply", PAIR_LIST_DM_REPLY },
{ NULL , -1 }
}
Attributes sent in response to the forked Disconnect-Request.
Definition: tmpl.h:101
Attributes to send in a forked CoA-Request.
Definition: tmpl.h:97
A copy of attributes in the request list that may be modified in pre-proxy before proxying the reques...
Definition: tmpl.h:90
Attributes to send in a forked Disconnect-Request.
Definition: tmpl.h:100
Attributes sent in response to the forked CoA-Request.
Definition: tmpl.h:98
Attributes in incoming or internally proxied request.
Definition: tmpl.h:82
Attributes to send in the response.
Definition: tmpl.h:84
Attributes to store multiple rounds of challenges/responses.
Definition: tmpl.h:87
Attributes that change the behaviour of modules.
Definition: tmpl.h:85
Attributes sent in response to the proxied request.
Definition: tmpl.h:93

Map keywords to pair_lists_t values.

Definition at line 53 of file tmpl.c.

const FR_NAME_NUMBER request_refs[]
Initial value:
= {
{ "outer", REQUEST_OUTER },
{ "current", REQUEST_CURRENT },
{ "parent", REQUEST_PARENT },
{ NULL , -1 }
}
REQUEST containing the outer layer of the EAP conversation.
Definition: tmpl.h:110
The current request.
Definition: tmpl.h:113
Not currently used.
Definition: tmpl.h:114

Map keywords to request_refs_t values.

Definition at line 74 of file tmpl.c.

FR_NAME_NUMBER const tmpl_names[]
Initial value:
= {
{ "literal", TMPL_TYPE_UNPARSED },
{ "xlat", TMPL_TYPE_XLAT },
{ "attr", TMPL_TYPE_ATTR },
{ "unknown attr", TMPL_TYPE_ATTR_UNDEFINED },
{ "list", TMPL_TYPE_LIST },
{ "regex", TMPL_TYPE_REGEX },
{ "exec", TMPL_TYPE_EXEC },
{ "data", TMPL_TYPE_DATA },
{ "parsed xlat", TMPL_TYPE_XLAT_STRUCT },
{ "parsed regex", TMPL_TYPE_REGEX_STRUCT },
{ "null", TMPL_TYPE_NULL },
{ NULL, 0 }
}
Dictionary attribute.
Definition: tmpl.h:133
Pre-parsed XLAT expansion.
Definition: tmpl.h:139
Unparsed literal string.
Definition: tmpl.h:131
Attribute not found in the global dictionary.
Definition: tmpl.h:134
Pre-parsed regular expression.
Definition: tmpl.h:140
Value in native format.
Definition: tmpl.h:138
Regular expression.
Definition: tmpl.h:136
Attribute list.
Definition: tmpl.h:135
Callout to an external script or program.
Definition: tmpl.h:137
XLAT expansion.
Definition: tmpl.h:132
Has no value.
Definition: tmpl.h:141

Map tmpl_type_t values to descriptive strings.

Definition at line 36 of file tmpl.c.