Debugging function definitions and structures. More...

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

Include dependency graph for debug.h:

Go to the source code of this file.

Macros
#define	_PANIC_ACTION_SIGABRT 0
	Bitmask of signal numbers to install the panic-action handler on.

#define	_PANIC_ACTION_SIGALRM 0

#define	_PANIC_ACTION_SIGFPE 0

#define	_PANIC_ACTION_SIGILL 0

#define	_PANIC_ACTION_SIGSEGV 0

#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)

#define	PANIC_ACTION_SIGNALS

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, unsigned long fault_signals)
	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

◆ _PANIC_ACTION_SIGABRT

#define _PANIC_ACTION_SIGABRT 0

Bitmask of signal numbers to install the panic-action handler on.

PANIC_ACTION_SIGNALS is the default set installed by every FreeRADIUS program. Callers that share a signal with another library (e.g. libFuzzer also uses SIGALRM for its own timeout) pass PANIC_ACTION_SIGNALS with the offending bit cleared so the FR handler is not registered for that signal and the other library's handler stays in place.

Definition at line 105 of file debug.h.

◆ _PANIC_ACTION_SIGALRM

#define _PANIC_ACTION_SIGALRM 0

Definition at line 125 of file debug.h.

◆ _PANIC_ACTION_SIGFPE

#define _PANIC_ACTION_SIGFPE 0

Definition at line 115 of file debug.h.

◆ _PANIC_ACTION_SIGILL

#define _PANIC_ACTION_SIGILL 0

Definition at line 110 of file debug.h.

◆ _PANIC_ACTION_SIGSEGV

#define _PANIC_ACTION_SIGSEGV 0

Definition at line 120 of file debug.h.

◆ 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 235 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 249 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 243 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 172 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 189 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 261 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 267 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 200 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 224 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 217 of file debug.h.

◆ FR_FAULT_LOG

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

Definition at line 52 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 53 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 38 of file debug.h.

◆ PANIC_ACTION_SIGNALS

#define PANIC_ACTION_SIGNALS

Value:

                                 (_PANIC_ACTION_SIGABRT | _PANIC_ACTION_SIGILL | \
                                 _PANIC_ACTION_SIGFPE | _PANIC_ACTION_SIGSEGV | \
                                 _PANIC_ACTION_SIGALRM)

Definition at line 128 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 66 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 41 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 1272 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 1308 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 1340 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 554 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 505 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 525 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 1034 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 812 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 1224 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 1238 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 1210 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 1258 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,
		unsigned long	fault_signals
	)

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.
[in]	program	Name of program currently executing (argv[0]).
[in]	fault_signals	Bitmask (bit N = signal N) of signals to install the panic-action handler on. Callers pass PANIC_ACTION_SIGNALS unless they need to leave a specific signal's handler alone (e.g. the fuzzer shares SIGALRM with libFuzzer's own timeout).

Returns

0 on success.
-1 on failure.

Definition at line 1074 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 493 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 245 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 975 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 578 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 756 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 688 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 673 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 1050 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

◆ _PANIC_ACTION_SIGABRT

◆ _PANIC_ACTION_SIGALRM

◆ _PANIC_ACTION_SIGFPE

◆ _PANIC_ACTION_SIGILL

◆ _PANIC_ACTION_SIGSEGV

◆ 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

◆ PANIC_ACTION_SIGNALS

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