function.h File Reference

Declarations for generic unlang functions. More...

#include <freeradius-devel/unlang/interpret.h>
#include <freeradius-devel/server/rcode.h>
#include <freeradius-devel/server/request.h>
#include <freeradius-devel/server/signal.h>

Include dependency graph for function.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	unlang_function_push(_request, _func, _repeat, _signal, _sigmask, _top_frame, _uctx)
	Push a generic function onto the unlang stack.
#define	unlang_function_push_with_result(_result_p, _request, _func, _repeat, _signal, _sigmask, _top_frame, _uctx)
	Push a generic function onto the unlang stack that produces a result.
#define	unlang_function_repeat_set(_request, _repeat)
	Set a new repeat function for an existing function frame.
#define	unlang_function_signal_set(_request, _signal, _sigmask)    _unlang_function_signal_set(_request, _signal, _sigmask, STRINGIFY(_signal))
	Set a new signal function for an existing function frame.

Typedefs
typedef unlang_action_t(*	unlang_function_no_result_t) (request_t *request, void *uctx)
	A generic function pushed by a module or xlat to functions deeper in the C call stack to create resumption points.
typedef void(*	unlang_function_signal_t) (request_t *request, fr_signal_t action, void *uctx)
	Function to call if the request was signalled.
typedef unlang_action_t(*	unlang_function_with_result_t) (unlang_result_t *p_result, request_t *request, void *uctx)
	A generic function pushed by a module or xlat to functions deeper in the C call stack to create resumption points.

Enumerations
enum	unlang_function_type_t {   UNLANG_FUNCTION_TYPE_WITH_RESULT ,   UNLANG_FUNCTION_TYPE_NO_RESULT }

Functions
unlang_action_t	_unlang_function_push_no_result (request_t *request, unlang_function_no_result_t func, char const *func_name, unlang_function_no_result_t repeat, char const *repeat_name, unlang_function_signal_t signal, fr_signal_t sigmask, char const *signal_name, bool top_frame, void *uctx)
	Push a generic function onto the unlang stack.
unlang_action_t	_unlang_function_push_with_result (unlang_result_t *p_result, request_t *request, unlang_function_with_result_t func, char const *func_name, unlang_function_with_result_t repeat, char const *repeat_name, unlang_function_signal_t signal, fr_signal_t sigmask, char const *signal_name, bool top_frame, void *uctx)
	Push a generic function onto the unlang stack with a result.
int	_unlang_function_repeat_set (request_t *request, void *repeat, char const *name, unlang_function_type_t type)
	Set a new repeat function for an existing function frame.
int	_unlang_function_signal_set (request_t *request, unlang_function_signal_t signal, fr_signal_t sigmask, char const *name)
	Set a new signal function for an existing function frame.
int	unlang_function_clear (request_t *request)
	Clear pending repeat function calls, and remove the signal handler.
int	unlang_function_repeat_clear (request_t *request)
	Clear the pending repeat function, and keep the signal handler.

Detailed Description

Declarations for generic unlang functions.

Id

5b0e7b929c2f08cee68ed5866aca0dbae3c19c1a

These are a useful alternative to module methods for library code. They're more light weight, and don't require instance data lookups to function.

Copyright

2021 The FreeRADIUS server project

Definition in file function.h.

Macro Definition Documentation

unlang_function_push

#define unlang_function_push	(		_request,
			_func,
			_repeat,
			_signal,
			_sigmask,
			_top_frame,
			_uctx
	)

Value:

                _unlang_function_push_no_result(_request, \
                                                _func, STRINGIFY(_func), \
                                                _repeat, STRINGIFY(_repeat), \
                                                _signal, _sigmask, STRINGIFY(_signal), \
                                                 _top_frame, _uctx)

Push a generic function onto the unlang stack.

These can be pushed by any other type of unlang op to allow a submodule or function deeper in the C call stack to establish a new resumption point.

Note

If you're pushing a function onto the stack to resume execution in a module, you're probably doing it wrong. Use unlang_module_yield() instead, and change the process function for the module.

Parameters

[in]	_request	The current request.
[in]	_func	to call going up the stack.
[in]	_repeat	function to call going back down the stack (may be NULL). This may be the same as func.
[in]	_signal	function to call if the request is signalled.
[in]	_sigmask	Signals to block.
[in]	_top_frame	Return out of the unlang interpreter when popping this frame.
[in]	_uctx	to pass to func(s).

Returns

• UNLANG_ACTION_PUSHED_CHILD on success.
• UNLANG_ACTION_FAIL on failure.

Definition at line 181 of file function.h.

unlang_function_push_with_result

#define unlang_function_push_with_result	(		_result_p,
			_request,
			_func,
			_repeat,
			_signal,
			_sigmask,
			_top_frame,
			_uctx
	)

Value:

                _unlang_function_push_with_result(_result_p, _request, \
                                                  _func, STRINGIFY(_func), \
                                                  _repeat, STRINGIFY(_repeat), \
                                                  _signal, _sigmask, STRINGIFY(_signal), \
                                                  _top_frame, _uctx)

Push a generic function onto the unlang stack that produces a result.

These can be pushed by any other type of unlang op to allow a submodule or function deeper in the C call stack to establish a new resumption point.

Note

If you're pushing a function onto the stack to resume execution in a module, you're probably doing it wrong. Use unlang_module_yield() instead, and change the process function for the module.

Parameters

[in]	_result_p	Where to write the result.
[in]	_request	The current request.
[in]	_func	to call going up the stack.
[in]	_repeat	function to call going back down the stack (may be NULL). This may be the same as func.
[in]	_signal	function to call if the request is signalled.
[in]	_sigmask	Signals to block.
[in]	_top_frame	Return out of the unlang interpreter when popping this frame.
[in]	_uctx	to pass to func(s).

Returns

• UNLANG_ACTION_PUSHED_CHILD on success.
• UNLANG_ACTION_FAIL on failure.

Definition at line 146 of file function.h.

unlang_function_repeat_set

#define unlang_function_repeat_set	(		_request,
			_repeat
	)

Value:

                _Generic((&(_repeat)), \
                        unlang_function_with_result_t: _unlang_function_repeat_set(_request,\
                                                                                   (void *)(_repeat), \
                                                                                   STRINGIFY(_repeat), \
                                                                                   UNLANG_FUNCTION_TYPE_WITH_RESULT), \
                        unlang_function_no_result_t: _unlang_function_repeat_set(_request,\
                                                                                 (void *)(_repeat), \
                                                                                 STRINGIFY(_repeat), \
                                                                                 UNLANG_FUNCTION_TYPE_NO_RESULT) \
                )

Set a new repeat function for an existing function frame.

The function frame being modified must be at the top of the stack.

Parameters

[in]	_request	The current request.
[in]	_repeat	the repeat function to set.

Returns

• 0 on success.
• -1 on failure.

Definition at line 110 of file function.h.

unlang_function_signal_set

#define unlang_function_signal_set	(		_request,
			_signal,
			_sigmask
	)		_unlang_function_signal_set(_request, _signal, _sigmask, STRINGIFY(_signal))

Set a new signal function for an existing function frame.

The function frame being modified must be at the top of the stack.

Parameters

[in]	_request	The current request.
[in]	_signal	The signal function to set.
[in]	_sigmask	Signals to block.

Returns

• 0 on success.
• -1 on failure.

Definition at line 95 of file function.h.

Typedef Documentation

unlang_function_no_result_t

typedef unlang_action_t(* unlang_function_no_result_t) (request_t *request, void *uctx)

A generic function pushed by a module or xlat to functions deeper in the C call stack to create resumption points.

Note

Returning UNLANG_ACTION_FAIL has an identical effect to returning UNLANG_ACTION_CALCULATE_RESULT and will not be visible to the caller.

Parameters

[in]	request	The current request.
[in,out]	uctx	Provided by whatever pushed the function. Is opaque to the interpreter, but should be usable by the function. All input (args) and output will be done using this structure.

Returns

an unlang_action_t.

Definition at line 68 of file function.h.

unlang_function_signal_t

typedef void(* unlang_function_signal_t) (request_t *request, fr_signal_t action, void *uctx)

Function to call if the request was signalled.

Parameters

[in]	request	The current request.
[in]	action	We're being signalled with.
[in,out]	uctx	Provided by whatever pushed the function. Is opaque to the interpreter, but should be usable by the function. All input (args) and output will be done using this structure.

Definition at line 78 of file function.h.

unlang_function_with_result_t

typedef unlang_action_t(* unlang_function_with_result_t) (unlang_result_t *p_result, request_t *request, void *uctx)

A generic function pushed by a module or xlat to functions deeper in the C call stack to create resumption points.

Parameters

[in]	p_result	The module return code and priority.
[in]	request	The current request.
[in,out]	uctx	Provided by whatever pushed the function. Is opaque to the interpreter, but should be usable by the function. All input (args) and output will be done using this structure.

Returns

an unlang_action_t.

Definition at line 55 of file function.h.

Enumeration Type Documentation

unlang_function_type_t

enum unlang_function_type_t

Enumerator
UNLANG_FUNCTION_TYPE_WITH_RESULT	Function with a result.
UNLANG_FUNCTION_TYPE_NO_RESULT	Function without a result.

Definition at line 41 of file function.h.

Function Documentation

_unlang_function_push_no_result()

unlang_action_t _unlang_function_push_no_result	(	request_t *	request,
		unlang_function_no_result_t	func,
		char const *	func_name,
		unlang_function_no_result_t	repeat,
		char const *	repeat_name,
		unlang_function_signal_t	signal,
		fr_signal_t	sigmask,
		char const *	signal_name,
		bool	top_frame,
		void *	uctx
	)

Push a generic function onto the unlang stack.

These can be pushed by any other type of unlang op to allow a submodule or function deeper in the C call stack to establish a new resumption point.

Parameters

[in]	request	The current request.
[in]	func	to call going up the stack.
[in]	func_name	Name of the function call (for debugging).
[in]	repeat	function to call going back down the stack (may be NULL). This may be the same as func.
[in]	repeat_name	Name of the repeat function call (for debugging).
[in]	signal	function to call if the request is signalled.
[in]	sigmask	Signals to block.
[in]	signal_name	Name of the signal function call (for debugging).
[in]	top_frame	Return out of the unlang interpreter when popping this frame.
[in]	uctx	to pass to func(s).

Returns

• UNLANG_ACTION_PUSHED_CHILD on success.
• UNLANG_ACTION_FAIL on failure.

Definition at line 538 of file function.c.

Here is the call graph for this function:

_unlang_function_push_with_result()

unlang_action_t _unlang_function_push_with_result	(	unlang_result_t *	p_result,
		request_t *	request,
		unlang_function_with_result_t	func,
		char const *	func_name,
		unlang_function_with_result_t	repeat,
		char const *	repeat_name,
		unlang_function_signal_t	signal,
		fr_signal_t	sigmask,
		char const *	signal_name,
		bool	top_frame,
		void *	uctx
	)

Push a generic function onto the unlang stack with a result.

These can be pushed by any other type of unlang op to allow a submodule or function deeper in the C call stack to establish a new resumption point.

Parameters

[in]	p_result	Where to write the result of the function evaluation.
[in]	request	The current request.
[in]	func	to call going up the stack.
[in]	func_name	Name of the function call (for debugging).
[in]	repeat	function to call going back down the stack (may be NULL). This may be the same as func.
[in]	repeat_name	Name of the repeat function call (for debugging).
[in]	signal	function to call if the request is signalled.
[in]	sigmask	Signals to block.
[in]	signal_name	Name of the signal function call (for debugging).
[in]	top_frame	Return out of the unlang interpreter when popping this frame.
[in]	uctx	to pass to func(s).

Returns

• UNLANG_ACTION_PUSHED_CHILD on success.
• UNLANG_ACTION_FAIL on failure.

Definition at line 487 of file function.c.

Here is the call graph for this function:

_unlang_function_repeat_set()

int _unlang_function_repeat_set	(	request_t *	request,
		void *	repeat,
		char const *	repeat_name,
		unlang_function_type_t	type
	)

Set a new repeat function for an existing function frame.

The function frame being modified must be at the top of the stack.

Parameters

[in]	request	The current request.
[in]	repeat	the repeat function to set.
[in]	repeat_name	Name of the repeat function call (for debugging).
[in]	type	Type of repeat function (with or without result).

Returns

• 0 on success.
• -1 on failure.

Definition at line 382 of file function.c.

Here is the call graph for this function:

_unlang_function_signal_set()

int _unlang_function_signal_set	(	request_t *	request,
		unlang_function_signal_t	signal,
		fr_signal_t	sigmask,
		char const *	signal_name
	)

Set a new signal function for an existing function frame.

The function frame being modified must be at the top of the stack.

Parameters

[in]	request	The current request.
[in]	signal	The signal function to set.
[in]	sigmask	Signals to block.
[in]	signal_name	Name of the signal function call (for debugging).

Returns

• 0 on success.
• -1 on failure.

Definition at line 343 of file function.c.

unlang_function_clear()

int unlang_function_clear

(

request_t *

request

)

Clear pending repeat function calls, and remove the signal handler.

The function frame being modified must be at the top of the stack.

Parameters

[in]

request

The current request.

Returns

• 0 on success.
• -1 on failure.

Definition at line 275 of file function.c.

Here is the call graph for this function:

unlang_function_repeat_clear()

int unlang_function_repeat_clear

(

request_t *

request

)

Clear the pending repeat function, and keep the signal handler.

If a unlang function returns UNLANG_ACTION_CALCULATE_RESULT with a repeat function set, the repeat function is never executed, and the signal handler for the frame (if set) is called to clean up state.

If the returning function does not want the cancellation callback to execute it should call unlang_function_repeat_clear to clear the repeat function.

Parameters

[in]

request

The current request.

Returns

• 0 on success.
• -1 on failure.

Definition at line 309 of file function.c.

Here is the call graph for this function: