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()
#define	MDBX_LOGGER_NOFMT_DONTCHANGE   ((MDBX_debug_func_nofmt *)(intptr_t)-1)

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

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.
LIBMDBX_API int	mdbx_setup_debug_nofmt (MDBX_log_level_t log_level, MDBX_debug_flags_t debug_flags, MDBX_debug_func_nofmt *logger, char *logger_buffer, size_t logger_buffer_size)
LIBMDBX_API int	mdbx_env_set_assert (MDBX_env *env, MDBX_assert_func *func)
	Set or reset the assert() callback of the environment.
LIBMDBX_API const char *	mdbx_dump_val (const MDBX_val *key, char *const buf, const size_t bufsize)
	Dump given MDBX_val to the buffer.
MDBX_NORETURN LIBMDBX_API void	mdbx_panic (const char *fmt,...) MDBX_PRINTF_ARGS(1
	Panics with message and causes abnormal process termination.
MDBX_NORETURN LIBMDBX_API void MDBX_NORETURN LIBMDBX_API void	mdbx_assert_fail (const MDBX_env *env, const char *msg, const char *func, unsigned line)
	Panics with asserton failed message and causes abnormal process termination.

Detailed Description

Note

Most of debug feature enabled only when libmdbx built 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()

MDBX_LOGGER_NOFMT_DONTCHANGE

#define MDBX_LOGGER_NOFMT_DONTCHANGE   ((MDBX_debug_func_nofmt *)(intptr_t)-1)

Typedef Documentation

MDBX_assert_func

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

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.
[in]	msg	The assertion message, not including newline.
[in]	function	The function name where the assertion check failed, may be NULL.
[in]	line	The line number in the source file where the assertion check failed, may be zero.

MDBX_debug_func

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

noexcept

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

See also

mdbx_setup_debug()

Parameters

[in]	loglevel	The severity of message.
[in]	function	The function name which emits message, may be NULL.
[in]	line	The source code line number which emits message, may be zero.
[in]	fmt	The printf-like format string with message.
[in]	args	The variable argument list respectively for the format-message string passed by fmt argument. Maybe NULL or invalid if the format-message string don't contain %-specification of arguments.

MDBX_debug_func_nofmt

typedef void MDBX_debug_func_nofmt(MDBX_log_level_t loglevel, const char *function, int line, const char *msg, unsigned length) noexcept

noexcept

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 built 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_assert_fail()

MDBX_NORETURN LIBMDBX_API void MDBX_NORETURN LIBMDBX_API void mdbx_assert_fail	(	const MDBX_env *	env,
		const char *	msg,
		const char *	func,
		unsigned	line
	)

Panics with asserton failed message and causes abnormal process termination.

mdbx_dump_val()

LIBMDBX_API const 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()

MDBX_NORETURN 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.

mdbx_setup_debug_nofmt()

LIBMDBX_API int mdbx_setup_debug_nofmt	(	MDBX_log_level_t	log_level,
		MDBX_debug_flags_t	debug_flags,
		MDBX_debug_func_nofmt *	logger,
		char *	logger_buffer,
		size_t	logger_buffer_size
	)