Group c_opening

Public Types

Type	Name
enum	MDBX_env_flags_t Environment flags .

Public Functions

Type	Name
int	mdbx_env_close (MDBX_env * env) The shortcut to calling mdbx_env_close_ex() with the`dont_sync=false` argument.
LIBMDBX_API int	mdbx_env_close_ex (MDBX_env * env, bool dont_sync) Close the environment and release the memory map.
LIBMDBX_API int	mdbx_env_create (MDBX_env ** penv) Create an MDBX environment instance.
LIBMDBX_API int	mdbx_env_open (MDBX_env * env, const char * pathname, MDBX_env_flags_t flags, mdbx_mode_t mode) Open an environment instance.
LIBMDBX_API int	mdbx_preopen_snapinfo (const char * pathname, MDBX_envinfo * info, size_t bytes) Gets basic information about the database without opening it.
LIBMDBX_API int	mdbx_preopen_snapinfoW (const wchar_t * pathname, MDBX_envinfo * info, size_t bytes) Gets basic information about the database without opening it.

Public Types Documentation

enum MDBX_env_flags_t

Environment flags .

enum MDBX_env_flags_t {
    MDBX_ENV_DEFAULTS = 0,
    MDBX_VALIDATION = UINT32_C(0x00002000),
    MDBX_NOSUBDIR = UINT32_C(0x4000),
    MDBX_RDONLY = UINT32_C(0x20000),
    MDBX_EXCLUSIVE = UINT32_C(0x400000),
    MDBX_ACCEDE = UINT32_C(0x40000000),
    MDBX_WRITEMAP = UINT32_C(0x80000),
    MDBX_NOSTICKYTHREADS = UINT32_C(0x200000),
    MDBX_NORDAHEAD = UINT32_C(0x800000),
    MDBX_NOMEMINIT = UINT32_C(0x1000000),
    MDBX_LIFORECLAIM = UINT32_C(0x4000000),
    MDBX_PAGEPERTURB = UINT32_C(0x8000000),
    MDBX_SYNC_DURABLE = 0,
    MDBX_NOMETASYNC = UINT32_C(0x40000),
    MDBX_SAFE_NOSYNC = UINT32_C(0x10000),
    MDBX_UTTERLY_NOSYNC = MDBX_SAFE_NOSYNC | UINT32_C(0x100000)
};

See also: mdbx_env_open()

See also: mdbx_env_set_flags()

Public Functions Documentation

function mdbx_env_close

The shortcut to calling mdbx_env_close_ex() with thedont_sync=false argument.

inline int mdbx_env_close (
    MDBX_env * env
)

function mdbx_env_close_ex

Close the environment and release the memory map.

LIBMDBX_API int mdbx_env_close_ex (
    MDBX_env * env,
    bool dont_sync
)

Only a single thread may call this function. All transactions, tables, and cursors must already be closed before calling this function. Attempts to use any such handles after calling this function is UB and would cause a SIGSEGV. The environment handle will be freed and must not be used again after this call.

Parameters:

env An environment handle returned by mdbx_env_create().
dont_sync A dont_sync flag, if non-zero the last checkpoint will be kept "as is" and may be still "weak" in the MDBX_SAFE_NOSYNC or MDBX_UTTERLY_NOSYNC modes. Such "weak" checkpoint will be ignored on opening next time, and transactions since the last non-weak checkpoint (meta-page update) will rolledback for consistency guarantee.

Returns:

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

Return value:

MDBX_BUSY The write transaction is running by other thread, in such case the MDBX_env instance has NOT been destroyed not released!

Note:

If any OTHER error code was returned then given MDBX_env instance has been destroyed and released.

Return value:

MDBX_EBADSIGN Environment handle already closed or not valid, i.e. mdbx_env_close() was already called for the env or was not created by mdbx_env_create().
MDBX_PANIC If mdbx_env_close_ex() was called in the child process after fork(). In this case MDBX_PANIC is expected, i.e. MDBX_env instance was freed in proper manner.
MDBX_EIO An error occurred during the flushing/writing data to a storage medium/disk.

function mdbx_env_create

Create an MDBX environment instance.

LIBMDBX_API int mdbx_env_create (
    MDBX_env ** penv
)

This function allocates memory for a MDBX_env structure. To release the allocated memory and discard the handle, call mdbx_env_close(). Before the handle may be used, it must be opened using mdbx_env_open().

Various other options may also need to be set before opening the handle, e.g. mdbx_env_set_geometry(), mdbx_env_set_maxreaders(), mdbx_env_set_maxdbs(), depending on usage requirements.

Parameters:

penv The address where the new handle will be stored.

Returns:

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

function mdbx_env_open

Open an environment instance.

LIBMDBX_API int mdbx_env_open (
    MDBX_env * env,
    const char * 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.

function mdbx_preopen_snapinfo

Gets basic information about the database without opening it.

LIBMDBX_API int mdbx_preopen_snapinfo (
    const char * pathname,
    MDBX_envinfo * info,
    size_t bytes
)

The purpose of the function is to obtain basic information without opening the database nor mapping data to memory, which can be quite a costly action for the OS kernel. The information obtained in this way can be useful for adjusting the options for working with the database before opening it, as well as in scripts, file managers and other auxiliary utilities.

Parameters:

pathname The path to the directory or database file.
info A pointer to the MDBX_envinfo structure to get information.
bytes The size of the MDBX_envinfo structure, which is used to ensure ABI compatibility.

Note:

Only some fields of the MDBX_envinfo structure will be provided/filled-in, the values of which can be obtained without mapping database files to memory and without acquiring locks: the size of the database page, the geometry of the database, the size of the allocated space (the number of the last distributed page), the number of the last transaction, and the boot-id stored in the corresponding meta-page.

Warning:

The information received is a snapshot for the moment of the function call and can be changed at any time by a process working with the database. In particular, there is no obstacle to another process deleting the database and recreating it with a different page size and/or changing any other parameters.

Returns:

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

function mdbx_preopen_snapinfoW

Gets basic information about the database without opening it.

LIBMDBX_API int mdbx_preopen_snapinfoW (
    const wchar_t * pathname,
    MDBX_envinfo * info,
    size_t bytes
)

The purpose of the function is to obtain basic information without opening the database nor mapping data to memory, which can be quite a costly action for the OS kernel. The information obtained in this way can be useful for adjusting the options for working with the database before opening it, as well as in scripts, file managers and other auxiliary utilities.

Parameters:

pathname The path to the directory or database file.
info A pointer to the MDBX_envinfo structure to get information.
bytes The size of the MDBX_envinfo structure, which is used to ensure ABI compatibility.

Note:

Only some fields of the MDBX_envinfo structure will be provided/filled-in, the values of which can be obtained without mapping database files to memory and without acquiring locks: the size of the database page, the geometry of the database, the size of the allocated space (the number of the last distributed page), the number of the last transaction, and the boot-id stored in the corresponding meta-page.

Warning:

The information received is a snapshot for the moment of the function call and can be changed at any time by a process working with the database. In particular, there is no obstacle to another process deleting the database and recreating it with a different page size and/or changing any other parameters.

Returns:

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

Note:

Available only on Windows.

See also: mdbx_preopen_snapinfo()