RU

Group c_api

Modules > c_api

Modules

Type	Name
module	Create/Read/Update/Delete (see Quick Reference in details)
module	Cursors
module	Tables
module	Logging and runtime debug
module	Error handling
module	Extra operations
module	Opening & Closing
module	Range query estimation
module	Settings
module	Statistics & Information
module	Transactions
module	Checking and Recovery
module	Key-to-Value functions Key-to-Value functions to avoid using custom comparators .
module	Value-to-Key functions Value-to-Key functions to avoid using custom comparators .

Classes

Type	Name
struct	MDBX_build_info libmdbx build information
struct	MDBX_cache_entry_t Lightweight transparent cache entry structure used by mdbx_cache_get() .
struct	MDBX_cache_result_t Pair of error code and cache status as a result of mdbx_cache_get() .
struct	MDBX_canary The four integer markers (aka "canary") associated with the environment.
struct	MDBX_commit_latency Latency of commit stages in 1/65536 of seconds units.
struct	MDBX_commit_latency.gc_prof Information for GC profiling.
struct	MDBX_commit_latency.gc_prof.pnl_merge_self Metrics of the amount of work and cost of merging lists of pages.
struct	MDBX_commit_latency.gc_prof.pnl_merge_work Metrics of the amount of work and cost of merging lists of pages.
struct	MDBX_defrag_result_t The numerical metrics of progress and result of database defragmentation.
struct	MDBX_envinfo Information about the environment.
struct	MDBX_envinfo.mi_bootid A mostly unique ID that is regenerated on each boot.
struct	MDBX_envinfo.mi_bootid.current
struct	MDBX_envinfo.mi_bootid.meta
struct	MDBX_envinfo.mi_dxbid
struct	MDBX_envinfo.mi_geo
struct	MDBX_envinfo.mi_pgop_stat
struct	MDBX_gc_info_t Information about Garbage Collection and page usage.
struct	MDBX_gc_info_t.gc_reclaimable
struct	MDBX_stat Statistics for a table in the environment.
struct	MDBX_txn_info Information about the transaction.
struct	MDBX_version_info libmdbx version information,
struct	MDBX_version_info.git

Public Types

Type	Name
enum	MDBX_constants
typedef struct MDBX_env	MDBX_env Opaque structure for a database environment.
typedef struct iovec	MDBX_val Generic structure used for passing keys and data in and out of the table. .
typedef int	mdbx_filehandle_t
typedef mode_t	mdbx_mode_t
typedef pid_t	mdbx_pid_t
typedef pthread_t	mdbx_tid_t

Public Attributes

Type	Name
LIBMDBX_VERINFO_API const struct MDBX_build_info	mdbx_build libmdbx build information
LIBMDBX_VERINFO_API const struct MDBX_version_info	mdbx_version libmdbx version information

Public Functions

Type	Name
LIBMDBX_API MDBX_hsr_func	mdbx_env_get_hsr (const MDBX_env * env) Gets current Handle-Slow-Readers callback used to resolve database full/overflow issue due to a reader(s) which prevents the old data from being recycled.
LIBMDBX_API int	mdbx_env_openW (MDBX_env * env, const wchar_t * pathname, MDBX_env_flags_t flags, mdbx_mode_t mode) Open an environment instance.

Macros

Type	Name
define	LIBMDBX_API \_\_dll\_export
define	LIBMDBX_API_TYPE
define	LIBMDBX_VERINFO_API \_\_dll\_export
define	MDBX_AMALGAMATED_SOURCE 1
define	MDBX_DATANAME "/mdbx.dat" The name of the data file in the environment without using MDBX_NOSUBDIR .
define	MDBX_LOCKNAME "/mdbx.lck" The name of the lock file in the environment without using MDBX_NOSUBDIR .
define	MDBX_LOCK_SUFFIX "-lck" The suffix of the lock file when MDBX_NOSUBDIR is used.
define	MDBX_VERSION_MAJOR 0
define	MDBX_VERSION_MINOR 15
define	MDBX_VERSION_UNSTABLE
define	mdbx_env_copyT (env, dest, flags) [**mdbx\_env\_copyW**](group__c__extra.md#function-mdbx_env_copyw)(env, dest, flags)
define	mdbx_env_deleteA (pathname, mode) [**mdbx\_env\_delete**](group__c__extra.md#function-mdbx_env_delete)(pathname, mode)
define	mdbx_env_deleteT (pathname, mode) [**mdbx\_env\_deleteA**](group__c__api.md#define-mdbx_env_deletea)(pathname, mode)
define	mdbx_env_get_pathT (env, dest) [**mdbx\_env\_get\_pathW**](group__c__statinfo.md#function-mdbx_env_get_pathw)(env, dest)
define	mdbx_env_openT (env, pathname, flags, mode) [**mdbx\_env\_openW**](group__c__api.md#function-mdbx_env_openw)(env, pathname, flags, mode)
define	mdbx_txn_copy2pathnameT (txn, dest, flags) [**mdbx\_txn\_copy2pathnameW**](group__c__extra.md#function-mdbx_txn_copy2pathnamew)(txn, dest, path)

Public Types Documentation

enum MDBX_constants

enum MDBX_constants {
    MDBX_MAX_DBI = UINT32_C(32765),
    MDBX_MAXDATASIZE = UINT32_C(0x7fff0000),
    MDBX_MIN_PAGESIZE = 256,
    MDBX_MAX_PAGESIZE = 65536
};

---

typedef MDBX_env

Opaque structure for a database environment.

typedef struct MDBX_env MDBX_env;

An environment supports multiple key-value tables (aka key-value maps, spaces or sub-databases), all residing in the same shared-memory map.

See also: mdbx_env_create()

See also: mdbx_env_close()

---

typedef MDBX_val

Generic structure used for passing keys and data in and out of the table. .

typedef struct iovec MDBX_val;

See also: mdbx::slice

See also: mdbx::buffer Values returned from the table are valid only until a subsequent update operation, or the end of the transaction. Do not modify or free them, they commonly point into the database itself.

Key sizes must be between 0 and mdbx_env_get_maxkeysize() inclusive. The same applies to data sizes in tables with the MDBX_DUPSORT flag. Other data items can in theory be from 0 to MDBX_MAXDATASIZE bytes long.

Note:

The notable difference between MDBX and LMDB is that MDBX support zero length keys.

---

typedef mdbx_filehandle_t

typedef int mdbx_filehandle_t;

---

typedef mdbx_mode_t

typedef mode_t mdbx_mode_t;

---

typedef mdbx_pid_t

typedef pid_t mdbx_pid_t;

---

typedef mdbx_tid_t

typedef pthread_t mdbx_tid_t;

---

Public Attributes Documentation

variable mdbx_build

libmdbx build information

LIBMDBX_VERINFO_API const struct MDBX_build_info mdbx_build;

---

variable mdbx_version

libmdbx version information

LIBMDBX_VERINFO_API const struct MDBX_version_info mdbx_version;

---

Public Functions Documentation

function mdbx_env_get_hsr

Gets current Handle-Slow-Readers callback used to resolve database full/overflow issue due to a reader(s) which prevents the old data from being recycled.

LIBMDBX_API  MDBX_hsr_func mdbx_env_get_hsr (
    const MDBX_env * env
) 

See also: MDBX_hsr_func

See also: mdbx_env_set_hsr()

See also: mdbx_txn_park()

See also: Long-lived read transactions

Parameters:

• env An environment handle returned by mdbx_env_create().

Returns:

A MDBX_hsr_func function or NULL if disabled or something wrong.

---

function mdbx_env_openW

Open an environment instance.

LIBMDBX_API int mdbx_env_openW (
    MDBX_env * env,
    const wchar_t * pathname,
    MDBX_env_flags_t flags,
    mdbx_mode_t mode
) 

Indifferently this function will fails or not, the mdbx_env_close() must be called later to discard the MDBX_env handle and release associated resources.

Note:

On Windows the mdbx_env_openW() is recommended to use.

Parameters:

• env An environment handle returned by mdbx_env_create()
• pathname The pathname for the database or the directory in which the database files reside. In the case of directory it must already exist and be writable.
• flags Specifies options for this environment. This parameter must be bitwise OR'ing together any constants described above in the env_flags and SYNC MODES sections.

Flags set by mdbx_env_set_flags() are also used: * MDBX_ENV_DEFAULTS, MDBX_NOSUBDIR, MDBX_RDONLY, MDBX_EXCLUSIVE, MDBX_WRITEMAP, MDBX_NOSTICKYTHREADS, MDBX_NORDAHEAD, MDBX_NOMEMINIT, MDBX_LIFORECLAIM. See env_flags section. * MDBX_SYNC_DURABLE, MDBX_NOMETASYNC, MDBX_SAFE_NOSYNC, MDBX_UTTERLY_NOSYNC. See SYNC MODES section.

Note:

The MDB_NOTLS option in MDBX is superseded by MDBX_NOSTICKYTHREADS.

Note:

The MDB_NOSYNC mode in MDBX is splitted into MDBX_UTTERLY_NOSYNC and MDBX_SAFE_NOSYNC, while MDBX_UTTERLY_NOSYNC acts basically the same as MDB_NOSYNC.

Note:

The MDB_NOLOCK flag don't supported by MDBX, try use MDBX_EXCLUSIVE as a replacement.

Note:

MDBX don't allow to mix processes with different MDBX_SAFE_NOSYNC or MDBX_UTTERLY_NOSYNC flags on the same environment. In such case MDBX_INCOMPATIBLE will be returned. You can try to combine the MDBX_ACCEDE flag to opend a database/environment which is already used by another process(es) with unknown mode/flags.

If the database is already exist and parameters specified early by mdbx_env_set_geometry() are incompatible (i.e. for instance, different page size) then mdbx_env_open() will return MDBX_INCOMPATIBLE or MDBX_TOO_LARGE error.

Parameters:

• mode The UNIX permissions to set on created files. Zero value means to open existing, but do not create.

Returns:

A non-zero error value on failure and 0 on success, some possible errors are:

Return value:

• MDBX_VERSION_MISMATCH The version of the MDBX library doesn't match the version that created the database environment.
• MDBX_INVALID The environment file headers are corrupted.
• MDBX_ENOENT The directory specified by the path parameter doesn't exist.
• MDBX_EACCES The user didn't have permission to access the environment files.
• MDBX_BUSY The MDBX_EXCLUSIVE flag was specified and the environment is in use by another process, or the current process tries to open environment more than once.
• MDBX_INCOMPATIBLE Environment is already opened by another process, but with different set of MDBX_SAFE_NOSYNC, MDBX_UTTERLY_NOSYNC flags. Or if the database is already exist and parameters specified early by mdbx_env_set_geometry() are incompatible (i.e. different pagesize, etc).
• MDBX_WANNA_RECOVERY The MDBX_RDONLY flag was specified but read-write access is required to rollback inconsistent state after a system crash.
• MDBX_TOO_LARGE Database is too large for this process, i.e. 32-bit process tries to open >4Gb database.

Note:

Available only on Windows.

See also: mdbx_env_open()

---

Macro Definition Documentation

define LIBMDBX_API

#define LIBMDBX_API `__dll_export`

---

define LIBMDBX_API_TYPE

#define LIBMDBX_API_TYPE 

---

define LIBMDBX_VERINFO_API

#define LIBMDBX_VERINFO_API `__dll_export`

---

define MDBX_AMALGAMATED_SOURCE

#define MDBX_AMALGAMATED_SOURCE `1`

---

define MDBX_DATANAME

The name of the data file in the environment without using MDBX_NOSUBDIR .

#define MDBX_DATANAME `"/mdbx.dat"`

---

define MDBX_LOCKNAME

The name of the lock file in the environment without using MDBX_NOSUBDIR .

#define MDBX_LOCKNAME `"/mdbx.lck"`

---

define MDBX_LOCK_SUFFIX

The suffix of the lock file when MDBX_NOSUBDIR is used.

#define MDBX_LOCK_SUFFIX `"-lck"`

---

define MDBX_VERSION_MAJOR

#define MDBX_VERSION_MAJOR `0`

---

define MDBX_VERSION_MINOR

#define MDBX_VERSION_MINOR `15`

---

define MDBX_VERSION_UNSTABLE

#define MDBX_VERSION_UNSTABLE 

---

define mdbx_env_copyT

#define mdbx_env_copyT (
    env,
    dest,
    flags
) `mdbx_env_copyW (env, dest, flags)`

---

define mdbx_env_deleteA

#define mdbx_env_deleteA (
    pathname,
    mode
) `mdbx_env_delete (pathname, mode)`

---

define mdbx_env_deleteT

#define mdbx_env_deleteT (
    pathname,
    mode
) `mdbx_env_deleteA (pathname, mode)`

---

define mdbx_env_get_pathT

#define mdbx_env_get_pathT (
    env,
    dest
) `mdbx_env_get_pathW (env, dest)`

---

define mdbx_env_openT

#define mdbx_env_openT (
    env,
    pathname,
    flags,
    mode
) `mdbx_env_openW (env, pathname, flags, mode)`

---

define mdbx_txn_copy2pathnameT

#define mdbx_txn_copy2pathnameT (
    txn,
    dest,
    flags
) `mdbx_txn_copy2pathnameW (txn, dest, path)`

---

---