Integration between the unlang interpreter and xlats. More...

#include <freeradius-devel/server/base.h>
#include <freeradius-devel/util/debug.h>
#include <ctype.h>
#include <freeradius-devel/unlang/xlat_priv.h>
#include "unlang_priv.h"

Include dependency graph for xlat.c:

Go to the source code of this file.

Data Structures
struct	unlang_frame_state_xlat_t
	State of an xlat expansion. More...

struct	unlang_xlat_event_t
	Wrap an fr_event_timer_t providing data needed for unlang events. More...

struct	unlang_xlat_retry_t

Functions
static int	_unlang_xlat_event_free (unlang_xlat_event_t *ev)
	Frees an unlang event, removing it from the request's event loop.

static int	_unlang_xlat_retry_free (unlang_xlat_retry_t *ev)
	Frees an unlang event, removing it from the request's event loop.

static unlang_action_t	unlang_xlat (rlm_rcode_t p_result, request_t request, unlang_stack_frame_t *frame)
	Stub function for calling the xlat interpreter.

int	unlang_xlat_eval (TALLOC_CTX ctx, fr_value_box_list_t out, request_t request, xlat_exp_head_t const xlat)
	Evaluate a "pure" (or not impure) xlat.

int	unlang_xlat_eval_type (TALLOC_CTX ctx, fr_value_box_t vb, fr_type_t type, fr_dict_attr_t const enumv, request_t request, xlat_exp_head_t const *xlat)
	Evaluate a "pure" (or not impure) xlat.

static void	unlang_xlat_event_retry_handler (UNUSED fr_event_list_t el, fr_time_t now, void uctx)
	Call the callback registered for a timeout event.

static void	unlang_xlat_event_timeout_handler (UNUSED fr_event_list_t el, fr_time_t now, void uctx)
	Call the callback registered for a timeout event.

void	unlang_xlat_init (void)
	Register xlat operation with the interpreter.

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.

static int	unlang_xlat_push_internal (TALLOC_CTX ctx, bool p_success, fr_value_box_list_t out, request_t request, xlat_exp_head_t const xlat, xlat_exp_t node, bool top_frame)
	Push a pre-compiled xlat onto the stack for evaluation.

int	unlang_xlat_push_node (TALLOC_CTX ctx, bool p_success, fr_value_box_list_t out, request_t request, xlat_exp_t *node)
	Push a pre-compiled xlat onto the stack for evaluation.

static unlang_action_t	unlang_xlat_repeat (rlm_rcode_t p_result, request_t request, unlang_stack_frame_t *frame)

static unlang_action_t	unlang_xlat_resume (rlm_rcode_t p_result, request_t request, unlang_stack_frame_t *frame)
	Called when we're ready to resume processing the request.

static void	unlang_xlat_signal (request_t request, unlang_stack_frame_t frame, fr_signal_t action)
	Send a signal (usually stop) to a request that's running an xlat expansions.

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.

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.

xlat_action_t	unlang_xlat_yield_to_retry (request_t request, xlat_func_t resume, fr_unlang_xlat_retry_t retry, xlat_func_signal_t signal, fr_signal_t sigmask, void rctx, fr_retry_config_t const *retry_cfg)
	Yield a request back to the interpreter, with retries.

Detailed Description

Integration between the unlang interpreter and xlats.

Id: d03c559b1d0fa7fe927b272df935b5f5c20b3214

Copyright: 2018 The FreeRADIUS server project; 2018 Arran Cudbard-Bell (a.cud.nosp@m.bard.nosp@m.b@fre.nosp@m.erad.nosp@m.ius.o.nosp@m.rg)

Definition in file xlat.c.

Data Structure Documentation

◆ unlang_frame_state_xlat_t

struct unlang_frame_state_xlat_t

State of an xlat expansion.

State of one level of nesting within an xlat expansion.

Definition at line 39 of file xlat.c.

Collaboration diagram for unlang_frame_state_xlat_t:

Data Fields
TALLOC_CTX *	ctx	to allocate boxes and values in.
void *	env_data	Expanded per call environment tmpls.
TALLOC_CTX *	event_ctx	for temporary events
xlat_exp_t const *	exp	current one we're evaluating
xlat_exp_head_t const *	head	of the xlat list
rindent_t	indent	indentation
fr_value_box_list_t	out	Head of the result of a nested expansion.
void *	rctx	for resume / signal
xlat_func_t	resume	called on resume
fr_signal_t	sigmask	Signals to block.
xlat_func_signal_t	signal	called on signal
bool *	success	If set, where to record the result of the execution.
fr_dcursor_t	values	Values aggregated so far.

◆ unlang_xlat_event_t

struct unlang_xlat_event_t

Wrap an fr_event_timer_t providing data needed for unlang events.

Definition at line 66 of file xlat.c.

Collaboration diagram for unlang_xlat_event_t:

Data Fields
fr_event_timer_t const *	ev	Event in this worker's event heap.
int	fd	File descriptor to wait on.
fr_unlang_xlat_fd_event_t	fd_error	Function to call when FD has errored.
fr_unlang_xlat_fd_event_t	fd_read	Function to call when FD is readable.
fr_unlang_xlat_fd_event_t	fd_write	Function to call when FD is writable.
xlat_inst_t *	inst	xlat instance data.
void const *	rctx	rctx data to pass to callbacks.
request_t *	request	Request this event pertains to.
xlat_thread_inst_t *	thread	Thread specific xlat instance.
fr_unlang_xlat_timeout_t	timeout	Function to call on timeout.

◆ unlang_xlat_retry_t

struct unlang_xlat_retry_t

Definition at line 79 of file xlat.c.

Collaboration diagram for unlang_xlat_retry_t:

Data Fields
fr_event_timer_t const *	ev	retry timer just for this xlat
xlat_inst_t *	inst	xlat instance data.
void *	rctx	rctx data to pass to timeout callback
request_t *	request
fr_retry_t	retry	retry timers, etc.
fr_unlang_xlat_retry_t	retry_cb	callback to run on timeout
xlat_thread_inst_t *	thread	Thread specific xlat instance.

Function Documentation

◆ _unlang_xlat_event_free()

static int _unlang_xlat_event_free ( unlang_xlat_event_t * ev )

static

Frees an unlang event, removing it from the request's event loop.

Parameters

[in] ev The event to free.

Returns: 0

Definition at line 97 of file xlat.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _unlang_xlat_retry_free()

static int _unlang_xlat_retry_free ( unlang_xlat_retry_t * ev )

static

Frees an unlang event, removing it from the request's event loop.

Parameters

[in] ev The event to free.

Returns: 0

Definition at line 600 of file xlat.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_xlat()

static unlang_action_t unlang_xlat	(	rlm_rcode_t *	p_result,
		request_t *	request,
		unlang_stack_frame_t *	frame
	)

static

Stub function for calling the xlat interpreter.

Calls the xlat interpreter and translates its wants and needs into unlang_action_t codes.

Definition at line 394 of file xlat.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_xlat_eval()

int unlang_xlat_eval	(	TALLOC_CTX *	ctx,
		fr_value_box_list_t *	out,
		request_t *	request,
		xlat_exp_head_t const *	xlat
	)

Evaluate a "pure" (or not impure) xlat.

Parameters

[in]	ctx	To allocate value boxes and values in.
[out]	out	Where to write the result of the expansion.
[in]	request	to push xlat onto.
[in]	xlat	to evaluate.

Returns

0 on success.
-1 on failure.

Definition at line 739 of file xlat.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_xlat_eval_type()

int unlang_xlat_eval_type	(	TALLOC_CTX *	ctx,
		fr_value_box_t *	vb,
		fr_type_t	type,
		fr_dict_attr_t const *	enumv,
		request_t *	request,
		xlat_exp_head_t const *	xlat
	)

Evaluate a "pure" (or not impure) xlat.

Parameters

[in]	ctx	To allocate value boxes and values in.
[out]	vb	output value-box
[in]	type	expected type
[in]	enumv	enum for type
[in]	request	to push xlat onto.
[in]	xlat	to evaluate.

Returns

0 on success.
-1 on failure.

Definition at line 769 of file xlat.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_xlat_event_retry_handler()

static void unlang_xlat_event_retry_handler	(	UNUSED fr_event_list_t *	el,
		fr_time_t	now,
		void *	uctx
	)

static

Call the callback registered for a timeout event.

Parameters

[in]	el	the event timer was inserted into.
[in]	now	The current time, as held by the event_list.
[in]	uctx	unlang_module_event_t structure holding callbacks.

Definition at line 614 of file xlat.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_xlat_event_timeout_handler()

static void unlang_xlat_event_timeout_handler	(	UNUSED fr_event_list_t *	el,
		fr_time_t	now,
		void *	uctx
	)

static

Call the callback registered for a timeout event.

Parameters

[in]	el	the event timer was inserted into.
[in]	now	The current time, as held by the event_list.
[in]	uctx	unlang_module_event_t structure holding callbacks.

Definition at line 118 of file xlat.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_xlat_init()

void unlang_xlat_init ( void )

Register xlat operation with the interpreter.

Definition at line 827 of file xlat.c.

Here is the call graph for this function:

Here is the caller 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]	ctx	To allocate value boxes and values in.
[out]	p_success	If set, and execution succeeds, true will be written here. If execution fails, false will be written.
[out]	out	Where to write the result of the expansion.
[in]	request	to push xlat onto.
[in]	xlat	to evaluate.
[in]	top_frame	Set 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 286 of file xlat.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_xlat_push_internal()

static int unlang_xlat_push_internal	(	TALLOC_CTX *	ctx,
		bool *	p_success,
		fr_value_box_list_t *	out,
		request_t *	request,
		xlat_exp_head_t const *	xlat,
		xlat_exp_t *	node,
		bool	top_frame
	)

static

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

Parameters

[in]	ctx	To allocate value boxes and values in.
[out]	p_success	If set, and execution succeeds, true will be written here. If execution fails, false will be written.
[out]	out	Where to write the result of the expansion.
[in]	request	to push xlat onto.
[in]	xlat	head of list
[in]	node	to evaluate.
[in]	top_frame	Set 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.

Static instruction for performing xlat evaluations

Definition at line 203 of file xlat.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_xlat_push_node()

int unlang_xlat_push_node	(	TALLOC_CTX *	ctx,
		bool *	p_success,
		fr_value_box_list_t *	out,
		request_t *	request,
		xlat_exp_t *	node
	)

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

Parameters

[in]	ctx	To allocate value boxes and values in.
[out]	p_success	If set, and execution succeeds, true will be written here. If execution fails, false will be written.
[out]	out	Where to write the result of the expansion.
[in]	request	to push xlat onto.
[in]	node	to evaluate. Only this node will be evaluated.

Returns

0 on success.
-1 on failure.

Definition at line 306 of file xlat.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_xlat_repeat()

static unlang_action_t unlang_xlat_repeat	(	rlm_rcode_t *	p_result,
		request_t *	request,
		unlang_stack_frame_t *	frame
	)

static

Definition at line 312 of file xlat.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_xlat_resume()

static unlang_action_t unlang_xlat_resume	(	rlm_rcode_t *	p_result,
		request_t *	request,
		unlang_stack_frame_t *	frame
	)

static

Called when we're ready to resume processing the request.

Parameters

[in]	p_result	the result of the xlat function. RLM_MODULE_OK on success. RLM_MODULE_FAIL on failure.
[in]	request	to resume processing.
[in]	frame	the current stack frame.

Returns

UNLANG_ACTION_YIELD if additional asynchronous operations need to be performed.
UNLANG_ACTION_CALCULATE_RESULT if done.

Definition at line 493 of file xlat.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_xlat_signal()

static void unlang_xlat_signal	(	request_t *	request,
		unlang_stack_frame_t *	frame,
		fr_signal_t	action
	)

static

Send a signal (usually stop) to a request that's running an xlat expansions.

This is typically called via an "async" action, i.e. an action outside of the normal processing of the request.

If there is no xlat_func_signal_t callback defined, the action is ignored.

Parameters

[in]	request	The current request.
[in]	frame	The current stack frame.
[in]	action	What the request should do (the type of signal).

Definition at line 465 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]	request	the request
[in]	callback	to run when the timeout hits
[in]	rctx	passed to the callback
[in]	when	when the timeout fires

Returns

<0 on error
0 on success

Definition at line 152 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]	request	The current request.
[in]	resume	Called on unlang_interpret_mark_runnable().
[in]	signal	Called on unlang_action().
[in]	sigmask	Signals to block.
[in]	rctx	to pass to the callbacks.

Returns: always returns XLAT_ACTION_YIELD

Definition at line 573 of file xlat.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_xlat_yield_to_retry()

xlat_action_t unlang_xlat_yield_to_retry	(	request_t *	request,
		xlat_func_t	resume,
		fr_unlang_xlat_retry_t	retry,
		xlat_func_signal_t	signal,
		fr_signal_t	sigmask,
		void *	rctx,
		fr_retry_config_t const *	retry_cfg
	)

Yield a request back to the interpreter, with retries.

This passes control of the request back to the unlang interpreter, setting callbacks to execute when the request is 'signalled' asynchronously, or when the retry timer hits.

Note: The module function which calls unlang_module_yield_to_retry should return control of the C stack to the unlang interpreter immediately after calling unlang_module_yield_to_retry. A common pattern is to use return unlang_module_yield_to_retry(...).

Parameters

[in]	request	The current request.
[in]	resume	Called on unlang_interpret_mark_runnable().
[in]	retry	Called on when a retry timer hits
[in]	signal	Called on unlang_action().
[in]	sigmask	Set of signals to block.
[in]	rctx	to pass to the callbacks.
[in]	retry_cfg	to set up the retries

Returns

XLAT_ACTION_YIELD on success
XLAT_ACTION_FAIL on failure

Definition at line 691 of file xlat.c.

Here is the call graph for this function:

Data Structures

Functions

Detailed Description

Data Structure Documentation

◆ unlang_frame_state_xlat_t

◆ unlang_xlat_event_t

◆ unlang_xlat_retry_t

Function Documentation

◆ _unlang_xlat_event_free()

◆ _unlang_xlat_retry_free()

◆ unlang_xlat()

◆ unlang_xlat_eval()

◆ unlang_xlat_eval_type()

◆ unlang_xlat_event_retry_handler()

◆ unlang_xlat_event_timeout_handler()

◆ unlang_xlat_init()

◆ unlang_xlat_push()

◆ unlang_xlat_push_internal()

◆ unlang_xlat_push_node()

◆ unlang_xlat_repeat()

◆ unlang_xlat_resume()

◆ unlang_xlat_signal()

◆ unlang_xlat_timeout_add()

◆ unlang_xlat_yield()

◆ unlang_xlat_yield_to_retry()