Debugging function definitions and structures. More...

#include <freeradius-devel/build.h>
#include <freeradius-devel/missing.h>
#include <freeradius-devel/util/fring.h>

Include dependency graph for debug.h:

Go to the source code of this file.

Macros
#define	FR_FAULT_LOG(_fmt, ...) fr_fault_log(_fmt "\n", ## __VA_ARGS__)

#define	FR_FAULT_LOG_HEX(_data, _data_len) fr_fault_log_hex(_data, _data_len)

#define	MEM(x) do { if (!(x)) { fr_cond_assert_msg(0 && (x), "OUT OF MEMORY"); _fr_exit(__FILE__, __LINE__, EXIT_FAILURE, true); } } while (0)

Typedefs
typedef int(*	fr_fault_cb_t) (int signum)
	Optional callback passed to fr_fault_setup.

Enumerations
enum	fr_debug_state_t { DEBUGGER_STATE_UNKNOWN_NO_PTRACE = -3 , DEBUGGER_STATE_UNKNOWN_NO_PTRACE_CAP = -2 , DEBUGGER_STATE_UNKNOWN = -1 , DEBUGGER_STATE_NOT_ATTACHED = 0 , DEBUGGER_STATE_ATTACHED = 1 }

Functions
void	fr_debug_break (bool always)
	Break in debugger (if were running under a debugger)

void	fr_debug_state_store (void)
	Should be run before using setuid or setgid to get useful results.

char const *	fr_debug_state_to_msg (fr_debug_state_t state)
	Return current value of debug_state.

void	fr_disable_null_tracking_on_free (TALLOC_CTX *ctx)
	Disable the null tracking context when a talloc chunk is freed.

void	fr_fault (int sig)
	Prints a simple backtrace (if execinfo is available) and calls panic_action if set.

void	fr_fault_log (char const *msg,...))
	Log output to the fr_fault_log_fd.

void	fr_fault_log_hex (uint8_t const *data, size_t data_len)
	Print data as a hex block.

void	fr_fault_set_cb (fr_fault_cb_t func)
	Set a callback to be called before fr_fault()

void	fr_fault_set_log_fd (int fd)
	Set a file descriptor to log memory reports to.

int	fr_fault_setup (TALLOC_CTX ctx, char const cmd, char const *program)
	Registers signal handlers to execute panic_action on fatal signal.

int	fr_get_debug_state (void)

int	fr_get_lsan_state (void)

int	fr_log_talloc_report (TALLOC_CTX const *ctx)
	Generate a talloc memory report for a context and print to stderr/stdout.

void	fr_panic_on_free (TALLOC_CTX *ctx)
	Insert memory into the context of another talloc memory chunk which causes a panic when freed.

int	fr_reset_dumpable (void)
	Reset dumpable state to previously configured value.

int	fr_set_dumpable (bool allow_core_dumps)
	Enable or disable core dumps.

int	fr_set_dumpable_init (void)
	Get the current maximum for core files.

void	fr_talloc_fault_setup (void)
	Register talloc fault handlers.

Variables
fr_debug_state_t	fr_debug_state
	Whether we're attached to by a debugger.

int	fr_fault_log_fd
	Where to write debug output.

Assertion and exit macros
#define	fr_assert(_x) if (unlikely(!((bool)(_x)))) _fr_assert_fail(__FILE__, __LINE__, #_x, NULL)
	Calls panic_action ifndef NDEBUG, else logs error.

#define	fr_assert_fail(_msg, ...) _fr_assert_fail(__FILE__, __LINE__, "false", _msg, ## __VA_ARGS__)
	Calls panic_action ifndef NDEBUG, else logs error.

#define	fr_assert_msg(_x, _msg, ...) if (unlikely(!((bool)(_x)))) _fr_assert_fail(__FILE__, __LINE__, #_x, _msg, ## __VA_ARGS__)
	Calls panic_action ifndef NDEBUG, else logs error and causes the server to exit immediately with code 134.

#define	fr_cond_assert(_x) likely((bool)((_x) ? true : (_fr_assert_fail(__FILE__, __LINE__, #_x, NULL) && false)))
	Calls panic_action ifndef NDEBUG, else logs error and evaluates to value of _x.

#define	fr_cond_assert_msg(_x, _fmt, ...) likely((bool)((_x) ? true : (_fr_assert_fail(__FILE__, __LINE__, #_x, _fmt, ## __VA_ARGS__) && false)))
	Calls panic_action ifndef NDEBUG, else logs error and evaluates to value of _x.

#define	fr_exit(_x) _fr_exit(__FILE__, __LINE__, (_x), false)
	Exit, producing a log message in debug builds.

#define	fr_exit_now(_x) _fr_exit(__FILE__, __LINE__, (_x), true)
	Exit without calling atexit() handlers, producing a log message in debug builds.

#define	fr_fatal_assert(_x) if (unlikely(!((bool)(_x)))) _fr_assert_fatal(__FILE__, __LINE__, #_x, NULL)
	Calls panic_action ifndef NDEBUG, else logs error and causes the server to exit immediately with code 134.

#define	fr_fatal_assert_fail(_msg, ...) _fr_assert_fatal(__FILE__, __LINE__, "false", _msg, ## __VA_ARGS__)
	Calls panic_action ifndef NDEBUG, else logs error and causes the server to exit immediately with code 134.

#define	fr_fatal_assert_msg(_x, _fmt, ...) if (unlikely(!((bool)(_x)))) _fr_assert_fatal(__FILE__, __LINE__, #_x, _fmt, ## __VA_ARGS__)
	Calls panic_action ifndef NDEBUG, else logs error and causes the server to exit immediately with code 134.

Assertion support functions
bool	_fr_assert_fail (char const file, int line, char const expr, char const *msg,...))
	A soft assertion which triggers the fault handler in debug builds.

NEVER_RETURNS void	_fr_assert_fatal (char const file, int line, char const expr, char const *msg,...))
	A fatal assertion which triggers the fault handler in debug builds or exits.

NEVER_RETURNS void	_fr_exit (char const *file, int line, int status, bool now)
	Exit possibly printing a message about why we're exiting.

Detailed Description

Debugging function definitions and structures.

Copyright: 2015-2017 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 debug.h.

Macro Definition Documentation

◆ fr_assert

#define fr_assert ( _x ) if (unlikely(!((bool)(_x)))) _fr_assert_fail(__FILE__, __LINE__, #_x, NULL)

Calls panic_action ifndef NDEBUG, else logs error.

Parameters

[in] _x expression to test (should evaluate to true)

Definition at line 194 of file debug.h.

◆ fr_assert_fail

#define fr_assert_fail	(	_msg,
		...
	)	_fr_assert_fail(__FILE__, __LINE__, "false", _msg, ## __VA_ARGS__)

Calls panic_action ifndef NDEBUG, else logs error.

Parameters

[in]	_msg	to log.
[in]	...	args.

Definition at line 208 of file debug.h.

◆ fr_assert_msg

#define fr_assert_msg	(	_x,
		_msg,
		...
	)	if (unlikely(!((bool)(_x)))) _fr_assert_fail(__FILE__, __LINE__, #_x, _msg, ## __VA_ARGS__)

Calls panic_action ifndef NDEBUG, else logs error and causes the server to exit immediately with code 134.

Parameters

[in]	_x	expression to test (should evaluate to true)
[in]	_msg	to log.
[in]	...	args.

Definition at line 202 of file debug.h.

◆ fr_cond_assert

#define fr_cond_assert ( _x ) likely((bool)((_x) ? true : (_fr_assert_fail(__FILE__, __LINE__, #_x, NULL) && false)))

Calls panic_action ifndef NDEBUG, else logs error and evaluates to value of _x.

Should be wrapped in a condition, and if false, should cause function to return an error code. This allows control to return to the caller if a precondition is not satisfied and we're not debugging.

Example:

  if (!fr_cond_assert(request)) return -1

Parameters

[in] _x expression to test (should evaluate to true)

Definition at line 131 of file debug.h.

◆ fr_cond_assert_msg

#define fr_cond_assert_msg	(	_x,
		_fmt,
		...
	)	likely((bool)((_x) ? true : (_fr_assert_fail(__FILE__, __LINE__, #_x, _fmt, ## __VA_ARGS__) && false)))

Calls panic_action ifndef NDEBUG, else logs error and evaluates to value of _x.

Should be wrapped in a condition, and if false, should cause function to return an error code. This allows control to return to the caller if a precondition is not satisfied and we're not debugging.

Example:

  if (!fr_cond_assert_msg(request, "Bad stuff happened: %s", fr_syserror(errno)))) return -1

Parameters

[in]	_x	expression to test (should evaluate to true)
[in]	_fmt	of message to log.
[in]	...	fmt arguments.

Definition at line 148 of file debug.h.

◆ fr_exit

#define fr_exit ( _x ) _fr_exit(__FILE__, __LINE__, (_x), false)

Exit, producing a log message in debug builds.

Parameters

[in] _x code to exit with.

Definition at line 220 of file debug.h.

◆ fr_exit_now

#define fr_exit_now ( _x ) _fr_exit(__FILE__, __LINE__, (_x), true)

Exit without calling atexit() handlers, producing a log message in debug builds.

Parameters

[in] _x code to exit with.

Definition at line 226 of file debug.h.

◆ fr_fatal_assert

#define fr_fatal_assert ( _x ) if (unlikely(!((bool)(_x)))) _fr_assert_fatal(__FILE__, __LINE__, #_x, NULL)

Calls panic_action ifndef NDEBUG, else logs error and causes the server to exit immediately with code 134.

Example:

  fr_fatal_assert(<extremely_unlikely_and_fatal_condition>);

Parameters

_x	expression to test (should evaluate to true)

Definition at line 159 of file debug.h.

◆ fr_fatal_assert_fail

#define fr_fatal_assert_fail	(	_msg,
		...
	)	_fr_assert_fatal(__FILE__, __LINE__, "false", _msg, ## __VA_ARGS__)

Calls panic_action ifndef NDEBUG, else logs error and causes the server to exit immediately with code 134.

Parameters

[in]	_msg	to log.
[in]	...	args.

Definition at line 183 of file debug.h.

◆ fr_fatal_assert_msg

#define fr_fatal_assert_msg	(	_x,
		_fmt,
		...
	)	if (unlikely(!((bool)(_x)))) _fr_assert_fatal(__FILE__, __LINE__, #_x, _fmt, ## __VA_ARGS__)

Calls panic_action ifndef NDEBUG, else logs error and causes the server to exit immediately with code 134.

Should be wrapped in a condition, and if false, should cause function to return an error code. This allows control to return to the caller if a precondition is not satisfied and we're not debugging.

Example:

  fr_fatal_assert(<extremely_unlikely_and_fatal_condition>);

Parameters

[in]	_x	expression to test (should evaluate to true)
[in]	_fmt	of message to log.
[in]	...	fmt arguments.

Definition at line 176 of file debug.h.

◆ FR_FAULT_LOG

#define FR_FAULT_LOG	(	_fmt,
		...
	)	fr_fault_log(_fmt "\n", ## __VA_ARGS__)

Definition at line 50 of file debug.h.

◆ FR_FAULT_LOG_HEX

#define FR_FAULT_LOG_HEX	(	_data,
		_data_len
	)	fr_fault_log_hex(_data, _data_len)

Definition at line 51 of file debug.h.

◆ MEM

#define MEM ( x ) do { if (!(x)) { fr_cond_assert_msg(0 && (x), "OUT OF MEMORY"); _fr_exit(__FILE__, __LINE__, EXIT_FAILURE, true); } } while (0)

Definition at line 36 of file debug.h.

Typedef Documentation

◆ fr_fault_cb_t

typedef int(* fr_fault_cb_t) (int signum)

Optional callback passed to fr_fault_setup.

Allows optional logic to be run before calling the main fault handler.

If the callback returns < 0, the main fault handler will not be called.

Parameters

signum signal raised.

Returns

0 on success.
< 0 on failure.

Definition at line 64 of file debug.h.

Enumeration Type Documentation

◆ fr_debug_state_t

enum fr_debug_state_t

Enumerator
DEBUGGER_STATE_UNKNOWN_NO_PTRACE	We don't have ptrace so can't check.
DEBUGGER_STATE_UNKNOWN_NO_PTRACE_CAP	CAP_SYS_PTRACE not set for the process.
DEBUGGER_STATE_UNKNOWN	Unknown, likely fr_get_debug_state() not called yet.
DEBUGGER_STATE_NOT_ATTACHED	We can attach, so a debugger must not be.
DEBUGGER_STATE_ATTACHED	We can't attach, it's likely a debugger is already tracing.

Definition at line 39 of file debug.h.

Function Documentation

◆ _fr_assert_fail()

bool _fr_assert_fail	(	char const *	file,
		int	line,
		char const *	expr,
		char const *	msg,
			...
	)

A soft assertion which triggers the fault handler in debug builds.

Parameters

[in]	file	the assertion failed in.
[in]	line	of the assertion in the file.
[in]	expr	that was evaluated.
[in]	msg	Message to print (may be NULL).
[in]	...	Arguments for msg string.

Returns: the value of cond.

Definition at line 1246 of file debug.c.

Here is the call graph for this function:

◆ _fr_assert_fatal()

NEVER_RETURNS void _fr_assert_fatal	(	char const *	file,
		int	line,
		char const *	expr,
		char const *	msg,
			...
	)

A fatal assertion which triggers the fault handler in debug builds or exits.

Parameters

[in]	file	the assertion failed in.
[in]	line	of the assertion in the file.
[in]	expr	that was evaluated.
[in]	msg	Message to print (may be NULL).
[in]	...	Arguments for msg string.

Definition at line 1282 of file debug.c.

Here is the call graph for this function:

◆ _fr_exit()

NEVER_RETURNS void _fr_exit	(	char const *	file,
		int	line,
		int	status,
		bool	now
	)

Exit possibly printing a message about why we're exiting.

Note: Use the fr_exit(status) macro instead of calling this function directly.

Parameters

[in]	file	where fr_exit() was called.
[in]	line	where fr_exit() was called.
[in]	status	we're exiting with.
[in]	now	Exit immediately.

Definition at line 1314 of file debug.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_debug_break()

void fr_debug_break ( bool always )

Break in debugger (if were running under a debugger)

If the server is running under a debugger this will raise a SIGTRAP which will pause the running process.

If the server is not running under debugger then this will do nothing.

Definition at line 540 of file debug.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_debug_state_store()

void fr_debug_state_store ( void )

Should be run before using setuid or setgid to get useful results.

Note: sets the fr_debug_state global.

Definition at line 491 of file debug.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_debug_state_to_msg()

char const * fr_debug_state_to_msg ( fr_debug_state_t state )

Return current value of debug_state.

Parameters

state to translate into a humanly readable value.

Returns: humanly readable version of debug state.

Definition at line 511 of file debug.c.

Here is the caller graph for this function:

◆ fr_disable_null_tracking_on_free()

void fr_disable_null_tracking_on_free ( TALLOC_CTX * ctx )

Disable the null tracking context when a talloc chunk is freed.

Definition at line 1020 of file debug.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_fault()

void fr_fault ( int sig )

Prints a simple backtrace (if execinfo is available) and calls panic_action if set.

Parameters

sig caught

Definition at line 798 of file debug.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_fault_log()

void fr_fault_log	(	char const *	msg,
			...
	)

Log output to the fr_fault_log_fd.

We used to support a user defined callback, which was set to a radlog function. Unfortunately, when logging to syslog, syslog would alloc memory which would result in a deadlock if fr_fault was triggered from within a allocation call.

Now we just write directly to the FD.

Definition at line 1198 of file debug.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_fault_log_hex()

void fr_fault_log_hex	(	uint8_t const *	data,
		size_t	data_len
	)

Print data as a hex block.

Definition at line 1212 of file debug.c.

Here is the call graph for this function:

◆ fr_fault_set_cb()

void fr_fault_set_cb ( fr_fault_cb_t func )

Set a callback to be called before fr_fault()

Parameters

func	to execute. If callback returns < 0 fr_fault will exit before running panic_action code.

Definition at line 1184 of file debug.c.

Here is the caller graph for this function:

◆ fr_fault_set_log_fd()

void fr_fault_set_log_fd ( int fd )

Set a file descriptor to log memory reports to.

Parameters

fd	to write output to.

Definition at line 1232 of file debug.c.

Here is the caller graph for this function:

◆ fr_fault_setup()

int fr_fault_setup	(	TALLOC_CTX *	ctx,
		char const *	cmd,
		char const *	program
	)

Registers signal handlers to execute panic_action on fatal signal.

May be called multiple time to change the panic_action/program.

Parameters

[in]	ctx	to allocate autofreeable resources in.
[in]	cmd	to execute on fault. If present p will be substituted for the parent PID before the command is executed, and e will be substituted for the currently running program.
	program	Name of program currently executing (argv[0]).

Returns

0 on success.
-1 on failure.

Definition at line 1055 of file debug.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_get_debug_state()

int fr_get_debug_state ( void )

Definition at line 479 of file debug.c.

Here is the caller graph for this function:

◆ fr_get_lsan_state()

int fr_get_lsan_state ( void )

Definition at line 231 of file debug.c.

Here is the caller graph for this function:

◆ fr_log_talloc_report()

int fr_log_talloc_report ( TALLOC_CTX const * ctx )

Generate a talloc memory report for a context and print to stderr/stdout.

Parameters

ctx	to generate a report for, may be NULL in which case the root context is used.

Definition at line 961 of file debug.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_panic_on_free()

void fr_panic_on_free ( TALLOC_CTX * ctx )

Insert memory into the context of another talloc memory chunk which causes a panic when freed.

Parameters

ctx	TALLOC_CTX to monitor for frees.

Definition at line 564 of file debug.c.

Here is the call graph for this function:

◆ fr_reset_dumpable()

int fr_reset_dumpable ( void )

Reset dumpable state to previously configured value.

Needed after suid up/down

Returns

0 on success.
-1 on failure.

Definition at line 742 of file debug.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_set_dumpable()

int fr_set_dumpable ( bool allow_core_dumps )

Enable or disable core dumps.

Parameters

allow_core_dumps whether to enable or disable core dumps.

Definition at line 674 of file debug.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_set_dumpable_init()

int fr_set_dumpable_init ( void )

Get the current maximum for core files.

Do this before anything else so as to ensure it's properly initialized.

Definition at line 659 of file debug.c.

Here is the call graph for this function:

◆ fr_talloc_fault_setup()

void fr_talloc_fault_setup ( void )

Register talloc fault handlers.

Just register the fault handlers we need to make talloc produce useful debugging output.

Definition at line 1036 of file debug.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ fr_debug_state

fr_debug_state_t fr_debug_state

extern

Whether we're attached to by a debugger.

Definition at line 74 of file debug.c.

◆ fr_fault_log_fd

int fr_fault_log_fd

extern

Where to write debug output.

Definition at line 72 of file debug.c.

Macros

Typedefs

Enumerations

Functions

Variables

Assertion and exit macros

Assertion support functions

Detailed Description

Macro Definition Documentation

◆ fr_assert

◆ fr_assert_fail

◆ fr_assert_msg

◆ fr_cond_assert

◆ fr_cond_assert_msg

◆ fr_exit

◆ fr_exit_now

◆ fr_fatal_assert

◆ fr_fatal_assert_fail

◆ fr_fatal_assert_msg

◆ FR_FAULT_LOG

◆ FR_FAULT_LOG_HEX

◆ MEM

Typedef Documentation

◆ fr_fault_cb_t

Enumeration Type Documentation

◆ fr_debug_state_t

Function Documentation

◆ _fr_assert_fail()

◆ _fr_assert_fatal()

◆ _fr_exit()

◆ fr_debug_break()

◆ fr_debug_state_store()

◆ fr_debug_state_to_msg()

◆ fr_disable_null_tracking_on_free()

◆ fr_fault()

◆ fr_fault_log()

◆ fr_fault_log_hex()

◆ fr_fault_set_cb()

◆ fr_fault_set_log_fd()

◆ fr_fault_setup()

◆ fr_get_debug_state()

◆ fr_get_lsan_state()

◆ fr_log_talloc_report()

◆ fr_panic_on_free()

◆ fr_reset_dumpable()

◆ fr_set_dumpable()

◆ fr_set_dumpable_init()

◆ fr_talloc_fault_setup()

Variable Documentation

◆ fr_debug_state

◆ fr_fault_log_fd