The FreeRADIUS server  $Id: 15bac2a4c627c01d1aa2047687b3418955ac7f00 $
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
xlat.h File Reference

xlat expansion parsing and evaluation API. More...

#include <freeradius-devel/server/request.h>
#include <freeradius-devel/server/cf_util.h>
#include <freeradius-devel/server/signal.h>
#include <freeradius-devel/server/tmpl.h>
#include <freeradius-devel/util/heap.h>
#include <freeradius-devel/util/pair.h>
#include <freeradius-devel/util/sbuff.h>
#include <freeradius-devel/util/time.h>
#include <freeradius-devel/util/value.h>
#include <freeradius-devel/unlang/call_env.h>
#include <freeradius-devel/unlang/xlat_ctx.h>
+ Include dependency graph for xlat.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  xlat_arg_parser_t
 Definition for a single argument consumend by an xlat function. More...
 
struct  xlat_flags_t
 Flags that control resolution and evaluation. More...
 
struct  xlat_inst_s
 Instance data for an xlat expansion node. More...
 
struct  xlat_res_rules_t
 
struct  xlat_thread_inst_s
 Thread specific instance data for xlat expansion node. More...
 

Macros

#define _XLAT_ARGS_X(XLAT_ARGS_N, _list, ...)   XLAT_ARGS_N(_list, __VA_ARGS__)
 Trampoline macro for selecting which XLAT_ARGS_<num> macro to expand. More...
 
#define XLAT_ARG_PARSER_TERMINATOR
 
#define XLAT_ARGS(_list, ...)   _XLAT_ARGS_X(JOIN(XLAT_ARGS_, VA_NARG(__VA_ARGS__)), _list, __VA_ARGS__)
 Populate local variables with value boxes from the input list. More...
 
#define XLAT_ARGS_1(_list, _a)    *(_a) = fr_value_box_list_head(_list)
 
#define XLAT_ARGS_2(_list, _a, _b)
 
#define XLAT_ARGS_3(_list, _a, _b, _c)
 
#define XLAT_ARGS_4(_list, _a, _b, _c, _d)
 
#define XLAT_ARGS_5(_list, _a, _b, _c, _d, _e)
 
#define XLAT_ARGS_6(_list, _a, _b, _c, _d, _e, _f)
 
#define XLAT_ARGS_7(_list, _a, _b, _c, _d, _e, _f, _g)
 
#define XLAT_ARGS_8(_list, _a, _b, _c, _d, _e, _f, _g, _h)
 
#define XLAT_ARGS_NEXT(_list, _prev, _curr)   *(_curr) = likely(*(_prev) != NULL) ? fr_value_box_list_next(_list, *(_prev)) : NULL
 Set the next argument to the next item in the input list or NULL. More...
 
#define xlat_copy(_ctx, _out, _in)   _xlat_copy(NDEBUG_LOCATION_EXP _ctx, _out, _in)
 
#define XLAT_HEAD_VERIFY(_head)
 
#define XLAT_VERIFY(_node)
 

Typedefs

typedef void(* fr_unlang_xlat_fd_event_t) (xlat_ctx_t const *xctx, request_t *request, int fd)
 A callback when the FD is ready for reading. More...
 
typedef void(* fr_unlang_xlat_timeout_t) (xlat_ctx_t const *xctx, request_t *request, fr_time_t fired)
 A callback when the the timeout occurs. More...
 
typedef struct unlang_interpret_s unlang_interpret_t
 
typedef int(* xlat_detach_t) (xlat_inst_ctx_t const *xctx)
 xlat detach callback More...
 
typedef int(* xlat_escape_func_t) (request_t *request, fr_value_box_t *vb, void *uctx)
 A function used to escape an argument passed to an xlat. More...
 
typedef size_t(* xlat_escape_legacy_t) (request_t *request, char *out, size_t outlen, char const *in, void *arg)
 
typedef void(* xlat_func_signal_t) (xlat_ctx_t const *xctx, request_t *request, fr_signal_t action)
 A callback when the request gets a fr_signal_t. More...
 
typedef xlat_action_t(* xlat_func_t) (TALLOC_CTX *ctx, fr_dcursor_t *out, xlat_ctx_t const *xctx, request_t *request, fr_value_box_list_t *in)
 xlat callback function More...
 
typedef struct xlat_inst_s xlat_inst_t
 
typedef int(* xlat_instantiate_t) (xlat_inst_ctx_t const *xctx)
 Allocate new instance data for an xlat instance. More...
 
typedef struct xlat_s xlat_t
 
typedef int(* xlat_thread_detach_t) (xlat_thread_inst_ctx_t const *xctx)
 xlat thread detach callback More...
 
typedef struct xlat_thread_inst_s xlat_thread_inst_t
 
typedef int(* xlat_thread_instantiate_t) (xlat_thread_inst_ctx_t const *xctx)
 Allocate new thread instance data for an xlat instance. More...
 

Enumerations

enum  xlat_action_t {
  XLAT_ACTION_PUSH_CHILD = 1 ,
  XLAT_ACTION_PUSH_UNLANG ,
  XLAT_ACTION_YIELD ,
  XLAT_ACTION_DONE ,
  XLAT_ACTION_FAIL
}
 
enum  xlat_arg_parser_variadic_t {
  XLAT_ARG_VARIADIC_DISABLED = 0 ,
  XLAT_ARG_VARIADIC_EMPTY_SQUASH = 1 ,
  XLAT_ARG_VARIADIC_EMPTY_KEEP = 2
}
 
enum  xlat_input_type_t {
  XLAT_INPUT_UNPROCESSED ,
  XLAT_INPUT_MONO ,
  XLAT_INPUT_ARGS
}
 

Functions

int _xlat_copy (NDEBUG_LOCATION_ARGS TALLOC_CTX *ctx, xlat_exp_head_t *out, xlat_exp_head_t const *in)
 
int unlang_xlat_push (TALLOC_CTX *ctx, bool *p_success, fr_value_box_list_t *out, request_t *request, xlat_exp_head_t const *head, bool top_frame)
 Push a pre-compiled xlat onto the stack for evaluation. More...
 
int unlang_xlat_timeout_add (request_t *request, fr_unlang_xlat_timeout_t callback, void const *rctx, fr_time_t when)
 Add a timeout for an xlat handler. More...
 
xlat_action_t unlang_xlat_yield (request_t *request, xlat_func_t callback, xlat_func_signal_t signal, fr_signal_t sigmask, void *rctx)
 Yield a request back to the interpreter from within a module. More...
 
ssize_t xlat_aeval (TALLOC_CTX *ctx, char **out, request_t *request, char const *fmt, xlat_escape_legacy_t escape, void const *escape_ctx))
 
ssize_t xlat_aeval_compiled (TALLOC_CTX *ctx, char **out, request_t *request, xlat_exp_head_t const *head, xlat_escape_legacy_t escape, void const *escape_ctx))
 
int xlat_aeval_compiled_argv (TALLOC_CTX *ctx, char ***argv, request_t *request, xlat_exp_head_t const *head, xlat_escape_legacy_t escape, void const *escape_ctx)
 Synchronous compile xlat_tokenize_argv() into argv[] array. More...
 
static fr_slen_t xlat_aprint (TALLOC_CTX *ctx, char **out, xlat_exp_head_t const *head, fr_sbuff_escape_rules_t const *e_rules) 1(xlat_print
 
void xlat_debug (xlat_exp_t const *node)
 
void xlat_debug_attr_list (request_t *request, fr_pair_list_t const *list)
 
void xlat_debug_attr_vp (request_t *request, fr_pair_t *vp, tmpl_t const *vpt)
 
void xlat_debug_head (xlat_exp_head_t const *head)
 
ssize_t xlat_eval (char *out, size_t outlen, request_t *request, char const *fmt, xlat_escape_legacy_t escape, void const *escape_ctx))
 
ssize_t xlat_eval_compiled (char *out, size_t outlen, request_t *request, xlat_exp_head_t const *head, xlat_escape_legacy_t escape, void const *escape_ctx))
 
int xlat_finalize (xlat_exp_head_t *head, fr_event_list_t *runtime_el)
 Bootstrap static xlats, or instantiate ephemeral ones. More...
 
int xlat_flatten_compiled_argv (TALLOC_CTX *ctx, xlat_exp_head_t ***argv, xlat_exp_head_t *head)
 Turn xlat_tokenize_argv() into an argv[] array, and nuke the input list. More...
 
int xlat_fmt_get_vp (fr_pair_t **out, request_t *request, char const *name)
 Return a VP from the specified request. More...
 
int xlat_from_tmpl_attr (TALLOC_CTX *ctx, xlat_exp_head_t **head, tmpl_t **vpt_p)
 Convert attr tmpl to an xlat for &attr[*]. More...
 
void xlat_global_free (void)
 De-register all xlat functions we created. More...
 
int xlat_global_init (TALLOC_CTX *ctx)
 Global initialisation for xlat. More...
 
int xlat_instance_register_func (xlat_exp_t *node)
 Callback for creating "permanent" instance data for a xlat_exp_t. More...
 
int xlat_instance_unregister_func (xlat_exp_t *node)
 Remove a node from the list of xlat instance data. More...
 
void xlat_instances_free (void)
 Walk over all registered instance data and free them explicitly. More...
 
int xlat_instantiate (void)
 Call instantiation functions for all registered, "permanent" xlats. More...
 
bool xlat_is_literal (xlat_exp_head_t const *head)
 Check to see if the expansion consists entirely of value-box elements. More...
 
static fr_slen_t e_rules bool xlat_is_truthy (xlat_exp_head_t const *head, bool *out)
 Allow callers to see if an xlat is truthy. More...
 
bool xlat_needs_resolving (xlat_exp_head_t const *head)
 Check to see if the expansion needs resolving. More...
 
fr_slen_t xlat_print (fr_sbuff_t *in, xlat_exp_head_t const *node, fr_sbuff_escape_rules_t const *e_rules)
 Reconstitute an xlat expression from its constituent nodes. More...
 
int xlat_protocols_register (void)
 Register xlats for any loaded dictionaries. More...
 
int xlat_purify (xlat_exp_head_t *head, unlang_interpret_t *intp)
 Purify an xlat. More...
 
int xlat_purify_op (TALLOC_CTX *ctx, xlat_exp_t **out, xlat_exp_t *lhs, fr_token_t op, xlat_exp_t *rhs)
 
int xlat_resolve (xlat_exp_head_t *head, xlat_res_rules_t const *xr_rules)
 Walk over an xlat tree recursively, resolving any unresolved functions or references. More...
 
void xlat_thread_detach (void)
 Destroy any thread specific xlat instances. More...
 
xlat_thread_inst_txlat_thread_instance_find (xlat_exp_t const *node)
 Retrieve xlat/thread specific instance data. More...
 
int xlat_thread_instantiate (TALLOC_CTX *ctx, fr_event_list_t *el)
 Create thread specific instance tree and create thread instances. More...
 
bool xlat_to_string (TALLOC_CTX *ctx, char **str, xlat_exp_head_t **head)
 Convert an xlat node to an unescaped literal string and free the original node. More...
 
tmpl_txlat_to_tmpl_attr (TALLOC_CTX *ctx, xlat_exp_head_t *xlat)
 Try to convert an xlat to a tmpl for efficiency. More...
 
fr_slen_t xlat_tokenize (TALLOC_CTX *ctx, xlat_exp_head_t **head, fr_sbuff_t *in, fr_sbuff_parse_rules_t const *p_rules, tmpl_rules_t const *t_rules, fr_value_box_safe_for_t literals_safe_for)
 Tokenize an xlat expansion. More...
 
fr_slen_t xlat_tokenize_argv (TALLOC_CTX *ctx, xlat_exp_head_t **head, fr_sbuff_t *in, xlat_t const *xlat, fr_sbuff_parse_rules_t const *p_rules, tmpl_rules_t const *t_rules, bool comma, bool allow_attr)
 Tokenize an xlat expansion into a series of XLAT_TYPE_CHILD arguments. More...
 
fr_slen_t xlat_tokenize_condition (TALLOC_CTX *ctx, xlat_exp_head_t **head, fr_sbuff_t *in, fr_sbuff_parse_rules_t const *p_rules, tmpl_rules_t const *t_rules)
 
fr_slen_t xlat_tokenize_expression (TALLOC_CTX *ctx, xlat_exp_head_t **head, fr_sbuff_t *in, fr_sbuff_parse_rules_t const *p_rules, tmpl_rules_t const *t_rules)
 
xlat_action_t xlat_transparent (UNUSED TALLOC_CTX *ctx, fr_dcursor_t *out, UNUSED xlat_ctx_t const *xctx, request_t *request, fr_value_box_list_t *args)
 
int xlat_validate_function_args (xlat_exp_t *node)
 
int xlat_validate_function_mono (xlat_exp_t *node)
 

Variables

static fr_slen_t head
 
fr_table_num_sorted_t const xlat_action_table []
 
size_t xlat_action_table_len
 

Detailed Description

xlat expansion parsing and evaluation API.

Id
729592a2773f02d8ea8291e2db9f43968eb4c195

Definition in file xlat.h.


Data Structure Documentation

◆ xlat_arg_parser_t

struct xlat_arg_parser_t

Definition for a single argument consumend by an xlat function.

Definition at line 145 of file xlat.h.

+ Collaboration diagram for xlat_arg_parser_t:
Data Fields
bool always_escape Pass all arguments to escape function not just tainted ones.
bool concat Concat boxes together.
xlat_escape_func_t func Function to handle tainted values.
bool required Argument must be present, and non-empty.
fr_value_box_safe_for_t safe_for Escaped value to set for boxes processed by this escape function.
bool single Argument must only contain a single box.
fr_type_t type Type to cast argument to.
void * uctx Argument to pass to escape callback.
xlat_arg_parser_variadic_t variadic All additional boxes should be processed using this definition.

◆ xlat_flags_t

struct xlat_flags_t

Flags that control resolution and evaluation.

Definition at line 111 of file xlat.h.

Data Fields
bool can_purify if the xlat has a pure function with pure arguments.
bool constant xlat is just tmpl_attr_tail_data, or XLAT_BOX
bool needs_resolving Needs pass2 resolution.
bool pure has no external side effects, true for BOX, LITERAL, and some functions
bool xlat it's an xlat wrapper

◆ xlat_inst_s

struct xlat_inst_s

Instance data for an xlat expansion node.

Definition at line 74 of file xlat.h.

+ Collaboration diagram for xlat_inst_s:
Data Fields
call_env_t const * call_env Per call environment.
void * data xlat node specific instance data.
fr_heap_index_t idx Entry in heap of xlat instances.

Identical instances are used for global instance data and thread-specific instance data.

xlat_exp_t * node Node this data relates to.

◆ xlat_res_rules_t

struct xlat_res_rules_t

Definition at line 160 of file xlat.h.

+ Collaboration diagram for xlat_res_rules_t:
Data Fields
bool allow_unresolved If false, all resolution steps must be completed.

this round, otherwise an error will be produced.

tmpl_res_rules_t const * tr_rules tmpl resolution rules.

◆ xlat_thread_inst_s

struct xlat_thread_inst_s

Thread specific instance data for xlat expansion node.

Definition at line 88 of file xlat.h.

+ Collaboration diagram for xlat_thread_inst_s:
Data Fields
uint64_t active_callers total number of times we've been called
void * data Thread specific instance data.
fr_event_list_t * el Event list associated with this thread.
fr_heap_index_t idx Entry in heap of xlat thread instances.

Identical instances are used for global instance data and thread-specific instance data.

module_ctx_t const * mctx A synthesised module calling ctx containing module global and thread instance data.
xlat_exp_t const * node Node this data relates to.
uint64_t total_calls

Macro Definition Documentation

◆ _XLAT_ARGS_X

#define _XLAT_ARGS_X (   XLAT_ARGS_N,
  _list,
  ... 
)    XLAT_ARGS_N(_list, __VA_ARGS__)

Trampoline macro for selecting which XLAT_ARGS_<num> macro to expand.

Parameters
[in]XLAT_ARGS_Nthe name of the macro to expand. Created by concatenating XLAT_ARGS_ + <number of variadic arguments>.
[in]_listThe input list of value boxes.
[in]...The variadic arguments themselves.

Definition at line 357 of file xlat.h.

◆ XLAT_ARG_PARSER_TERMINATOR

#define XLAT_ARG_PARSER_TERMINATOR
Value:
{ .required = false, .concat = false, .single = false, .variadic = false, \
.type = FR_TYPE_NULL, .func = NULL, .uctx = NULL }
@ FR_TYPE_NULL
Invalid (uninitialised) attribute type.
Definition: merged_model.c:81

Definition at line 166 of file xlat.h.

◆ XLAT_ARGS

#define XLAT_ARGS (   _list,
  ... 
)    _XLAT_ARGS_X(JOIN(XLAT_ARGS_, VA_NARG(__VA_ARGS__)), _list, __VA_ARGS__)

Populate local variables with value boxes from the input list.

Parameters
[in]_listinput list to pull arguments from.
[in]...1-8 output boxes pointers fr_value_box_t ** e.g. XLAT_ARGS(in, &arg0, &arg1, &argN)`.

Definition at line 365 of file xlat.h.

◆ XLAT_ARGS_1

#define XLAT_ARGS_1 (   _list,
  _a 
)     *(_a) = fr_value_box_list_head(_list)

Definition at line 283 of file xlat.h.

◆ XLAT_ARGS_2

#define XLAT_ARGS_2 (   _list,
  _a,
  _b 
)
Value:
do { \
*(_a) = fr_value_box_list_head(_list); \
XLAT_ARGS_NEXT(_list, _a, _b); \
} while (0)

Definition at line 286 of file xlat.h.

◆ XLAT_ARGS_3

#define XLAT_ARGS_3 (   _list,
  _a,
  _b,
  _c 
)
Value:
do { \
*(_a) = fr_value_box_list_head(_list); \
XLAT_ARGS_NEXT(_list, _a, _b); \
XLAT_ARGS_NEXT(_list, _b, _c); \
} while (0)

Definition at line 292 of file xlat.h.

◆ XLAT_ARGS_4

#define XLAT_ARGS_4 (   _list,
  _a,
  _b,
  _c,
  _d 
)
Value:
do { \
*(_a) = fr_value_box_list_head(_list); \
XLAT_ARGS_NEXT(_list, _a, _b); \
XLAT_ARGS_NEXT(_list, _b, _c); \
XLAT_ARGS_NEXT(_list, _c, _d); \
} while (0)

Definition at line 299 of file xlat.h.

◆ XLAT_ARGS_5

#define XLAT_ARGS_5 (   _list,
  _a,
  _b,
  _c,
  _d,
  _e 
)
Value:
do { \
*(_a) = fr_value_box_list_head(_list); \
XLAT_ARGS_NEXT(_list, _a, _b); \
XLAT_ARGS_NEXT(_list, _b, _c); \
XLAT_ARGS_NEXT(_list, _c, _d); \
XLAT_ARGS_NEXT(_list, _d, _e); \
} while (0)

Definition at line 307 of file xlat.h.

◆ XLAT_ARGS_6

#define XLAT_ARGS_6 (   _list,
  _a,
  _b,
  _c,
  _d,
  _e,
  _f 
)
Value:
do { \
*(_a) = fr_value_box_list_head(_list); \
XLAT_ARGS_NEXT(_list, _a, _b); \
XLAT_ARGS_NEXT(_list, _b, _c); \
XLAT_ARGS_NEXT(_list, _c, _d); \
XLAT_ARGS_NEXT(_list, _d, _e); \
XLAT_ARGS_NEXT(_list, _e, _f); \
} while (0)

Definition at line 316 of file xlat.h.

◆ XLAT_ARGS_7

#define XLAT_ARGS_7 (   _list,
  _a,
  _b,
  _c,
  _d,
  _e,
  _f,
  _g 
)
Value:
do { \
*(_a) = fr_value_box_list_head(_list); \
XLAT_ARGS_NEXT(_list, _a, _b); \
XLAT_ARGS_NEXT(_list, _b, _c); \
XLAT_ARGS_NEXT(_list, _c, _d); \
XLAT_ARGS_NEXT(_list, _d, _e); \
XLAT_ARGS_NEXT(_list, _e, _f); \
XLAT_ARGS_NEXT(_list, _f, _g); \
} while (0)

Definition at line 326 of file xlat.h.

◆ XLAT_ARGS_8

#define XLAT_ARGS_8 (   _list,
  _a,
  _b,
  _c,
  _d,
  _e,
  _f,
  _g,
  _h 
)
Value:
do { \
*(_a) = fr_value_box_list_head(_list); \
XLAT_ARGS_NEXT(_list, _a, _b); \
XLAT_ARGS_NEXT(_list, _b, _c); \
XLAT_ARGS_NEXT(_list, _c, _d); \
XLAT_ARGS_NEXT(_list, _d, _e); \
XLAT_ARGS_NEXT(_list, _e, _f); \
XLAT_ARGS_NEXT(_list, _f, _g); \
XLAT_ARGS_NEXT(_list, _g, _h); \
} while (0)

Definition at line 337 of file xlat.h.

◆ XLAT_ARGS_NEXT

#define XLAT_ARGS_NEXT (   _list,
  _prev,
  _curr 
)    *(_curr) = likely(*(_prev) != NULL) ? fr_value_box_list_next(_list, *(_prev)) : NULL

Set the next argument to the next item in the input list or NULL.

Parameters
[in]_listwe're extracting arguments from.
[in]_prevargument.
[in]_currargument we're populating.

Definition at line 281 of file xlat.h.

◆ xlat_copy

#define xlat_copy (   _ctx,
  _out,
  _in 
)    _xlat_copy(NDEBUG_LOCATION_EXP _ctx, _out, _in)

Definition at line 445 of file xlat.h.

◆ XLAT_HEAD_VERIFY

#define XLAT_HEAD_VERIFY (   _head)

Definition at line 454 of file xlat.h.

◆ XLAT_VERIFY

#define XLAT_VERIFY (   _node)

Definition at line 453 of file xlat.h.

Typedef Documentation

◆ fr_unlang_xlat_fd_event_t

typedef void(* fr_unlang_xlat_fd_event_t) (xlat_ctx_t const *xctx, request_t *request, int fd)

A callback when the FD is ready for reading.

Used when a xlat needs to read from an FD. Typically the callback is set, and then the xlat returns unlang_xlat_yield().

Note
The callback is automatically removed on unlang_interpret_mark_runnable(), so
Parameters
[in]xctxxlat calling ctx. Contains all instance data.
[in]requestthe current request.
[in]fdthe file descriptor.

Definition at line 194 of file xlat.h.

◆ fr_unlang_xlat_timeout_t

typedef void(* fr_unlang_xlat_timeout_t) (xlat_ctx_t const *xctx, request_t *request, fr_time_t fired)

A callback when the the timeout occurs.

Used when a xlat needs wait for an event. Typically the callback is set, and then the xlat returns unlang_xlat_yield().

Note
The callback is automatically removed on unlang_interpret_mark_runnable(), i.e. if an event on a registered FD occurs before the timeout event fires.
Parameters
[in]xctxxlat calling ctx. Contains all instance data.
[in]requestthe request.
[in]firedthe time the timeout event actually fired.

Definition at line 181 of file xlat.h.

◆ unlang_interpret_t

Definition at line 474 of file xlat.h.

◆ xlat_detach_t

typedef int(* xlat_detach_t) (xlat_inst_ctx_t const *xctx)

xlat detach callback

Is called whenever an xlat_node_t is freed.

Detach should close all handles associated with the xlat instance, and free any memory allocated during instantiate.

Parameters
[in]xctxinstantiate/detach calling ctx.
Returns
  • 0 on success.
  • -1 if detach failed.

Definition at line 258 of file xlat.h.

◆ xlat_escape_func_t

typedef int(* xlat_escape_func_t) (request_t *request, fr_value_box_t *vb, void *uctx)

A function used to escape an argument passed to an xlat.

Parameters
[in]requestbeing processed. Used mostly for debugging.
[in,out]vbto escape
[in]uctxa "context" for the escaping
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 132 of file xlat.h.

◆ xlat_escape_legacy_t

typedef size_t(* xlat_escape_legacy_t) (request_t *request, char *out, size_t outlen, char const *in, void *arg)

Definition at line 56 of file xlat.h.

◆ xlat_func_signal_t

typedef void(* xlat_func_signal_t) (xlat_ctx_t const *xctx, request_t *request, fr_signal_t action)

A callback when the request gets a fr_signal_t.

Note
The callback is automatically removed on unlang_interpret_mark_runnable().
Parameters
[in]requestThe current request.
[in]xctxxlat calling ctx. Contains all instance data.
[in]actionwhich is signalling the request.

Definition at line 225 of file xlat.h.

◆ xlat_func_t

typedef xlat_action_t(* xlat_func_t) (TALLOC_CTX *ctx, fr_dcursor_t *out, xlat_ctx_t const *xctx, request_t *request, fr_value_box_list_t *in)

xlat callback function

Ingests a list of value boxes as arguments.

Parameters
[in]ctxto allocate any fr_value_box_t in.
[out]outWhere to append fr_value_box_t containing the output of this function.
[in]xctxxlat calling ctx. Contains all instance data and the resume ctx if this function is being resumed.
[in]requestThe current request.
[in]inInput arguments.
Returns
  • XLAT_ACTION_YIELD xlat function is waiting on an I/O event and has pushed a resumption function onto the stack.
  • XLAT_ACTION_DONE xlat function completed. This does not necessarily mean it turned a result.
  • XLAT_ACTION_FAIL the xlat function failed.

Definition at line 214 of file xlat.h.

◆ xlat_inst_t

typedef struct xlat_inst_s xlat_inst_t

Definition at line 1 of file xlat.h.

◆ xlat_instantiate_t

typedef int(* xlat_instantiate_t) (xlat_inst_ctx_t const *xctx)

Allocate new instance data for an xlat instance.

Parameters
[in]xctxinstantiate/detach calling ctx.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 235 of file xlat.h.

◆ xlat_t

typedef struct xlat_s xlat_t

Definition at line 56 of file xlat.h.

◆ xlat_thread_detach_t

typedef int(* xlat_thread_detach_t) (xlat_thread_inst_ctx_t const *xctx)

xlat thread detach callback

Is called whenever an xlat_node_t is freed (if ephemeral), or when a thread exits.

Detach should close all handles associated with the xlat instance, and free any memory allocated during instantiate.

Parameters
[in]xctxthread instantiate/detach calling ctx.
Returns
  • 0 on success.
  • -1 if detach failed.

Definition at line 273 of file xlat.h.

◆ xlat_thread_inst_t

Definition at line 1 of file xlat.h.

◆ xlat_thread_instantiate_t

typedef int(* xlat_thread_instantiate_t) (xlat_thread_inst_ctx_t const *xctx)

Allocate new thread instance data for an xlat instance.

Parameters
[in]xctxthread instantiate/detach ctx.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 244 of file xlat.h.

Enumeration Type Documentation

◆ xlat_action_t

Enumerator
XLAT_ACTION_PUSH_CHILD 

A deeper level of nesting needs to be evaluated.

XLAT_ACTION_PUSH_UNLANG 

An xlat function pushed an unlang frame onto the unlang stack.

This frame needs to be evaluated, and then we need to call the xlat's resume function.

XLAT_ACTION_YIELD 

An xlat function pushed a resume frame onto the stack.

XLAT_ACTION_DONE 

We're done evaluating this level of nesting.

XLAT_ACTION_FAIL 

An xlat function failed.

Definition at line 35 of file xlat.h.

◆ xlat_arg_parser_variadic_t

Enumerator
XLAT_ARG_VARIADIC_DISABLED 
XLAT_ARG_VARIADIC_EMPTY_SQUASH 

Empty argument groups are removed.

XLAT_ARG_VARIADIC_EMPTY_KEEP 

Empty argument groups are left alone, and either passed through as empty groups or null boxes.

Definition at line 134 of file xlat.h.

◆ xlat_input_type_t

Enumerator
XLAT_INPUT_UNPROCESSED 

No input argument processing.

XLAT_INPUT_MONO 

Ingests a single argument.

XLAT_INPUT_ARGS 

Ingests a number of arguments.

Definition at line 45 of file xlat.h.

Function Documentation

◆ _xlat_copy()

int _xlat_copy ( NDEBUG_LOCATION_ARGS TALLOC_CTX *  ctx,
xlat_exp_head_t out,
xlat_exp_head_t const *  in 
)

Definition at line 314 of file xlat_alloc.c.

+ Here is the call graph for this function:

◆ unlang_xlat_push()

int unlang_xlat_push ( TALLOC_CTX *  ctx,
bool p_success,
fr_value_box_list_t *  out,
request_t request,
xlat_exp_head_t const *  xlat,
bool  top_frame 
)

Push a pre-compiled xlat onto the stack for evaluation.

Parameters
[in]ctxTo allocate value boxes and values in.
[out]p_successIf set, and execution succeeds, true will be written here. If execution fails, false will be written.
[out]outWhere to write the result of the expansion.
[in]requestto push xlat onto.
[in]xlatto evaluate.
[in]top_frameSet to UNLANG_TOP_FRAME if the interpreter should return. Set to UNLANG_SUB_FRAME if the interprer should continue.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 274 of file xlat.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ unlang_xlat_timeout_add()

int unlang_xlat_timeout_add ( request_t request,
fr_unlang_xlat_timeout_t  callback,
void const *  rctx,
fr_time_t  when 
)

Add a timeout for an xlat handler.

Note
The timeout is automatically removed when the xlat is cancelled or resumed.
Parameters
[in]requestthe request
[in]callbackto run when the timeout hits
[in]rctxpassed to the callback
[in]whenwhen the timeout fires
Returns
  • <0 on error
  • 0 on success

Definition at line 140 of file xlat.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ unlang_xlat_yield()

xlat_action_t unlang_xlat_yield ( request_t request,
xlat_func_t  resume,
xlat_func_signal_t  signal,
fr_signal_t  sigmask,
void *  rctx 
)

Yield a request back to the interpreter from within a module.

This passes control of the request back to the unlang interpreter, setting callbacks to execute when the request is 'signalled' asynchronously, or whatever timer or I/O event the module was waiting for occurs.

Note
The module function which calls unlang_module_yield should return control of the C stack to the unlang interpreter immediately after calling unlang_xlat_yield. A common pattern is to use return unlang_xlat_yield(...).
Parameters
[in]requestThe current request.
[in]resumeCalled on unlang_interpret_mark_runnable().
[in]signalCalled on unlang_action().
[in]sigmaskSignals to block.
[in]rctxto pass to the callbacks.
Returns
always returns XLAT_ACTION_YIELD

Definition at line 561 of file xlat.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_aeval()

ssize_t xlat_aeval ( TALLOC_CTX *  ctx,
char **  out,
request_t request,
char const *  fmt,
xlat_escape_legacy_t  escape,
void const *  escape_ctx 
)

Definition at line 1470 of file xlat_eval.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_aeval_compiled()

ssize_t xlat_aeval_compiled ( TALLOC_CTX *  ctx,
char **  out,
request_t request,
xlat_exp_head_t const *  head,
xlat_escape_legacy_t  escape,
void const *  escape_ctx 
)

Definition at line 1479 of file xlat_eval.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_aeval_compiled_argv()

int xlat_aeval_compiled_argv ( TALLOC_CTX *  ctx,
char ***  argv,
request_t request,
xlat_exp_head_t const *  head,
xlat_escape_legacy_t  escape,
void const *  escape_ctx 
)

Synchronous compile xlat_tokenize_argv() into argv[] array.

This is mostly for synchronous evaluation.

Parameters
ctxThe talloc_ctx
[out]argvthe argv array of resulting strings, size is argc + 1
requestthe request
headfrom xlat_tokenize_argv()
escapeescape function
escape_ctxcontext for escape function
Returns
  • <=0 on error number indicates which argument caused the problem
  • >0 on success which is argc to the corresponding argv

Definition at line 1503 of file xlat_eval.c.

+ Here is the call graph for this function:

◆ xlat_aprint()

static fr_slen_t xlat_aprint ( TALLOC_CTX *  ctx,
char **  out,
xlat_exp_head_t const *  head,
fr_sbuff_escape_rules_t const *  e_rules 
)
inlinestatic
+ Here is the caller graph for this function:

◆ xlat_debug()

void xlat_debug ( xlat_exp_t const *  node)

Definition at line 1020 of file xlat_tokenize.c.

+ Here is the call graph for this function:

◆ xlat_debug_attr_list()

void xlat_debug_attr_list ( request_t request,
fr_pair_list_t const *  list 
)

Definition at line 252 of file xlat_builtin.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_debug_attr_vp()

void xlat_debug_attr_vp ( request_t request,
fr_pair_t vp,
tmpl_t const *  vpt 
)

Definition at line 154 of file xlat_builtin.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_debug_head()

void xlat_debug_head ( xlat_exp_head_t const *  head)

Definition at line 1048 of file xlat_tokenize.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_eval()

ssize_t xlat_eval ( char *  out,
size_t  outlen,
request_t request,
char const *  fmt,
xlat_escape_legacy_t  escape,
void const *  escape_ctx 
)

Definition at line 215 of file merged_model.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_eval_compiled()

ssize_t xlat_eval_compiled ( char *  out,
size_t  outlen,
request_t request,
xlat_exp_head_t const *  head,
xlat_escape_legacy_t  escape,
void const *  escape_ctx 
)

Definition at line 1462 of file xlat_eval.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_finalize()

int xlat_finalize ( xlat_exp_head_t head,
fr_event_list_t runtime_el 
)

Bootstrap static xlats, or instantiate ephemeral ones.

Parameters
[in]headof xlat tree to create instance data for.
[in]runtime_eldetermines whether we do ephemeral or static instantiation. If NULL, we perform static instantiation, otherwise will perform ephemeral instantiation passing the el to the instantiation functions.

Definition at line 690 of file xlat_inst.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_flatten_compiled_argv()

int xlat_flatten_compiled_argv ( TALLOC_CTX *  ctx,
xlat_exp_head_t ***  argv,
xlat_exp_head_t head 
)

Turn xlat_tokenize_argv() into an argv[] array, and nuke the input list.

This is mostly for async use.

Definition at line 1538 of file xlat_eval.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_fmt_get_vp()

int xlat_fmt_get_vp ( fr_pair_t **  out,
request_t request,
char const *  name 
)

Return a VP from the specified request.

Note
DEPRECATED, TO NOT USE.
Parameters
outwhere to write the pointer to the resolved VP. Will be NULL if the attribute couldn't be resolved.
requestcurrent request.
nameattribute name including qualifiers.
Returns
  • -4 if either the attribute or qualifier were invalid.
  • The same error codes as tmpl_find_vp for other error conditions.

Definition at line 76 of file xlat_builtin.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_from_tmpl_attr()

int xlat_from_tmpl_attr ( TALLOC_CTX *  ctx,
xlat_exp_head_t **  out,
tmpl_t **  vpt_p 
)

Convert attr tmpl to an xlat for &attr[*].

Parameters
[in]ctxto allocate new expansion in.
[out]outWhere to write new xlat node.
[in,out]vpt_pto convert to xlat expansion. Will be set to NULL on completion
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 1826 of file xlat_tokenize.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_global_free()

void xlat_global_free ( void  )

De-register all xlat functions we created.

Definition at line 4065 of file xlat_builtin.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_global_init()

int xlat_global_init ( TALLOC_CTX *  ctx)

Global initialisation for xlat.

Note
Free memory with #xlat_free
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 3919 of file xlat_builtin.c.

+ Here is the caller graph for this function:

◆ xlat_instance_register_func()

int xlat_instance_register_func ( xlat_exp_t node)

Callback for creating "permanent" instance data for a xlat_exp_t.

This function records the xlat_exp_t requiring instantiation but does not call the instantiation function. This is to allow for a clear separation between the module instantiation phase and the xlat instantiation phase.

Note
This is very similar to xlat_instance_register but does not walk the children of the node. This is primarily used to register individual nodes for instantiation and when an xlat function is resolved in a subsequent resolution pass and needs to be registered for instantiation.
Parameters
[in]nodeto create "permanent" instance data for.
Returns
  • 0 if instantiation functions were successful.
  • -1 if either instantiation function failed.

Definition at line 590 of file xlat_inst.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_instance_unregister_func()

int xlat_instance_unregister_func ( xlat_exp_t node)

Remove a node from the list of xlat instance data.

Note
This is primarily used during "purification", to remove xlats which are no longer used.
Parameters
[in]nodeto remove instance data for.

Definition at line 545 of file xlat_inst.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_instances_free()

void xlat_instances_free ( void  )

Walk over all registered instance data and free them explicitly.

This must be called before any modules or xlats are deregistered/unloaded and before the mainconfig is freed, as the xlat_t need to still exist in order to call the detach functions within them.

Definition at line 704 of file xlat_inst.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_instantiate()

int xlat_instantiate ( void  )

Call instantiation functions for all registered, "permanent" xlats.

Should be called after all the permanent xlats have been tokenised/bootstrapped.

Definition at line 508 of file xlat_inst.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_is_literal()

bool xlat_is_literal ( xlat_exp_head_t const *  head)

Check to see if the expansion consists entirely of value-box elements.

Parameters
[in]headto check.
Returns
  • true if expansion contains only literal elements.
  • false if expansion contains expandable elements.

Definition at line 1536 of file xlat_tokenize.c.

+ Here is the caller graph for this function:

◆ xlat_is_truthy()

static fr_slen_t e_rules bool xlat_is_truthy ( xlat_exp_head_t const *  head,
bool out 
)

Allow callers to see if an xlat is truthy.

So the caller can cache it, and needs to check fewer things at run time.

Parameters
[in]headof the xlat to check
[out]outtruthiness of the box
Returns

Definition at line 3040 of file xlat_expr.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_needs_resolving()

bool xlat_needs_resolving ( xlat_exp_head_t const *  head)

Check to see if the expansion needs resolving.

Parameters
[in]headto check.
Returns
  • true if expansion needs resolving
  • false otherwise

Definition at line 1552 of file xlat_tokenize.c.

+ Here is the caller graph for this function:

◆ xlat_print()

fr_slen_t xlat_print ( fr_sbuff_t out,
xlat_exp_head_t const *  head,
fr_sbuff_escape_rules_t const *  e_rules 
)

Reconstitute an xlat expression from its constituent nodes.

Parameters
[in]outWhere to write the output string.
[in]headFirst node to print.
[in]e_rulesSpecifying how to escape literal values.

Definition at line 1231 of file xlat_tokenize.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_protocols_register()

int xlat_protocols_register ( void  )

Register xlats for any loaded dictionaries.

Definition at line 3889 of file xlat_builtin.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_purify()

int xlat_purify ( xlat_exp_head_t head,
unlang_interpret_t intp 
)

Purify an xlat.

Parameters
headthe xlat to be purified
intpthe interpreter to use.

Definition at line 194 of file xlat_purify.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_purify_op()

int xlat_purify_op ( TALLOC_CTX *  ctx,
xlat_exp_t **  out,
xlat_exp_t lhs,
fr_token_t  op,
xlat_exp_t rhs 
)

Definition at line 425 of file xlat_purify.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_resolve()

int xlat_resolve ( xlat_exp_head_t head,
xlat_res_rules_t const *  xr_rules 
)

Walk over an xlat tree recursively, resolving any unresolved functions or references.

Parameters
[in,out]headof xlat tree to resolve.
[in]xr_rulesSpecifies rules to use for resolution passes after initial tokenization.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 1607 of file xlat_tokenize.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_thread_detach()

void xlat_thread_detach ( void  )

Destroy any thread specific xlat instances.

Definition at line 484 of file xlat_inst.c.

+ Here is the caller graph for this function:

◆ xlat_thread_instance_find()

xlat_thread_inst_t* xlat_thread_instance_find ( xlat_exp_t const *  node)

Retrieve xlat/thread specific instance data.

Parameters
[in]nodeto find thread specific data for.
Returns
  • Thread specific data on success.
  • NULL if the xlat has no thread instance data.

Definition at line 402 of file xlat_inst.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_thread_instantiate()

int xlat_thread_instantiate ( TALLOC_CTX *  ctx,
fr_event_list_t el 
)

Create thread specific instance tree and create thread instances.

This should be called directly after the modules_thread_instantiate() function.

Memory will be freed automatically when the thread exits.

Parameters
[in]ctxto bind instance tree lifetime to. Must not be shared between multiple threads.
[in]elEvent list to pass to all thread instantiation functions.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 439 of file xlat_inst.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_to_string()

bool xlat_to_string ( TALLOC_CTX *  ctx,
char **  str,
xlat_exp_head_t **  head 
)

Convert an xlat node to an unescaped literal string and free the original node.

This is really "unparse the xlat nodes, and convert back to their original string".

Parameters
[in]ctxto allocate the new string in.
[out]stra duplicate of the node's fmt string.
[in,out]headto convert.
Returns
  • true the tree consists of a single value node which was converted.
  • false the tree was more complex than a single literal, op was a noop.

Definition at line 1568 of file xlat_tokenize.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_to_tmpl_attr()

tmpl_t* xlat_to_tmpl_attr ( TALLOC_CTX *  ctx,
xlat_exp_head_t head 
)

Try to convert an xlat to a tmpl for efficiency.

Parameters
ctxto allocate new tmpl_t in.
headto convert.
Returns
  • NULL if unable to convert (not necessarily error).
  • A new tmpl_t.

Definition at line 1793 of file xlat_tokenize.c.

+ Here is the call graph for this function:

◆ xlat_tokenize()

fr_slen_t xlat_tokenize ( TALLOC_CTX *  ctx,
xlat_exp_head_t **  out,
fr_sbuff_t in,
fr_sbuff_parse_rules_t const *  p_rules,
tmpl_rules_t const *  t_rules,
fr_value_box_safe_for_t  literals_safe_for 
)

Tokenize an xlat expansion.

Parameters
[in]ctxto allocate dynamic buffers in.
[out]outthe head of the xlat list / tree structure.
[in]inthe format string to expand.
[in]p_rulescontrolling how the string containing the xlat expansions should be parsed.
[in]t_rulescontrolling how attribute references are parsed. Do NOT alter this function to take tmpl_rules_t as this provides another value for literals_safe_for and this gets very confusing.
[in]literals_safe_forthe safe_for value to assign to any literals occurring at the top level of the expansion.
Returns
  • >0 on success.
  • 0 and *head == NULL - Parse failure on first char.
  • 0 and *head != NULL - Zero length expansion
  • < 0 the negative offset of the parse failure.

Definition at line 1498 of file xlat_tokenize.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_tokenize_argv()

fr_slen_t xlat_tokenize_argv ( TALLOC_CTX *  ctx,
xlat_exp_head_t **  out,
fr_sbuff_t in,
xlat_t const *  xlat,
fr_sbuff_parse_rules_t const *  p_rules,
tmpl_rules_t const *  t_rules,
bool  comma,
bool  allow_attr 
)

Tokenize an xlat expansion into a series of XLAT_TYPE_CHILD arguments.

Parameters
[in]ctxto allocate nodes in. Note: All nodes will be allocated in the same ctx. This is to allow manipulation by xlat instantiation functions later.
[out]outthe head of the xlat list / tree structure.
[in]inthe format string to expand.
[in]xlatwe're tokenizing arguments for.
[in]p_rulescontrolling how to parse the string outside of any expansions.
[in]t_rulescontrolling how attribute references are parsed.
[in]commawhether the arguments are delimited by commas
[in]allow_attrallow attribute references as arguments
Returns
  • < 0 on error.
  • >0 on success which is the number of characters parsed.

Definition at line 1263 of file xlat_tokenize.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_tokenize_condition()

fr_slen_t xlat_tokenize_condition ( TALLOC_CTX *  ctx,
xlat_exp_head_t **  head,
fr_sbuff_t in,
fr_sbuff_parse_rules_t const *  p_rules,
tmpl_rules_t const *  t_rules 
)

Definition at line 3023 of file xlat_expr.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_tokenize_expression()

fr_slen_t xlat_tokenize_expression ( TALLOC_CTX *  ctx,
xlat_exp_head_t **  head,
fr_sbuff_t in,
fr_sbuff_parse_rules_t const *  p_rules,
tmpl_rules_t const *  t_rules 
)

Definition at line 3017 of file xlat_expr.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_transparent()

xlat_action_t xlat_transparent ( UNUSED TALLOC_CTX *  ctx,
fr_dcursor_t out,
UNUSED xlat_ctx_t const *  xctx,
request_t request,
fr_value_box_list_t *  args 
)
+ Here is the caller graph for this function:

◆ xlat_validate_function_args()

int xlat_validate_function_args ( xlat_exp_t node)

Definition at line 241 of file xlat_tokenize.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ xlat_validate_function_mono()

int xlat_validate_function_mono ( xlat_exp_t node)

Definition at line 167 of file xlat_tokenize.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

Variable Documentation

◆ head

fr_slen_t head

Definition at line 408 of file xlat.h.

◆ xlat_action_table

fr_table_num_sorted_t const xlat_action_table[]
extern

Definition at line 60 of file xlat_eval.c.

◆ xlat_action_table_len

size_t xlat_action_table_len
extern

Definition at line 66 of file xlat_eval.c.