Logging and runtime debug

Macros
#define	MDBX_LOGGER_DONTCHANGE   ((MDBX_debug_func *)(intptr_t)-1)
	The "don't change `logger`" value for mdbx_setup_debug() More...

Typedefs
typedef enum MDBX_log_level_t	MDBX_log_level_t
typedef enum MDBX_debug_flags_t	MDBX_debug_flags_t
typedef void	MDBX_debug_func(MDBX_log_level_t loglevel, const char *function, int line, const char *fmt, va_list args) MDBX_CXX17_NOEXCEPT
	A debug-logger callback function, called before printing the message and aborting. More...
typedef void	MDBX_assert_func(const MDBX_env *env, const char *msg, const char *function, unsigned line) MDBX_CXX17_NOEXCEPT
	A callback function for most MDBX assert() failures, called before printing the message and aborting. More...

Enumerations
enum	MDBX_log_level_t {   MDBX_LOG_FATAL = 0, MDBX_LOG_ERROR = 1, MDBX_LOG_WARN = 2, MDBX_LOG_NOTICE = 3,   MDBX_LOG_VERBOSE = 4, MDBX_LOG_DEBUG = 5, MDBX_LOG_TRACE = 6, MDBX_LOG_EXTRA = 7,   MDBX_LOG_DONTCHANGE = -1 }
enum	MDBX_debug_flags_t {   MDBX_DBG_NONE = 0, MDBX_DBG_ASSERT = 1, MDBX_DBG_AUDIT = 2, MDBX_DBG_JITTER = 4,   MDBX_DBG_DUMP = 8, MDBX_DBG_LEGACY_MULTIOPEN = 16, MDBX_DBG_LEGACY_OVERLAP = 32, MDBX_DBG_DONT_UPGRADE = 64,   MDBX_DBG_DONTCHANGE = -1 }
	Runtime debug flags. More...

Functions
LIBMDBX_API int	mdbx_setup_debug (MDBX_log_level_t log_level, MDBX_debug_flags_t debug_flags, MDBX_debug_func *logger)
	Setup global log-level, debug options and debug logger. More...
LIBMDBX_API int	mdbx_env_set_assert (MDBX_env *env, MDBX_assert_func *func)
	Set or reset the assert() callback of the environment. More...
const LIBMDBX_API char *	mdbx_dump_val (const MDBX_val *key, char *const buf, const size_t bufsize)
	Dump given MDBX_val to the buffer. More...
LIBMDBX_API void	mdbx_panic (const char *fmt,...) MDBX_PRINTF_ARGS(1
	Panics with message and causes abnormal process termination. More...

Detailed Description

Note

Most of debug feature enabled only when libmdbx builded with MDBX_DEBUG build option.

Macro Definition Documentation

MDBX_LOGGER_DONTCHANGE

#define MDBX_LOGGER_DONTCHANGE   ((MDBX_debug_func *)(intptr_t)-1)

The "don't change `logger`" value for mdbx_setup_debug()

Typedef Documentation

MDBX_assert_func

typedef void MDBX_assert_func(const MDBX_env *env, const char *msg, const char *function, unsigned line) MDBX_CXX17_NOEXCEPT

A callback function for most MDBX assert() failures, called before printing the message and aborting.

See also

mdbx_env_set_assert()

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[in]	msg	The assertion message, not including newline.

MDBX_debug_flags_t

typedef enum MDBX_debug_flags_t MDBX_debug_flags_t

MDBX_debug_func

typedef void MDBX_debug_func(MDBX_log_level_t loglevel, const char *function, int line, const char *fmt, va_list args) MDBX_CXX17_NOEXCEPT

A debug-logger callback function, called before printing the message and aborting.

See also

mdbx_setup_debug()

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[in]	msg	The assertion message, not including newline.

MDBX_log_level_t

typedef enum MDBX_log_level_t MDBX_log_level_t

Enumeration Type Documentation

MDBX_debug_flags_t

enum MDBX_debug_flags_t

Runtime debug flags.

MDBX_DBG_DUMP and MDBX_DBG_LEGACY_MULTIOPEN always have an effect, but MDBX_DBG_ASSERT, MDBX_DBG_AUDIT and MDBX_DBG_JITTER only if libmdbx builded with MDBX_DEBUG.

Enumerator
MDBX_DBG_NONE
MDBX_DBG_ASSERT	Enable assertion checks. Note Always enabled for builds with MDBX_FORCE_ASSERTIONS option, otherwise requires build with MDBX_DEBUG > 0
MDBX_DBG_AUDIT	Enable pages usage audit at commit transactions. Note Requires build with MDBX_DEBUG > 0
MDBX_DBG_JITTER	Enable small random delays in critical points. Note Requires build with MDBX_DEBUG > 0
MDBX_DBG_DUMP	Include or not meta-pages in coredump files. Note May affect performance in MDBX_WRITEMAP mode
MDBX_DBG_LEGACY_MULTIOPEN	Allow multi-opening environment(s)
MDBX_DBG_LEGACY_OVERLAP	Allow read and write transactions overlapping for the same thread.
MDBX_DBG_DONT_UPGRADE	Don't auto-upgrade format signature. Note However a new write transactions will use and store the last signature regardless this flag
MDBX_DBG_DONTCHANGE	for mdbx_setup_debug() only: Don't change current settings

MDBX_log_level_t

enum MDBX_log_level_t

Log level

Note

Levels detailed than (great than) MDBX_LOG_NOTICE requires build libmdbx with MDBX_DEBUG option.

Enumerator
MDBX_LOG_FATAL	Critical conditions, i.e. assertion failures. Note libmdbx always produces such messages regardless of MDBX_DEBUG build option.
MDBX_LOG_ERROR	Enables logging for error conditions and MDBX_LOG_FATAL. Note libmdbx always produces such messages regardless of MDBX_DEBUG build option.
MDBX_LOG_WARN	Enables logging for warning conditions and MDBX_LOG_ERROR ... MDBX_LOG_FATAL. Note libmdbx always produces such messages regardless of MDBX_DEBUG build option.
MDBX_LOG_NOTICE	Enables logging for normal but significant condition and MDBX_LOG_WARN ... MDBX_LOG_FATAL. Note libmdbx always produces such messages regardless of MDBX_DEBUG build option.
MDBX_LOG_VERBOSE	Enables logging for verbose informational and MDBX_LOG_NOTICE ... MDBX_LOG_FATAL. Note Requires build libmdbx with MDBX_DEBUG option.
MDBX_LOG_DEBUG	Enables logging for debug-level messages and MDBX_LOG_VERBOSE ... MDBX_LOG_FATAL. Note Requires build libmdbx with MDBX_DEBUG option.
MDBX_LOG_TRACE	Enables logging for trace debug-level messages and MDBX_LOG_DEBUG ... MDBX_LOG_FATAL. Note Requires build libmdbx with MDBX_DEBUG option.
MDBX_LOG_EXTRA	Enables extra debug-level messages (dump pgno lists) and all other log-messages. Note Requires build libmdbx with MDBX_DEBUG option.
MDBX_LOG_DONTCHANGE	for mdbx_setup_debug() only: Don't change current settings

Function Documentation

mdbx_dump_val()

const LIBMDBX_API char* mdbx_dump_val	(	const MDBX_val *	key,
		char *const	buf,
		const size_t	bufsize
	)

Dump given MDBX_val to the buffer.

Dumps it as string if value is printable (all bytes in the range 0x20..0x7E), otherwise made hexadecimal dump. Requires at least 4 byte length buffer.

Returns

One of:

• NULL if given buffer size less than 4 bytes;
• pointer to constant string if given value NULL or empty;
• otherwise pointer to given buffer.

mdbx_env_set_assert()

LIBMDBX_API int mdbx_env_set_assert	(	MDBX_env *	env,
		MDBX_assert_func *	func
	)

Set or reset the assert() callback of the environment.

Does nothing if libmdbx was built with MDBX_DEBUG=0 or with NDEBUG, and will return MDBX_ENOSYS in such case.

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[in]	func	An MDBX_assert_func function, or 0.

Returns

A non-zero error value on failure and 0 on success.

mdbx_panic()

LIBMDBX_API void mdbx_panic	(	const char *	fmt,
			...
	)

Panics with message and causes abnormal process termination.

mdbx_setup_debug()

LIBMDBX_API int mdbx_setup_debug	(	MDBX_log_level_t	log_level,
		MDBX_debug_flags_t	debug_flags,
		MDBX_debug_func *	logger
	)

Setup global log-level, debug options and debug logger.

Returns

The previously debug_flags in the 0-15 bits and log_level in the 16-31 bits.