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_panic_func) (const char *msg, const char *function, unsigned line, const void *obj, const char *obj_class) noexcept
	A callback function for most assertion 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)
MDBX_NORETURN LIBMDBX_API void	mdbx_assert_fail (const char *msg, const char *func, unsigned line)
	Auxiliary function for MDBX_INLINE_API_ASSERT().
LIBMDBX_API void	mdbx_set_panic (MDBX_panic_func func)
	Sets or reset the callback for panic() and assert() for the current process.
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.

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_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

MDBX_panic_func

typedef void(* MDBX_panic_func) (const char *msg, const char *function, unsigned line, const void *obj, const char *obj_class) noexcept

noexcept

A callback function for most assertion failures, called before printing the message and aborting.

See also

mdbx_env_set_panic()

Parameters

[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.
[in]	obj	A handle of object associated with the assertion, it could be MDBX_env, MDBX_txn, MDBX_cursor or an internal page structure.
[in]	obj_class	A value corresponding to the object type: 'env', 'txn', 'cursor', etc.

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.

See also

mdbx_setup_debug()

MDBX_debug_flags_t

Enumerator
MDBX_DBG_NONE
MDBX_DBG_ASSERT	Enables costly check of debug-like assertions. Note Has effect only for debugging builds with the build option MDBX_CHECKING >= 2.
MDBX_DBG_AUDIT	Enables extra costly checks and deep verification of page lists, including page usage audit at commit transactions. Note Has effect only for debugging builds with the build option MDBX_CHECKING >= 3.
MDBX_DBG_JITTER	Enables small random delays in critical points. Note Requires build with MDBX_DEBUG > 0
MDBX_DBG_DUMP	Controls including of a database(s) 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	Disables automatic updating of the database format signature, i.e. upgrade database format on a media. Note Nonetheless 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.

See also

mdbx_setup_debug()

MDBX_log_level_t

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_assert_fail	(	const char *	msg,
		const char *	func,
		unsigned	line )

Auxiliary function for MDBX_INLINE_API_ASSERT().

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_set_panic()

LIBMDBX_API void mdbx_set_panic

(

MDBX_panic_func

func

)

Sets or reset the callback for panic() and assert() for the current process.

Parameters

[in]

func

An MDBX_assert_func function, or 0.

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.

See also

MDBX_log_level_t

MDBX_debug_flags_t

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 )