libmdbx  0.11.9.0 (2022-08-02T12:00:30+03:00)
One of the fastest compact embeddable key-value ACID database without WAL.
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) 1
 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) 1
 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...
 
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. More...
 
LIBMDBX_API void mdbx_panic (const char *fmt,...) MDBX_PRINTF_ARGS(1
 Panics with message and causes abnormal process termination. More...
 
LIBMDBX_API void 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. 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) 1

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

See also
mdbx_env_set_assert()
Parameters
[in]envAn environment handle returned by mdbx_env_create().
[in]msgThe assertion message, not including newline.

◆ 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) 1

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

See also
mdbx_setup_debug()
Parameters
[in]envAn environment handle returned by mdbx_env_create().
[in]msgThe assertion message, not including newline.

◆ MDBX_log_level_t

Enumeration Type Documentation

◆ 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

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

LIBMDBX_API void 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]envAn environment handle returned by mdbx_env_create().
[in]funcAn 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.