1 /**
2
3 _libmdbx_ is an extremely fast, compact, powerful, embedded,
4 transactional [key-value
5 store](https://en.wikipedia.org/wiki/Key-value_database) database, with
6 [permissive license](./LICENSE). _MDBX_ has a specific set of properties and
7 capabilities, focused on creating unique lightweight solutions with
8 extraordinary performance.
9
10 _libmdbx_ is superior to [LMDB](https://bit.ly/26ts7tL) in terms of features
11 and reliability, not inferior in performance. In comparison to LMDB, _libmdbx_
12 makes many things just work perfectly, not silently and catastrophically
13 break down. _libmdbx_ supports Linux, Windows, MacOS, OSX, iOS, Android,
14 FreeBSD, DragonFly, Solaris, OpenSolaris, OpenIndiana, NetBSD, OpenBSD and other
15 systems compliant with POSIX.1-2008.
16
17 _The Future will (be) [Positive](https://www.ptsecurity.com). Всё будет хорошо._
18
19
20 \section copyright LICENSE & COPYRIGHT
21
22 \authors Copyright (c) 2015-2021, Leonid Yuriev <leo@yuriev.ru>
23 and other _libmdbx_ authors: please see [AUTHORS](./AUTHORS) file.
24
25 \copyright Redistribution and use in source and binary forms, with or without
26 modification, are permitted only as authorized by the OpenLDAP Public License.
27
28 A copy of this license is available in the file LICENSE in the
29 top-level directory of the distribution or, alternatively, at
30 <http://www.OpenLDAP.org/license.html>.
31
32 ---
33
34 This code is derived from "LMDB engine" written by
35 Howard Chu (Symas Corporation), which itself derived from btree.c
36 written by Martin Hedenfalk.
37
38 ---
39
40 Portions Copyright 2011-2015 Howard Chu, Symas Corp. All rights reserved.
41
42 Redistribution and use in source and binary forms, with or without
43 modification, are permitted only as authorized by the OpenLDAP
44 Public License.
45
46 A copy of this license is available in the file LICENSE in the
47 top-level directory of the distribution or, alternatively, at
48 <http://www.OpenLDAP.org/license.html>.
49
50 ---
51
52 Portions Copyright (c) 2009, 2010 Martin Hedenfalk <martin@bzero.se>
53
54 Permission to use, copy, modify, and distribute this software for any
55 purpose with or without fee is hereby granted, provided that the above
56 copyright notice and this permission notice appear in all copies.
57
58 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
59 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
60 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
61 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
62 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
63 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
64 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
65
66 *******************************************************************************/
67
68 #pragma once
69 #ifndef LIBMDBX_H
70 #define LIBMDBX_H
71
72 #ifdef _MSC_VER
73 #pragma warning(push, 1)
74 #pragma warning(disable : 4548) /* expression before comma has no effect; \
75 expected expression with side - effect */
76 #pragma warning(disable : 4530) /* C++ exception handler used, but unwind \
77 * semantics are not enabled. Specify /EHsc */
78 #pragma warning(disable : 4577) /* 'noexcept' used with no exception handling \
79 * mode specified; termination on exception is \
80 * not guaranteed. Specify /EHsc */
81 #endif /* _MSC_VER (warnings) */
82
83 /* *INDENT-OFF* */
84 /* clang-format off */
85
86 /**
87 \file mdbx.h
88 \brief The libmdbx C API header file
89
90 \defgroup c_api C API
91 @{
92 \defgroup c_err Error handling
93 \defgroup c_opening Opening & Closing
94 \defgroup c_transactions Transactions
95 \defgroup c_dbi Databases
96 \defgroup c_crud Create/Read/Update/Delete (see Quick Reference in details)
97
98 \details
99 \anchor c_crud_hints
100 # Quick Reference for Insert/Update/Delete operations
101
102 Historically, libmdbx inherits the API basis from LMDB, where it is often
103 difficult to select flags/options and functions for the desired operation.
104 So it is recommend using this hints.
105
106 ## Databases with UNIQUE keys
107
108 In databases created without the \ref MDBX_DUPSORT option, keys are always
109 unique. Thus always a single value corresponds to the each key, and so there
110 are only a few cases of changing data.
111
112 | Case | Flags to use | Result |
113 |---------------------------------------------|---------------------|------------------------|
114 | _INSERTING_|||
115 |Key is absent → Insertion |\ref MDBX_NOOVERWRITE|Insertion |
116 |Key exist → Error since key present |\ref MDBX_NOOVERWRITE|Error \ref MDBX_KEYEXIST and return Present value|
117 | _UPSERTING_|||
118 |Key is absent → Insertion |\ref MDBX_UPSERT |Insertion |
119 |Key exist → Update |\ref MDBX_UPSERT |Update |
120 | _UPDATING_|||
121 |Key is absent → Error since no such key |\ref MDBX_CURRENT |Error \ref MDBX_NOTFOUND|
122 |Key exist → Update |\ref MDBX_CURRENT |Update value |
123 | _DELETING_|||
124 |Key is absent → Error since no such key |\ref mdbx_del() or \ref mdbx_replace()|Error \ref MDBX_NOTFOUND|
125 |Key exist → Delete by key |\ref mdbx_del() with the parameter `data = NULL`|Deletion|
126 |Key exist → Delete by key with with data matching check|\ref mdbx_del() with the parameter `data` filled with the value which should be match for deletion|Deletion or \ref MDBX_NOTFOUND if the value does not match|
127 |Delete at the current cursor position |\ref mdbx_cursor_del() with \ref MDBX_CURRENT flag|Deletion|
128 |Extract (read & delete) value by the key |\ref mdbx_replace() with zero flag and parameter `new_data = NULL`|Returning a deleted value|
129
130
131 ## Databases with NON-UNIQUE keys
132
133 In databases created with the \ref MDBX_DUPSORT (Sorted Duplicates) option, keys
134 may be non unique. Such non-unique keys in a key-value database may be treated
135 as a duplicates or as like a multiple values corresponds to keys.
136
137
138 | Case | Flags to use | Result |
139 |---------------------------------------------|---------------------|------------------------|
140 | _INSERTING_|||
141 |Key is absent → Insertion |\ref MDBX_NOOVERWRITE|Insertion|
142 |Key exist → Needn't to add new values |\ref MDBX_NOOVERWRITE|Error \ref MDBX_KEYEXIST with returning the first value from those already present|
143 | _UPSERTING_|||
144 |Key is absent → Insertion |\ref MDBX_UPSERT |Insertion|
145 |Key exist → Wanna to add new values |\ref MDBX_UPSERT |Add one more value to the key|
146 |Key exist → Replace all values with a new one|\ref MDBX_UPSERT + \ref MDBX_ALLDUPS|Overwrite by single new value|
147 | _UPDATING_|||
148 |Key is absent → Error since no such key |\ref MDBX_CURRENT |Error \ref MDBX_NOTFOUND|
149 |Key exist, Single value → Update |\ref MDBX_CURRENT |Update single value |
150 |Key exist, Multiple values → Replace all values with a new one|\ref MDBX_CURRENT + \ref MDBX_ALLDUPS|Overwrite by single new value|
151 |Key exist, Multiple values → Error since it is unclear which of the values should be updated|\ref mdbx_put() with \ref MDBX_CURRENT|Error \ref MDBX_EMULTIVAL|
152 |Key exist, Multiple values → Update particular entry of multi-value|\ref mdbx_replace() with \ref MDBX_CURRENT + \ref MDBX_NOOVERWRITE and the parameter `old_value` filled with the value that wanna to update|Update one multi-value entry|
153 |Key exist, Multiple values → Update the current entry of multi-value|\ref mdbx_cursor_put() with \ref MDBX_CURRENT|Update one multi-value entry|
154 | _DELETING_|||
155 |Key is absent → Error since no such key |\ref mdbx_del() or \ref mdbx_replace()|Error \ref MDBX_NOTFOUND|
156 |Key exist → Delete all values corresponds given key|\ref mdbx_del() with the parameter `data = NULL`|Deletion|
157 |Key exist → Delete particular value corresponds given key|\ref mdbx_del() with the parameter `data` filled with the value that wanna to delete, or \ref mdbx_replace() with \ref MDBX_CURRENT + \ref MDBX_NOOVERWRITE and the `old_value` parameter filled with the value that wanna to delete and `new_data = NULL`| Deletion or \ref MDBX_NOTFOUND if no such key-value pair|
158 |Delete one value at the current cursor position|\ref mdbx_cursor_del() with \ref MDBX_CURRENT flag|Deletion only the current entry|
159 |Delete all values of key at the current cursor position|\ref mdbx_cursor_del() with with \ref MDBX_ALLDUPS flag|Deletion all duplicates of key (all multi-values) at the current cursor position|
160
161 \defgroup c_cursors Cursors
162 \defgroup c_statinfo Statistics & Information
163 \defgroup c_settings Settings
164 \defgroup c_debug Logging and runtime debug
165 \defgroup c_rqest Range query estimation
166 \defgroup c_extra Extra operations
167 */
168
169 /* *INDENT-ON* */
170 /* clang-format on */
171
172 #include <stdarg.h>
173 #include <stddef.h>
174 #include <stdint.h>
175
176 #if defined(_WIN32) || defined(_WIN64)
177 #include <windows.h>
178 #include <winnt.h>
179 #ifndef __mode_t_defined
180 typedef unsigned short mdbx_mode_t;
181 #else
182 typedef mode_t mdbx_mode_t;
183 #endif /* __mode_t_defined */
184 typedef HANDLE mdbx_filehandle_t;
185 typedef DWORD mdbx_pid_t;
186 typedef DWORD mdbx_tid_t;
187 #else /* Windows */
188 #include <errno.h> /* for error codes */
189 #include <pthread.h> /* for pthread_t */
190 #include <sys/types.h> /* for pid_t */
191 #include <sys/uio.h> /* for struct iovec */
192 #define HAVE_STRUCT_IOVEC 1
193 typedef int mdbx_filehandle_t;
194 typedef pid_t mdbx_pid_t;
195 typedef pthread_t mdbx_tid_t;
196 typedef mode_t mdbx_mode_t;
197 #endif /* !Windows */
198
199 #ifdef _MSC_VER
200 #pragma warning(pop)
201 #endif
202
203 /** @} close c_api
204 * \defgroup api_macros Common Macros
205 * @{ */
206
207 /*----------------------------------------------------------------------------*/
208
209 #ifndef __has_attribute
210 #define __has_attribute(x) (0)
211 #endif /* __has_attribute */
212
213 #ifndef __has_cpp_attribute
214 #define __has_cpp_attribute(x) 0
215 #endif /* __has_cpp_attribute */
216
217 #ifndef __has_feature
218 #define __has_feature(x) (0)
219 #endif /* __has_feature */
220
221 #ifndef __has_extension
222 #define __has_extension(x) (0)
223 #endif /* __has_extension */
224
225 #ifndef __has_builtin
226 #define __has_builtin(x) (0)
227 #endif /* __has_builtin */
228
229 /** Many functions have no effects except the return value and their
230 * return value depends only on the parameters and/or global variables.
231 * Such a function can be subject to common subexpression elimination
232 * and loop optimization just as an arithmetic operator would be.
233 * These functions should be declared with the attribute pure. */
234 #if (defined(__GNUC__) || __has_attribute(__pure__)) && \
235 (!defined(__clang__) /* https://bugs.llvm.org/show_bug.cgi?id=43275 */ \
236 || !defined(__cplusplus) || !__has_feature(cxx_exceptions))
237 #define MDBX_PURE_FUNCTION __attribute__((__pure__))
238 #elif defined(_MSC_VER) && !defined(__clang__) && _MSC_VER >= 1920
239 #define MDBX_PURE_FUNCTION
240 #elif defined(__cplusplus) && __has_cpp_attribute(gnu::pure) && \
241 (!defined(__clang__) || !__has_feature(cxx_exceptions))
242 #define MDBX_PURE_FUNCTION [[gnu::pure]]
243 #else
244 #define MDBX_PURE_FUNCTION
245 #endif /* MDBX_PURE_FUNCTION */
246
247 /** Like \ref MDBX_PURE_FUNCTION with addition `noexcept` restriction
248 * that is compatible to CLANG and proposed [[pure]]. */
249 #if defined(__GNUC__) || \
250 (__has_attribute(__pure__) && __has_attribute(__nothrow__))
251 #define MDBX_NOTHROW_PURE_FUNCTION __attribute__((__pure__, __nothrow__))
252 #elif defined(_MSC_VER) && !defined(__clang__) && _MSC_VER >= 1920
253 #if __has_cpp_attribute(pure)
254 #define MDBX_NOTHROW_PURE_FUNCTION [[pure]]
255 #else
256 #define MDBX_NOTHROW_PURE_FUNCTION
257 #endif
258 #elif defined(__cplusplus) && __has_cpp_attribute(gnu::pure)
259 #if __has_cpp_attribute(gnu::nothrow)
260 #define MDBX_NOTHROW_PURE_FUNCTION [[gnu::pure, gnu::nothrow]]
261 #else
262 #define MDBX_NOTHROW_PURE_FUNCTION [[gnu::pure]]
263 #endif
264 #elif defined(__cplusplus) && __has_cpp_attribute(pure)
265 #define MDBX_NOTHROW_PURE_FUNCTION [[pure]]
266 #else
267 #define MDBX_NOTHROW_PURE_FUNCTION
268 #endif /* MDBX_NOTHROW_PURE_FUNCTION */
269
270 /** Many functions do not examine any values except their arguments,
271 * and have no effects except the return value. Basically this is just
272 * slightly more strict class than the PURE attribute, since function
273 * is not allowed to read global memory.
274 *
275 * Note that a function that has pointer arguments and examines the
276 * data pointed to must not be declared const. Likewise, a function
277 * that calls a non-const function usually must not be const.
278 * It does not make sense for a const function to return void. */
279 #if (defined(__GNUC__) || __has_attribute(__pure__)) && \
280 (!defined(__clang__) /* https://bugs.llvm.org/show_bug.cgi?id=43275 */ \
281 || !defined(__cplusplus) || !__has_feature(cxx_exceptions))
282 #define MDBX_CONST_FUNCTION __attribute__((__const__))
283 #elif defined(_MSC_VER) && !defined(__clang__) && _MSC_VER >= 1920
284 #define MDBX_CONST_FUNCTION MDBX_PURE_FUNCTION
285 #elif defined(__cplusplus) && __has_cpp_attribute(gnu::const) && \
286 (!defined(__clang__) || !__has_feature(cxx_exceptions))
287 #define MDBX_CONST_FUNCTION [[gnu::const]]
288 #else
289 #define MDBX_CONST_FUNCTION MDBX_PURE_FUNCTION
290 #endif /* MDBX_CONST_FUNCTION */
291
292 /** Like \ref MDBX_CONST_FUNCTION with addition `noexcept` restriction
293 * that is compatible to CLANG and future [[const]]. */
294 #if defined(__GNUC__) || \
295 (__has_attribute(__const__) && __has_attribute(__nothrow__))
296 #define MDBX_NOTHROW_CONST_FUNCTION __attribute__((__const__, __nothrow__))
297 #elif defined(_MSC_VER) && !defined(__clang__) && _MSC_VER >= 1920
298 #define MDBX_NOTHROW_CONST_FUNCTION MDBX_NOTHROW_PURE_FUNCTION
299 #elif defined(__cplusplus) && __has_cpp_attribute(gnu::const)
300 #if __has_cpp_attribute(gnu::nothrow)
301 #define MDBX_NOTHROW_PURE_FUNCTION [[gnu::const, gnu::nothrow]]
302 #else
303 #define MDBX_NOTHROW_PURE_FUNCTION [[gnu::const]]
304 #endif
305 #elif defined(__cplusplus) && __has_cpp_attribute(const)
306 #define MDBX_NOTHROW_CONST_FUNCTION [[const]]
307 #else
308 #define MDBX_NOTHROW_CONST_FUNCTION MDBX_NOTHROW_PURE_FUNCTION
309 #endif /* MDBX_NOTHROW_CONST_FUNCTION */
310
311 #ifndef MDBX_DEPRECATED /* may be predefined to avoid warnings "deprecated" */
312 #ifdef __deprecated
313 #define MDBX_DEPRECATED __deprecated
314 #elif defined(__GNUC__) || __has_attribute(__deprecated__)
315 #define MDBX_DEPRECATED __attribute__((__deprecated__))
316 #elif defined(_MSC_VER)
317 #define MDBX_DEPRECATED __declspec(deprecated)
318 #else
319 #define MDBX_DEPRECATED
320 #endif
321 #endif /* MDBX_DEPRECATED */
322
323 #ifndef __dll_export
324 #if defined(_WIN32) || defined(__CYGWIN__)
325 #if defined(__GNUC__) || __has_attribute(__dllexport__)
326 #define __dll_export __attribute__((__dllexport__))
327 #elif defined(_MSC_VER)
328 #define __dll_export __declspec(dllexport)
329 #else
330 #define __dll_export
331 #endif
332 #elif defined(__GNUC__) || __has_attribute(__visibility__)
333 #define __dll_export __attribute__((__visibility__("default")))
334 #else
335 #define __dll_export
336 #endif
337 #endif /* __dll_export */
338
339 #ifndef __dll_import
340 #if defined(_WIN32) || defined(__CYGWIN__)
341 #if defined(__GNUC__) || __has_attribute(__dllimport__)
342 #define __dll_import __attribute__((__dllimport__))
343 #elif defined(_MSC_VER)
344 #define __dll_import __declspec(dllimport)
345 #else
346 #define __dll_import
347 #endif
348 #else
349 #define __dll_import
350 #endif
351 #endif /* __dll_import */
352
353 /** \brief Auxiliary macro for robustly define the both inline version of API
354 * function and non-inline fallback dll-exported version for applications linked
355 * with old version of libmdbx, with a strictly ODR-common implementation. */
356 #if defined(LIBMDBX_INTERNALS) && !defined(LIBMDBX_NO_EXPORTS_LEGACY_API)
357 #define LIBMDBX_INLINE_API(TYPE, NAME, ARGS) \
358 /* proto of exported which uses common impl */ LIBMDBX_API TYPE NAME ARGS; \
359 /* definition of common impl */ static __inline TYPE __inline_##NAME ARGS
360 #else
361 #define LIBMDBX_INLINE_API(TYPE, NAME, ARGS) static __inline TYPE NAME ARGS
362 #endif /* LIBMDBX_INLINE_API */
363
364 /** \brief Converts a macro argument into a string constant. */
365 #ifndef MDBX_STRINGIFY
366 #define MDBX_STRINGIFY_HELPER(x) #x
367 #define MDBX_STRINGIFY(x) MDBX_STRINGIFY_HELPER(x)
368 #endif /* MDBX_STRINGIFY */
369
370 /*----------------------------------------------------------------------------*/
371
372 #ifndef __cplusplus
373 #ifndef bool
374 #define bool _Bool
375 #endif
376 #ifndef true
377 #define true (1)
378 #endif
379 #ifndef false
380 #define false (0)
381 #endif
382 #endif /* bool without __cplusplus */
383
384 #if !defined(DOXYGEN) && (!defined(__cpp_noexcept_function_type) || \
385 __cpp_noexcept_function_type < 201510L)
386 #define MDBX_CXX17_NOEXCEPT
387 #else
388 #define MDBX_CXX17_NOEXCEPT noexcept
389 #endif /* MDBX_CXX17_NOEXCEPT */
390
391 /* Workaround for old compilers without properly support for constexpr. */
392 #if !defined(__cplusplus)
393 #define MDBX_CXX01_CONSTEXPR __inline
394 #define MDBX_CXX01_CONSTEXPR_VAR const
395 #elif !defined(DOXYGEN) && \
396 ((__cplusplus < 201103L && defined(__cpp_constexpr) && \
397 __cpp_constexpr < 200704L) || \
398 (defined(__LCC__) && __LCC__ < 124) || \
399 (defined(__GNUC__) && (__GNUC__ * 100 + __GNUC_MINOR__ < 407) && \
400 !defined(__clang__) && !defined(__LCC__)) || \
401 (defined(_MSC_VER) && _MSC_VER < 1910) || \
402 (defined(__clang__) && __clang_major__ < 4))
403 #define MDBX_CXX01_CONSTEXPR inline
404 #define MDBX_CXX01_CONSTEXPR_VAR const
405 #else
406 #define MDBX_CXX01_CONSTEXPR constexpr
407 #define MDBX_CXX01_CONSTEXPR_VAR constexpr
408 #endif /* MDBX_CXX01_CONSTEXPR */
409
410 #if !defined(__cplusplus)
411 #define MDBX_CXX11_CONSTEXPR __inline
412 #define MDBX_CXX11_CONSTEXPR_VAR const
413 #elif !defined(DOXYGEN) && \
414 (!defined(__cpp_constexpr) || __cpp_constexpr < 201304L || \
415 (defined(__LCC__) && __LCC__ < 124) || \
416 (defined(__GNUC__) && __GNUC__ < 6 && !defined(__clang__) && \
417 !defined(__LCC__)) || \
418 (defined(_MSC_VER) && _MSC_VER < 1910) || \
419 (defined(__clang__) && __clang_major__ < 5))
420 #define MDBX_CXX11_CONSTEXPR inline
421 #define MDBX_CXX11_CONSTEXPR_VAR const
422 #else
423 #define MDBX_CXX11_CONSTEXPR constexpr
424 #define MDBX_CXX11_CONSTEXPR_VAR constexpr
425 #endif /* MDBX_CXX11_CONSTEXPR */
426
427 #if !defined(__cplusplus)
428 #define MDBX_CXX14_CONSTEXPR __inline
429 #define MDBX_CXX14_CONSTEXPR_VAR const
430 #elif defined(DOXYGEN) || \
431 defined(__cpp_constexpr) && __cpp_constexpr >= 201304L && \
432 ((defined(_MSC_VER) && _MSC_VER >= 1910) || \
433 (defined(__clang__) && __clang_major__ > 4) || \
434 (defined(__GNUC__) && __GNUC__ > 6) || \
435 (!defined(__GNUC__) && !defined(__clang__) && !defined(_MSC_VER)))
436 #define MDBX_CXX14_CONSTEXPR constexpr
437 #define MDBX_CXX14_CONSTEXPR_VAR constexpr
438 #else
439 #define MDBX_CXX14_CONSTEXPR inline
440 #define MDBX_CXX14_CONSTEXPR_VAR const
441 #endif /* MDBX_CXX14_CONSTEXPR */
442
443 #if defined(__noreturn)
444 #define MDBX_NORETURN __noreturn
445 #elif defined(_Noreturn)
446 #define MDBX_NORETURN _Noreturn
447 #elif defined(__GNUC__) || __has_attribute(__noreturn__)
448 #define MDBX_NORETURN __attribute__((__noreturn__))
449 #elif defined(_MSC_VER) && !defined(__clang__)
450 #define MDBX_NORETURN __declspec(noreturn)
451 #else
452 #define MDBX_NORETURN
453 #endif /* MDBX_NORETURN */
454
455 #ifndef MDBX_PRINTF_ARGS
456 #if defined(__GNUC__) || __has_attribute(__format__)
457 #define MDBX_PRINTF_ARGS(format_index, first_arg) \
458 __attribute__((__format__(__printf__, format_index, first_arg)))
459 #else
460 #define MDBX_PRINTF_ARGS(format_index, first_arg)
461 #endif
462 #endif /* MDBX_PRINTF_ARGS */
463
464 #if defined(DOXYGEN) || \
465 (defined(__cplusplus) && __cplusplus >= 201603 && \
466 __has_cpp_attribute(maybe_unused) && \
467 __has_cpp_attribute(maybe_unused) >= 201603) || \
468 (!defined(__cplusplus) && defined(__STDC_VERSION__) && \
469 __STDC_VERSION__ > 202005L)
470 #define MDBX_MAYBE_UNUSED [[maybe_unused]]
471 #elif defined(__GNUC__) || __has_attribute(__unused__)
472 #define MDBX_MAYBE_UNUSED __attribute__((__unused__))
473 #else
474 #define MDBX_MAYBE_UNUSED
475 #endif /* MDBX_MAYBE_UNUSED */
476
477 #if __has_attribute(no_sanitize)
478 #define MDBX_NOSANITIZE_ENUM __attribute((__no_sanitize__("enum")))
479 #else
480 #define MDBX_NOSANITIZE_ENUM
481 #endif /* MDBX_NOSANITIZE_ENUM */
482
483 /* Oh, below are some songs and dances since:
484 * - C++ requires explicit definition of the necessary operators.
485 * - the proper implementation of DEFINE_ENUM_FLAG_OPERATORS for C++ required
486 * the constexpr feature which is broken in most old compilers;
487 * - DEFINE_ENUM_FLAG_OPERATORS may be defined broken as in the Windows SDK. */
488 #ifndef DEFINE_ENUM_FLAG_OPERATORS
489
490 #ifdef __cplusplus
491 #if !defined(__cpp_constexpr) || __cpp_constexpr < 200704L || \
492 (defined(__LCC__) && __LCC__ < 124) || \
493 (defined(__GNUC__) && (__GNUC__ * 100 + __GNUC_MINOR__ < 407) && \
494 !defined(__clang__) && !defined(__LCC__)) || \
495 (defined(_MSC_VER) && _MSC_VER < 1910) || \
496 (defined(__clang__) && __clang_major__ < 4)
497 /* The constexpr feature is not available or (may be) broken */
498 #define CONSTEXPR_ENUM_FLAGS_OPERATIONS 0
499 #else
500 /* C always allows these operators for enums */
501 #define CONSTEXPR_ENUM_FLAGS_OPERATIONS 1
502 #endif /* __cpp_constexpr */
503
504 /// Define operator overloads to enable bit operations on enum values that are
505 /// used to define flags (based on Microsoft's DEFINE_ENUM_FLAG_OPERATORS).
506 #define DEFINE_ENUM_FLAG_OPERATORS(ENUM) \
507 extern "C++" { \
508 MDBX_NOSANITIZE_ENUM MDBX_CXX01_CONSTEXPR ENUM operator|(ENUM a, ENUM b) { \
509 return ENUM(unsigned(a) | unsigned(b)); \
510 } \
511 MDBX_NOSANITIZE_ENUM MDBX_CXX14_CONSTEXPR ENUM &operator|=(ENUM &a, \
512 ENUM b) { \
513 return a = a | b; \
514 } \
515 MDBX_NOSANITIZE_ENUM MDBX_CXX01_CONSTEXPR ENUM operator&(ENUM a, ENUM b) { \
516 return ENUM(unsigned(a) & unsigned(b)); \
517 } \
518 MDBX_NOSANITIZE_ENUM MDBX_CXX01_CONSTEXPR ENUM operator&(ENUM a, \
519 unsigned b) { \
520 return ENUM(unsigned(a) & b); \
521 } \
522 MDBX_NOSANITIZE_ENUM MDBX_CXX01_CONSTEXPR ENUM operator&(unsigned a, \
523 ENUM b) { \
524 return ENUM(a & unsigned(b)); \
525 } \
526 MDBX_NOSANITIZE_ENUM MDBX_CXX14_CONSTEXPR ENUM &operator&=(ENUM &a, \
527 ENUM b) { \
528 return a = a & b; \
529 } \
530 MDBX_NOSANITIZE_ENUM MDBX_CXX14_CONSTEXPR ENUM &operator&=(ENUM &a, \
531 unsigned b) { \
532 return a = a & b; \
533 } \
534 MDBX_CXX01_CONSTEXPR unsigned operator~(ENUM a) { return ~unsigned(a); } \
535 MDBX_NOSANITIZE_ENUM MDBX_CXX01_CONSTEXPR ENUM operator^(ENUM a, ENUM b) { \
536 return ENUM(unsigned(a) ^ unsigned(b)); \
537 } \
538 MDBX_NOSANITIZE_ENUM MDBX_CXX14_CONSTEXPR ENUM &operator^=(ENUM &a, \
539 ENUM b) { \
540 return a = a ^ b; \
541 } \
542 }
543 #else /* __cplusplus */
544 /* nope for C since it always allows these operators for enums */
545 #define DEFINE_ENUM_FLAG_OPERATORS(ENUM)
546 #define CONSTEXPR_ENUM_FLAGS_OPERATIONS 1
547 #endif /* !__cplusplus */
548
549 #elif !defined(CONSTEXPR_ENUM_FLAGS_OPERATIONS)
550
551 #ifdef __cplusplus
552 /* DEFINE_ENUM_FLAG_OPERATORS may be defined broken as in the Windows SDK */
553 #define CONSTEXPR_ENUM_FLAGS_OPERATIONS 0
554 #else
555 /* C always allows these operators for enums */
556 #define CONSTEXPR_ENUM_FLAGS_OPERATIONS 1
557 #endif
558
559 #endif /* DEFINE_ENUM_FLAG_OPERATORS */
560
561 /** @} end of Common Macros */
562
563 /*----------------------------------------------------------------------------*/
564
565 /** \addtogroup c_api
566 * @{ */
567
568 #ifdef __cplusplus
569 extern "C" {
570 #endif
571
572 /* MDBX version 0.11.x */
573 #define MDBX_VERSION_MAJOR 0
574 #define MDBX_VERSION_MINOR 11
575
576 #ifndef LIBMDBX_API
577 #if defined(LIBMDBX_EXPORTS)
578 #define LIBMDBX_API __dll_export
579 #elif defined(LIBMDBX_IMPORTS)
580 #define LIBMDBX_API __dll_import
581 #else
582 #define LIBMDBX_API
583 #endif
584 #endif /* LIBMDBX_API */
585
586 #ifdef __cplusplus
587 #if defined(__clang__) || __has_attribute(type_visibility)
588 #define LIBMDBX_API_TYPE LIBMDBX_API __attribute__((type_visibility("default")))
589 #else
590 #define LIBMDBX_API_TYPE LIBMDBX_API
591 #endif
592 #else
593 #define LIBMDBX_API_TYPE
594 #endif /* LIBMDBX_API_TYPE */
595
596 #if defined(LIBMDBX_IMPORTS)
597 #define LIBMDBX_VERINFO_API __dll_import
598 #else
599 #define LIBMDBX_VERINFO_API __dll_export
600 #endif /* LIBMDBX_VERINFO_API */
601
602 /** \brief libmdbx version information */
603 extern LIBMDBX_VERINFO_API const struct MDBX_version_info {
604 uint8_t major; /**< Major version number */
605 uint8_t minor; /**< Minor version number */
606 uint16_t release; /**< Release number of Major.Minor */
607 uint32_t revision; /**< Revision number of Release */
608 struct {
609 const char *datetime; /**< committer date, strict ISO-8601 format */
610 const char *tree; /**< commit hash (hexadecimal digits) */
611 const char *commit; /**< tree hash, i.e. digest of the source code */
612 const char *describe; /**< git-describe string */
613 } git; /**< source information from git */
614 const char *sourcery; /**< sourcery anchor for pinning */
615 } /** \brief libmdbx version information */ mdbx_version;
616
617 /** \brief libmdbx build information
618 * \attention Some strings could be NULL in case no corresponding information
619 * was provided at build time (i.e. flags). */
620 extern LIBMDBX_VERINFO_API const struct MDBX_build_info {
621 const char *datetime; /**< build timestamp (ISO-8601 or __DATE__ __TIME__) */
622 const char *target; /**< cpu/arch-system-config triplet */
623 const char *options; /**< mdbx-related options */
624 const char *compiler; /**< compiler */
625 const char *flags; /**< CFLAGS and CXXFLAGS */
626 } /** \brief libmdbx build information */ mdbx_build;
627
628 #if (defined(_WIN32) || defined(_WIN64)) && !MDBX_BUILD_SHARED_LIBRARY
629 /* MDBX internally uses global and thread local storage destructors to
630 * automatically (de)initialization, releasing reader lock table slots
631 * and so on.
632 *
633 * If MDBX builded as a DLL this is done out-of-the-box by DllEntry() function,
634 * which called automatically by Windows core with passing corresponding reason
635 * argument.
636 *
637 * Otherwise, if MDBX was builded not as a DLL, some black magic
638 * may be required depending of Windows version:
639 *
640 * - Modern Windows versions, including Windows Vista and later, provides
641 * support for "TLS Directory" (e.g .CRT$XL[A-Z] sections in executable
642 * or dll file). In this case, MDBX capable of doing all automatically,
643 * therefore you DON'T NEED to call mdbx_module_handler()
644 * so the MDBX_MANUAL_MODULE_HANDLER defined as 0.
645 *
646 * - Obsolete versions of Windows, prior to Windows Vista, REQUIRES calling
647 * mdbx_module_handler() manually from corresponding DllMain() or WinMain()
648 * of your DLL or application,
649 * so the MDBX_MANUAL_MODULE_HANDLER defined as 1.
650 *
651 * Therefore, building MDBX as a DLL is recommended for all version of Windows.
652 * So, if you doubt, just build MDBX as the separate DLL and don't care about
653 * the MDBX_MANUAL_MODULE_HANDLER. */
654
655 #ifndef _WIN32_WINNT
656 #error Non-dll build libmdbx requires target Windows version \
657 to be explicitly defined via _WIN32_WINNT for properly \
658 handling thread local storage destructors.
659 #endif /* _WIN32_WINNT */
660
661 #if _WIN32_WINNT >= 0x0600 /* Windows Vista */
662 /* As described above mdbx_module_handler() is NOT needed for Windows Vista
663 * and later. */
664 #define MDBX_MANUAL_MODULE_HANDLER 0
665 #else
666 /* As described above mdbx_module_handler() IS REQUIRED for Windows versions
667 * prior to Windows Vista. */
668 #define MDBX_MANUAL_MODULE_HANDLER 1
669 void LIBMDBX_API NTAPI mdbx_module_handler(PVOID module, DWORD reason,
670 PVOID reserved);
671 #endif
672
673 #endif /* Windows && !DLL && MDBX_MANUAL_MODULE_HANDLER */
674
675 /* OPACITY STRUCTURES *********************************************************/
676
677 /** \brief Opaque structure for a database environment.
678 * \details An environment supports multiple key-value sub-databases (aka
679 * key-value spaces or tables), all residing in the same shared-memory map.
680 * \see mdbx_env_create() \see mdbx_env_close() */
681 #ifndef __cplusplus
682 typedef struct MDBX_env MDBX_env;
683 #else
684 struct MDBX_env;
685 #endif
686
687 /** \brief Opaque structure for a transaction handle.
688 * \ingroup c_transactions
689 * \details All database operations require a transaction handle. Transactions
690 * may be read-only or read-write.
691 * \see mdbx_txn_begin() \see mdbx_txn_commit() \see mdbx_txn_abort() */
692 #ifndef __cplusplus
693 typedef struct MDBX_txn MDBX_txn;
694 #else
695 struct MDBX_txn;
696 #endif
697
698 /** \brief A handle for an individual database (key-value spaces) in the
699 * environment. \ingroup c_dbi \details Zero handle is used internally (hidden
700 * Garbage Collection DB). So, any valid DBI-handle great than 0 and less than
701 * or equal \ref MDBX_MAX_DBI. \see mdbx_dbi_open() \see mdbx_dbi_close() */
702 typedef uint32_t MDBX_dbi;
703
704 /** \brief Opaque structure for navigating through a database
705 * \ingroup c_cursors
706 * \see mdbx_cursor_create() \see mdbx_cursor_bind() \see mdbx_cursor_close()
707 */
708 #ifndef __cplusplus
709 typedef struct MDBX_cursor MDBX_cursor;
710 #else
711 struct MDBX_cursor;
712 #endif
713
714 /** \brief Generic structure used for passing keys and data in and out of the
715 * database.
716 * \anchor MDBX_val \see mdbx::slice \see mdbx::buffer
717 *
718 * \details Values returned from the database are valid only until a subsequent
719 * update operation, or the end of the transaction. Do not modify or
720 * free them, they commonly point into the database itself.
721 *
722 * Key sizes must be between 0 and \ref mdbx_env_get_maxkeysize() inclusive.
723 * The same applies to data sizes in databases with the \ref MDBX_DUPSORT flag.
724 * Other data items can in theory be from 0 to \ref MDBX_MAXDATASIZE bytes long.
725 *
726 * \note The notable difference between MDBX and LMDB is that MDBX support zero
727 * length keys. */
728 #ifndef HAVE_STRUCT_IOVEC
729 struct iovec {
730 void *iov_base; /**< pointer to some data */
731 size_t iov_len; /**< the length of data in bytes */
732 };
733 #define HAVE_STRUCT_IOVEC
734 #endif /* HAVE_STRUCT_IOVEC */
735
736 #if defined(__sun) || defined(__SVR4) || defined(__svr4__)
737 /* The `iov_len` is signed on Sun/Solaris.
738 * So define custom MDBX_val to avoid a lot of warnings. */
739 struct MDBX_val {
740 void *iov_base; /**< pointer to some data */
741 size_t iov_len; /**< the length of data in bytes */
742 };
743 #ifndef __cplusplus
744 typedef struct MDBX_val MDBX_val;
745 #endif
746 #else /* SunOS */
747 typedef struct iovec MDBX_val;
748 #endif /* ! SunOS */
749
750 enum MDBX_constants {
751 /** The hard limit for DBI handles */
752 MDBX_MAX_DBI = UINT32_C(32765),
753
754 /** The maximum size of a data item. */
755 MDBX_MAXDATASIZE = UINT32_C(0x7fff0000),
756
757 /** The minimal database page size in bytes. */
758 MDBX_MIN_PAGESIZE = 256,
759
760 /** The maximal database page size in bytes. */
761 MDBX_MAX_PAGESIZE = 65536,
762 };
763
764 /* THE FILES *******************************************************************
765 * At the file system level, the environment corresponds to a pair of files. */
766
767 /** \brief The name of the lock file in the environment */
768 #define MDBX_LOCKNAME "/mdbx.lck"
769 /** \brief The name of the data file in the environment */
770 #define MDBX_DATANAME "/mdbx.dat"
771
772 /** \brief The suffix of the lock file when \ref MDBX_NOSUBDIR is used */
773 #define MDBX_LOCK_SUFFIX "-lck"
774
775 /* DEBUG & LOGGING ************************************************************/
776
777 /** \addtogroup c_debug
778 * \note Most of debug feature enabled only when libmdbx builded with
779 * \ref MDBX_DEBUG build option. @{ */
780
781 /** Log level (requires build libmdbx with \ref MDBX_DEBUG option) */
782 enum MDBX_log_level_t {
783 /** Critical conditions, i.e. assertion failures */
784 MDBX_LOG_FATAL = 0,
785
786 /** Enables logging for error conditions and \ref MDBX_LOG_FATAL */
787 MDBX_LOG_ERROR = 1,
788
789 /** Enables logging for warning conditions and \ref MDBX_LOG_ERROR ...
790 \ref MDBX_LOG_FATAL */
791 MDBX_LOG_WARN = 2,
792
793 /** Enables logging for normal but significant condition and
794 \ref MDBX_LOG_WARN ... \ref MDBX_LOG_FATAL */
795 MDBX_LOG_NOTICE = 3,
796
797 /** Enables logging for verbose informational and \ref MDBX_LOG_NOTICE ...
798 \ref MDBX_LOG_FATAL */
799 MDBX_LOG_VERBOSE = 4,
800
801 /** Enables logging for debug-level messages and \ref MDBX_LOG_VERBOSE ...
802 \ref MDBX_LOG_FATAL */
803 MDBX_LOG_DEBUG = 5,
804
805 /** Enables logging for trace debug-level messages and \ref MDBX_LOG_DEBUG ...
806 \ref MDBX_LOG_FATAL */
807 MDBX_LOG_TRACE = 6,
808
809 /** Enables extra debug-level messages (dump pgno lists)
810 and all other log-messages */
811 MDBX_LOG_EXTRA = 7,
812
813 #ifdef ENABLE_UBSAN
814 MDBX_LOG_MAX = 7 /* avoid UBSAN false-positive trap by a tests */,
815 #endif /* ENABLE_UBSAN */
816
817 /** for \ref mdbx_setup_debug() only: Don't change current settings */
818 MDBX_LOG_DONTCHANGE = -1
819 };
820 #ifndef __cplusplus
821 typedef enum MDBX_log_level_t MDBX_log_level_t;
822 #endif
823
824 /** \brief Runtime debug flags
825 *
826 * \details `MDBX_DBG_DUMP` and `MDBX_DBG_LEGACY_MULTIOPEN` always have an
827 * effect, but `MDBX_DBG_ASSERT`, `MDBX_DBG_AUDIT` and `MDBX_DBG_JITTER` only if
828 * libmdbx builded with \ref MDBX_DEBUG. */
829 enum MDBX_debug_flags_t {
830 MDBX_DBG_NONE = 0,
831
832 /** Enable assertion checks.
833 * Requires build with \ref MDBX_DEBUG > 0 */
834 MDBX_DBG_ASSERT = 1,
835
836 /** Enable pages usage audit at commit transactions.
837 * Requires build with \ref MDBX_DEBUG > 0 */
838 MDBX_DBG_AUDIT = 2,
839
840 /** Enable small random delays in critical points.
841 * Requires build with \ref MDBX_DEBUG > 0 */
842 MDBX_DBG_JITTER = 4,
843
844 /** Include or not meta-pages in coredump files.
845 * May affect performance in \ref MDBX_WRITEMAP mode */
846 MDBX_DBG_DUMP = 8,
847
848 /** Allow multi-opening environment(s) */
849 MDBX_DBG_LEGACY_MULTIOPEN = 16,
850
851 /** Allow read and write transactions overlapping for the same thread */
852 MDBX_DBG_LEGACY_OVERLAP = 32,
853
854 #ifdef ENABLE_UBSAN
855 MDBX_DBG_MAX = ((unsigned)MDBX_LOG_MAX) << 16 |
856 63 /* avoid UBSAN false-positive trap by a tests */,
857 #endif /* ENABLE_UBSAN */
858
859 /** for mdbx_setup_debug() only: Don't change current settings */
860 MDBX_DBG_DONTCHANGE = -1
861 };
862 #ifndef __cplusplus
863 typedef enum MDBX_debug_flags_t MDBX_debug_flags_t;
864 #else
865 DEFINE_ENUM_FLAG_OPERATORS(MDBX_debug_flags_t)
866 #endif
867
868 /** \brief A debug-logger callback function,
869 * called before printing the message and aborting.
870 * \see mdbx_setup_debug()
871 *
872 * \param [in] env An environment handle returned by \ref mdbx_env_create().
873 * \param [in] msg The assertion message, not including newline. */
874 typedef void MDBX_debug_func(MDBX_log_level_t loglevel, const char *function,
875 int line, const char *fmt,
876 va_list args) MDBX_CXX17_NOEXCEPT;
877
878 /** \brief The "don't change `logger`" value for mdbx_setup_debug() */
879 #define MDBX_LOGGER_DONTCHANGE ((MDBX_debug_func *)(intptr_t)-1)
880
881 /** \brief Setup global log-level, debug options and debug logger.
882 * \returns The previously `debug_flags` in the 0-15 bits
883 * and `log_level` in the 16-31 bits. */
884 LIBMDBX_API int mdbx_setup_debug(MDBX_log_level_t log_level,
885 MDBX_debug_flags_t debug_flags,
886 MDBX_debug_func *logger);
887
888 /** \brief A callback function for most MDBX assert() failures,
889 * called before printing the message and aborting.
890 * \see mdbx_env_set_assert()
891 *
892 * \param [in] env An environment handle returned by mdbx_env_create().
893 * \param [in] msg The assertion message, not including newline. */
894 typedef void MDBX_assert_func(const MDBX_env *env, const char *msg,
895 const char *function,
896 unsigned line) MDBX_CXX17_NOEXCEPT;
897
898 /** \brief Set or reset the assert() callback of the environment.
899 *
900 * Does nothing if libmdbx was built with MDBX_DEBUG=0 or with NDEBUG,
901 * and will return `MDBX_ENOSYS` in such case.
902 *
903 * \param [in] env An environment handle returned by mdbx_env_create().
904 * \param [in] func An MDBX_assert_func function, or 0.
905 *
906 * \returns A non-zero error value on failure and 0 on success. */
907 LIBMDBX_API int mdbx_env_set_assert(MDBX_env *env, MDBX_assert_func *func);
908
909 /** \brief Dump given MDBX_val to the buffer
910 *
911 * Dumps it as string if value is printable (all bytes in the range 0x20..0x7E),
912 * otherwise made hexadecimal dump. Requires at least 4 byte length buffer.
913 *
914 * \returns One of:
915 * - NULL if given buffer size less than 4 bytes;
916 * - pointer to constant string if given value NULL or empty;
917 * - otherwise pointer to given buffer. */
918 LIBMDBX_API const char *mdbx_dump_val(const MDBX_val *key, char *const buf,
919 const size_t bufsize);
920
921 /** \brief Panics with message and causes abnormal process termination. */
922 LIBMDBX_API void mdbx_panic(const char *fmt, ...) MDBX_PRINTF_ARGS(1, 2);
923
924 /** @} end of logging & debug */
925
926 /** \brief Environment flags
927 * \ingroup c_opening
928 * \anchor env_flags
929 * \see mdbx_env_open() \see mdbx_env_set_flags() */
930 enum MDBX_env_flags_t {
931 MDBX_ENV_DEFAULTS = 0,
932
933 /** No environment directory.
934 *
935 * By default, MDBX creates its environment in a directory whose pathname is
936 * given in path, and creates its data and lock files under that directory.
937 * With this option, path is used as-is for the database main data file.
938 * The database lock file is the path with "-lck" appended.
939 *
940 * - with `MDBX_NOSUBDIR` = in a filesystem we have the pair of MDBX-files
941 * which names derived from given pathname by appending predefined suffixes.
942 *
943 * - without `MDBX_NOSUBDIR` = in a filesystem we have the MDBX-directory with
944 * given pathname, within that a pair of MDBX-files with predefined names.
945 *
946 * This flag affects only at new environment creating by \ref mdbx_env_open(),
947 * otherwise at opening an existing environment libmdbx will choice this
948 * automatically. */
949 MDBX_NOSUBDIR = UINT32_C(0x4000),
950
951 /** Read only mode.
952 *
953 * Open the environment in read-only mode. No write operations will be
954 * allowed. MDBX will still modify the lock file - except on read-only
955 * filesystems, where MDBX does not use locks.
956 *
957 * - with `MDBX_RDONLY` = open environment in read-only mode.
958 * MDBX supports pure read-only mode (i.e. without opening LCK-file) only
959 * when environment directory and/or both files are not writable (and the
960 * LCK-file may be missing). In such case allowing file(s) to be placed
961 * on a network read-only share.
962 *
963 * - without `MDBX_RDONLY` = open environment in read-write mode.
964 *
965 * This flag affects only at environment opening but can't be changed after.
966 */
967 MDBX_RDONLY = UINT32_C(0x20000),
968
969 /** Open environment in exclusive/monopolistic mode.
970 *
971 * `MDBX_EXCLUSIVE` flag can be used as a replacement for `MDB_NOLOCK`,
972 * which don't supported by MDBX.
973 * In this way, you can get the minimal overhead, but with the correct
974 * multi-process and multi-thread locking.
975 *
976 * - with `MDBX_EXCLUSIVE` = open environment in exclusive/monopolistic mode
977 * or return \ref MDBX_BUSY if environment already used by other process.
978 * The main feature of the exclusive mode is the ability to open the
979 * environment placed on a network share.
980 *
981 * - without `MDBX_EXCLUSIVE` = open environment in cooperative mode,
982 * i.e. for multi-process access/interaction/cooperation.
983 * The main requirements of the cooperative mode are:
984 *
985 * 1. data files MUST be placed in the LOCAL file system,
986 * but NOT on a network share.
987 * 2. environment MUST be opened only by LOCAL processes,
988 * but NOT over a network.
989 * 3. OS kernel (i.e. file system and memory mapping implementation) and
990 * all processes that open the given environment MUST be running
991 * in the physically single RAM with cache-coherency. The only
992 * exception for cache-consistency requirement is Linux on MIPS
993 * architecture, but this case has not been tested for a long time).
994 *
995 * This flag affects only at environment opening but can't be changed after.
996 */
997 MDBX_EXCLUSIVE = UINT32_C(0x400000),
998
999 /** Using database/environment which already opened by another process(es).
1000 *
1001 * The `MDBX_ACCEDE` flag is useful to avoid \ref MDBX_INCOMPATIBLE error
1002 * while opening the database/environment which is already used by another
1003 * process(es) with unknown mode/flags. In such cases, if there is a
1004 * difference in the specified flags (\ref MDBX_NOMETASYNC,
1005 * \ref MDBX_SAFE_NOSYNC, \ref MDBX_UTTERLY_NOSYNC, \ref MDBX_LIFORECLAIM,
1006 * \ref MDBX_COALESCE and \ref MDBX_NORDAHEAD), instead of returning an error,
1007 * the database will be opened in a compatibility with the already used mode.
1008 *
1009 * `MDBX_ACCEDE` has no effect if the current process is the only one either
1010 * opening the DB in read-only mode or other process(es) uses the DB in
1011 * read-only mode. */
1012 MDBX_ACCEDE = UINT32_C(0x40000000),
1013
1014 /** Map data into memory with write permission.
1015 *
1016 * Use a writeable memory map unless \ref MDBX_RDONLY is set. This uses fewer
1017 * mallocs and requires much less work for tracking database pages, but
1018 * loses protection from application bugs like wild pointer writes and other
1019 * bad updates into the database. This may be slightly faster for DBs that
1020 * fit entirely in RAM, but is slower for DBs larger than RAM. Also adds the
1021 * possibility for stray application writes thru pointers to silently
1022 * corrupt the database.
1023 *
1024 * - with `MDBX_WRITEMAP` = all data will be mapped into memory in the
1025 * read-write mode. This offers a significant performance benefit, since the
1026 * data will be modified directly in mapped memory and then flushed to disk
1027 * by single system call, without any memory management nor copying.
1028 *
1029 * - without `MDBX_WRITEMAP` = data will be mapped into memory in the
1030 * read-only mode. This requires stocking all modified database pages in
1031 * memory and then writing them to disk through file operations.
1032 *
1033 * \warning On the other hand, `MDBX_WRITEMAP` adds the possibility for stray
1034 * application writes thru pointers to silently corrupt the database.
1035 *
1036 * \note The `MDBX_WRITEMAP` mode is incompatible with nested transactions,
1037 * since this is unreasonable. I.e. nested transactions requires mallocation
1038 * of database pages and more work for tracking ones, which neuters a
1039 * performance boost caused by the `MDBX_WRITEMAP` mode.
1040 *
1041 * This flag affects only at environment opening but can't be changed after.
1042 */
1043 MDBX_WRITEMAP = UINT32_C(0x80000),
1044
1045 /** Tie reader locktable slots to read-only transactions
1046 * instead of to threads.
1047 *
1048 * Don't use Thread-Local Storage, instead tie reader locktable slots to
1049 * \ref MDBX_txn objects instead of to threads. So, \ref mdbx_txn_reset()
1050 * keeps the slot reserved for the \ref MDBX_txn object. A thread may use
1051 * parallel read-only transactions. And a read-only transaction may span
1052 * threads if you synchronizes its use.
1053 *
1054 * Applications that multiplex many user threads over individual OS threads
1055 * need this option. Such an application must also serialize the write
1056 * transactions in an OS thread, since MDBX's write locking is unaware of
1057 * the user threads.
1058 *
1059 * \note Regardless to `MDBX_NOTLS` flag a write transaction entirely should
1060 * always be used in one thread from start to finish. MDBX checks this in a
1061 * reasonable manner and return the \ref MDBX_THREAD_MISMATCH error in rules
1062 * violation.
1063 *
1064 * This flag affects only at environment opening but can't be changed after.
1065 */
1066 MDBX_NOTLS = UINT32_C(0x200000),
1067
1068 /** Don't do readahead.
1069 *
1070 * Turn off readahead. Most operating systems perform readahead on read
1071 * requests by default. This option turns it off if the OS supports it.
1072 * Turning it off may help random read performance when the DB is larger
1073 * than RAM and system RAM is full.
1074 *
1075 * By default libmdbx dynamically enables/disables readahead depending on
1076 * the actual database size and currently available memory. On the other
1077 * hand, such automation has some limitation, i.e. could be performed only
1078 * when DB size changing but can't tracks and reacts changing a free RAM
1079 * availability, since it changes independently and asynchronously.
1080 *
1081 * \note The mdbx_is_readahead_reasonable() function allows to quickly find
1082 * out whether to use readahead or not based on the size of the data and the
1083 * amount of available memory.
1084 *
1085 * This flag affects only at environment opening and can't be changed after.
1086 */
1087 MDBX_NORDAHEAD = UINT32_C(0x800000),
1088
1089 /** Don't initialize malloc'ed memory before writing to datafile.
1090 *
1091 * Don't initialize malloc'ed memory before writing to unused spaces in the
1092 * data file. By default, memory for pages written to the data file is
1093 * obtained using malloc. While these pages may be reused in subsequent
1094 * transactions, freshly malloc'ed pages will be initialized to zeroes before
1095 * use. This avoids persisting leftover data from other code (that used the
1096 * heap and subsequently freed the memory) into the data file.
1097 *
1098 * Note that many other system libraries may allocate and free memory from
1099 * the heap for arbitrary uses. E.g., stdio may use the heap for file I/O
1100 * buffers. This initialization step has a modest performance cost so some
1101 * applications may want to disable it using this flag. This option can be a
1102 * problem for applications which handle sensitive data like passwords, and
1103 * it makes memory checkers like Valgrind noisy. This flag is not needed
1104 * with \ref MDBX_WRITEMAP, which writes directly to the mmap instead of using
1105 * malloc for pages. The initialization is also skipped if \ref MDBX_RESERVE
1106 * is used; the caller is expected to overwrite all of the memory that was
1107 * reserved in that case.
1108 *
1109 * This flag may be changed at any time using `mdbx_env_set_flags()`. */
1110 MDBX_NOMEMINIT = UINT32_C(0x1000000),
1111
1112 /** Aims to coalesce a Garbage Collection items.
1113 *
1114 * With `MDBX_COALESCE` flag MDBX will aims to coalesce items while recycling
1115 * a Garbage Collection. Technically, when possible short lists of pages
1116 * will be combined into longer ones, but to fit on one database page. As a
1117 * result, there will be fewer items in Garbage Collection and a page lists
1118 * are longer, which slightly increases the likelihood of returning pages to
1119 * Unallocated space and reducing the database file.
1120 *
1121 * This flag may be changed at any time using mdbx_env_set_flags(). */
1122 MDBX_COALESCE = UINT32_C(0x2000000),
1123
1124 /** LIFO policy for recycling a Garbage Collection items.
1125 *
1126 * `MDBX_LIFORECLAIM` flag turns on LIFO policy for recycling a Garbage
1127 * Collection items, instead of FIFO by default. On systems with a disk
1128 * write-back cache, this can significantly increase write performance, up
1129 * to several times in a best case scenario.
1130 *
1131 * LIFO recycling policy means that for reuse pages will be taken which became
1132 * unused the lastest (i.e. just now or most recently). Therefore the loop of
1133 * database pages circulation becomes as short as possible. In other words,
1134 * the number of pages, that are overwritten in memory and on disk during a
1135 * series of write transactions, will be as small as possible. Thus creates
1136 * ideal conditions for the efficient operation of the disk write-back cache.
1137 *
1138 * \ref MDBX_LIFORECLAIM is compatible with all no-sync flags, but gives NO
1139 * noticeable impact in combination with \ref MDBX_SAFE_NOSYNC or
1140 * \ref MDBX_UTTERLY_NOSYNC. Because MDBX will reused pages only before the
1141 * last "steady" MVCC-snapshot, i.e. the loop length of database pages
1142 * circulation will be mostly defined by frequency of calling
1143 * \ref mdbx_env_sync() rather than LIFO and FIFO difference.
1144 *
1145 * This flag may be changed at any time using mdbx_env_set_flags(). */
1146 MDBX_LIFORECLAIM = UINT32_C(0x4000000),
1147
1148 /** Debugging option, fill/perturb released pages. */
1149 MDBX_PAGEPERTURB = UINT32_C(0x8000000),
1150
1151 /* SYNC MODES****************************************************************/
1152 /** \defgroup sync_modes SYNC MODES
1153 *
1154 * \attention Using any combination of \ref MDBX_SAFE_NOSYNC, \ref
1155 * MDBX_NOMETASYNC and especially \ref MDBX_UTTERLY_NOSYNC is always a deal to
1156 * reduce durability for gain write performance. You must know exactly what
1157 * you are doing and what risks you are taking!
1158 *
1159 * \note for LMDB users: \ref MDBX_SAFE_NOSYNC is NOT similar to LMDB_NOSYNC,
1160 * but \ref MDBX_UTTERLY_NOSYNC is exactly match LMDB_NOSYNC. See details
1161 * below.
1162 *
1163 * THE SCENE:
1164 * - The DAT-file contains several MVCC-snapshots of B-tree at same time,
1165 * each of those B-tree has its own root page.
1166 * - Each of meta pages at the beginning of the DAT file contains a
1167 * pointer to the root page of B-tree which is the result of the particular
1168 * transaction, and a number of this transaction.
1169 * - For data durability, MDBX must first write all MVCC-snapshot data
1170 * pages and ensure that are written to the disk, then update a meta page
1171 * with the new transaction number and a pointer to the corresponding new
1172 * root page, and flush any buffers yet again.
1173 * - Thus during commit a I/O buffers should be flushed to the disk twice;
1174 * i.e. fdatasync(), FlushFileBuffers() or similar syscall should be
1175 * called twice for each commit. This is very expensive for performance,
1176 * but guaranteed durability even on unexpected system failure or power
1177 * outage. Of course, provided that the operating system and the
1178 * underlying hardware (e.g. disk) work correctly.
1179 *
1180 * TRADE-OFF:
1181 * By skipping some stages described above, you can significantly benefit in
1182 * speed, while partially or completely losing in the guarantee of data
1183 * durability and/or consistency in the event of system or power failure.
1184 * Moreover, if for any reason disk write order is not preserved, then at
1185 * moment of a system crash, a meta-page with a pointer to the new B-tree may
1186 * be written to disk, while the itself B-tree not yet. In that case, the
1187 * database will be corrupted!
1188 *
1189 * \see MDBX_SYNC_DURABLE \see MDBX_NOMETASYNC \see MDBX_SAFE_NOSYNC
1190 * \see MDBX_UTTERLY_NOSYNC
1191 *
1192 * @{ */
1193
1194 /** Default robust and durable sync mode.
1195 *
1196 * Metadata is written and flushed to disk after a data is written and
1197 * flushed, which guarantees the integrity of the database in the event
1198 * of a crash at any time.
1199 *
1200 * \attention Please do not use other modes until you have studied all the
1201 * details and are sure. Otherwise, you may lose your users' data, as happens
1202 * in [Miranda NG](https://www.miranda-ng.org/) messenger. */
1203 MDBX_SYNC_DURABLE = 0,
1204
1205 /** Don't sync the meta-page after commit.
1206 *
1207 * Flush system buffers to disk only once per transaction commit, omit the
1208 * metadata flush. Defer that until the system flushes files to disk,
1209 * or next non-\ref MDBX_RDONLY commit or \ref mdbx_env_sync(). Depending on
1210 * the platform and hardware, with \ref MDBX_NOMETASYNC you may get a doubling
1211 * of write performance.
1212 *
1213 * This trade-off maintains database integrity, but a system crash may
1214 * undo the last committed transaction. I.e. it preserves the ACI
1215 * (atomicity, consistency, isolation) but not D (durability) database
1216 * property.
1217 *
1218 * `MDBX_NOMETASYNC` flag may be changed at any time using
1219 * \ref mdbx_env_set_flags() or by passing to \ref mdbx_txn_begin() for
1220 * particular write transaction. \see sync_modes */
1221 MDBX_NOMETASYNC = UINT32_C(0x40000),
1222
1223 /** Don't sync anything but keep previous steady commits.
1224 *
1225 * Like \ref MDBX_UTTERLY_NOSYNC the `MDBX_SAFE_NOSYNC` flag disable similarly
1226 * flush system buffers to disk when committing a transaction. But there is a
1227 * huge difference in how are recycled the MVCC snapshots corresponding to
1228 * previous "steady" transactions (see below).
1229 *
1230 * With \ref MDBX_WRITEMAP the `MDBX_SAFE_NOSYNC` instructs MDBX to use
1231 * asynchronous mmap-flushes to disk. Asynchronous mmap-flushes means that
1232 * actually all writes will scheduled and performed by operation system on it
1233 * own manner, i.e. unordered. MDBX itself just notify operating system that
1234 * it would be nice to write data to disk, but no more.
1235 *
1236 * Depending on the platform and hardware, with `MDBX_SAFE_NOSYNC` you may get
1237 * a multiple increase of write performance, even 10 times or more.
1238 *
1239 * In contrast to \ref MDBX_UTTERLY_NOSYNC mode, with `MDBX_SAFE_NOSYNC` flag
1240 * MDBX will keeps untouched pages within B-tree of the last transaction
1241 * "steady" which was synced to disk completely. This has big implications for
1242 * both data durability and (unfortunately) performance:
1243 * - a system crash can't corrupt the database, but you will lose the last
1244 * transactions; because MDBX will rollback to last steady commit since it
1245 * kept explicitly.
1246 * - the last steady transaction makes an effect similar to "long-lived" read
1247 * transaction (see above in the \ref restrictions section) since prevents
1248 * reuse of pages freed by newer write transactions, thus the any data
1249 * changes will be placed in newly allocated pages.
1250 * - to avoid rapid database growth, the system will sync data and issue
1251 * a steady commit-point to resume reuse pages, each time there is
1252 * insufficient space and before increasing the size of the file on disk.
1253 *
1254 * In other words, with `MDBX_SAFE_NOSYNC` flag MDBX insures you from the
1255 * whole database corruption, at the cost increasing database size and/or
1256 * number of disk IOPs. So, `MDBX_SAFE_NOSYNC` flag could be used with
1257 * \ref mdbx_env_sync() as alternatively for batch committing or nested
1258 * transaction (in some cases). As well, auto-sync feature exposed by
1259 * \ref mdbx_env_set_syncbytes() and \ref mdbx_env_set_syncperiod() functions
1260 * could be very useful with `MDBX_SAFE_NOSYNC` flag.
1261 *
1262 * The number and volume of of disk IOPs with MDBX_SAFE_NOSYNC flag will
1263 * exactly the as without any no-sync flags. However, you should expect a
1264 * larger process's [work set](https://bit.ly/2kA2tFX) and significantly worse
1265 * a [locality of reference](https://bit.ly/2mbYq2J), due to the more
1266 * intensive allocation of previously unused pages and increase the size of
1267 * the database.
1268 *
1269 * `MDBX_SAFE_NOSYNC` flag may be changed at any time using
1270 * \ref mdbx_env_set_flags() or by passing to \ref mdbx_txn_begin() for
1271 * particular write transaction. */
1272 MDBX_SAFE_NOSYNC = UINT32_C(0x10000),
1273
1274 /** \deprecated Please use \ref MDBX_SAFE_NOSYNC instead of `MDBX_MAPASYNC`.
1275 *
1276 * Since version 0.9.x the `MDBX_MAPASYNC` is deprecated and has the same
1277 * effect as \ref MDBX_SAFE_NOSYNC with \ref MDBX_WRITEMAP. This just API
1278 * simplification is for convenience and clarity. */
1279 MDBX_MAPASYNC = MDBX_SAFE_NOSYNC,
1280
1281 /** Don't sync anything and wipe previous steady commits.
1282 *
1283 * Don't flush system buffers to disk when committing a transaction. This
1284 * optimization means a system crash can corrupt the database, if buffers are
1285 * not yet flushed to disk. Depending on the platform and hardware, with
1286 * `MDBX_UTTERLY_NOSYNC` you may get a multiple increase of write performance,
1287 * even 100 times or more.
1288 *
1289 * If the filesystem preserves write order (which is rare and never provided
1290 * unless explicitly noted) and the \ref MDBX_WRITEMAP and \ref
1291 * MDBX_LIFORECLAIM flags are not used, then a system crash can't corrupt the
1292 * database, but you can lose the last transactions, if at least one buffer is
1293 * not yet flushed to disk. The risk is governed by how often the system
1294 * flushes dirty buffers to disk and how often \ref mdbx_env_sync() is called.
1295 * So, transactions exhibit ACI (atomicity, consistency, isolation) properties
1296 * and only lose `D` (durability). I.e. database integrity is maintained, but
1297 * a system crash may undo the final transactions.
1298 *
1299 * Otherwise, if the filesystem not preserves write order (which is
1300 * typically) or \ref MDBX_WRITEMAP or \ref MDBX_LIFORECLAIM flags are used,
1301 * you should expect the corrupted database after a system crash.
1302 *
1303 * So, most important thing about `MDBX_UTTERLY_NOSYNC`:
1304 * - a system crash immediately after commit the write transaction
1305 * high likely lead to database corruption.
1306 * - successful completion of mdbx_env_sync(force = true) after one or
1307 * more committed transactions guarantees consistency and durability.
1308 * - BUT by committing two or more transactions you back database into
1309 * a weak state, in which a system crash may lead to database corruption!
1310 * In case single transaction after mdbx_env_sync, you may lose transaction
1311 * itself, but not a whole database.
1312 *
1313 * Nevertheless, `MDBX_UTTERLY_NOSYNC` provides "weak" durability in case
1314 * of an application crash (but no durability on system failure), and
1315 * therefore may be very useful in scenarios where data durability is
1316 * not required over a system failure (e.g for short-lived data), or if you
1317 * can take such risk.
1318 *
1319 * `MDBX_UTTERLY_NOSYNC` flag may be changed at any time using
1320 * \ref mdbx_env_set_flags(), but don't has effect if passed to
1321 * \ref mdbx_txn_begin() for particular write transaction. \see sync_modes */
1322 MDBX_UTTERLY_NOSYNC = MDBX_SAFE_NOSYNC | UINT32_C(0x100000),
1323
1324 /** @} end of SYNC MODES */
1325 };
1326 #ifndef __cplusplus
1327 /** \ingroup c_opening */
1328 typedef enum MDBX_env_flags_t MDBX_env_flags_t;
1329 #else
1330 DEFINE_ENUM_FLAG_OPERATORS(MDBX_env_flags_t)
1331 #endif
1332
1333 /** Transaction flags
1334 * \ingroup c_transactions
1335 * \anchor txn_flags
1336 * \see mdbx_txn_begin() \see mdbx_txn_flags() */
1337 enum MDBX_txn_flags_t {
1338 /** Start read-write transaction.
1339 *
1340 * Only one write transaction may be active at a time. Writes are fully
1341 * serialized, which guarantees that writers can never deadlock. */
1342 MDBX_TXN_READWRITE = 0,
1343
1344 /** Start read-only transaction.
1345 *
1346 * There can be multiple read-only transactions simultaneously that do not
1347 * block each other and a write transactions. */
1348 MDBX_TXN_RDONLY = MDBX_RDONLY,
1349
1350 /** Prepare but not start read-only transaction.
1351 *
1352 * Transaction will not be started immediately, but created transaction handle
1353 * will be ready for use with \ref mdbx_txn_renew(). This flag allows to
1354 * preallocate memory and assign a reader slot, thus avoiding these operations
1355 * at the next start of the transaction. */
1356 #if CONSTEXPR_ENUM_FLAGS_OPERATIONS || defined(DOXYGEN)
1357 MDBX_TXN_RDONLY_PREPARE = MDBX_RDONLY | MDBX_NOMEMINIT,
1358 #else
1359 MDBX_TXN_RDONLY_PREPARE = uint32_t(MDBX_RDONLY) | uint32_t(MDBX_NOMEMINIT),
1360 #endif
1361
1362 /** Do not block when starting a write transaction. */
1363 MDBX_TXN_TRY = UINT32_C(0x10000000),
1364
1365 /** Exactly the same as \ref MDBX_NOMETASYNC,
1366 * but for this transaction only */
1367 MDBX_TXN_NOMETASYNC = MDBX_NOMETASYNC,
1368
1369 /** Exactly the same as \ref MDBX_SAFE_NOSYNC,
1370 * but for this transaction only */
1371 MDBX_TXN_NOSYNC = MDBX_SAFE_NOSYNC
1372 };
1373 #ifndef __cplusplus
1374 typedef enum MDBX_txn_flags_t MDBX_txn_flags_t;
1375 #else
1376 DEFINE_ENUM_FLAG_OPERATORS(MDBX_txn_flags_t)
1377 #endif
1378
1379 /** \brief Database flags
1380 * \ingroup c_dbi
1381 * \anchor db_flags
1382 * \see mdbx_dbi_open() */
1383 enum MDBX_db_flags_t {
1384 MDBX_DB_DEFAULTS = 0,
1385
1386 /** Use reverse string comparison for keys. */
1387 MDBX_REVERSEKEY = UINT32_C(0x02),
1388
1389 /** Use sorted duplicates, i.e. allow multi-values for a keys. */
1390 MDBX_DUPSORT = UINT32_C(0x04),
1391
1392 /** Numeric keys in native byte order either uint32_t or uint64_t. The keys
1393 * must all be of the same size and must be aligned while passing as
1394 * arguments. */
1395 MDBX_INTEGERKEY = UINT32_C(0x08),
1396
1397 /** With \ref MDBX_DUPSORT; sorted dup items have fixed size. The data values
1398 * must all be of the same size. */
1399 MDBX_DUPFIXED = UINT32_C(0x10),
1400
1401 /** With \ref MDBX_DUPSORT and with \ref MDBX_DUPFIXED; dups are fixed size
1402 * like \ref MDBX_INTEGERKEY -style integers. The data values must all be of
1403 * the same size and must be aligned while passing as arguments. */
1404 MDBX_INTEGERDUP = UINT32_C(0x20),
1405
1406 /** With \ref MDBX_DUPSORT; use reverse string comparison for data values. */
1407 MDBX_REVERSEDUP = UINT32_C(0x40),
1408
1409 /** Create DB if not already existing. */
1410 MDBX_CREATE = UINT32_C(0x40000),
1411
1412 /** Opens an existing sub-database created with unknown flags.
1413 *
1414 * The `MDBX_DB_ACCEDE` flag is intend to open a existing sub-database which
1415 * was created with unknown flags (\ref MDBX_REVERSEKEY, \ref MDBX_DUPSORT,
1416 * \ref MDBX_INTEGERKEY, \ref MDBX_DUPFIXED, \ref MDBX_INTEGERDUP and
1417 * \ref MDBX_REVERSEDUP).
1418 *
1419 * In such cases, instead of returning the \ref MDBX_INCOMPATIBLE error, the
1420 * sub-database will be opened with flags which it was created, and then an
1421 * application could determine the actual flags by \ref mdbx_dbi_flags(). */
1422 MDBX_DB_ACCEDE = MDBX_ACCEDE
1423 };
1424 #ifndef __cplusplus
1425 /** \ingroup c_dbi */
1426 typedef enum MDBX_db_flags_t MDBX_db_flags_t;
1427 #else
1428 DEFINE_ENUM_FLAG_OPERATORS(MDBX_db_flags_t)
1429 #endif
1430
1431 /** \brief Data changing flags
1432 * \ingroup c_crud
1433 * \see \ref c_crud_hints "Quick reference for Insert/Update/Delete operations"
1434 * \see mdbx_put() \see mdbx_cursor_put() \see mdbx_replace() */
1435 enum MDBX_put_flags_t {
1436 /** Upsertion by default (without any other flags) */
1437 MDBX_UPSERT = 0,
1438
1439 /** For insertion: Don't write if the key already exists. */
1440 MDBX_NOOVERWRITE = UINT32_C(0x10),
1441
1442 /** Has effect only for \ref MDBX_DUPSORT databases.
1443 * For upsertion: don't write if the key-value pair already exist.
1444 * For deletion: remove all values for key. */
1445 MDBX_NODUPDATA = UINT32_C(0x20),
1446
1447 /** For upsertion: overwrite the current key/data pair.
1448 * MDBX allows this flag for \ref mdbx_put() for explicit overwrite/update
1449 * without insertion.
1450 * For deletion: remove only single entry at the current cursor position. */
1451 MDBX_CURRENT = UINT32_C(0x40),
1452
1453 /** Has effect only for \ref MDBX_DUPSORT databases.
1454 * For deletion: remove all multi-values (aka duplicates) for given key.
1455 * For upsertion: replace all multi-values for given key with a new one. */
1456 MDBX_ALLDUPS = UINT32_C(0x80),
1457
1458 /** For upsertion: Just reserve space for data, don't copy it.
1459 * Return a pointer to the reserved space. */
1460 MDBX_RESERVE = UINT32_C(0x10000),
1461
1462 /** Data is being appended.
1463 * Don't split full pages, continue on a new instead. */
1464 MDBX_APPEND = UINT32_C(0x20000),
1465
1466 /** Has effect only for \ref MDBX_DUPSORT databases.
1467 * Duplicate data is being appended.
1468 * Don't split full pages, continue on a new instead. */
1469 MDBX_APPENDDUP = UINT32_C(0x40000),
1470
1471 /** Only for \ref MDBX_DUPFIXED.
1472 * Store multiple data items in one call. */
1473 MDBX_MULTIPLE = UINT32_C(0x80000)
1474 };
1475 #ifndef __cplusplus
1476 /** \ingroup c_crud */
1477 typedef enum MDBX_put_flags_t MDBX_put_flags_t;
1478 #else
1479 DEFINE_ENUM_FLAG_OPERATORS(MDBX_put_flags_t)
1480 #endif
1481
1482 /** \brief Environment copy flags
1483 * \ingroup c_extra
1484 * \see mdbx_env_copy() \see mdbx_env_copy2fd() */
1485 enum MDBX_copy_flags_t {
1486 MDBX_CP_DEFAULTS = 0,
1487
1488 /** Copy with compactification: Omit free space from copy and renumber all
1489 * pages sequentially */
1490 MDBX_CP_COMPACT = 1u,
1491
1492 /** Force to make resizeable copy, i.e. dynamic size instead of fixed */
1493 MDBX_CP_FORCE_DYNAMIC_SIZE = 2u
1494 };
1495 #ifndef __cplusplus
1496 /** \ingroup c_extra */
1497 typedef enum MDBX_copy_flags_t MDBX_copy_flags_t;
1498 #else
1499 DEFINE_ENUM_FLAG_OPERATORS(MDBX_copy_flags_t)
1500 #endif
1501
1502 /** \brief Cursor operations
1503 * \ingroup c_cursors
1504 * This is the set of all operations for retrieving data using a cursor.
1505 * \see mdbx_cursor_get() */
1506 enum MDBX_cursor_op {
1507 /** Position at first key/data item */
1508 MDBX_FIRST,
1509
1510 /** \ref MDBX_DUPSORT -only: Position at first data item of current key. */
1511 MDBX_FIRST_DUP,
1512
1513 /** \ref MDBX_DUPSORT -only: Position at key/data pair. */
1514 MDBX_GET_BOTH,
1515
1516 /** \ref MDBX_DUPSORT -only: Position at given key and at first data greater
1517 * than or equal to specified data. */
1518 MDBX_GET_BOTH_RANGE,
1519
1520 /** Return key/data at current cursor position */
1521 MDBX_GET_CURRENT,
1522
1523 /** \ref MDBX_DUPFIXED -only: Return up to a page of duplicate data items
1524 * from current cursor position. Move cursor to prepare
1525 * for \ref MDBX_NEXT_MULTIPLE. */
1526 MDBX_GET_MULTIPLE,
1527
1528 /** Position at last key/data item */
1529 MDBX_LAST,
1530
1531 /** \ref MDBX_DUPSORT -only: Position at last data item of current key. */
1532 MDBX_LAST_DUP,
1533
1534 /** Position at next data item */
1535 MDBX_NEXT,
1536
1537 /** \ref MDBX_DUPSORT -only: Position at next data item of current key. */
1538 MDBX_NEXT_DUP,
1539
1540 /** \ref MDBX_DUPFIXED -only: Return up to a page of duplicate data items
1541 * from next cursor position. Move cursor to prepare
1542 * for `MDBX_NEXT_MULTIPLE`. */
1543 MDBX_NEXT_MULTIPLE,
1544
1545 /** Position at first data item of next key */
1546 MDBX_NEXT_NODUP,
1547
1548 /** Position at previous data item */
1549 MDBX_PREV,
1550
1551 /** \ref MDBX_DUPSORT -only: Position at previous data item of current key. */
1552 MDBX_PREV_DUP,
1553
1554 /** Position at last data item of previous key */
1555 MDBX_PREV_NODUP,
1556
1557 /** Position at specified key */
1558 MDBX_SET,
1559
1560 /** Position at specified key, return both key and data */
1561 MDBX_SET_KEY,
1562
1563 /** Position at first key greater than or equal to specified key. */
1564 MDBX_SET_RANGE,
1565
1566 /** \ref MDBX_DUPFIXED -only: Position at previous page and return up to
1567 * a page of duplicate data items. */
1568 MDBX_PREV_MULTIPLE,
1569
1570 /** Position at first key-value pair greater than or equal to specified,
1571 * return both key and data, and the return code depends on a exact match.
1572 *
1573 * For non DUPSORT-ed collections this work the same to \ref MDBX_SET_RANGE,
1574 * but returns \ref MDBX_SUCCESS if key found exactly and
1575 * \ref MDBX_RESULT_TRUE if greater key was found.
1576 *
1577 * For DUPSORT-ed a data value is taken into account for duplicates,
1578 * i.e. for a pairs/tuples of a key and an each data value of duplicates.
1579 * Returns \ref MDBX_SUCCESS if key-value pair found exactly and
1580 * \ref MDBX_RESULT_TRUE if the next pair was returned. */
1581 MDBX_SET_LOWERBOUND
1582 };
1583 #ifndef __cplusplus
1584 /** \ingroup c_cursors */
1585 typedef enum MDBX_cursor_op MDBX_cursor_op;
1586 #endif
1587
1588 /** \brief Errors and return codes
1589 * \ingroup c_err
1590 *
1591 * BerkeleyDB uses -30800 to -30999, we'll go under them
1592 * \see mdbx_strerror() \see mdbx_strerror_r() \see mdbx_liberr2str() */
1593 enum MDBX_error_t {
1594 /** Successful result */
1595 MDBX_SUCCESS = 0,
1596
1597 /** Alias for \ref MDBX_SUCCESS */
1598 MDBX_RESULT_FALSE = MDBX_SUCCESS,
1599
1600 /** Successful result with special meaning or a flag */
1601 MDBX_RESULT_TRUE = -1,
1602
1603 /** key/data pair already exists */
1604 MDBX_KEYEXIST = -30799,
1605
1606 /** The first LMDB-compatible defined error code */
1607 MDBX_FIRST_LMDB_ERRCODE = MDBX_KEYEXIST,
1608
1609 /** key/data pair not found (EOF) */
1610 MDBX_NOTFOUND = -30798,
1611
1612 /** Requested page not found - this usually indicates corruption */
1613 MDBX_PAGE_NOTFOUND = -30797,
1614
1615 /** Database is corrupted (page was wrong type and so on) */
1616 MDBX_CORRUPTED = -30796,
1617
1618 /** Environment had fatal error,
1619 * i.e. update of meta page failed and so on. */
1620 MDBX_PANIC = -30795,
1621
1622 /** DB file version mismatch with libmdbx */
1623 MDBX_VERSION_MISMATCH = -30794,
1624
1625 /** File is not a valid MDBX file */
1626 MDBX_INVALID = -30793,
1627
1628 /** Environment mapsize reached */
1629 MDBX_MAP_FULL = -30792,
1630
1631 /** Environment maxdbs reached */
1632 MDBX_DBS_FULL = -30791,
1633
1634 /** Environment maxreaders reached */
1635 MDBX_READERS_FULL = -30790,
1636
1637 /** Transaction has too many dirty pages, i.e transaction too big */
1638 MDBX_TXN_FULL = -30788,
1639
1640 /** Cursor stack too deep - this usually indicates corruption,
1641 * i.e branch-pages loop */
1642 MDBX_CURSOR_FULL = -30787,
1643
1644 /** Page has not enough space - internal error */
1645 MDBX_PAGE_FULL = -30786,
1646
1647 /** Database engine was unable to extend mapping, e.g. since address space
1648 * is unavailable or busy. This can mean:
1649 * - Database size extended by other process beyond to environment mapsize
1650 * and engine was unable to extend mapping while starting read
1651 * transaction. Environment should be reopened to continue.
1652 * - Engine was unable to extend mapping during write transaction
1653 * or explicit call of \ref mdbx_env_set_geometry(). */
1654 MDBX_UNABLE_EXTEND_MAPSIZE = -30785,
1655
1656 /** Environment or database is not compatible with the requested operation
1657 * or the specified flags. This can mean:
1658 * - The operation expects an \ref MDBX_DUPSORT / \ref MDBX_DUPFIXED
1659 * database.
1660 * - Opening a named DB when the unnamed DB has \ref MDBX_DUPSORT /
1661 * \ref MDBX_INTEGERKEY.
1662 * - Accessing a data record as a database, or vice versa.
1663 * - The database was dropped and recreated with different flags. */
1664 MDBX_INCOMPATIBLE = -30784,
1665
1666 /** Invalid reuse of reader locktable slot,
1667 * e.g. read-transaction already run for current thread */
1668 MDBX_BAD_RSLOT = -30783,
1669
1670 /** Transaction is not valid for requested operation,
1671 * e.g. had errored and be must aborted, has a child, or is invalid */
1672 MDBX_BAD_TXN = -30782,
1673
1674 /** Invalid size or alignment of key or data for target database,
1675 * either invalid subDB name */
1676 MDBX_BAD_VALSIZE = -30781,
1677
1678 /** The specified DBI-handle is invalid
1679 * or changed by another thread/transaction */
1680 MDBX_BAD_DBI = -30780,
1681
1682 /** Unexpected internal error, transaction should be aborted */
1683 MDBX_PROBLEM = -30779,
1684
1685 /** The last LMDB-compatible defined error code */
1686 MDBX_LAST_LMDB_ERRCODE = MDBX_PROBLEM,
1687
1688 /** Another write transaction is running or environment is already used while
1689 * opening with \ref MDBX_EXCLUSIVE flag */
1690 MDBX_BUSY = -30778,
1691
1692 /** The first of MDBX-added error codes */
1693 MDBX_FIRST_ADDED_ERRCODE = MDBX_BUSY,
1694
1695 /** The specified key has more than one associated value */
1696 MDBX_EMULTIVAL = -30421,
1697
1698 /** Bad signature of a runtime object(s), this can mean:
1699 * - memory corruption or double-free;
1700 * - ABI version mismatch (rare case); */
1701 MDBX_EBADSIGN = -30420,
1702
1703 /** Database should be recovered, but this could NOT be done for now
1704 * since it opened in read-only mode */
1705 MDBX_WANNA_RECOVERY = -30419,
1706
1707 /** The given key value is mismatched to the current cursor position */
1708 MDBX_EKEYMISMATCH = -30418,
1709
1710 /** Database is too large for current system,
1711 * e.g. could NOT be mapped into RAM. */
1712 MDBX_TOO_LARGE = -30417,
1713
1714 /** A thread has attempted to use a not owned object,
1715 * e.g. a transaction that started by another thread. */
1716 MDBX_THREAD_MISMATCH = -30416,
1717
1718 /** Overlapping read and write transactions for the current thread */
1719 MDBX_TXN_OVERLAPPING = -30415,
1720
1721 /* The last of MDBX-added error codes */
1722 MDBX_LAST_ADDED_ERRCODE = MDBX_TXN_OVERLAPPING,
1723
1724 #if defined(_WIN32) || defined(_WIN64)
1725 MDBX_ENODATA = ERROR_HANDLE_EOF,
1726 MDBX_EINVAL = ERROR_INVALID_PARAMETER,
1727 MDBX_EACCESS = ERROR_ACCESS_DENIED,
1728 MDBX_ENOMEM = ERROR_OUTOFMEMORY,
1729 MDBX_EROFS = ERROR_FILE_READ_ONLY,
1730 MDBX_ENOSYS = ERROR_NOT_SUPPORTED,
1731 MDBX_EIO = ERROR_WRITE_FAULT,
1732 MDBX_EPERM = ERROR_INVALID_FUNCTION,
1733 MDBX_EINTR = ERROR_CANCELLED,
1734 MDBX_ENOFILE = ERROR_FILE_NOT_FOUND,
1735 MDBX_EREMOTE = ERROR_REMOTE_STORAGE_MEDIA_ERROR
1736 #else /* Windows */
1737 #ifdef ENODATA
1738 MDBX_ENODATA = ENODATA,
1739 #else
1740 MDBX_ENODATA = 9919 /* for compatibility with LLVM's C++ libraries/headers */,
1741 #endif /* ENODATA */
1742 MDBX_EINVAL = EINVAL,
1743 MDBX_EACCESS = EACCES,
1744 MDBX_ENOMEM = ENOMEM,
1745 MDBX_EROFS = EROFS,
1746 MDBX_ENOSYS = ENOSYS,
1747 MDBX_EIO = EIO,
1748 MDBX_EPERM = EPERM,
1749 MDBX_EINTR = EINTR,
1750 MDBX_ENOFILE = ENOENT,
1751 MDBX_EREMOTE = ENOTBLK
1752 #endif /* !Windows */
1753 };
1754 #ifndef __cplusplus
1755 /** \ingroup c_err */
1756 typedef enum MDBX_error_t MDBX_error_t;
1757 #endif
1758
1759 /** MDBX_MAP_RESIZED
1760 * \ingroup c_err
1761 * \deprecated Please review your code to use MDBX_UNABLE_EXTEND_MAPSIZE
1762 * instead. */
MDBX_MAP_RESIZED_is_deprecated()1763 MDBX_DEPRECATED static __inline int MDBX_MAP_RESIZED_is_deprecated() {
1764 return MDBX_UNABLE_EXTEND_MAPSIZE;
1765 }
1766 #define MDBX_MAP_RESIZED MDBX_MAP_RESIZED_is_deprecated()
1767
1768 /** \brief Return a string describing a given error code.
1769 * \ingroup c_err
1770 *
1771 * This function is a superset of the ANSI C X3.159-1989 (ANSI C) `strerror()`
1772 * function. If the error code is greater than or equal to 0, then the string
1773 * returned by the system function `strerror()` is returned. If the error code
1774 * is less than 0, an error string corresponding to the MDBX library error is
1775 * returned. See errors for a list of MDBX-specific error codes.
1776 *
1777 * `mdbx_strerror()` is NOT thread-safe because may share common internal buffer
1778 * for system messages. The returned string must NOT be modified by the
1779 * application, but MAY be modified by a subsequent call to
1780 * \ref mdbx_strerror(), `strerror()` and other related functions.
1781 * \see mdbx_strerror_r()
1782 *
1783 * \param [in] errnum The error code.
1784 *
1785 * \returns "error message" The description of the error. */
1786 LIBMDBX_API const char *mdbx_strerror(int errnum);
1787
1788 /** \brief Return a string describing a given error code.
1789 * \ingroup c_err
1790 *
1791 * This function is a superset of the ANSI C X3.159-1989 (ANSI C) `strerror()`
1792 * function. If the error code is greater than or equal to 0, then the string
1793 * returned by the system function `strerror()` is returned. If the error code
1794 * is less than 0, an error string corresponding to the MDBX library error is
1795 * returned. See errors for a list of MDBX-specific error codes.
1796 *
1797 * `mdbx_strerror_r()` is thread-safe since uses user-supplied buffer where
1798 * appropriate. The returned string must NOT be modified by the application,
1799 * since it may be pointer to internal constant string. However, there is no
1800 * restriction if the returned string points to the supplied buffer.
1801 * \see mdbx_strerror()
1802 *
1803 * mdbx_liberr2str() returns string describing only MDBX error numbers but NULL
1804 * for non-MDBX error codes. This function is thread-safe since return pointer
1805 * to constant non-localized strings.
1806 *
1807 * \param [in] errnum The error code.
1808 * \param [in,out] buf Buffer to store the error message.
1809 * \param [in] buflen The size of buffer to store the message.
1810 *
1811 * \returns "error message" The description of the error. */
1812 LIBMDBX_API const char *mdbx_strerror_r(int errnum, char *buf, size_t buflen);
1813 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API const char *mdbx_liberr2str(int errnum);
1814
1815 #if defined(_WIN32) || defined(_WIN64) || defined(DOXYGEN)
1816 /** Bit of Windows' madness. The similar to \ref mdbx_strerror() but returns
1817 * Windows error-messages in the OEM-encoding for console utilities.
1818 * \ingroup c_err
1819 * \see mdbx_strerror_r_ANSI2OEM() */
1820 LIBMDBX_API const char *mdbx_strerror_ANSI2OEM(int errnum);
1821
1822 /** Bit of Windows' madness. The similar to \ref mdbx_strerror_r() but returns
1823 * Windows error-messages in the OEM-encoding for console utilities.
1824 * \ingroup c_err
1825 * \see mdbx_strerror_ANSI2OEM() */
1826 LIBMDBX_API const char *mdbx_strerror_r_ANSI2OEM(int errnum, char *buf,
1827 size_t buflen);
1828 #endif /* Bit of Windows' madness */
1829
1830 /** \brief Create an MDBX environment instance.
1831 * \ingroup c_opening
1832 *
1833 * This function allocates memory for a \ref MDBX_env structure. To release
1834 * the allocated memory and discard the handle, call \ref mdbx_env_close().
1835 * Before the handle may be used, it must be opened using \ref mdbx_env_open().
1836 *
1837 * Various other options may also need to be set before opening the handle,
1838 * e.g. \ref mdbx_env_set_geometry(), \ref mdbx_env_set_maxreaders(),
1839 * \ref mdbx_env_set_maxdbs(), depending on usage requirements.
1840 *
1841 * \param [out] penv The address where the new handle will be stored.
1842 *
1843 * \returns a non-zero error value on failure and 0 on success. */
1844 LIBMDBX_API int mdbx_env_create(MDBX_env **penv);
1845
1846 /** \brief MDBX environment options. */
1847 enum MDBX_option_t {
1848 /** \brief Controls the maximum number of named databases for the environment.
1849 *
1850 * \details By default only unnamed key-value database could used and
1851 * appropriate value should set by `MDBX_opt_max_db` to using any more named
1852 * subDB(s). To reduce overhead, use the minimum sufficient value. This option
1853 * may only set after \ref mdbx_env_create() and before \ref mdbx_env_open().
1854 *
1855 * \see mdbx_env_set_maxdbs() \see mdbx_env_get_maxdbs() */
1856 MDBX_opt_max_db,
1857
1858 /** \brief Defines the maximum number of threads/reader slots
1859 * for all processes interacting with the database.
1860 *
1861 * \details This defines the number of slots in the lock table that is used to
1862 * track readers in the the environment. The default is about 100 for 4K
1863 * system page size. Starting a read-only transaction normally ties a lock
1864 * table slot to the current thread until the environment closes or the thread
1865 * exits. If \ref MDBX_NOTLS is in use, \ref mdbx_txn_begin() instead ties the
1866 * slot to the \ref MDBX_txn object until it or the \ref MDBX_env object is
1867 * destroyed. This option may only set after \ref mdbx_env_create() and before
1868 * \ref mdbx_env_open(), and has an effect only when the database is opened by
1869 * the first process interacts with the database.
1870 *
1871 * \see mdbx_env_set_maxreaders() \see mdbx_env_get_maxreaders() */
1872 MDBX_opt_max_readers,
1873
1874 /** \brief Controls interprocess/shared threshold to force flush the data
1875 * buffers to disk, if \ref MDBX_SAFE_NOSYNC is used.
1876 *
1877 * \see mdbx_env_set_syncbytes() \see mdbx_env_get_syncbytes() */
1878 MDBX_opt_sync_bytes,
1879
1880 /** \brief Controls interprocess/shared relative period since the last
1881 * unsteady commit to force flush the data buffers to disk,
1882 * if \ref MDBX_SAFE_NOSYNC is used.
1883 * \see mdbx_env_set_syncperiod() \see mdbx_env_get_syncperiod() */
1884 MDBX_opt_sync_period,
1885
1886 /** \brief Controls the in-process limit to grow a list of reclaimed/recycled
1887 * page's numbers for finding a sequence of contiguous pages for large data
1888 * items.
1889 *
1890 * \details A long values requires allocation of contiguous database pages.
1891 * To find such sequences, it may be necessary to accumulate very large lists,
1892 * especially when placing very long values (more than a megabyte) in a large
1893 * databases (several tens of gigabytes), which is much expensive in extreme
1894 * cases. This threshold allows you to avoid such costs by allocating new
1895 * pages at the end of the database (with its possible growth on disk),
1896 * instead of further accumulating/reclaiming Garbage Collection records.
1897 *
1898 * On the other hand, too small threshold will lead to unreasonable database
1899 * growth, or/and to the inability of put long values.
1900 *
1901 * The `MDBX_opt_rp_augment_limit` controls described limit for the current
1902 * process. Default is 262144, it is usually enough for most cases. */
1903 MDBX_opt_rp_augment_limit,
1904
1905 /** \brief Controls the in-process limit to grow a cache of dirty
1906 * pages for reuse in the current transaction.
1907 *
1908 * \details A 'dirty page' refers to a page that has been updated in memory
1909 * only, the changes to a dirty page are not yet stored on disk.
1910 * To reduce overhead, it is reasonable to release not all such pages
1911 * immediately, but to leave some ones in cache for reuse in the current
1912 * transaction.
1913 *
1914 * The `MDBX_opt_loose_limit` allows you to set a limit for such cache inside
1915 * the current process. Should be in the range 0..255, default is 64. */
1916 MDBX_opt_loose_limit,
1917
1918 /** \brief Controls the in-process limit of a pre-allocated memory items
1919 * for dirty pages.
1920 *
1921 * \details A 'dirty page' refers to a page that has been updated in memory
1922 * only, the changes to a dirty page are not yet stored on disk.
1923 * Without \ref MDBX_WRITEMAP dirty pages are allocated from memory and
1924 * released when a transaction is committed. To reduce overhead, it is
1925 * reasonable to release not all ones, but to leave some allocations in
1926 * reserve for reuse in the next transaction(s).
1927 *
1928 * The `MDBX_opt_dp_reserve_limit` allows you to set a limit for such reserve
1929 * inside the current process. Default is 1024. */
1930 MDBX_opt_dp_reserve_limit,
1931
1932 /** \brief Controls the in-process limit of dirty pages
1933 * for a write transaction.
1934 *
1935 * \details A 'dirty page' refers to a page that has been updated in memory
1936 * only, the changes to a dirty page are not yet stored on disk.
1937 * Without \ref MDBX_WRITEMAP dirty pages are allocated from memory and will
1938 * be busy until are written to disk. Therefore for a large transactions is
1939 * reasonable to limit dirty pages collecting above an some threshold but
1940 * spill to disk instead.
1941 *
1942 * The `MDBX_opt_txn_dp_limit` controls described threshold for the current
1943 * process. Default is 65536, it is usually enough for most cases. */
1944 MDBX_opt_txn_dp_limit,
1945
1946 /** \brief Controls the in-process initial allocation size for dirty pages
1947 * list of a write transaction. Default is 1024. */
1948 MDBX_opt_txn_dp_initial,
1949
1950 /** \brief Controls the in-process how maximal part of the dirty pages may be
1951 * spilled when necessary.
1952 *
1953 * \details The `MDBX_opt_spill_max_denominator` defines the denominator for
1954 * limiting from the top for part of the current dirty pages may be spilled
1955 * when the free room for a new dirty pages (i.e. distance to the
1956 * `MDBX_opt_txn_dp_limit` threshold) is not enough to perform requested
1957 * operation.
1958 * Exactly `max_pages_to_spill = dirty_pages - dirty_pages / N`,
1959 * where `N` is the value set by `MDBX_opt_spill_max_denominator`.
1960 *
1961 * Should be in the range 0..255, where zero means no limit, i.e. all dirty
1962 * pages could be spilled. Default is 8, i.e. no more than 7/8 of the current
1963 * dirty pages may be spilled when reached the condition described above. */
1964 MDBX_opt_spill_max_denominator,
1965
1966 /** \brief Controls the in-process how minimal part of the dirty pages should
1967 * be spilled when necessary.
1968 *
1969 * \details The `MDBX_opt_spill_min_denominator` defines the denominator for
1970 * limiting from the bottom for part of the current dirty pages should be
1971 * spilled when the free room for a new dirty pages (i.e. distance to the
1972 * `MDBX_opt_txn_dp_limit` threshold) is not enough to perform requested
1973 * operation.
1974 * Exactly `min_pages_to_spill = dirty_pages / N`,
1975 * where `N` is the value set by `MDBX_opt_spill_min_denominator`.
1976 *
1977 * Should be in the range 0..255, where zero means no restriction at the
1978 * bottom. Default is 8, i.e. at least the 1/8 of the current dirty pages
1979 * should be spilled when reached the condition described above. */
1980 MDBX_opt_spill_min_denominator,
1981
1982 /** \brief Controls the in-process how much of the parent transaction dirty
1983 * pages will be spilled while start each child transaction.
1984 *
1985 * \details The `MDBX_opt_spill_parent4child_denominator` defines the
1986 * denominator to determine how much of parent transaction dirty pages will be
1987 * spilled explicitly while start each child transaction.
1988 * Exactly `pages_to_spill = dirty_pages / N`,
1989 * where `N` is the value set by `MDBX_opt_spill_parent4child_denominator`.
1990 *
1991 * For a stack of nested transactions each dirty page could be spilled only
1992 * once, and parent's dirty pages couldn't be spilled while child
1993 * transaction(s) are running. Therefore a child transaction could reach
1994 * \ref MDBX_TXN_FULL when parent(s) transaction has spilled too less (and
1995 * child reach the limit of dirty pages), either when parent(s) has spilled
1996 * too more (since child can't spill already spilled pages). So there is no
1997 * universal golden ratio.
1998 *
1999 * Should be in the range 0..255, where zero means no explicit spilling will
2000 * be performed during starting nested transactions.
2001 * Default is 0, i.e. by default no spilling performed during starting nested
2002 * transactions, that correspond historically behaviour. */
2003 MDBX_opt_spill_parent4child_denominator,
2004
2005 /** \brief Controls the in-process threshold of semi-empty pages merge.
2006 * \warning This is experimental option and subject for change or removal.
2007 * \details This option controls the in-process threshold of minimum page
2008 * fill, as used space of percentage of a page. Neighbour pages emptier than
2009 * this value are candidates for merging. The threshold value is specified
2010 * in 1/65536 of percent, which is equivalent to the 16-dot-16 fixed point
2011 * format. The specified value must be in the range from 12.5% (almost empty)
2012 * to 50% (half empty) which corresponds to the range from 8192 and to 32768
2013 * in units respectively. */
2014 MDBX_opt_merge_threshold_16dot16_percent,
2015 };
2016 #ifndef __cplusplus
2017 /** \ingroup c_settings */
2018 typedef enum MDBX_option_t MDBX_option_t;
2019 #endif
2020
2021 /** \brief Sets the value of a runtime options for an environment.
2022 * \ingroup c_settings
2023 *
2024 * \param [in] env An environment handle returned by \ref mdbx_env_create().
2025 * \param [in] option The option from \ref MDBX_option_t to set value of it.
2026 * \param [in] value The value of option to be set.
2027 *
2028 * \see MDBX_option_t
2029 * \see mdbx_env_get_option()
2030 * \returns A non-zero error value on failure and 0 on success. */
2031 LIBMDBX_API int mdbx_env_set_option(MDBX_env *env, const MDBX_option_t option,
2032 const uint64_t value);
2033
2034 /** \brief Gets the value of runtime options from an environment.
2035 * \ingroup c_settings
2036 *
2037 * \param [in] env An environment handle returned by \ref mdbx_env_create().
2038 * \param [in] option The option from \ref MDBX_option_t to get value of it.
2039 * \param [out] pvalue The address where the option's value will be stored.
2040 *
2041 * \see MDBX_option_t
2042 * \see mdbx_env_get_option()
2043 * \returns A non-zero error value on failure and 0 on success. */
2044 LIBMDBX_API int mdbx_env_get_option(const MDBX_env *env,
2045 const MDBX_option_t option,
2046 uint64_t *pvalue);
2047
2048 /** \brief Open an environment instance.
2049 * \ingroup c_opening
2050 *
2051 * Indifferently this function will fails or not, the \ref mdbx_env_close() must
2052 * be called later to discard the \ref MDBX_env handle and release associated
2053 * resources.
2054 *
2055 * \param [in] env An environment handle returned
2056 * by \ref mdbx_env_create()
2057 *
2058 * \param [in] pathname The pathname for the database or the directory in which
2059 * the database files reside. In the case of directory it
2060 * must already exist and be writable.
2061 *
2062 * \param [in] flags Special options for this environment. This parameter
2063 * must be set to 0 or by bitwise OR'ing together one
2064 * or more of the values described above in the
2065 * \ref env_flags and \ref sync_modes sections.
2066 *
2067 * Flags set by mdbx_env_set_flags() are also used:
2068 * - \ref MDBX_NOSUBDIR, \ref MDBX_RDONLY, \ref MDBX_EXCLUSIVE,
2069 * \ref MDBX_WRITEMAP, \ref MDBX_NOTLS, \ref MDBX_NORDAHEAD,
2070 * \ref MDBX_NOMEMINIT, \ref MDBX_COALESCE, \ref MDBX_LIFORECLAIM.
2071 * See \ref env_flags section.
2072 *
2073 * - \ref MDBX_NOMETASYNC, \ref MDBX_SAFE_NOSYNC, \ref MDBX_UTTERLY_NOSYNC.
2074 * See \ref sync_modes section.
2075 *
2076 * \note `MDB_NOLOCK` flag don't supported by MDBX,
2077 * try use \ref MDBX_EXCLUSIVE as a replacement.
2078 *
2079 * \note MDBX don't allow to mix processes with different \ref MDBX_SAFE_NOSYNC
2080 * flags on the same environment.
2081 * In such case \ref MDBX_INCOMPATIBLE will be returned.
2082 *
2083 * If the database is already exist and parameters specified early by
2084 * \ref mdbx_env_set_geometry() are incompatible (i.e. for instance, different
2085 * page size) then \ref mdbx_env_open() will return \ref MDBX_INCOMPATIBLE
2086 * error.
2087 *
2088 * \param [in] mode The UNIX permissions to set on created files.
2089 * Zero value means to open existing, but do not create.
2090 *
2091 * \return A non-zero error value on failure and 0 on success,
2092 * some possible errors are:
2093 * \retval MDBX_VERSION_MISMATCH The version of the MDBX library doesn't match
2094 * the version that created the database environment.
2095 * \retval MDBX_INVALID The environment file headers are corrupted.
2096 * \retval MDBX_ENOENT The directory specified by the path parameter
2097 * doesn't exist.
2098 * \retval MDBX_EACCES The user didn't have permission to access
2099 * the environment files.
2100 * \retval MDBX_EAGAIN The environment was locked by another process.
2101 * \retval MDBX_BUSY The \ref MDBX_EXCLUSIVE flag was specified and the
2102 * environment is in use by another process,
2103 * or the current process tries to open environment
2104 * more than once.
2105 * \retval MDBX_INCOMPATIBLE Environment is already opened by another process,
2106 * but with different set of \ref MDBX_SAFE_NOSYNC,
2107 * \ref MDBX_UTTERLY_NOSYNC flags.
2108 * Or if the database is already exist and parameters
2109 * specified early by \ref mdbx_env_set_geometry()
2110 * are incompatible (i.e. different pagesize, etc).
2111 *
2112 * \retval MDBX_WANNA_RECOVERY The \ref MDBX_RDONLY flag was specified but
2113 * read-write access is required to rollback
2114 * inconsistent state after a system crash.
2115 *
2116 * \retval MDBX_TOO_LARGE Database is too large for this process,
2117 * i.e. 32-bit process tries to open >4Gb database.
2118 */
2119 LIBMDBX_API int mdbx_env_open(MDBX_env *env, const char *pathname,
2120 MDBX_env_flags_t flags, mdbx_mode_t mode);
2121
2122 /** \brief Deletion modes for \ref mdbx_env_delete().
2123 * \ingroup c_extra
2124 * \see mdbx_env_delete() */
2125 enum MDBX_env_delete_mode_t {
2126 /** \brief Just delete the environment's files and directory if any.
2127 * \note On POSIX systems, processes already working with the database will
2128 * continue to work without interference until it close the environment.
2129 * \note On Windows, the behavior of `MDB_ENV_JUST_DELETE` is different
2130 * because the system does not support deleting files that are currently
2131 * memory mapped. */
2132 MDBX_ENV_JUST_DELETE = 0,
2133 /** \brief Make sure that the environment is not being used by other
2134 * processes, or return an error otherwise. */
2135 MDBX_ENV_ENSURE_UNUSED = 1,
2136 /** \brief Wait until other processes closes the environment before deletion.
2137 */
2138 MDBX_ENV_WAIT_FOR_UNUSED = 2,
2139 };
2140 #ifndef __cplusplus
2141 /** \ingroup c_extra */
2142 typedef enum MDBX_env_delete_mode_t MDBX_env_delete_mode_t;
2143 #endif
2144
2145 /** \brief Delete the environment's files in a proper and multiprocess-safe way.
2146 * \ingroup c_extra
2147 *
2148 * \param [in] pathname The pathname for the database or the directory in which
2149 * the database files reside.
2150 *
2151 * \param [in] mode Special deletion mode for the environment. This
2152 * parameter must be set to one of the values described
2153 * above in the \ref MDBX_env_delete_mode_t section.
2154 *
2155 * \note The \ref MDBX_ENV_JUST_DELETE don't supported on Windows since system
2156 * unable to delete a memory-mapped files.
2157 *
2158 * \returns A non-zero error value on failure and 0 on success,
2159 * some possible errors are:
2160 * \retval MDBX_RESULT_TRUE No corresponding files or directories were found,
2161 * so no deletion was performed. */
2162 LIBMDBX_API int mdbx_env_delete(const char *pathname,
2163 MDBX_env_delete_mode_t mode);
2164
2165 /** \brief Copy an MDBX environment to the specified path, with options.
2166 * \ingroup c_extra
2167 *
2168 * This function may be used to make a backup of an existing environment.
2169 * No lockfile is created, since it gets recreated at need.
2170 * \note This call can trigger significant file size growth if run in
2171 * parallel with write transactions, because it employs a read-only
2172 * transaction. See long-lived transactions under \ref restrictions section.
2173 *
2174 * \param [in] env An environment handle returned by mdbx_env_create().
2175 * It must have already been opened successfully.
2176 * \param [in] dest The pathname of a file in which the copy will reside.
2177 * This file must not be already exist, but parent directory
2178 * must be writable.
2179 * \param [in] flags Special options for this operation. This parameter must
2180 * be set to 0 or by bitwise OR'ing together one or more
2181 * of the values described here:
2182 *
2183 * - \ref MDBX_CP_COMPACT
2184 * Perform compaction while copying: omit free pages and sequentially
2185 * renumber all pages in output. This option consumes little bit more
2186 * CPU for processing, but may running quickly than the default, on
2187 * account skipping free pages.
2188 *
2189 * - \ref MDBX_CP_FORCE_DYNAMIC_SIZE
2190 * Force to make resizeable copy, i.e. dynamic size instead of fixed.
2191 *
2192 * \returns A non-zero error value on failure and 0 on success. */
2193 LIBMDBX_API int mdbx_env_copy(MDBX_env *env, const char *dest,
2194 MDBX_copy_flags_t flags);
2195
2196 /** \brief Copy an environment to the specified file descriptor, with
2197 * options. \ingroup c_extra
2198 *
2199 * This function may be used to make a backup of an existing environment.
2200 * No lockfile is created, since it gets recreated at need.
2201 * \see mdbx_env_copy()
2202 *
2203 * \note This call can trigger significant file size growth if run in
2204 * parallel with write transactions, because it employs a read-only
2205 * transaction. See long-lived transactions under \ref restrictions
2206 * section.
2207 *
2208 * \note Fails if the environment has suffered a page leak and the destination
2209 * file descriptor is associated with a pipe, socket, or FIFO.
2210 *
2211 * \param [in] env An environment handle returned by mdbx_env_create().
2212 * It must have already been opened successfully.
2213 * \param [in] fd The file descriptor to write the copy to. It must have
2214 * already been opened for Write access.
2215 * \param [in] flags Special options for this operation. \see mdbx_env_copy()
2216 *
2217 * \returns A non-zero error value on failure and 0 on success. */
2218 LIBMDBX_API int mdbx_env_copy2fd(MDBX_env *env, mdbx_filehandle_t fd,
2219 MDBX_copy_flags_t flags);
2220
2221 /** \brief Statistics for a database in the environment
2222 * \ingroup c_statinfo
2223 * \see mdbx_env_stat_ex() \see mdbx_dbi_stat() */
2224 struct MDBX_stat {
2225 uint32_t ms_psize; /**< Size of a database page. This is the same for all
2226 databases. */
2227 uint32_t ms_depth; /**< Depth (height) of the B-tree */
2228 uint64_t ms_branch_pages; /**< Number of internal (non-leaf) pages */
2229 uint64_t ms_leaf_pages; /**< Number of leaf pages */
2230 uint64_t ms_overflow_pages; /**< Number of overflow pages */
2231 uint64_t ms_entries; /**< Number of data items */
2232 uint64_t ms_mod_txnid; /**< Transaction ID of committed last modification */
2233 };
2234 #ifndef __cplusplus
2235 /** \ingroup c_statinfo */
2236 typedef struct MDBX_stat MDBX_stat;
2237 #endif
2238
2239 /** \brief Return statistics about the MDBX environment.
2240 * \ingroup c_statinfo
2241 *
2242 * At least one of env or txn argument must be non-null. If txn is passed
2243 * non-null then stat will be filled accordingly to the given transaction.
2244 * Otherwise, if txn is null, then stat will be populated by a snapshot from
2245 * the last committed write transaction, and at next time, other information
2246 * can be returned.
2247 *
2248 * Legacy mdbx_env_stat() correspond to calling \ref mdbx_env_stat_ex() with the
2249 * null `txn` argument.
2250 *
2251 * \param [in] env An environment handle returned by \ref mdbx_env_create()
2252 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin()
2253 * \param [out] stat The address of an \ref MDBX_stat structure where
2254 * the statistics will be copied
2255 * \param [in] bytes The size of \ref MDBX_stat.
2256 *
2257 * \returns A non-zero error value on failure and 0 on success. */
2258 LIBMDBX_API int mdbx_env_stat_ex(const MDBX_env *env, const MDBX_txn *txn,
2259 MDBX_stat *stat, size_t bytes);
2260
2261 /** \brief Return statistics about the MDBX environment.
2262 * \ingroup c_statinfo
2263 * \deprecated Please use mdbx_env_stat_ex() instead. */
2264 MDBX_DEPRECATED LIBMDBX_INLINE_API(int, mdbx_env_stat,
2265 (const MDBX_env *env, MDBX_stat *stat,
2266 size_t bytes)) {
2267 return mdbx_env_stat_ex(env, NULL, stat, bytes);
2268 }
2269
2270 /** \brief Information about the environment
2271 * \ingroup c_statinfo
2272 * \see mdbx_env_info_ex() */
2273 struct MDBX_envinfo {
2274 struct {
2275 uint64_t lower; /**< Lower limit for datafile size */
2276 uint64_t upper; /**< Upper limit for datafile size */
2277 uint64_t current; /**< Current datafile size */
2278 uint64_t shrink; /**< Shrink threshold for datafile */
2279 uint64_t grow; /**< Growth step for datafile */
2280 } mi_geo;
2281 uint64_t mi_mapsize; /**< Size of the data memory map */
2282 uint64_t mi_last_pgno; /**< Number of the last used page */
2283 uint64_t mi_recent_txnid; /**< ID of the last committed transaction */
2284 uint64_t mi_latter_reader_txnid; /**< ID of the last reader transaction */
2285 uint64_t mi_self_latter_reader_txnid; /**< ID of the last reader transaction
2286 of caller process */
2287 uint64_t mi_meta0_txnid, mi_meta0_sign;
2288 uint64_t mi_meta1_txnid, mi_meta1_sign;
2289 uint64_t mi_meta2_txnid, mi_meta2_sign;
2290 uint32_t mi_maxreaders; /**< Total reader slots in the environment */
2291 uint32_t mi_numreaders; /**< Max reader slots used in the environment */
2292 uint32_t mi_dxb_pagesize; /**< Database pagesize */
2293 uint32_t mi_sys_pagesize; /**< System pagesize */
2294
2295 /** \brief A mostly unique ID that is regenerated on each boot.
2296
2297 As such it can be used to identify the local machine's current boot. MDBX
2298 uses such when open the database to determine whether rollback required to
2299 the last steady sync point or not. I.e. if current bootid is differ from the
2300 value within a database then the system was rebooted and all changes since
2301 last steady sync must be reverted for data integrity. Zeros mean that no
2302 relevant information is available from the system. */
2303 struct {
2304 struct {
2305 uint64_t x, y;
2306 } current, meta0, meta1, meta2;
2307 } mi_bootid;
2308
2309 /** Bytes not explicitly synchronized to disk */
2310 uint64_t mi_unsync_volume;
2311 /** Current auto-sync threshold, see \ref mdbx_env_set_syncbytes(). */
2312 uint64_t mi_autosync_threshold;
2313 /** Time since the last steady sync in 1/65536 of second */
2314 uint32_t mi_since_sync_seconds16dot16;
2315 /** Current auto-sync period in 1/65536 of second,
2316 * see \ref mdbx_env_set_syncperiod(). */
2317 uint32_t mi_autosync_period_seconds16dot16;
2318 /** Time since the last readers check in 1/65536 of second,
2319 * see \ref mdbx_reader_check(). */
2320 uint32_t mi_since_reader_check_seconds16dot16;
2321 /** Current environment mode.
2322 * The same as \ref mdbx_env_get_flags() returns. */
2323 uint32_t mi_mode;
2324
2325 /** Statistics of page operations.
2326 * \details Overall statistics of page operations of all (running, completed
2327 * and aborted) transactions in the current multi-process session (since the
2328 * first process opened the database after everyone had previously closed it).
2329 */
2330 struct {
2331 uint64_t newly; /**< Quantity of a new pages added */
2332 uint64_t cow; /**< Quantity of pages copied for update */
2333 uint64_t clone; /**< Quantity of parent's dirty pages clones
2334 for nested transactions */
2335 uint64_t split; /**< Page splits */
2336 uint64_t merge; /**< Page merges */
2337 uint64_t spill; /**< Quantity of spilled dirty pages */
2338 uint64_t unspill; /**< Quantity of unspilled/reloaded pages */
2339 uint64_t wops; /**< Number of explicit write operations (not a pages)
2340 to a disk */
2341 } mi_pgop_stat;
2342 };
2343 #ifndef __cplusplus
2344 /** \ingroup c_statinfo */
2345 typedef struct MDBX_envinfo MDBX_envinfo;
2346 #endif
2347
2348 /** \brief Return information about the MDBX environment.
2349 * \ingroup c_statinfo
2350 *
2351 * At least one of env or txn argument must be non-null. If txn is passed
2352 * non-null then stat will be filled accordingly to the given transaction.
2353 * Otherwise, if txn is null, then stat will be populated by a snapshot from
2354 * the last committed write transaction, and at next time, other information
2355 * can be returned.
2356 *
2357 * Legacy \ref mdbx_env_info() correspond to calling \ref mdbx_env_info_ex()
2358 * with the null `txn` argument.
2359 *
2360 * \param [in] env An environment handle returned by \ref mdbx_env_create()
2361 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin()
2362 * \param [out] info The address of an \ref MDBX_envinfo structure
2363 * where the information will be copied
2364 * \param [in] bytes The size of \ref MDBX_envinfo.
2365 *
2366 * \returns A non-zero error value on failure and 0 on success. */
2367 LIBMDBX_API int mdbx_env_info_ex(const MDBX_env *env, const MDBX_txn *txn,
2368 MDBX_envinfo *info, size_t bytes);
2369 /** \brief Return information about the MDBX environment.
2370 * \ingroup c_statinfo
2371 * \deprecated Please use mdbx_env_info_ex() instead. */
2372 MDBX_DEPRECATED LIBMDBX_INLINE_API(int, mdbx_env_info,
2373 (const MDBX_env *env, MDBX_envinfo *info,
2374 size_t bytes)) {
2375 return mdbx_env_info_ex(env, NULL, info, bytes);
2376 }
2377
2378 /** \brief Flush the environment data buffers to disk.
2379 * \ingroup c_extra
2380 *
2381 * Unless the environment was opened with no-sync flags (\ref MDBX_NOMETASYNC,
2382 * \ref MDBX_SAFE_NOSYNC and \ref MDBX_UTTERLY_NOSYNC), then
2383 * data is always written an flushed to disk when \ref mdbx_txn_commit() is
2384 * called. Otherwise \ref mdbx_env_sync() may be called to manually write and
2385 * flush unsynced data to disk.
2386 *
2387 * Besides, \ref mdbx_env_sync_ex() with argument `force=false` may be used to
2388 * provide polling mode for lazy/asynchronous sync in conjunction with
2389 * \ref mdbx_env_set_syncbytes() and/or \ref mdbx_env_set_syncperiod().
2390 *
2391 * \note This call is not valid if the environment was opened with MDBX_RDONLY.
2392 *
2393 * \param [in] env An environment handle returned by \ref mdbx_env_create()
2394 * \param [in] force If non-zero, force a flush. Otherwise, If force is
2395 * zero, then will run in polling mode,
2396 * i.e. it will check the thresholds that were
2397 * set \ref mdbx_env_set_syncbytes()
2398 * and/or \ref mdbx_env_set_syncperiod() and perform flush
2399 * if at least one of the thresholds is reached.
2400 *
2401 * \param [in] nonblock Don't wait if write transaction
2402 * is running by other thread.
2403 *
2404 * \returns A non-zero error value on failure and \ref MDBX_RESULT_TRUE or 0 on
2405 * success. The \ref MDBX_RESULT_TRUE means no data pending for flush
2406 * to disk, and 0 otherwise. Some possible errors are:
2407 *
2408 * \retval MDBX_EACCES the environment is read-only.
2409 * \retval MDBX_BUSY the environment is used by other thread
2410 * and `nonblock=true`.
2411 * \retval MDBX_EINVAL an invalid parameter was specified.
2412 * \retval MDBX_EIO an error occurred during synchronization. */
2413 LIBMDBX_API int mdbx_env_sync_ex(MDBX_env *env, bool force, bool nonblock);
2414
2415 /** \brief The shortcut to calling \ref mdbx_env_sync_ex() with
2416 * the `force=true` and `nonblock=false` arguments.
2417 * \ingroup c_extra */
2418 LIBMDBX_INLINE_API(int, mdbx_env_sync, (MDBX_env * env)) {
2419 return mdbx_env_sync_ex(env, true, false);
2420 }
2421
2422 /** \brief The shortcut to calling \ref mdbx_env_sync_ex() with
2423 * the `force=false` and `nonblock=true` arguments.
2424 * \ingroup c_extra */
2425 LIBMDBX_INLINE_API(int, mdbx_env_sync_poll, (MDBX_env * env)) {
2426 return mdbx_env_sync_ex(env, false, true);
2427 }
2428
2429 /** \brief Sets threshold to force flush the data buffers to disk, even any of
2430 * \ref MDBX_SAFE_NOSYNC flag in the environment.
2431 * \ingroup c_settings
2432 *
2433 * The threshold value affects all processes which operates with given
2434 * environment until the last process close environment or a new value will be
2435 * settled.
2436 *
2437 * Data is always written to disk when \ref mdbx_txn_commit() is called, but
2438 * the operating system may keep it buffered. MDBX always flushes the OS buffers
2439 * upon commit as well, unless the environment was opened with
2440 * \ref MDBX_SAFE_NOSYNC, \ref MDBX_UTTERLY_NOSYNC
2441 * or in part \ref MDBX_NOMETASYNC.
2442 *
2443 * The default is 0, than mean no any threshold checked, and no additional
2444 * flush will be made.
2445 *
2446 * \param [in] env An environment handle returned by mdbx_env_create().
2447 * \param [in] threshold The size in bytes of summary changes when
2448 * a synchronous flush would be made.
2449 *
2450 * \returns A non-zero error value on failure and 0 on success. */
2451 LIBMDBX_INLINE_API(int, mdbx_env_set_syncbytes,
2452 (MDBX_env * env, size_t threshold)) {
2453 return mdbx_env_set_option(env, MDBX_opt_sync_bytes, threshold);
2454 }
2455
2456 /** \brief Sets relative period since the last unsteady commit to force flush
2457 * the data buffers to disk, even of \ref MDBX_SAFE_NOSYNC flag in the
2458 * environment.
2459 *
2460 * \ingroup c_settings
2461 *
2462 * The relative period value affects all processes which operates with given
2463 * environment until the last process close environment or a new value will be
2464 * settled.
2465 *
2466 * Data is always written to disk when \ref mdbx_txn_commit() is called, but the
2467 * operating system may keep it buffered. MDBX always flushes the OS buffers
2468 * upon commit as well, unless the environment was opened with
2469 * \ref MDBX_SAFE_NOSYNC or in part \ref MDBX_NOMETASYNC.
2470 *
2471 * Settled period don't checked asynchronously, but only by the
2472 * \ref mdbx_txn_commit() and \ref mdbx_env_sync() functions. Therefore, in
2473 * cases where transactions are committed infrequently and/or irregularly,
2474 * polling by \ref mdbx_env_sync() may be a reasonable solution to timeout
2475 * enforcement.
2476 *
2477 * The default is 0, than mean no any timeout checked, and no additional
2478 * flush will be made.
2479 *
2480 * \param [in] env An environment handle returned by \ref mdbx_env_create().
2481 * \param [in] seconds_16dot16 The period in 1/65536 of second when
2482 * a synchronous flush would be made since
2483 * the last unsteady commit.
2484 *
2485 * \returns A non-zero error value on failure and 0 on success. */
2486 LIBMDBX_INLINE_API(int, mdbx_env_set_syncperiod,
2487 (MDBX_env * env, unsigned seconds_16dot16)) {
2488 return mdbx_env_set_option(env, MDBX_opt_sync_period, seconds_16dot16);
2489 }
2490
2491 /** \brief Close the environment and release the memory map.
2492 * \ingroup c_opening
2493 *
2494 * Only a single thread may call this function. All transactions, databases,
2495 * and cursors must already be closed before calling this function. Attempts
2496 * to use any such handles after calling this function will cause a `SIGSEGV`.
2497 * The environment handle will be freed and must not be used again after this
2498 * call.
2499 *
2500 * \param [in] env An environment handle returned by
2501 * \ref mdbx_env_create().
2502 *
2503 * \param [in] dont_sync A dont'sync flag, if non-zero the last checkpoint
2504 * will be kept "as is" and may be still "weak" in the
2505 * \ref MDBX_SAFE_NOSYNC or \ref MDBX_UTTERLY_NOSYNC
2506 * modes. Such "weak" checkpoint will be ignored on
2507 * opening next time, and transactions since the last
2508 * non-weak checkpoint (meta-page update) will rolledback
2509 * for consistency guarantee.
2510 *
2511 * \returns A non-zero error value on failure and 0 on success,
2512 * some possible errors are:
2513 * \retval MDBX_BUSY The write transaction is running by other thread,
2514 * in such case \ref MDBX_env instance has NOT be destroyed
2515 * not released!
2516 * \note If any OTHER error code was returned then
2517 * given MDBX_env instance has been destroyed and released.
2518 *
2519 * \retval MDBX_EBADSIGN Environment handle already closed or not valid,
2520 * i.e. \ref mdbx_env_close() was already called for the
2521 * `env` or was not created by \ref mdbx_env_create().
2522 *
2523 * \retval MDBX_PANIC If \ref mdbx_env_close_ex() was called in the child
2524 * process after `fork()`. In this case \ref MDBX_PANIC
2525 * is expected, i.e. \ref MDBX_env instance was freed in
2526 * proper manner.
2527 *
2528 * \retval MDBX_EIO An error occurred during synchronization. */
2529 LIBMDBX_API int mdbx_env_close_ex(MDBX_env *env, bool dont_sync);
2530
2531 /** \brief The shortcut to calling \ref mdbx_env_close_ex() with
2532 * the `dont_sync=false` argument.
2533 * \ingroup c_opening */
2534 LIBMDBX_INLINE_API(int, mdbx_env_close, (MDBX_env * env)) {
2535 return mdbx_env_close_ex(env, false);
2536 }
2537
2538 /** \brief Set environment flags.
2539 * \ingroup c_settings
2540 *
2541 * This may be used to set some flags in addition to those from
2542 * mdbx_env_open(), or to unset these flags.
2543 * \see mdbx_env_get_flags()
2544 *
2545 * \note In contrast to LMDB, the MDBX serialize threads via mutex while
2546 * changing the flags. Therefore this function will be blocked while a write
2547 * transaction running by other thread, or \ref MDBX_BUSY will be returned if
2548 * function called within a write transaction.
2549 *
2550 * \param [in] env An environment handle returned
2551 * by \ref mdbx_env_create().
2552 * \param [in] flags The \ref env_flags to change, bitwise OR'ed together.
2553 * \param [in] onoff A non-zero value sets the flags, zero clears them.
2554 *
2555 * \returns A non-zero error value on failure and 0 on success,
2556 * some possible errors are:
2557 * \retval MDBX_EINVAL An invalid parameter was specified. */
2558 LIBMDBX_API int mdbx_env_set_flags(MDBX_env *env, MDBX_env_flags_t flags,
2559 bool onoff);
2560
2561 /** \brief Get environment flags.
2562 * \ingroup c_statinfo
2563 * \see mdbx_env_set_flags()
2564 *
2565 * \param [in] env An environment handle returned by \ref mdbx_env_create().
2566 * \param [out] flags The address of an integer to store the flags.
2567 *
2568 * \returns A non-zero error value on failure and 0 on success,
2569 * some possible errors are:
2570 * \retval MDBX_EINVAL An invalid parameter was specified. */
2571 LIBMDBX_API int mdbx_env_get_flags(const MDBX_env *env, unsigned *flags);
2572
2573 /** \brief Return the path that was used in mdbx_env_open().
2574 * \ingroup c_statinfo
2575 *
2576 * \param [in] env An environment handle returned by \ref mdbx_env_create()
2577 * \param [out] dest Address of a string pointer to contain the path.
2578 * This is the actual string in the environment, not a
2579 * copy. It should not be altered in any way.
2580 *
2581 * \returns A non-zero error value on failure and 0 on success,
2582 * some possible errors are:
2583 * \retval MDBX_EINVAL An invalid parameter was specified. */
2584 LIBMDBX_API int mdbx_env_get_path(const MDBX_env *env, const char **dest);
2585
2586 /** \brief Return the file descriptor for the given environment.
2587 * \ingroup c_statinfo
2588 *
2589 * \note All MDBX file descriptors have `FD_CLOEXEC` and
2590 * couldn't be used after exec() and or `fork()`.
2591 *
2592 * \param [in] env An environment handle returned by \ref mdbx_env_create().
2593 * \param [out] fd Address of a int to contain the descriptor.
2594 *
2595 * \returns A non-zero error value on failure and 0 on success,
2596 * some possible errors are:
2597 * \retval MDBX_EINVAL An invalid parameter was specified. */
2598 LIBMDBX_API int mdbx_env_get_fd(const MDBX_env *env, mdbx_filehandle_t *fd);
2599
2600 /** \brief Set all size-related parameters of environment, including page size
2601 * and the min/max size of the memory map. \ingroup c_settings
2602 *
2603 * In contrast to LMDB, the MDBX provide automatic size management of an
2604 * database according the given parameters, including shrinking and resizing
2605 * on the fly. From user point of view all of these just working. Nevertheless,
2606 * it is reasonable to know some details in order to make optimal decisions
2607 * when choosing parameters.
2608 *
2609 * Both \ref mdbx_env_info_ex() and legacy \ref mdbx_env_info() are inapplicable
2610 * to read-only opened environment.
2611 *
2612 * Both \ref mdbx_env_info_ex() and legacy \ref mdbx_env_info() could be called
2613 * either before or after \ref mdbx_env_open(), either within the write
2614 * transaction running by current thread or not:
2615 *
2616 * - In case \ref mdbx_env_info_ex() or legacy \ref mdbx_env_info() was called
2617 * BEFORE \ref mdbx_env_open(), i.e. for closed environment, then the
2618 * specified parameters will be used for new database creation, or will be
2619 * applied during opening if database exists and no other process using it.
2620 *
2621 * If the database is already exist, opened with \ref MDBX_EXCLUSIVE or not
2622 * used by any other process, and parameters specified by
2623 * \ref mdbx_env_set_geometry() are incompatible (i.e. for instance,
2624 * different page size) then \ref mdbx_env_open() will return
2625 * \ref MDBX_INCOMPATIBLE error.
2626 *
2627 * In another way, if database will opened read-only or will used by other
2628 * process during calling \ref mdbx_env_open() that specified parameters will
2629 * silently discarded (open the database with \ref MDBX_EXCLUSIVE flag
2630 * to avoid this).
2631 *
2632 * - In case \ref mdbx_env_info_ex() or legacy \ref mdbx_env_info() was called
2633 * after \ref mdbx_env_open() WITHIN the write transaction running by current
2634 * thread, then specified parameters will be applied as a part of write
2635 * transaction, i.e. will not be visible to any others processes until the
2636 * current write transaction has been committed by the current process.
2637 * However, if transaction will be aborted, then the database file will be
2638 * reverted to the previous size not immediately, but when a next transaction
2639 * will be committed or when the database will be opened next time.
2640 *
2641 * - In case \ref mdbx_env_info_ex() or legacy \ref mdbx_env_info() was called
2642 * after \ref mdbx_env_open() but OUTSIDE a write transaction, then MDBX will
2643 * execute internal pseudo-transaction to apply new parameters (but only if
2644 * anything has been changed), and changes be visible to any others processes
2645 * immediately after succesful completion of function.
2646 *
2647 * Essentially a concept of "automatic size management" is simple and useful:
2648 * - There are the lower and upper bound of the database file size;
2649 * - There is the growth step by which the database file will be increased,
2650 * in case of lack of space.
2651 * - There is the threshold for unused space, beyond which the database file
2652 * will be shrunk.
2653 * - The size of the memory map is also the maximum size of the database.
2654 * - MDBX will automatically manage both the size of the database and the size
2655 * of memory map, according to the given parameters.
2656 *
2657 * So, there some considerations about choosing these parameters:
2658 * - The lower bound allows you to prevent database shrinking below some
2659 * rational size to avoid unnecessary resizing costs.
2660 * - The upper bound allows you to prevent database growth above some rational
2661 * size. Besides, the upper bound defines the linear address space
2662 * reservation in each process that opens the database. Therefore changing
2663 * the upper bound is costly and may be required reopening environment in
2664 * case of \ref MDBX_UNABLE_EXTEND_MAPSIZE errors, and so on. Therefore, this
2665 * value should be chosen reasonable as large as possible, to accommodate
2666 * future growth of the database.
2667 * - The growth step must be greater than zero to allow the database to grow,
2668 * but also reasonable not too small, since increasing the size by little
2669 * steps will result a large overhead.
2670 * - The shrink threshold must be greater than zero to allow the database
2671 * to shrink but also reasonable not too small (to avoid extra overhead) and
2672 * not less than growth step to avoid up-and-down flouncing.
2673 * - The current size (i.e. size_now argument) is an auxiliary parameter for
2674 * simulation legacy \ref mdbx_env_set_mapsize() and as workaround Windows
2675 * issues (see below).
2676 *
2677 * Unfortunately, Windows has is a several issues
2678 * with resizing of memory-mapped file:
2679 * - Windows unable shrinking a memory-mapped file (i.e memory-mapped section)
2680 * in any way except unmapping file entirely and then map again. Moreover,
2681 * it is impossible in any way if a memory-mapped file is used more than
2682 * one process.
2683 * - Windows does not provide the usual API to augment a memory-mapped file
2684 * (that is, a memory-mapped partition), but only by using "Native API"
2685 * in an undocumented way.
2686 *
2687 * MDBX bypasses all Windows issues, but at a cost:
2688 * - Ability to resize database on the fly requires an additional lock
2689 * and release `SlimReadWriteLock during` each read-only transaction.
2690 * - During resize all in-process threads should be paused and then resumed.
2691 * - Shrinking of database file is performed only when it used by single
2692 * process, i.e. when a database closes by the last process or opened
2693 * by the first.
2694 * = Therefore, the size_now argument may be useful to set database size
2695 * by the first process which open a database, and thus avoid expensive
2696 * remapping further.
2697 *
2698 * For create a new database with particular parameters, including the page
2699 * size, \ref mdbx_env_set_geometry() should be called after
2700 * \ref mdbx_env_create() and before mdbx_env_open(). Once the database is
2701 * created, the page size cannot be changed. If you do not specify all or some
2702 * of the parameters, the corresponding default values will be used. For
2703 * instance, the default for database size is 10485760 bytes.
2704 *
2705 * If the mapsize is increased by another process, MDBX silently and
2706 * transparently adopt these changes at next transaction start. However,
2707 * \ref mdbx_txn_begin() will return \ref MDBX_UNABLE_EXTEND_MAPSIZE if new
2708 * mapping size could not be applied for current process (for instance if
2709 * address space is busy). Therefore, in the case of
2710 * \ref MDBX_UNABLE_EXTEND_MAPSIZE error you need close and reopen the
2711 * environment to resolve error.
2712 *
2713 * \note Actual values may be different than your have specified because of
2714 * rounding to specified database page size, the system page size and/or the
2715 * size of the system virtual memory management unit. You can get actual values
2716 * by \ref mdbx_env_sync_ex() or see by using the tool `mdbx_chk` with the `-v`
2717 * option.
2718 *
2719 * Legacy \ref mdbx_env_set_mapsize() correspond to calling
2720 * \ref mdbx_env_set_geometry() with the arguments `size_lower`, `size_now`,
2721 * `size_upper` equal to the `size` and `-1` (i.e. default) for all other
2722 * parameters.
2723 *
2724 * \param [in] env An environment handle returned
2725 * by \ref mdbx_env_create()
2726 *
2727 * \param [in] size_lower The lower bound of database size in bytes.
2728 * Zero value means "minimal acceptable",
2729 * and negative means "keep current or use default".
2730 *
2731 * \param [in] size_now The size in bytes to setup the database size for
2732 * now. Zero value means "minimal acceptable", and
2733 * negative means "keep current or use default". So,
2734 * it is recommended always pass -1 in this argument
2735 * except some special cases.
2736 *
2737 * \param [in] size_upper The upper bound of database size in bytes.
2738 * Zero value means "minimal acceptable",
2739 * and negative means "keep current or use default".
2740 * It is recommended to avoid change upper bound while
2741 * database is used by other processes or threaded
2742 * (i.e. just pass -1 in this argument except absolutely
2743 * necessary). Otherwise you must be ready for
2744 * \ref MDBX_UNABLE_EXTEND_MAPSIZE error(s), unexpected
2745 * pauses during remapping and/or system errors like
2746 * "address busy", and so on. In other words, there
2747 * is no way to handle a growth of the upper bound
2748 * robustly because there may be a lack of appropriate
2749 * system resources (which are extremely volatile in
2750 * a multi-process multi-threaded environment).
2751 *
2752 * \param [in] growth_step The growth step in bytes, must be greater than
2753 * zero to allow the database to grow. Negative value
2754 * means "keep current or use default".
2755 *
2756 * \param [in] shrink_threshold The shrink threshold in bytes, must be greater
2757 * than zero to allow the database to shrink and
2758 * greater than growth_step to avoid shrinking
2759 * right after grow.
2760 * Negative value means "keep current
2761 * or use default". Default is 2*growth_step.
2762 *
2763 * \param [in] pagesize The database page size for new database
2764 * creation or -1 otherwise. Must be power of 2
2765 * in the range between \ref MDBX_MIN_PAGESIZE and
2766 * \ref MDBX_MAX_PAGESIZE. Zero value means
2767 * "minimal acceptable", and negative means
2768 * "keep current or use default".
2769 *
2770 * \returns A non-zero error value on failure and 0 on success,
2771 * some possible errors are:
2772 * \retval MDBX_EINVAL An invalid parameter was specified,
2773 * or the environment has an active write transaction.
2774 * \retval MDBX_EPERM Specific for Windows: Shrinking was disabled before
2775 * and now it wanna be enabled, but there are reading
2776 * threads that don't use the additional `SRWL` (that
2777 * is required to avoid Windows issues).
2778 * \retval MDBX_EACCESS The environment opened in read-only.
2779 * \retval MDBX_MAP_FULL Specified size smaller than the space already
2780 * consumed by the environment.
2781 * \retval MDBX_TOO_LARGE Specified size is too large, i.e. too many pages for
2782 * given size, or a 32-bit process requests too much
2783 * bytes for the 32-bit address space. */
2784 LIBMDBX_API int mdbx_env_set_geometry(MDBX_env *env, intptr_t size_lower,
2785 intptr_t size_now, intptr_t size_upper,
2786 intptr_t growth_step,
2787 intptr_t shrink_threshold,
2788 intptr_t pagesize);
2789
2790 /** \deprecated Please use \ref mdbx_env_set_geometry() instead.
2791 * \ingroup c_settings */
2792 MDBX_DEPRECATED LIBMDBX_INLINE_API(int, mdbx_env_set_mapsize,
2793 (MDBX_env * env, size_t size)) {
2794 return mdbx_env_set_geometry(env, size, size, size, -1, -1, -1);
2795 }
2796
2797 /** \brief Find out whether to use readahead or not, based on the given database
2798 * size and the amount of available memory. \ingroup c_extra
2799 *
2800 * \param [in] volume The expected database size in bytes.
2801 * \param [in] redundancy Additional reserve or overload in case of negative
2802 * value.
2803 *
2804 * \returns A \ref MDBX_RESULT_TRUE or \ref MDBX_RESULT_FALSE value,
2805 * otherwise the error code:
2806 * \retval MDBX_RESULT_TRUE Readahead is reasonable.
2807 * \retval MDBX_RESULT_FALSE Readahead is NOT reasonable,
2808 * i.e. \ref MDBX_NORDAHEAD is useful to
2809 * open environment by \ref mdbx_env_open().
2810 * \retval Otherwise the error code. */
2811 LIBMDBX_API int mdbx_is_readahead_reasonable(size_t volume,
2812 intptr_t redundancy);
2813
2814 /** \brief Returns the minimal database page size in bytes.
2815 * \ingroup c_statinfo */
2816 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_INLINE_API(intptr_t, mdbx_limits_pgsize_min,
2817 (void)) {
2818 return MDBX_MIN_PAGESIZE;
2819 }
2820
2821 /** \brief Returns the maximal database page size in bytes.
2822 * \ingroup c_statinfo */
2823 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_INLINE_API(intptr_t, mdbx_limits_pgsize_max,
2824 (void)) {
2825 return MDBX_MAX_PAGESIZE;
2826 }
2827
2828 /** \brief Returns minimal database size in bytes for given page size,
2829 * or -1 if pagesize is invalid.
2830 * \ingroup c_statinfo */
2831 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API intptr_t
2832 mdbx_limits_dbsize_min(intptr_t pagesize);
2833
2834 /** \brief Returns maximal database size in bytes for given page size,
2835 * or -1 if pagesize is invalid.
2836 * \ingroup c_statinfo */
2837 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API intptr_t
2838 mdbx_limits_dbsize_max(intptr_t pagesize);
2839
2840 /** \brief Returns maximal key size in bytes for given page size
2841 * and database flags, or -1 if pagesize is invalid.
2842 * \ingroup c_statinfo
2843 * \see db_flags */
2844 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API intptr_t
2845 mdbx_limits_keysize_max(intptr_t pagesize, MDBX_db_flags_t flags);
2846
2847 /** \brief Returns maximal data size in bytes for given page size
2848 * and database flags, or -1 if pagesize is invalid.
2849 * \ingroup c_statinfo
2850 * \see db_flags */
2851 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API intptr_t
2852 mdbx_limits_valsize_max(intptr_t pagesize, MDBX_db_flags_t flags);
2853
2854 /** \brief Returns maximal write transaction size (i.e. limit for summary volume
2855 * of dirty pages) in bytes for given page size, or -1 if pagesize is invalid.
2856 * \ingroup c_statinfo */
2857 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API intptr_t
2858 mdbx_limits_txnsize_max(intptr_t pagesize);
2859
2860 /** \brief Set the maximum number of threads/reader slots for for all processes
2861 * interacts with the database. \ingroup c_settings
2862 *
2863 * \details This defines the number of slots in the lock table that is used to
2864 * track readers in the the environment. The default is about 100 for 4K system
2865 * page size. Starting a read-only transaction normally ties a lock table slot
2866 * to the current thread until the environment closes or the thread exits. If
2867 * \ref MDBX_NOTLS is in use, \ref mdbx_txn_begin() instead ties the slot to the
2868 * \ref MDBX_txn object until it or the \ref MDBX_env object is destroyed.
2869 * This function may only be called after \ref mdbx_env_create() and before
2870 * \ref mdbx_env_open(), and has an effect only when the database is opened by
2871 * the first process interacts with the database.
2872 * \see mdbx_env_get_maxreaders()
2873 *
2874 * \param [in] env An environment handle returned
2875 * by \ref mdbx_env_create().
2876 * \param [in] readers The maximum number of reader lock table slots.
2877 *
2878 * \returns A non-zero error value on failure and 0 on success,
2879 * some possible errors are:
2880 * \retval MDBX_EINVAL An invalid parameter was specified.
2881 * \retval MDBX_EPERM The environment is already open. */
2882 LIBMDBX_INLINE_API(int, mdbx_env_set_maxreaders,
2883 (MDBX_env * env, unsigned readers)) {
2884 return mdbx_env_set_option(env, MDBX_opt_max_readers, readers);
2885 }
2886
2887 /** \brief Get the maximum number of threads/reader slots for the environment.
2888 * \ingroup c_statinfo
2889 * \see mdbx_env_set_maxreaders()
2890 *
2891 * \param [in] env An environment handle returned
2892 * by \ref mdbx_env_create().
2893 * \param [out] readers Address of an integer to store the number of readers.
2894 *
2895 * \returns A non-zero error value on failure and 0 on success,
2896 * some possible errors are:
2897 * \retval MDBX_EINVAL An invalid parameter was specified. */
2898 LIBMDBX_INLINE_API(int, mdbx_env_get_maxreaders,
2899 (const MDBX_env *env, unsigned *readers)) {
2900 int rc = MDBX_EINVAL;
2901 if (readers) {
2902 uint64_t proxy = 0;
2903 rc = mdbx_env_get_option(env, MDBX_opt_max_readers, &proxy);
2904 *readers = (unsigned)proxy;
2905 }
2906 return rc;
2907 }
2908
2909 /** \brief Set the maximum number of named databases for the environment.
2910 * \ingroup c_settings
2911 *
2912 * This function is only needed if multiple databases will be used in the
2913 * environment. Simpler applications that use the environment as a single
2914 * unnamed database can ignore this option.
2915 * This function may only be called after \ref mdbx_env_create() and before
2916 * \ref mdbx_env_open().
2917 *
2918 * Currently a moderate number of slots are cheap but a huge number gets
2919 * expensive: 7-120 words per transaction, and every \ref mdbx_dbi_open()
2920 * does a linear search of the opened slots.
2921 * \see mdbx_env_get_maxdbs()
2922 *
2923 * \param [in] env An environment handle returned by \ref mdbx_env_create().
2924 * \param [in] dbs The maximum number of databases.
2925 *
2926 * \returns A non-zero error value on failure and 0 on success,
2927 * some possible errors are:
2928 * \retval MDBX_EINVAL An invalid parameter was specified.
2929 * \retval MDBX_EPERM The environment is already open. */
2930 LIBMDBX_INLINE_API(int, mdbx_env_set_maxdbs, (MDBX_env * env, MDBX_dbi dbs)) {
2931 return mdbx_env_set_option(env, MDBX_opt_max_db, dbs);
2932 }
2933
2934 /** \brief Get the maximum number of named databases for the environment.
2935 * \ingroup c_statinfo
2936 * \see mdbx_env_set_maxdbs()
2937 *
2938 * \param [in] env An environment handle returned by \ref mdbx_env_create().
2939 * \param [out] dbs Address to store the maximum number of databases.
2940 *
2941 * \returns A non-zero error value on failure and 0 on success,
2942 * some possible errors are:
2943 * \retval MDBX_EINVAL An invalid parameter was specified. */
2944 LIBMDBX_INLINE_API(int, mdbx_env_get_maxdbs,
2945 (const MDBX_env *env, MDBX_dbi *dbs)) {
2946 int rc = MDBX_EINVAL;
2947 if (dbs) {
2948 uint64_t proxy = 0;
2949 rc = mdbx_env_get_option(env, MDBX_opt_max_db, &proxy);
2950 *dbs = (MDBX_dbi)proxy;
2951 }
2952 return rc;
2953 }
2954
2955 /** \brief Returns the default size of database page for the current system.
2956 * \ingroup c_statinfo
2957 * \details Default size of database page depends on the size of the system
2958 * page and usually exactly match it. */
2959 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API size_t mdbx_default_pagesize(void);
2960
2961 /** \brief Returns basic information about system RAM.
2962 * This function provides a portable way to get information about available RAM
2963 * and can be useful in that it returns the same information that libmdbx uses
2964 * internally to adjust various options and control readahead.
2965 * \ingroup c_statinfo
2966 *
2967 * \param [out] page_size Optional address where the system page size
2968 * will be stored.
2969 * \param [out] total_pages Optional address where the number of total RAM
2970 * pages will be stored.
2971 * \param [out] avail_pages Optional address where the number of
2972 * available/free RAM pages will be stored.
2973 *
2974 * \returns A non-zero error value on failure and 0 on success. */
2975 LIBMDBX_API int mdbx_get_sysraminfo(intptr_t *page_size, intptr_t *total_pages,
2976 intptr_t *avail_pages);
2977
2978 /** \brief Returns the maximum size of keys can put.
2979 * \ingroup c_statinfo
2980 *
2981 * \param [in] env An environment handle returned by \ref mdbx_env_create().
2982 * \param [in] flags Database options (\ref MDBX_DUPSORT, \ref MDBX_INTEGERKEY
2983 * and so on). \see db_flags
2984 *
2985 * \returns The maximum size of a key can write,
2986 * or -1 if something is wrong. */
2987 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int
2988 mdbx_env_get_maxkeysize_ex(const MDBX_env *env, MDBX_db_flags_t flags);
2989
2990 /** \brief Returns the maximum size of data we can put.
2991 * \ingroup c_statinfo
2992 *
2993 * \param [in] env An environment handle returned by \ref mdbx_env_create().
2994 * \param [in] flags Database options (\ref MDBX_DUPSORT, \ref MDBX_INTEGERKEY
2995 * and so on). \see db_flags
2996 *
2997 * \returns The maximum size of a data can write,
2998 * or -1 if something is wrong. */
2999 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int
3000 mdbx_env_get_maxvalsize_ex(const MDBX_env *env, MDBX_db_flags_t flags);
3001
3002 /** \deprecated Please use \ref mdbx_env_get_maxkeysize_ex()
3003 * and/or \ref mdbx_env_get_maxvalsize_ex()
3004 * \ingroup c_statinfo */
3005 MDBX_NOTHROW_PURE_FUNCTION MDBX_DEPRECATED LIBMDBX_API int
3006 mdbx_env_get_maxkeysize(const MDBX_env *env);
3007
3008 /** \brief Sets application information (a context pointer) associated with
3009 * the environment.
3010 * \see mdbx_env_get_userctx()
3011 * \ingroup c_settings
3012 *
3013 * \param [in] env An environment handle returned by \ref mdbx_env_create().
3014 * \param [in] ctx An arbitrary pointer for whatever the application needs.
3015 *
3016 * \returns A non-zero error value on failure and 0 on success. */
3017 LIBMDBX_API int mdbx_env_set_userctx(MDBX_env *env, void *ctx);
3018
3019 /** \brief Returns an application information (a context pointer) associated
3020 * with the environment.
3021 * \see mdbx_env_set_userctx()
3022 * \ingroup c_statinfo
3023 *
3024 * \param [in] env An environment handle returned by \ref mdbx_env_create()
3025 * \returns The pointer set by \ref mdbx_env_set_userctx()
3026 * or `NULL` if something wrong. */
3027 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API void *
3028 mdbx_env_get_userctx(const MDBX_env *env);
3029
3030 /** \brief Create a transaction with a user provided context pointer
3031 * for use with the environment.
3032 * \ingroup c_transactions
3033 *
3034 * The transaction handle may be discarded using \ref mdbx_txn_abort()
3035 * or \ref mdbx_txn_commit().
3036 * \see mdbx_txn_begin()
3037 *
3038 * \note A transaction and its cursors must only be used by a single thread,
3039 * and a thread may only have a single transaction at a time. If \ref MDBX_NOTLS
3040 * is in use, this does not apply to read-only transactions.
3041 *
3042 * \note Cursors may not span transactions.
3043 *
3044 * \param [in] env An environment handle returned by \ref mdbx_env_create().
3045 *
3046 * \param [in] parent If this parameter is non-NULL, the new transaction will
3047 * be a nested transaction, with the transaction indicated
3048 * by parent as its parent. Transactions may be nested
3049 * to any level. A parent transaction and its cursors may
3050 * not issue any other operations than mdbx_txn_commit and
3051 * \ref mdbx_txn_abort() while it has active child
3052 * transactions.
3053 *
3054 * \param [in] flags Special options for this transaction. This parameter
3055 * must be set to 0 or by bitwise OR'ing together one
3056 * or more of the values described here:
3057 * - \ref MDBX_RDONLY This transaction will not perform
3058 * any write operations.
3059 *
3060 * - \ref MDBX_TXN_TRY Do not block when starting
3061 * a write transaction.
3062 *
3063 * - \ref MDBX_SAFE_NOSYNC, \ref MDBX_NOMETASYNC.
3064 * Do not sync data to disk corresponding
3065 * to \ref MDBX_NOMETASYNC or \ref MDBX_SAFE_NOSYNC
3066 * description. \see sync_modes
3067 *
3068 * \param [out] txn Address where the new \ref MDBX_txn handle
3069 * will be stored.
3070 *
3071 * \param [in] context A pointer to application context to be associated with
3072 * created transaction and could be retrieved by
3073 * \ref mdbx_txn_get_userctx() until transaction finished.
3074 *
3075 * \returns A non-zero error value on failure and 0 on success,
3076 * some possible errors are:
3077 * \retval MDBX_PANIC A fatal error occurred earlier and the
3078 * environment must be shut down.
3079 * \retval MDBX_UNABLE_EXTEND_MAPSIZE Another process wrote data beyond
3080 * this MDBX_env's mapsize and this
3081 * environment map must be resized as well.
3082 * See \ref mdbx_env_set_mapsize().
3083 * \retval MDBX_READERS_FULL A read-only transaction was requested and
3084 * the reader lock table is full.
3085 * See \ref mdbx_env_set_maxreaders().
3086 * \retval MDBX_ENOMEM Out of memory.
3087 * \retval MDBX_BUSY The write transaction is already started by the
3088 * current thread. */
3089 LIBMDBX_API int mdbx_txn_begin_ex(MDBX_env *env, MDBX_txn *parent,
3090 MDBX_txn_flags_t flags, MDBX_txn **txn,
3091 void *context);
3092
3093 /** \brief Create a transaction for use with the environment.
3094 * \ingroup c_transactions
3095 *
3096 * The transaction handle may be discarded using \ref mdbx_txn_abort()
3097 * or \ref mdbx_txn_commit().
3098 * \see mdbx_txn_begin_ex()
3099 *
3100 * \note A transaction and its cursors must only be used by a single thread,
3101 * and a thread may only have a single transaction at a time. If \ref MDBX_NOTLS
3102 * is in use, this does not apply to read-only transactions.
3103 *
3104 * \note Cursors may not span transactions.
3105 *
3106 * \param [in] env An environment handle returned by \ref mdbx_env_create().
3107 *
3108 * \param [in] parent If this parameter is non-NULL, the new transaction will
3109 * be a nested transaction, with the transaction indicated
3110 * by parent as its parent. Transactions may be nested
3111 * to any level. A parent transaction and its cursors may
3112 * not issue any other operations than mdbx_txn_commit and
3113 * \ref mdbx_txn_abort() while it has active child
3114 * transactions.
3115 *
3116 * \param [in] flags Special options for this transaction. This parameter
3117 * must be set to 0 or by bitwise OR'ing together one
3118 * or more of the values described here:
3119 * - \ref MDBX_RDONLY This transaction will not perform
3120 * any write operations.
3121 *
3122 * - \ref MDBX_TXN_TRY Do not block when starting
3123 * a write transaction.
3124 *
3125 * - \ref MDBX_SAFE_NOSYNC, \ref MDBX_NOMETASYNC.
3126 * Do not sync data to disk corresponding
3127 * to \ref MDBX_NOMETASYNC or \ref MDBX_SAFE_NOSYNC
3128 * description. \see sync_modes
3129 *
3130 * \param [out] txn Address where the new \ref MDBX_txn handle
3131 * will be stored.
3132 *
3133 * \returns A non-zero error value on failure and 0 on success,
3134 * some possible errors are:
3135 * \retval MDBX_PANIC A fatal error occurred earlier and the
3136 * environment must be shut down.
3137 * \retval MDBX_UNABLE_EXTEND_MAPSIZE Another process wrote data beyond
3138 * this MDBX_env's mapsize and this
3139 * environment map must be resized as well.
3140 * See \ref mdbx_env_set_mapsize().
3141 * \retval MDBX_READERS_FULL A read-only transaction was requested and
3142 * the reader lock table is full.
3143 * See \ref mdbx_env_set_maxreaders().
3144 * \retval MDBX_ENOMEM Out of memory.
3145 * \retval MDBX_BUSY The write transaction is already started by the
3146 * current thread. */
3147 LIBMDBX_INLINE_API(int, mdbx_txn_begin,
3148 (MDBX_env * env, MDBX_txn *parent, MDBX_txn_flags_t flags,
3149 MDBX_txn **txn)) {
3150 return mdbx_txn_begin_ex(env, parent, flags, txn, NULL);
3151 }
3152
3153 /** \brief Sets application information associated (a context pointer) with the
3154 * transaction.
3155 * \ingroup c_transactions
3156 * \see mdbx_txn_get_userctx()
3157 *
3158 * \param [in] txn An transaction handle returned by \ref mdbx_txn_begin_ex()
3159 * or \ref mdbx_txn_begin().
3160 * \param [in] ctx An arbitrary pointer for whatever the application needs.
3161 *
3162 * \returns A non-zero error value on failure and 0 on success. */
3163 LIBMDBX_API int mdbx_txn_set_userctx(MDBX_txn *txn, void *ctx);
3164
3165 /** \brief Returns an application information (a context pointer) associated
3166 * with the transaction.
3167 * \ingroup c_transactions
3168 * \see mdbx_txn_set_userctx()
3169 *
3170 * \param [in] txn An transaction handle returned by \ref mdbx_txn_begin_ex()
3171 * or \ref mdbx_txn_begin().
3172 * \returns The pointer which was passed via the `context` parameter
3173 * of `mdbx_txn_begin_ex()` or set by \ref mdbx_txn_set_userctx(),
3174 * or `NULL` if something wrong. */
3175 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API void *
3176 mdbx_txn_get_userctx(const MDBX_txn *txn);
3177
3178 /** \brief Information about the transaction
3179 * \ingroup c_statinfo
3180 * \see mdbx_txn_info */
3181 struct MDBX_txn_info {
3182 /** The ID of the transaction. For a READ-ONLY transaction, this corresponds
3183 to the snapshot being read. */
3184 uint64_t txn_id;
3185
3186 /** For READ-ONLY transaction: the lag from a recent MVCC-snapshot, i.e. the
3187 number of committed transaction since read transaction started.
3188 For WRITE transaction (provided if `scan_rlt=true`): the lag of the oldest
3189 reader from current transaction (i.e. at least 1 if any reader running). */
3190 uint64_t txn_reader_lag;
3191
3192 /** Used space by this transaction, i.e. corresponding to the last used
3193 * database page. */
3194 uint64_t txn_space_used;
3195
3196 /** Current size of database file. */
3197 uint64_t txn_space_limit_soft;
3198
3199 /** Upper bound for size the database file, i.e. the value `size_upper`
3200 argument of the appropriate call of \ref mdbx_env_set_geometry(). */
3201 uint64_t txn_space_limit_hard;
3202
3203 /** For READ-ONLY transaction: The total size of the database pages that were
3204 retired by committed write transactions after the reader's MVCC-snapshot,
3205 i.e. the space which would be freed after the Reader releases the
3206 MVCC-snapshot for reuse by completion read transaction.
3207 For WRITE transaction: The summarized size of the database pages that were
3208 retired for now due Copy-On-Write during this transaction. */
3209 uint64_t txn_space_retired;
3210
3211 /** For READ-ONLY transaction: the space available for writer(s) and that
3212 must be exhausted for reason to call the Handle-Slow-Readers callback for
3213 this read transaction.
3214 For WRITE transaction: the space inside transaction
3215 that left to `MDBX_TXN_FULL` error. */
3216 uint64_t txn_space_leftover;
3217
3218 /** For READ-ONLY transaction (provided if `scan_rlt=true`): The space that
3219 actually become available for reuse when only this transaction will be
3220 finished.
3221 For WRITE transaction: The summarized size of the dirty database
3222 pages that generated during this transaction. */
3223 uint64_t txn_space_dirty;
3224 };
3225 #ifndef __cplusplus
3226 /** \ingroup c_statinfo */
3227 typedef struct MDBX_txn_info MDBX_txn_info;
3228 #endif
3229
3230 /** \brief Return information about the MDBX transaction.
3231 * \ingroup c_statinfo
3232 *
3233 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin()
3234 * \param [out] info The address of an \ref MDBX_txn_info structure
3235 * where the information will be copied.
3236 * \param [in] scan_rlt The boolean flag controls the scan of the read lock
3237 * table to provide complete information. Such scan
3238 * is relatively expensive and you can avoid it
3239 * if corresponding fields are not needed.
3240 * See description of \ref MDBX_txn_info.
3241 *
3242 * \returns A non-zero error value on failure and 0 on success. */
3243 LIBMDBX_API int mdbx_txn_info(const MDBX_txn *txn, MDBX_txn_info *info,
3244 bool scan_rlt);
3245
3246 /** \brief Returns the transaction's MDBX_env.
3247 * \ingroup c_transactions
3248 *
3249 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin() */
3250 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API MDBX_env *
3251 mdbx_txn_env(const MDBX_txn *txn);
3252
3253 /** \brief Return the transaction's flags.
3254 * \ingroup c_transactions
3255 *
3256 * This returns the flags associated with this transaction.
3257 *
3258 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
3259 *
3260 * \returns A transaction flags, valid if input is an valid transaction,
3261 * otherwise -1. */
3262 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int mdbx_txn_flags(const MDBX_txn *txn);
3263
3264 /** \brief Return the transaction's ID.
3265 * \ingroup c_statinfo
3266 *
3267 * This returns the identifier associated with this transaction. For a
3268 * read-only transaction, this corresponds to the snapshot being read;
3269 * concurrent readers will frequently have the same transaction ID.
3270 *
3271 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
3272 *
3273 * \returns A transaction ID, valid if input is an active transaction,
3274 * otherwise 0. */
3275 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API uint64_t
3276 mdbx_txn_id(const MDBX_txn *txn);
3277
3278 /** \brief Latency of commit stages in 1/65536 of seconds units.
3279 * \warning This structure may be changed in future releases.
3280 * \see mdbx_txn_commit_ex() */
3281 struct MDBX_commit_latency {
3282 /** \brief Duration of preparation (commit child transactions, update
3283 * sub-databases records and cursors destroying). */
3284 uint32_t preparation;
3285 /** \brief Duration of GC/freeDB handling & updation. */
3286 uint32_t gc;
3287 /** \brief Duration of internal audit if enabled. */
3288 uint32_t audit;
3289 /** \brief Duration of writing dirty/modified data pages to a filesystem,
3290 * i.e. the summary duration of a `write()` syscalls during commit. */
3291 uint32_t write;
3292 /** \brief Duration of syncing written data to the disk/storage, i.e.
3293 * the duration of a `fdatasync()` or a `msync()` syscall during commit. */
3294 uint32_t sync;
3295 /** \brief Duration of transaction ending (releasing resources). */
3296 uint32_t ending;
3297 /** \brief The total duration of a commit. */
3298 uint32_t whole;
3299 };
3300 #ifndef __cplusplus
3301 /** \ingroup c_statinfo */
3302 typedef struct MDBX_commit_latency MDBX_commit_latency;
3303 #endif
3304
3305 /** \brief Commit all the operations of a transaction into the database and
3306 * collect latency information.
3307 * \see mdbx_txn_commit()
3308 * \ingroup c_statinfo
3309 * \warning This function may be changed in future releases. */
3310 LIBMDBX_API int mdbx_txn_commit_ex(MDBX_txn *txn, MDBX_commit_latency *latency);
3311
3312 /** \brief Commit all the operations of a transaction into the database.
3313 * \ingroup c_transactions
3314 *
3315 * If the current thread is not eligible to manage the transaction then
3316 * the \ref MDBX_THREAD_MISMATCH error will returned. Otherwise the transaction
3317 * will be committed and its handle is freed. If the transaction cannot
3318 * be committed, it will be aborted with the corresponding error returned.
3319 *
3320 * Thus, a result other than \ref MDBX_THREAD_MISMATCH means that the
3321 * transaction is terminated:
3322 * - Resources are released;
3323 * - Transaction handle is invalid;
3324 * - Cursor(s) associated with transaction must not be used, except with
3325 * mdbx_cursor_renew() and \ref mdbx_cursor_close().
3326 * Such cursor(s) must be closed explicitly by \ref mdbx_cursor_close()
3327 * before or after transaction commit, either can be reused with
3328 * \ref mdbx_cursor_renew() until it will be explicitly closed by
3329 * \ref mdbx_cursor_close().
3330 *
3331 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
3332 *
3333 * \returns A non-zero error value on failure and 0 on success,
3334 * some possible errors are:
3335 * \retval MDBX_RESULT_TRUE Transaction was aborted since it should
3336 * be aborted due to previous errors.
3337 * \retval MDBX_PANIC A fatal error occurred earlier
3338 * and the environment must be shut down.
3339 * \retval MDBX_BAD_TXN Transaction is already finished or never began.
3340 * \retval MDBX_EBADSIGN Transaction object has invalid signature,
3341 * e.g. transaction was already terminated
3342 * or memory was corrupted.
3343 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned
3344 * by current thread.
3345 * \retval MDBX_EINVAL Transaction handle is NULL.
3346 * \retval MDBX_ENOSPC No more disk space.
3347 * \retval MDBX_EIO A system-level I/O error occurred.
3348 * \retval MDBX_ENOMEM Out of memory. */
3349 LIBMDBX_INLINE_API(int, mdbx_txn_commit, (MDBX_txn * txn)) {
3350 return mdbx_txn_commit_ex(txn, NULL);
3351 }
3352
3353 /** \brief Abandon all the operations of the transaction instead of saving them.
3354 * \ingroup c_transactions
3355 *
3356 * The transaction handle is freed. It and its cursors must not be used again
3357 * after this call, except with \ref mdbx_cursor_renew() and
3358 * \ref mdbx_cursor_close().
3359 *
3360 * If the current thread is not eligible to manage the transaction then
3361 * the \ref MDBX_THREAD_MISMATCH error will returned. Otherwise the transaction
3362 * will be aborted and its handle is freed. Thus, a result other than
3363 * \ref MDBX_THREAD_MISMATCH means that the transaction is terminated:
3364 * - Resources are released;
3365 * - Transaction handle is invalid;
3366 * - Cursor(s) associated with transaction must not be used, except with
3367 * \ref mdbx_cursor_renew() and \ref mdbx_cursor_close().
3368 * Such cursor(s) must be closed explicitly by \ref mdbx_cursor_close()
3369 * before or after transaction abort, either can be reused with
3370 * \ref mdbx_cursor_renew() until it will be explicitly closed by
3371 * \ref mdbx_cursor_close().
3372 *
3373 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
3374 *
3375 * \returns A non-zero error value on failure and 0 on success,
3376 * some possible errors are:
3377 * \retval MDBX_PANIC A fatal error occurred earlier and
3378 * the environment must be shut down.
3379 * \retval MDBX_BAD_TXN Transaction is already finished or never began.
3380 * \retval MDBX_EBADSIGN Transaction object has invalid signature,
3381 * e.g. transaction was already terminated
3382 * or memory was corrupted.
3383 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned
3384 * by current thread.
3385 * \retval MDBX_EINVAL Transaction handle is NULL. */
3386 LIBMDBX_API int mdbx_txn_abort(MDBX_txn *txn);
3387
3388 /** \brief Marks transaction as broken.
3389 * \ingroup c_transactions
3390 *
3391 * Function keeps the transaction handle and corresponding locks, but makes
3392 * impossible to perform any operations within a broken transaction.
3393 * Broken transaction must then be aborted explicitly later.
3394 *
3395 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
3396 *
3397 * \see mdbx_txn_abort() \see mdbx_txn_reset() \see mdbx_txn_commit()
3398 * \returns A non-zero error value on failure and 0 on success. */
3399 LIBMDBX_API int mdbx_txn_break(MDBX_txn *txn);
3400
3401 /** \brief Reset a read-only transaction.
3402 * \ingroup c_transactions
3403 *
3404 * Abort the read-only transaction like \ref mdbx_txn_abort(), but keep the
3405 * transaction handle. Therefore \ref mdbx_txn_renew() may reuse the handle.
3406 * This saves allocation overhead if the process will start a new read-only
3407 * transaction soon, and also locking overhead if \ref MDBX_NOTLS is in use. The
3408 * reader table lock is released, but the table slot stays tied to its thread
3409 * or \ref MDBX_txn. Use \ref mdbx_txn_abort() to discard a reset handle, and to
3410 * free its lock table slot if \ref MDBX_NOTLS is in use.
3411 *
3412 * Cursors opened within the transaction must not be used again after this
3413 * call, except with \ref mdbx_cursor_renew() and \ref mdbx_cursor_close().
3414 *
3415 * Reader locks generally don't interfere with writers, but they keep old
3416 * versions of database pages allocated. Thus they prevent the old pages from
3417 * being reused when writers commit new data, and so under heavy load the
3418 * database size may grow much more rapidly than otherwise.
3419 *
3420 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
3421 *
3422 * \returns A non-zero error value on failure and 0 on success,
3423 * some possible errors are:
3424 * \retval MDBX_PANIC A fatal error occurred earlier and
3425 * the environment must be shut down.
3426 * \retval MDBX_BAD_TXN Transaction is already finished or never began.
3427 * \retval MDBX_EBADSIGN Transaction object has invalid signature,
3428 * e.g. transaction was already terminated
3429 * or memory was corrupted.
3430 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned
3431 * by current thread.
3432 * \retval MDBX_EINVAL Transaction handle is NULL. */
3433 LIBMDBX_API int mdbx_txn_reset(MDBX_txn *txn);
3434
3435 /** \brief Renew a read-only transaction.
3436 * \ingroup c_transactions
3437 *
3438 * This acquires a new reader lock for a transaction handle that had been
3439 * released by \ref mdbx_txn_reset(). It must be called before a reset
3440 * transaction may be used again.
3441 *
3442 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
3443 *
3444 * \returns A non-zero error value on failure and 0 on success,
3445 * some possible errors are:
3446 * \retval MDBX_PANIC A fatal error occurred earlier and
3447 * the environment must be shut down.
3448 * \retval MDBX_BAD_TXN Transaction is already finished or never began.
3449 * \retval MDBX_EBADSIGN Transaction object has invalid signature,
3450 * e.g. transaction was already terminated
3451 * or memory was corrupted.
3452 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned
3453 * by current thread.
3454 * \retval MDBX_EINVAL Transaction handle is NULL. */
3455 LIBMDBX_API int mdbx_txn_renew(MDBX_txn *txn);
3456
3457 /** \brief The fours integers markers (aka "canary") associated with the
3458 * environment. \ingroup c_crud \see mdbx_canary_set() \see mdbx_canary_get()
3459 *
3460 * The `x`, `y` and `z` values could be set by \ref mdbx_canary_put(), while the
3461 * 'v' will be always set to the transaction number. Updated values becomes
3462 * visible outside the current transaction only after it was committed. Current
3463 * values could be retrieved by \ref mdbx_canary_get(). */
3464 struct MDBX_canary {
3465 uint64_t x, y, z, v;
3466 };
3467 #ifndef __cplusplus
3468 /** \ingroup c_crud */
3469 typedef struct MDBX_canary MDBX_canary;
3470 #endif
3471
3472 /** \brief Set integers markers (aka "canary") associated with the environment.
3473 * \ingroup c_crud
3474 * \see mdbx_canary_get()
3475 *
3476 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin()
3477 * \param [in] canary A optional pointer to \ref MDBX_canary structure for `x`,
3478 * `y` and `z` values from.
3479 * - If canary is NOT NULL then the `x`, `y` and `z` values will be
3480 * updated from given canary argument, but the 'v' be always set
3481 * to the current transaction number if at least one `x`, `y` or
3482 * `z` values have changed (i.e. if `x`, `y` and `z` have the same
3483 * values as currently present then nothing will be changes or
3484 * updated).
3485 * - if canary is NULL then the `v` value will be explicitly update
3486 * to the current transaction number without changes `x`, `y` nor
3487 * `z`.
3488 *
3489 * \returns A non-zero error value on failure and 0 on success. */
3490 LIBMDBX_API int mdbx_canary_put(MDBX_txn *txn, const MDBX_canary *canary);
3491
3492 /** \brief Returns fours integers markers (aka "canary") associated with the
3493 * environment.
3494 * \ingroup c_crud
3495 * \see mdbx_canary_set()
3496 *
3497 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
3498 * \param [in] canary The address of an MDBX_canary structure where the
3499 * information will be copied.
3500 *
3501 * \returns A non-zero error value on failure and 0 on success. */
3502 LIBMDBX_API int mdbx_canary_get(const MDBX_txn *txn, MDBX_canary *canary);
3503
3504 /** \brief A callback function used to compare two keys in a database
3505 * \ingroup c_crud
3506 * \see mdbx_cmp() \see mdbx_get_keycmp()
3507 * \see mdbx_get_datacmp \see mdbx_dcmp()
3508 *
3509 * \anchor avoid_custom_comparators
3510 * It is recommend not using custom comparison functions, but instead
3511 * converting the keys to one of the forms that are suitable for built-in
3512 * comparators (for instance take look to the \ref value2key).
3513 * The reasons to not using custom comparators are:
3514 * - The order of records could not be validated without your code.
3515 * So `mdbx_chk` utility will reports "wrong order" errors
3516 * and the `-i` option is required to suppress ones.
3517 * - A records could not be ordered or sorted without your code.
3518 * So `mdbx_load` utility should be used with `-a` option to preserve
3519 * input data order.
3520 * - However, the custom comparators feature will never be removed.
3521 * You have been warned but still can use custom comparators knowing
3522 * about the issues noted above. In this case you should ignore `deprecated`
3523 * warnings or define `MDBX_DEPRECATED` macro to empty to avoid ones. */
3524 typedef int(MDBX_cmp_func)(const MDBX_val *a,
3525 const MDBX_val *b) MDBX_CXX17_NOEXCEPT;
3526
3527 /** \brief Open or Create a database in the environment.
3528 * \ingroup c_dbi
3529 *
3530 * A database handle denotes the name and parameters of a database,
3531 * independently of whether such a database exists. The database handle may be
3532 * discarded by calling \ref mdbx_dbi_close(). The old database handle is
3533 * returned if the database was already open. The handle may only be closed
3534 * once.
3535 *
3536 * \note A notable difference between MDBX and LMDB is that MDBX make handles
3537 * opened for existing databases immediately available for other transactions,
3538 * regardless this transaction will be aborted or reset. The REASON for this is
3539 * to avoiding the requirement for multiple opening a same handles in
3540 * concurrent read transactions, and tracking of such open but hidden handles
3541 * until the completion of read transactions which opened them.
3542 *
3543 * Nevertheless, the handle for the NEWLY CREATED database will be invisible
3544 * for other transactions until the this write transaction is successfully
3545 * committed. If the write transaction is aborted the handle will be closed
3546 * automatically. After a successful commit the such handle will reside in the
3547 * shared environment, and may be used by other transactions.
3548 *
3549 * In contrast to LMDB, the MDBX allow this function to be called from multiple
3550 * concurrent transactions or threads in the same process.
3551 *
3552 * To use named database (with name != NULL), \ref mdbx_env_set_maxdbs()
3553 * must be called before opening the environment. Table names are
3554 * keys in the internal unnamed database, and may be read but not written.
3555 *
3556 * \param [in] txn transaction handle returned by \ref mdbx_txn_begin().
3557 * \param [in] name The name of the database to open. If only a single
3558 * database is needed in the environment,
3559 * this value may be NULL.
3560 * \param [in] flags Special options for this database. This parameter must
3561 * be set to 0 or by bitwise OR'ing together one or more
3562 * of the values described here:
3563 * - \ref MDBX_REVERSEKEY
3564 * Keys are strings to be compared in reverse order, from the end
3565 * of the strings to the beginning. By default, Keys are treated as
3566 * strings and compared from beginning to end.
3567 * - \ref MDBX_INTEGERKEY
3568 * Keys are binary integers in native byte order, either uint32_t or
3569 * uint64_t, and will be sorted as such. The keys must all be of the
3570 * same size and must be aligned while passing as arguments.
3571 * - \ref MDBX_DUPSORT
3572 * Duplicate keys may be used in the database. Or, from another point of
3573 * view, keys may have multiple data items, stored in sorted order. By
3574 * default keys must be unique and may have only a single data item.
3575 * - \ref MDBX_DUPFIXED
3576 * This flag may only be used in combination with \ref MDBX_DUPSORT. This
3577 * option tells the library that the data items for this database are
3578 * all the same size, which allows further optimizations in storage and
3579 * retrieval. When all data items are the same size, the
3580 * \ref MDBX_GET_MULTIPLE, \ref MDBX_NEXT_MULTIPLE and
3581 * \ref MDBX_PREV_MULTIPLE cursor operations may be used to retrieve
3582 * multiple items at once.
3583 * - \ref MDBX_INTEGERDUP
3584 * This option specifies that duplicate data items are binary integers,
3585 * similar to \ref MDBX_INTEGERKEY keys. The data values must all be of the
3586 * same size and must be aligned while passing as arguments.
3587 * - \ref MDBX_REVERSEDUP
3588 * This option specifies that duplicate data items should be compared as
3589 * strings in reverse order (the comparison is performed in the direction
3590 * from the last byte to the first).
3591 * - \ref MDBX_CREATE
3592 * Create the named database if it doesn't exist. This option is not
3593 * allowed in a read-only transaction or a read-only environment.
3594 *
3595 * \param [out] dbi Address where the new \ref MDBX_dbi handle
3596 * will be stored.
3597 *
3598 * For \ref mdbx_dbi_open_ex() additional arguments allow you to set custom
3599 * comparison functions for keys and values (for multimaps).
3600 * \see avoid_custom_comparators
3601 *
3602 * \returns A non-zero error value on failure and 0 on success,
3603 * some possible errors are:
3604 * \retval MDBX_NOTFOUND The specified database doesn't exist in the
3605 * environment and \ref MDBX_CREATE was not specified.
3606 * \retval MDBX_DBS_FULL Too many databases have been opened.
3607 * \see mdbx_env_set_maxdbs()
3608 * \retval MDBX_INCOMPATIBLE Database is incompatible with given flags,
3609 * i.e. the passed flags is different with which the
3610 * database was created, or the database was already
3611 * opened with a different comparison function(s).
3612 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned
3613 * by current thread. */
3614 LIBMDBX_API int mdbx_dbi_open(MDBX_txn *txn, const char *name,
3615 MDBX_db_flags_t flags, MDBX_dbi *dbi);
3616
3617 /** \deprecated Please
3618 * \ref avoid_custom_comparators "avoid using custom comparators" and use
3619 * \ref mdbx_dbi_open() instead.
3620 *
3621 * \ingroup c_dbi
3622 *
3623 * \param [in] txn transaction handle returned by \ref mdbx_txn_begin().
3624 * \param [in] name The name of the database to open. If only a single
3625 * database is needed in the environment,
3626 * this value may be NULL.
3627 * \param [in] flags Special options for this database.
3628 * \param [in] keycmp Optional custom key comparison function for a database.
3629 * \param [in] datacmp Optional custom data comparison function for a database.
3630 * \param [out] dbi Address where the new MDBX_dbi handle will be stored.
3631 * \returns A non-zero error value on failure and 0 on success. */
3632 MDBX_DEPRECATED LIBMDBX_API int
3633 mdbx_dbi_open_ex(MDBX_txn *txn, const char *name, MDBX_db_flags_t flags,
3634 MDBX_dbi *dbi, MDBX_cmp_func *keycmp, MDBX_cmp_func *datacmp);
3635
3636 /** \defgroup value2key Value-to-Key functions
3637 * \brief Value-to-Key functions to
3638 * \ref avoid_custom_comparators "avoid using custom comparators"
3639 * \see key2value
3640 * @{
3641 *
3642 * The \ref mdbx_key_from_jsonInteger() build a keys which are comparable with
3643 * keys created by \ref mdbx_key_from_double(). So this allows mixing `int64_t`
3644 * and IEEE754 double values in one index for JSON-numbers with restriction for
3645 * integer numbers range corresponding to RFC-7159, i.e. \f$[-2^{53}+1,
3646 * 2^{53}-1]\f$. See bottom of page 6 at https://tools.ietf.org/html/rfc7159 */
3647 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API uint64_t
3648 mdbx_key_from_jsonInteger(const int64_t json_integer);
3649
3650 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API uint64_t
3651 mdbx_key_from_double(const double ieee754_64bit);
3652
3653 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API uint64_t
3654 mdbx_key_from_ptrdouble(const double *const ieee754_64bit);
3655
3656 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API uint32_t
3657 mdbx_key_from_float(const float ieee754_32bit);
3658
3659 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API uint32_t
3660 mdbx_key_from_ptrfloat(const float *const ieee754_32bit);
3661
3662 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_INLINE_API(uint64_t, mdbx_key_from_int64,
3663 (const int64_t i64)) {
3664 return UINT64_C(0x8000000000000000) + i64;
3665 }
3666
3667 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_INLINE_API(uint32_t, mdbx_key_from_int32,
3668 (const int32_t i32)) {
3669 return UINT32_C(0x80000000) + i32;
3670 }
3671 /** @} */
3672
3673 /** \defgroup key2value Key-to-Value functions
3674 * \brief Key-to-Value functions to
3675 * \ref avoid_custom_comparators "avoid using custom comparators"
3676 * \see value2key
3677 * @{ */
3678 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int64_t
3679 mdbx_jsonInteger_from_key(const MDBX_val);
3680
3681 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API double
3682 mdbx_double_from_key(const MDBX_val);
3683
3684 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API float
3685 mdbx_float_from_key(const MDBX_val);
3686
3687 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int32_t
3688 mdbx_int32_from_key(const MDBX_val);
3689
3690 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int64_t
3691 mdbx_int64_from_key(const MDBX_val);
3692 /** @} */
3693
3694 /** \brief Retrieve statistics for a database.
3695 * \ingroup c_statinfo
3696 *
3697 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
3698 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
3699 * \param [out] stat The address of an \ref MDBX_stat structure where
3700 * the statistics will be copied.
3701 * \param [in] bytes The size of \ref MDBX_stat.
3702 *
3703 * \returns A non-zero error value on failure and 0 on success,
3704 * some possible errors are:
3705 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned
3706 * by current thread.
3707 * \retval MDBX_EINVAL An invalid parameter was specified. */
3708 LIBMDBX_API int mdbx_dbi_stat(MDBX_txn *txn, MDBX_dbi dbi, MDBX_stat *stat,
3709 size_t bytes);
3710
3711 /** \brief Retrieve depth (bitmask) information of nested dupsort (multi-value)
3712 * B+trees for given database.
3713 * \ingroup c_statinfo
3714 *
3715 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
3716 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
3717 * \param [out] mask The address of an uint32_t value where the bitmask
3718 * will be stored.
3719 *
3720 * \returns A non-zero error value on failure and 0 on success,
3721 * some possible errors are:
3722 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned
3723 * by current thread.
3724 * \retval MDBX_EINVAL An invalid parameter was specified.
3725 * \retval MDBX_RESULT_TRUE The dbi isn't a dupsort (multi-value) database. */
3726 LIBMDBX_API int mdbx_dbi_dupsort_depthmask(MDBX_txn *txn, MDBX_dbi dbi,
3727 uint32_t *mask);
3728
3729 /** \brief DBI state bits returted by \ref mdbx_dbi_flags_ex()
3730 * \ingroup c_statinfo
3731 * \see mdbx_dbi_flags_ex() */
3732 enum MDBX_dbi_state_t {
3733 /** DB was written in this txn */
3734 MDBX_DBI_DIRTY = 0x01,
3735 /** Named-DB record is older than txnID */
3736 MDBX_DBI_STALE = 0x02,
3737 /** Named-DB handle opened in this txn */
3738 MDBX_DBI_FRESH = 0x04,
3739 /** Named-DB handle created in this txn */
3740 MDBX_DBI_CREAT = 0x08,
3741 };
3742 #ifndef __cplusplus
3743 /** \ingroup c_statinfo */
3744 typedef enum MDBX_dbi_state_t MDBX_dbi_state_t;
3745 #else
3746 DEFINE_ENUM_FLAG_OPERATORS(MDBX_dbi_state_t)
3747 #endif
3748
3749 /** \brief Retrieve the DB flags and status for a database handle.
3750 * \ingroup c_statinfo
3751 *
3752 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
3753 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
3754 * \param [out] flags Address where the flags will be returned.
3755 * \param [out] state Address where the state will be returned.
3756 *
3757 * \returns A non-zero error value on failure and 0 on success. */
3758 LIBMDBX_API int mdbx_dbi_flags_ex(MDBX_txn *txn, MDBX_dbi dbi, unsigned *flags,
3759 unsigned *state);
3760 /** \brief The shortcut to calling \ref mdbx_dbi_flags_ex() with `state=NULL`
3761 * for discarding it result. \ingroup c_statinfo */
3762 LIBMDBX_INLINE_API(int, mdbx_dbi_flags,
3763 (MDBX_txn * txn, MDBX_dbi dbi, unsigned *flags)) {
3764 unsigned state;
3765 return mdbx_dbi_flags_ex(txn, dbi, flags, &state);
3766 }
3767
3768 /** \brief Close a database handle. Normally unnecessary.
3769 * \ingroup c_dbi
3770 *
3771 * Closing a database handle is not necessary, but lets \ref mdbx_dbi_open()
3772 * reuse the handle value. Usually it's better to set a bigger
3773 * \ref mdbx_env_set_maxdbs(), unless that value would be large.
3774 *
3775 * \note Use with care.
3776 * This call is synchronized via mutex with \ref mdbx_dbi_close(), but NOT with
3777 * other transactions running by other threads. The "next" version of libmdbx
3778 * (\ref MithrilDB) will solve this issue.
3779 *
3780 * Handles should only be closed if no other threads are going to reference
3781 * the database handle or one of its cursors any further. Do not close a handle
3782 * if an existing transaction has modified its database. Doing so can cause
3783 * misbehavior from database corruption to errors like \ref MDBX_BAD_DBI
3784 * (since the DB name is gone).
3785 *
3786 * \param [in] env An environment handle returned by \ref mdbx_env_create().
3787 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
3788 *
3789 * \returns A non-zero error value on failure and 0 on success. */
3790 LIBMDBX_API int mdbx_dbi_close(MDBX_env *env, MDBX_dbi dbi);
3791
3792 /** \brief Empty or delete and close a database.
3793 * \ingroup c_crud
3794 *
3795 * \see mdbx_dbi_close() \see mdbx_dbi_open()
3796 *
3797 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
3798 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
3799 * \param [in] del `false` to empty the DB, `true` to delete it
3800 * from the environment and close the DB handle.
3801 *
3802 * \returns A non-zero error value on failure and 0 on success. */
3803 LIBMDBX_API int mdbx_drop(MDBX_txn *txn, MDBX_dbi dbi, bool del);
3804
3805 /** \brief Get items from a database.
3806 * \ingroup c_crud
3807 *
3808 * This function retrieves key/data pairs from the database. The address
3809 * and length of the data associated with the specified key are returned
3810 * in the structure to which data refers.
3811 * If the database supports duplicate keys (\ref MDBX_DUPSORT) then the
3812 * first data item for the key will be returned. Retrieval of other
3813 * items requires the use of \ref mdbx_cursor_get().
3814 *
3815 * \note The memory pointed to by the returned values is owned by the
3816 * database. The caller need not dispose of the memory, and may not
3817 * modify it in any way. For values returned in a read-only transaction
3818 * any modification attempts will cause a `SIGSEGV`.
3819 *
3820 * \note Values returned from the database are valid only until a
3821 * subsequent update operation, or the end of the transaction.
3822 *
3823 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
3824 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
3825 * \param [in] key The key to search for in the database.
3826 * \param [in,out] data The data corresponding to the key.
3827 *
3828 * \returns A non-zero error value on failure and 0 on success,
3829 * some possible errors are:
3830 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned
3831 * by current thread.
3832 * \retval MDBX_NOTFOUND The key was not in the database.
3833 * \retval MDBX_EINVAL An invalid parameter was specified. */
3834 LIBMDBX_API int mdbx_get(MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key,
3835 MDBX_val *data);
3836
3837 /** \brief Get items from a database
3838 * and optionally number of data items for a given key.
3839 *
3840 * \ingroup c_crud
3841 *
3842 * Briefly this function does the same as \ref mdbx_get() with a few
3843 * differences:
3844 * 1. If values_count is NOT NULL, then returns the count
3845 * of multi-values/duplicates for a given key.
3846 * 2. Updates BOTH the key and the data for pointing to the actual key-value
3847 * pair inside the database.
3848 *
3849 * \param [in] txn A transaction handle returned
3850 * by \ref mdbx_txn_begin().
3851 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
3852 * \param [in,out] key The key to search for in the database.
3853 * \param [in,out] data The data corresponding to the key.
3854 * \param [out] values_count The optional address to return number of values
3855 * associated with given key:
3856 * = 0 - in case \ref MDBX_NOTFOUND error;
3857 * = 1 - exactly for databases
3858 * WITHOUT \ref MDBX_DUPSORT;
3859 * >= 1 for databases WITH \ref MDBX_DUPSORT.
3860 *
3861 * \returns A non-zero error value on failure and 0 on success,
3862 * some possible errors are:
3863 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned
3864 * by current thread.
3865 * \retval MDBX_NOTFOUND The key was not in the database.
3866 * \retval MDBX_EINVAL An invalid parameter was specified. */
3867 LIBMDBX_API int mdbx_get_ex(MDBX_txn *txn, MDBX_dbi dbi, MDBX_val *key,
3868 MDBX_val *data, size_t *values_count);
3869
3870 /** \brief Get equal or great item from a database.
3871 * \ingroup c_crud
3872 *
3873 * Briefly this function does the same as \ref mdbx_get() with a few
3874 * differences:
3875 * 1. Return equal or great (due comparison function) key-value
3876 * pair, but not only exactly matching with the key.
3877 * 2. On success return \ref MDBX_SUCCESS if key found exactly,
3878 * and \ref MDBX_RESULT_TRUE otherwise. Moreover, for databases with
3879 * \ref MDBX_DUPSORT flag the data argument also will be used to match over
3880 * multi-value/duplicates, and \ref MDBX_SUCCESS will be returned only when
3881 * BOTH the key and the data match exactly.
3882 * 3. Updates BOTH the key and the data for pointing to the actual key-value
3883 * pair inside the database.
3884 *
3885 * \param [in] txn A transaction handle returned
3886 * by \ref mdbx_txn_begin().
3887 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
3888 * \param [in,out] key The key to search for in the database.
3889 * \param [in,out] data The data corresponding to the key.
3890 *
3891 * \returns A non-zero error value on failure and \ref MDBX_RESULT_FALSE
3892 * or \ref MDBX_RESULT_TRUE on success (as described above).
3893 * Some possible errors are:
3894 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned
3895 * by current thread.
3896 * \retval MDBX_NOTFOUND The key was not in the database.
3897 * \retval MDBX_EINVAL An invalid parameter was specified. */
3898 LIBMDBX_API int mdbx_get_equal_or_great(MDBX_txn *txn, MDBX_dbi dbi,
3899 MDBX_val *key, MDBX_val *data);
3900
3901 /** \brief Store items into a database.
3902 * \ingroup c_crud
3903 *
3904 * This function stores key/data pairs in the database. The default behavior
3905 * is to enter the new key/data pair, replacing any previously existing key
3906 * if duplicates are disallowed, or adding a duplicate data item if
3907 * duplicates are allowed (see \ref MDBX_DUPSORT).
3908 *
3909 * \param [in] txn A transaction handle returned
3910 * by \ref mdbx_txn_begin().
3911 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
3912 * \param [in] key The key to store in the database.
3913 * \param [in,out] data The data to store.
3914 * \param [in] flags Special options for this operation.
3915 * This parameter must be set to 0 or by bitwise OR'ing
3916 * together one or more of the values described here:
3917 * - \ref MDBX_NODUPDATA
3918 * Enter the new key-value pair only if it does not already appear
3919 * in the database. This flag may only be specified if the database
3920 * was opened with \ref MDBX_DUPSORT. The function will return
3921 * \ref MDBX_KEYEXIST if the key/data pair already appears in the database.
3922 *
3923 * - \ref MDBX_NOOVERWRITE
3924 * Enter the new key/data pair only if the key does not already appear
3925 * in the database. The function will return \ref MDBX_KEYEXIST if the key
3926 * already appears in the database, even if the database supports
3927 * duplicates (see \ref MDBX_DUPSORT). The data parameter will be set
3928 * to point to the existing item.
3929 *
3930 * - \ref MDBX_CURRENT
3931 * Update an single existing entry, but not add new ones. The function will
3932 * return \ref MDBX_NOTFOUND if the given key not exist in the database.
3933 * In case multi-values for the given key, with combination of
3934 * the \ref MDBX_ALLDUPS will replace all multi-values,
3935 * otherwise return the \ref MDBX_EMULTIVAL.
3936 *
3937 * - \ref MDBX_RESERVE
3938 * Reserve space for data of the given size, but don't copy the given
3939 * data. Instead, return a pointer to the reserved space, which the
3940 * caller can fill in later - before the next update operation or the
3941 * transaction ends. This saves an extra memcpy if the data is being
3942 * generated later. MDBX does nothing else with this memory, the caller
3943 * is expected to modify all of the space requested. This flag must not
3944 * be specified if the database was opened with \ref MDBX_DUPSORT.
3945 *
3946 * - \ref MDBX_APPEND
3947 * Append the given key/data pair to the end of the database. This option
3948 * allows fast bulk loading when keys are already known to be in the
3949 * correct order. Loading unsorted keys with this flag will cause
3950 * a \ref MDBX_EKEYMISMATCH error.
3951 *
3952 * - \ref MDBX_APPENDDUP
3953 * As above, but for sorted dup data.
3954 *
3955 * - \ref MDBX_MULTIPLE
3956 * Store multiple contiguous data elements in a single request. This flag
3957 * may only be specified if the database was opened with
3958 * \ref MDBX_DUPFIXED. With combination the \ref MDBX_ALLDUPS
3959 * will replace all multi-values.
3960 * The data argument must be an array of two \ref MDBX_val. The `iov_len`
3961 * of the first \ref MDBX_val must be the size of a single data element.
3962 * The `iov_base` of the first \ref MDBX_val must point to the beginning
3963 * of the array of contiguous data elements which must be properly aligned
3964 * in case of database with \ref MDBX_INTEGERDUP flag.
3965 * The `iov_len` of the second \ref MDBX_val must be the count of the
3966 * number of data elements to store. On return this field will be set to
3967 * the count of the number of elements actually written. The `iov_base` of
3968 * the second \ref MDBX_val is unused.
3969 *
3970 * \see \ref c_crud_hints "Quick reference for Insert/Update/Delete operations"
3971 *
3972 * \returns A non-zero error value on failure and 0 on success,
3973 * some possible errors are:
3974 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned
3975 * by current thread.
3976 * \retval MDBX_KEYEXIST The key/value pair already exists in the database.
3977 * \retval MDBX_MAP_FULL The database is full, see \ref mdbx_env_set_mapsize().
3978 * \retval MDBX_TXN_FULL The transaction has too many dirty pages.
3979 * \retval MDBX_EACCES An attempt was made to write
3980 * in a read-only transaction.
3981 * \retval MDBX_EINVAL An invalid parameter was specified. */
3982 LIBMDBX_API int mdbx_put(MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key,
3983 MDBX_val *data, MDBX_put_flags_t flags);
3984
3985 /** \brief Replace items in a database.
3986 * \ingroup c_crud
3987 *
3988 * This function allows to update or delete an existing value at the same time
3989 * as the previous value is retrieved. If the argument new_data equal is NULL
3990 * zero, the removal is performed, otherwise the update/insert.
3991 *
3992 * The current value may be in an already changed (aka dirty) page. In this
3993 * case, the page will be overwritten during the update, and the old value will
3994 * be lost. Therefore, an additional buffer must be passed via old_data
3995 * argument initially to copy the old value. If the buffer passed in is too
3996 * small, the function will return \ref MDBX_RESULT_TRUE by setting iov_len
3997 * field pointed by old_data argument to the appropriate value, without
3998 * performing any changes.
3999 *
4000 * For databases with non-unique keys (i.e. with \ref MDBX_DUPSORT flag),
4001 * another use case is also possible, when by old_data argument selects a
4002 * specific item from multi-value/duplicates with the same key for deletion or
4003 * update. To select this scenario in flags should simultaneously specify
4004 * \ref MDBX_CURRENT and \ref MDBX_NOOVERWRITE. This combination is chosen
4005 * because it makes no sense, and thus allows you to identify the request of
4006 * such a scenario.
4007 *
4008 * \param [in] txn A transaction handle returned
4009 * by \ref mdbx_txn_begin().
4010 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
4011 * \param [in] key The key to store in the database.
4012 * \param [in] new_data The data to store, if NULL then deletion will
4013 * be performed.
4014 * \param [in,out] old_data The buffer for retrieve previous value as describe
4015 * above.
4016 * \param [in] flags Special options for this operation.
4017 * This parameter must be set to 0 or by bitwise
4018 * OR'ing together one or more of the values
4019 * described in \ref mdbx_put() description above,
4020 * and additionally
4021 * (\ref MDBX_CURRENT | \ref MDBX_NOOVERWRITE)
4022 * combination for selection particular item from
4023 * multi-value/duplicates.
4024 *
4025 * \see \ref c_crud_hints "Quick reference for Insert/Update/Delete operations"
4026 *
4027 * \returns A non-zero error value on failure and 0 on success. */
4028 LIBMDBX_API int mdbx_replace(MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key,
4029 MDBX_val *new_data, MDBX_val *old_data,
4030 MDBX_put_flags_t flags);
4031
4032 typedef int (*MDBX_preserve_func)(void *context, MDBX_val *target,
4033 const void *src, size_t bytes);
4034 LIBMDBX_API int mdbx_replace_ex(MDBX_txn *txn, MDBX_dbi dbi,
4035 const MDBX_val *key, MDBX_val *new_data,
4036 MDBX_val *old_data, MDBX_put_flags_t flags,
4037 MDBX_preserve_func preserver,
4038 void *preserver_context);
4039
4040 /** \brief Delete items from a database.
4041 * \ingroup c_crud
4042 *
4043 * This function removes key/data pairs from the database.
4044 *
4045 * \note The data parameter is NOT ignored regardless the database does
4046 * support sorted duplicate data items or not. If the data parameter
4047 * is non-NULL only the matching data item will be deleted. Otherwise, if data
4048 * parameter is NULL, any/all value(s) for specified key will be deleted.
4049 *
4050 * This function will return \ref MDBX_NOTFOUND if the specified key/data
4051 * pair is not in the database.
4052 *
4053 * \see \ref c_crud_hints "Quick reference for Insert/Update/Delete operations"
4054 *
4055 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
4056 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
4057 * \param [in] key The key to delete from the database.
4058 * \param [in] data The data to delete.
4059 *
4060 * \returns A non-zero error value on failure and 0 on success,
4061 * some possible errors are:
4062 * \retval MDBX_EACCES An attempt was made to write
4063 * in a read-only transaction.
4064 * \retval MDBX_EINVAL An invalid parameter was specified. */
4065 LIBMDBX_API int mdbx_del(MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key,
4066 const MDBX_val *data);
4067
4068 /** \brief Create a cursor handle but not bind it to transaction nor DBI handle.
4069 * \ingroup c_cursors
4070 *
4071 * An capable of operation cursor is associated with a specific transaction and
4072 * database. A cursor cannot be used when its database handle is closed. Nor
4073 * when its transaction has ended, except with \ref mdbx_cursor_bind() and
4074 * \ref mdbx_cursor_renew().
4075 * Also it can be discarded with \ref mdbx_cursor_close().
4076 *
4077 * A cursor must be closed explicitly always, before or after its transaction
4078 * ends. It can be reused with \ref mdbx_cursor_bind()
4079 * or \ref mdbx_cursor_renew() before finally closing it.
4080 *
4081 * \note In contrast to LMDB, the MDBX required that any opened cursors can be
4082 * reused and must be freed explicitly, regardless ones was opened in a
4083 * read-only or write transaction. The REASON for this is eliminates ambiguity
4084 * which helps to avoid errors such as: use-after-free, double-free, i.e.
4085 * memory corruption and segfaults.
4086 *
4087 * \param [in] context A pointer to application context to be associated with
4088 * created cursor and could be retrieved by
4089 * \ref mdbx_cursor_get_userctx() until cursor closed.
4090 *
4091 * \returns Created cursor handle or NULL in case out of memory. */
4092 LIBMDBX_API MDBX_cursor *mdbx_cursor_create(void *context);
4093
4094 /** \brief Set application information associated with the \ref MDBX_cursor.
4095 * \ingroup c_cursors
4096 * \see mdbx_cursor_get_userctx()
4097 *
4098 * \param [in] cursor An cursor handle returned by \ref mdbx_cursor_create()
4099 * or \ref mdbx_cursor_open().
4100 * \param [in] ctx An arbitrary pointer for whatever the application needs.
4101 *
4102 * \returns A non-zero error value on failure and 0 on success. */
4103 LIBMDBX_API int mdbx_cursor_set_userctx(MDBX_cursor *cursor, void *ctx);
4104
4105 /** \brief Get the application information associated with the MDBX_cursor.
4106 * \ingroup c_cursors
4107 * \see mdbx_cursor_set_userctx()
4108 *
4109 * \param [in] cursor An cursor handle returned by \ref mdbx_cursor_create()
4110 * or \ref mdbx_cursor_open().
4111 * \returns The pointer which was passed via the `context` parameter
4112 * of `mdbx_cursor_create()` or set by \ref mdbx_cursor_set_userctx(),
4113 * or `NULL` if something wrong. */
4114 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API void *
4115 mdbx_cursor_get_userctx(const MDBX_cursor *cursor);
4116
4117 /** \brief Bind cursor to specified transaction and DBI handle.
4118 * \ingroup c_cursors
4119 *
4120 * Using of the `mdbx_cursor_bind()` is equivalent to calling
4121 * \ref mdbx_cursor_renew() but with specifying an arbitrary dbi handle.
4122 *
4123 * An capable of operation cursor is associated with a specific transaction and
4124 * database. The cursor may be associated with a new transaction,
4125 * and referencing a new or the same database handle as it was created with.
4126 * This may be done whether the previous transaction is live or dead.
4127 *
4128 * \note In contrast to LMDB, the MDBX required that any opened cursors can be
4129 * reused and must be freed explicitly, regardless ones was opened in a
4130 * read-only or write transaction. The REASON for this is eliminates ambiguity
4131 * which helps to avoid errors such as: use-after-free, double-free, i.e.
4132 * memory corruption and segfaults.
4133 *
4134 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
4135 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
4136 * \param [out] cursor A cursor handle returned by \ref mdbx_cursor_create().
4137 *
4138 * \returns A non-zero error value on failure and 0 on success,
4139 * some possible errors are:
4140 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned
4141 * by current thread.
4142 * \retval MDBX_EINVAL An invalid parameter was specified. */
4143 LIBMDBX_API int mdbx_cursor_bind(MDBX_txn *txn, MDBX_cursor *cursor,
4144 MDBX_dbi dbi);
4145
4146 /** \brief Create a cursor handle for the specified transaction and DBI handle.
4147 * \ingroup c_cursors
4148 *
4149 * Using of the `mdbx_cursor_open()` is equivalent to calling
4150 * \ref mdbx_cursor_create() and then \ref mdbx_cursor_bind() functions.
4151 *
4152 * An capable of operation cursor is associated with a specific transaction and
4153 * database. A cursor cannot be used when its database handle is closed. Nor
4154 * when its transaction has ended, except with \ref mdbx_cursor_bind() and
4155 * \ref mdbx_cursor_renew().
4156 * Also it can be discarded with \ref mdbx_cursor_close().
4157 *
4158 * A cursor must be closed explicitly always, before or after its transaction
4159 * ends. It can be reused with \ref mdbx_cursor_bind()
4160 * or \ref mdbx_cursor_renew() before finally closing it.
4161 *
4162 * \note In contrast to LMDB, the MDBX required that any opened cursors can be
4163 * reused and must be freed explicitly, regardless ones was opened in a
4164 * read-only or write transaction. The REASON for this is eliminates ambiguity
4165 * which helps to avoid errors such as: use-after-free, double-free, i.e.
4166 * memory corruption and segfaults.
4167 *
4168 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
4169 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
4170 * \param [out] cursor Address where the new \ref MDBX_cursor handle will be
4171 * stored.
4172 *
4173 * \returns A non-zero error value on failure and 0 on success,
4174 * some possible errors are:
4175 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned
4176 * by current thread.
4177 * \retval MDBX_EINVAL An invalid parameter was specified. */
4178 LIBMDBX_API int mdbx_cursor_open(MDBX_txn *txn, MDBX_dbi dbi,
4179 MDBX_cursor **cursor);
4180
4181 /** \brief Close a cursor handle.
4182 * \ingroup c_cursors
4183 *
4184 * The cursor handle will be freed and must not be used again after this call,
4185 * but its transaction may still be live.
4186 *
4187 * \note In contrast to LMDB, the MDBX required that any opened cursors can be
4188 * reused and must be freed explicitly, regardless ones was opened in a
4189 * read-only or write transaction. The REASON for this is eliminates ambiguity
4190 * which helps to avoid errors such as: use-after-free, double-free, i.e.
4191 * memory corruption and segfaults.
4192 *
4193 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open()
4194 * or \ref mdbx_cursor_create(). */
4195 LIBMDBX_API void mdbx_cursor_close(MDBX_cursor *cursor);
4196
4197 /** \brief Renew a cursor handle.
4198 * \ingroup c_cursors
4199 *
4200 * An capable of operation cursor is associated with a specific transaction and
4201 * database. The cursor may be associated with a new transaction,
4202 * and referencing a new or the same database handle as it was created with.
4203 * This may be done whether the previous transaction is live or dead.
4204 *
4205 * Using of the `mdbx_cursor_renew()` is equivalent to calling
4206 * \ref mdbx_cursor_bind() with the DBI handle that previously
4207 * the cursor was used with.
4208 *
4209 * \note In contrast to LMDB, the MDBX allow any cursor to be re-used by using
4210 * \ref mdbx_cursor_renew(), to avoid unnecessary malloc/free overhead until it
4211 * freed by \ref mdbx_cursor_close().
4212 *
4213 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
4214 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open().
4215 *
4216 * \returns A non-zero error value on failure and 0 on success,
4217 * some possible errors are:
4218 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned
4219 * by current thread.
4220 * \retval MDBX_EINVAL An invalid parameter was specified. */
4221 LIBMDBX_API int mdbx_cursor_renew(MDBX_txn *txn, MDBX_cursor *cursor);
4222
4223 /** \brief Return the cursor's transaction handle.
4224 * \ingroup c_cursors
4225 *
4226 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open(). */
4227 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API MDBX_txn *
4228 mdbx_cursor_txn(const MDBX_cursor *cursor);
4229
4230 /** \brief Return the cursor's database handle.
4231 * \ingroup c_cursors
4232 *
4233 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open(). */
4234 LIBMDBX_API MDBX_dbi mdbx_cursor_dbi(const MDBX_cursor *cursor);
4235
4236 /** \brief Copy cursor position and state.
4237 * \ingroup c_cursors
4238 *
4239 * \param [in] src A source cursor handle returned
4240 * by \ref mdbx_cursor_create() or \ref mdbx_cursor_open().
4241 *
4242 * \param [in,out] dest A destination cursor handle returned
4243 * by \ref mdbx_cursor_create() or \ref mdbx_cursor_open().
4244 *
4245 * \returns A non-zero error value on failure and 0 on success. */
4246 LIBMDBX_API int mdbx_cursor_copy(const MDBX_cursor *src, MDBX_cursor *dest);
4247
4248 /** \brief Retrieve by cursor.
4249 * \ingroup c_crud
4250 *
4251 * This function retrieves key/data pairs from the database. The address and
4252 * length of the key are returned in the object to which key refers (except
4253 * for the case of the \ref MDBX_SET option, in which the key object is
4254 * unchanged), and the address and length of the data are returned in the object
4255 * to which data refers.
4256 * \see mdbx_get()
4257 *
4258 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open().
4259 * \param [in,out] key The key for a retrieved item.
4260 * \param [in,out] data The data of a retrieved item.
4261 * \param [in] op A cursor operation \ref MDBX_cursor_op.
4262 *
4263 * \returns A non-zero error value on failure and 0 on success,
4264 * some possible errors are:
4265 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned
4266 * by current thread.
4267 * \retval MDBX_NOTFOUND No matching key found.
4268 * \retval MDBX_EINVAL An invalid parameter was specified. */
4269 LIBMDBX_API int mdbx_cursor_get(MDBX_cursor *cursor, MDBX_val *key,
4270 MDBX_val *data, MDBX_cursor_op op);
4271
4272 /** \brief Store by cursor.
4273 * \ingroup c_crud
4274 *
4275 * This function stores key/data pairs into the database. The cursor is
4276 * positioned at the new item, or on failure usually near it.
4277 *
4278 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open().
4279 * \param [in] key The key operated on.
4280 * \param [in,out] data The data operated on.
4281 * \param [in] flags Options for this operation. This parameter
4282 * must be set to 0 or by bitwise OR'ing together
4283 * one or more of the values described here:
4284 * - \ref MDBX_CURRENT
4285 * Replace the item at the current cursor position. The key parameter
4286 * must still be provided, and must match it, otherwise the function
4287 * return \ref MDBX_EKEYMISMATCH. With combination the
4288 * \ref MDBX_ALLDUPS will replace all multi-values.
4289 *
4290 * \note MDBX allows (unlike LMDB) you to change the size of the data and
4291 * automatically handles reordering for sorted duplicates
4292 * (see \ref MDBX_DUPSORT).
4293 *
4294 * - \ref MDBX_NODUPDATA
4295 * Enter the new key-value pair only if it does not already appear in the
4296 * database. This flag may only be specified if the database was opened
4297 * with \ref MDBX_DUPSORT. The function will return \ref MDBX_KEYEXIST
4298 * if the key/data pair already appears in the database.
4299 *
4300 * - \ref MDBX_NOOVERWRITE
4301 * Enter the new key/data pair only if the key does not already appear
4302 * in the database. The function will return \ref MDBX_KEYEXIST if the key
4303 * already appears in the database, even if the database supports
4304 * duplicates (\ref MDBX_DUPSORT).
4305 *
4306 * - \ref MDBX_RESERVE
4307 * Reserve space for data of the given size, but don't copy the given
4308 * data. Instead, return a pointer to the reserved space, which the
4309 * caller can fill in later - before the next update operation or the
4310 * transaction ends. This saves an extra memcpy if the data is being
4311 * generated later. This flag must not be specified if the database
4312 * was opened with \ref MDBX_DUPSORT.
4313 *
4314 * - \ref MDBX_APPEND
4315 * Append the given key/data pair to the end of the database. No key
4316 * comparisons are performed. This option allows fast bulk loading when
4317 * keys are already known to be in the correct order. Loading unsorted
4318 * keys with this flag will cause a \ref MDBX_KEYEXIST error.
4319 *
4320 * - \ref MDBX_APPENDDUP
4321 * As above, but for sorted dup data.
4322 *
4323 * - \ref MDBX_MULTIPLE
4324 * Store multiple contiguous data elements in a single request. This flag
4325 * may only be specified if the database was opened with
4326 * \ref MDBX_DUPFIXED. With combination the \ref MDBX_ALLDUPS
4327 * will replace all multi-values.
4328 * The data argument must be an array of two \ref MDBX_val. The `iov_len`
4329 * of the first \ref MDBX_val must be the size of a single data element.
4330 * The `iov_base` of the first \ref MDBX_val must point to the beginning
4331 * of the array of contiguous data elements which must be properly aligned
4332 * in case of database with \ref MDBX_INTEGERDUP flag.
4333 * The `iov_len` of the second \ref MDBX_val must be the count of the
4334 * number of data elements to store. On return this field will be set to
4335 * the count of the number of elements actually written. The `iov_base` of
4336 * the second \ref MDBX_val is unused.
4337 *
4338 * \see \ref c_crud_hints "Quick reference for Insert/Update/Delete operations"
4339 *
4340 * \returns A non-zero error value on failure and 0 on success,
4341 * some possible errors are:
4342 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned
4343 * by current thread.
4344 * \retval MDBX_EKEYMISMATCH The given key value is mismatched to the current
4345 * cursor position
4346 * \retval MDBX_MAP_FULL The database is full,
4347 * see \ref mdbx_env_set_mapsize().
4348 * \retval MDBX_TXN_FULL The transaction has too many dirty pages.
4349 * \retval MDBX_EACCES An attempt was made to write in a read-only
4350 * transaction.
4351 * \retval MDBX_EINVAL An invalid parameter was specified. */
4352 LIBMDBX_API int mdbx_cursor_put(MDBX_cursor *cursor, const MDBX_val *key,
4353 MDBX_val *data, MDBX_put_flags_t flags);
4354
4355 /** \brief Delete current key/data pair.
4356 * \ingroup c_crud
4357 *
4358 * This function deletes the key/data pair to which the cursor refers. This
4359 * does not invalidate the cursor, so operations such as \ref MDBX_NEXT can
4360 * still be used on it. Both \ref MDBX_NEXT and \ref MDBX_GET_CURRENT will
4361 * return the same record after this operation.
4362 *
4363 * \param [in] cursor A cursor handle returned by mdbx_cursor_open().
4364 * \param [in] flags Options for this operation. This parameter must be set
4365 * to one of the values described here.
4366 *
4367 * - \ref MDBX_CURRENT Delete only single entry at current cursor position.
4368 * - \ref MDBX_ALLDUPS
4369 * or \ref MDBX_NODUPDATA (supported for compatibility)
4370 * Delete all of the data items for the current key. This flag has effect
4371 * only for database(s) was created with \ref MDBX_DUPSORT.
4372 *
4373 * \see \ref c_crud_hints "Quick reference for Insert/Update/Delete operations"
4374 *
4375 * \returns A non-zero error value on failure and 0 on success,
4376 * some possible errors are:
4377 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned
4378 * by current thread.
4379 * \retval MDBX_MAP_FULL The database is full,
4380 * see \ref mdbx_env_set_mapsize().
4381 * \retval MDBX_TXN_FULL The transaction has too many dirty pages.
4382 * \retval MDBX_EACCES An attempt was made to write in a read-only
4383 * transaction.
4384 * \retval MDBX_EINVAL An invalid parameter was specified. */
4385 LIBMDBX_API int mdbx_cursor_del(MDBX_cursor *cursor, MDBX_put_flags_t flags);
4386
4387 /** \brief Return count of duplicates for current key.
4388 * \ingroup c_crud
4389 *
4390 * This call is valid for all databases, but reasonable only for that support
4391 * sorted duplicate data items \ref MDBX_DUPSORT.
4392 *
4393 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open().
4394 * \param [out] pcount Address where the count will be stored.
4395 *
4396 * \returns A non-zero error value on failure and 0 on success,
4397 * some possible errors are:
4398 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned
4399 * by current thread.
4400 * \retval MDBX_EINVAL Cursor is not initialized, or an invalid parameter
4401 * was specified. */
4402 LIBMDBX_API int mdbx_cursor_count(const MDBX_cursor *cursor, size_t *pcount);
4403
4404 /** \brief Determines whether the cursor is pointed to a key-value pair or not,
4405 * i.e. was not positioned or points to the end of data.
4406 * \ingroup c_cursors
4407 *
4408 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open().
4409 *
4410 * \returns A \ref MDBX_RESULT_TRUE or \ref MDBX_RESULT_FALSE value,
4411 * otherwise the error code:
4412 * \retval MDBX_RESULT_TRUE No more data available or cursor not
4413 * positioned
4414 * \retval MDBX_RESULT_FALSE A data is available
4415 * \retval Otherwise the error code */
4416 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int
4417 mdbx_cursor_eof(const MDBX_cursor *cursor);
4418
4419 /** \brief Determines whether the cursor is pointed to the first key-value pair
4420 * or not. \ingroup c_cursors
4421 *
4422 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open().
4423 *
4424 * \returns A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value,
4425 * otherwise the error code:
4426 * \retval MDBX_RESULT_TRUE Cursor positioned to the first key-value pair
4427 * \retval MDBX_RESULT_FALSE Cursor NOT positioned to the first key-value
4428 * pair \retval Otherwise the error code */
4429 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int
4430 mdbx_cursor_on_first(const MDBX_cursor *cursor);
4431
4432 /** \brief Determines whether the cursor is pointed to the last key-value pair
4433 * or not. \ingroup c_cursors
4434 *
4435 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open().
4436 *
4437 * \returns A \ref MDBX_RESULT_TRUE or \ref MDBX_RESULT_FALSE value,
4438 * otherwise the error code:
4439 * \retval MDBX_RESULT_TRUE Cursor positioned to the last key-value pair
4440 * \retval MDBX_RESULT_FALSE Cursor NOT positioned to the last key-value pair
4441 * \retval Otherwise the error code */
4442 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int
4443 mdbx_cursor_on_last(const MDBX_cursor *cursor);
4444
4445 /** \addtogroup c_rqest
4446 * \details \note The estimation result varies greatly depending on the filling
4447 * of specific pages and the overall balance of the b-tree:
4448 *
4449 * 1. The number of items is estimated by analyzing the height and fullness of
4450 * the b-tree. The accuracy of the result directly depends on the balance of
4451 * the b-tree, which in turn is determined by the history of previous
4452 * insert/delete operations and the nature of the data (i.e. variability of
4453 * keys length and so on). Therefore, the accuracy of the estimation can vary
4454 * greatly in a particular situation.
4455 *
4456 * 2. To understand the potential spread of results, you should consider a
4457 * possible situations basing on the general criteria for splitting and merging
4458 * b-tree pages:
4459 * - the page is split into two when there is no space for added data;
4460 * - two pages merge if the result fits in half a page;
4461 * - thus, the b-tree can consist of an arbitrary combination of pages filled
4462 * both completely and only 1/4. Therefore, in the worst case, the result
4463 * can diverge 4 times for each level of the b-tree excepting the first and
4464 * the last.
4465 *
4466 * 3. In practice, the probability of extreme cases of the above situation is
4467 * close to zero and in most cases the error does not exceed a few percent. On
4468 * the other hand, it's just a chance you shouldn't overestimate. */
4469
4470 /** \brief Estimates the distance between cursors as a number of elements.
4471 * \ingroup c_rqest
4472 *
4473 * This function performs a rough estimate based only on b-tree pages that are
4474 * common for the both cursor's stacks. The results of such estimation can be
4475 * used to build and/or optimize query execution plans.
4476 *
4477 * Please see notes on accuracy of the result in the details
4478 * of \ref c_rqest section.
4479 *
4480 * Both cursors must be initialized for the same database and the same
4481 * transaction.
4482 *
4483 * \param [in] first The first cursor for estimation.
4484 * \param [in] last The second cursor for estimation.
4485 * \param [out] distance_items The pointer to store estimated distance value,
4486 * i.e. `*distance_items = distance(first, last)`.
4487 *
4488 * \returns A non-zero error value on failure and 0 on success. */
4489 LIBMDBX_API int mdbx_estimate_distance(const MDBX_cursor *first,
4490 const MDBX_cursor *last,
4491 ptrdiff_t *distance_items);
4492
4493 /** \brief Estimates the move distance.
4494 * \ingroup c_rqest
4495 *
4496 * This function performs a rough estimate distance between the current
4497 * cursor position and next position after the specified move-operation with
4498 * given key and data. The results of such estimation can be used to build
4499 * and/or optimize query execution plans. Current cursor position and state are
4500 * preserved.
4501 *
4502 * Please see notes on accuracy of the result in the details
4503 * of \ref c_rqest section.
4504 *
4505 * \param [in] cursor Cursor for estimation.
4506 * \param [in,out] key The key for a retrieved item.
4507 * \param [in,out] data The data of a retrieved item.
4508 * \param [in] move_op A cursor operation \ref MDBX_cursor_op.
4509 * \param [out] distance_items A pointer to store estimated move distance
4510 * as the number of elements.
4511 *
4512 * \returns A non-zero error value on failure and 0 on success. */
4513 LIBMDBX_API int mdbx_estimate_move(const MDBX_cursor *cursor, MDBX_val *key,
4514 MDBX_val *data, MDBX_cursor_op move_op,
4515 ptrdiff_t *distance_items);
4516
4517 /** \brief Estimates the size of a range as a number of elements.
4518 * \ingroup c_rqest
4519 *
4520 * The results of such estimation can be used to build and/or optimize query
4521 * execution plans.
4522 *
4523 * Please see notes on accuracy of the result in the details
4524 * of \ref c_rqest section.
4525 *
4526 *
4527 * \param [in] txn A transaction handle returned
4528 * by \ref mdbx_txn_begin().
4529 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
4530 * \param [in] begin_key The key of range beginning or NULL for explicit FIRST.
4531 * \param [in] begin_data Optional additional data to seeking among sorted
4532 * duplicates.
4533 * Only for \ref MDBX_DUPSORT, NULL otherwise.
4534 * \param [in] end_key The key of range ending or NULL for explicit LAST.
4535 * \param [in] end_data Optional additional data to seeking among sorted
4536 * duplicates.
4537 * Only for \ref MDBX_DUPSORT, NULL otherwise.
4538 * \param [out] distance_items A pointer to store range estimation result.
4539 *
4540 * \returns A non-zero error value on failure and 0 on success. */
4541 LIBMDBX_API int mdbx_estimate_range(MDBX_txn *txn, MDBX_dbi dbi,
4542 MDBX_val *begin_key, MDBX_val *begin_data,
4543 MDBX_val *end_key, MDBX_val *end_data,
4544 ptrdiff_t *distance_items);
4545
4546 /** \brief The EPSILON value for mdbx_estimate_range()
4547 * \ingroup c_rqest */
4548 #define MDBX_EPSILON ((MDBX_val *)((ptrdiff_t)-1))
4549
4550 /** \brief Determines whether the given address is on a dirty database page of
4551 * the transaction or not. \ingroup c_statinfo
4552 *
4553 * Ultimately, this allows to avoid copy data from non-dirty pages.
4554 *
4555 * "Dirty" pages are those that have already been changed during a write
4556 * transaction. Accordingly, any further changes may result in such pages being
4557 * overwritten. Therefore, all functions libmdbx performing changes inside the
4558 * database as arguments should NOT get pointers to data in those pages. In
4559 * turn, "not dirty" pages before modification will be copied.
4560 *
4561 * In other words, data from dirty pages must either be copied before being
4562 * passed as arguments for further processing or rejected at the argument
4563 * validation stage. Thus, `mdbx_is_dirty()` allows you to get rid of
4564 * unnecessary copying, and perform a more complete check of the arguments.
4565 *
4566 * \note The address passed must point to the beginning of the data. This is
4567 * the only way to ensure that the actual page header is physically located in
4568 * the same memory page, including for multi-pages with long data.
4569 *
4570 * \note In rare cases the function may return a false positive answer
4571 * (\ref MDBX_RESULT_TRUE when data is NOT on a dirty page), but never a false
4572 * negative if the arguments are correct.
4573 *
4574 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
4575 * \param [in] ptr The address of data to check.
4576 *
4577 * \returns A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value,
4578 * otherwise the error code:
4579 * \retval MDBX_RESULT_TRUE Given address is on the dirty page.
4580 * \retval MDBX_RESULT_FALSE Given address is NOT on the dirty page.
4581 * \retval Otherwise the error code. */
4582 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int mdbx_is_dirty(const MDBX_txn *txn,
4583 const void *ptr);
4584
4585 /** \brief Sequence generation for a database.
4586 * \ingroup c_crud
4587 *
4588 * The function allows to create a linear sequence of unique positive integers
4589 * for each database. The function can be called for a read transaction to
4590 * retrieve the current sequence value, and the increment must be zero.
4591 * Sequence changes become visible outside the current write transaction after
4592 * it is committed, and discarded on abort.
4593 *
4594 * \param [in] txn A transaction handle returned
4595 * by \ref mdbx_txn_begin().
4596 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
4597 * \param [out] result The optional address where the value of sequence
4598 * before the change will be stored.
4599 * \param [in] increment Value to increase the sequence,
4600 * must be 0 for read-only transactions.
4601 *
4602 * \returns A non-zero error value on failure and 0 on success,
4603 * some possible errors are:
4604 * \retval MDBX_RESULT_TRUE Increasing the sequence has resulted in an
4605 * overflow and therefore cannot be executed. */
4606 LIBMDBX_API int mdbx_dbi_sequence(MDBX_txn *txn, MDBX_dbi dbi, uint64_t *result,
4607 uint64_t increment);
4608
4609 /** \brief Compare two keys according to a particular database.
4610 * \ingroup c_crud
4611 * \see MDBX_cmp_func
4612 *
4613 * This returns a comparison as if the two data items were keys in the
4614 * specified database.
4615 *
4616 * \warning There ss a Undefined behavior if one of arguments is invalid.
4617 *
4618 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
4619 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
4620 * \param [in] a The first item to compare.
4621 * \param [in] b The second item to compare.
4622 *
4623 * \returns < 0 if a < b, 0 if a == b, > 0 if a > b */
4624 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int mdbx_cmp(const MDBX_txn *txn,
4625 MDBX_dbi dbi,
4626 const MDBX_val *a,
4627 const MDBX_val *b);
4628
4629 /** \brief Returns default internal key's comparator for given database flags.
4630 * \ingroup c_extra */
4631 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API MDBX_cmp_func *
4632 mdbx_get_keycmp(MDBX_db_flags_t flags);
4633
4634 /** \brief Compare two data items according to a particular database.
4635 * \ingroup c_crud
4636 * \see MDBX_cmp_func
4637 *
4638 * This returns a comparison as if the two items were data items of the
4639 * specified database.
4640 *
4641 * \warning There ss a Undefined behavior if one of arguments is invalid.
4642 *
4643 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
4644 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
4645 * \param [in] a The first item to compare.
4646 * \param [in] b The second item to compare.
4647 *
4648 * \returns < 0 if a < b, 0 if a == b, > 0 if a > b */
4649 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int mdbx_dcmp(const MDBX_txn *txn,
4650 MDBX_dbi dbi,
4651 const MDBX_val *a,
4652 const MDBX_val *b);
4653
4654 /** \brief Returns default internal data's comparator for given database flags
4655 * \ingroup c_extra */
4656 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API MDBX_cmp_func *
4657 mdbx_get_datacmp(MDBX_db_flags_t flags);
4658
4659 /** \brief A callback function used to enumerate the reader lock table.
4660 * \ingroup c_statinfo
4661 *
4662 * \param [in] ctx An arbitrary context pointer for the callback.
4663 * \param [in] num The serial number during enumeration,
4664 * starting from 1.
4665 * \param [in] slot The reader lock table slot number.
4666 * \param [in] txnid The ID of the transaction being read,
4667 * i.e. the MVCC-snapshot number.
4668 * \param [in] lag The lag from a recent MVCC-snapshot,
4669 * i.e. the number of committed write transactions
4670 * since the current read transaction started.
4671 * \param [in] pid The reader process ID.
4672 * \param [in] thread The reader thread ID.
4673 * \param [in] bytes_used The number of last used page in the MVCC-snapshot
4674 * which being read,
4675 * i.e. database file can't shrinked beyond this.
4676 * \param [in] bytes_retired The total size of the database pages that were
4677 * retired by committed write transactions after
4678 * the reader's MVCC-snapshot,
4679 * i.e. the space which would be freed after
4680 * the Reader releases the MVCC-snapshot
4681 * for reuse by completion read transaction.
4682 *
4683 * \returns < 0 on failure, >= 0 on success. \see mdbx_reader_list() */
4684 typedef int(MDBX_reader_list_func)(void *ctx, int num, int slot, mdbx_pid_t pid,
4685 mdbx_tid_t thread, uint64_t txnid,
4686 uint64_t lag, size_t bytes_used,
4687 size_t bytes_retained) MDBX_CXX17_NOEXCEPT;
4688
4689 /** \brief Enumerate the entries in the reader lock table.
4690 *
4691 * \ingroup c_statinfo
4692 *
4693 * \param [in] env An environment handle returned by \ref mdbx_env_create().
4694 * \param [in] func A \ref MDBX_reader_list_func function.
4695 * \param [in] ctx An arbitrary context pointer for the enumeration
4696 * function.
4697 *
4698 * \returns A non-zero error value on failure and 0 on success,
4699 * or \ref MDBX_RESULT_TRUE if the reader lock table is empty. */
4700 LIBMDBX_API int mdbx_reader_list(const MDBX_env *env,
4701 MDBX_reader_list_func *func, void *ctx);
4702
4703 /** \brief Check for stale entries in the reader lock table.
4704 * \ingroup c_extra
4705 *
4706 * \param [in] env An environment handle returned by \ref mdbx_env_create().
4707 * \param [out] dead Number of stale slots that were cleared.
4708 *
4709 * \returns A non-zero error value on failure and 0 on success,
4710 * or \ref MDBX_RESULT_TRUE if a dead reader(s) found or mutex was recovered. */
4711 LIBMDBX_API int mdbx_reader_check(MDBX_env *env, int *dead);
4712
4713 /** \brief Returns a lag of the reading for the given transaction.
4714 * \ingroup c_statinfo
4715 *
4716 * Returns an information for estimate how much given read-only
4717 * transaction is lagging relative the to actual head.
4718 * \deprecated Please use \ref mdbx_txn_info() instead.
4719 *
4720 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
4721 * \param [out] percent Percentage of page allocation in the database.
4722 *
4723 * \returns Number of transactions committed after the given was started for
4724 * read, or negative value on failure. */
4725 MDBX_DEPRECATED LIBMDBX_API int mdbx_txn_straggler(const MDBX_txn *txn,
4726 int *percent);
4727
4728 /** \brief Registers the current thread as a reader for the environment.
4729 * \ingroup c_extra
4730 *
4731 * To perform read operations without blocking, a reader slot must be assigned
4732 * for each thread. However, this assignment requires a short-term lock
4733 * acquisition which is performed automatically. This function allows you to
4734 * assign the reader slot in advance and thus avoid capturing the blocker when
4735 * the read transaction starts firstly from current thread.
4736 * \see mdbx_thread_unregister()
4737 *
4738 * \note Threads are registered automatically the first time a read transaction
4739 * starts. Therefore, there is no need to use this function, except in
4740 * special cases.
4741 *
4742 * \param [in] env An environment handle returned by \ref mdbx_env_create().
4743 *
4744 * \returns A non-zero error value on failure and 0 on success,
4745 * or \ref MDBX_RESULT_TRUE if thread is already registered. */
4746 LIBMDBX_API int mdbx_thread_register(const MDBX_env *env);
4747
4748 /** \brief Unregisters the current thread as a reader for the environment.
4749 * \ingroup c_extra
4750 *
4751 * To perform read operations without blocking, a reader slot must be assigned
4752 * for each thread. However, the assigned reader slot will remain occupied until
4753 * the thread ends or the environment closes. This function allows you to
4754 * explicitly release the assigned reader slot.
4755 * \see mdbx_thread_register()
4756 *
4757 * \param [in] env An environment handle returned by \ref mdbx_env_create().
4758 *
4759 * \returns A non-zero error value on failure and 0 on success, or
4760 * \ref MDBX_RESULT_TRUE if thread is not registered or already unregistered. */
4761 LIBMDBX_API int mdbx_thread_unregister(const MDBX_env *env);
4762
4763 /** \brief A Handle-Slow-Readers callback function to resolve database
4764 * full/overflow issue due to a reader(s) which prevents the old data from being
4765 * recycled.
4766 * \ingroup c_err
4767 *
4768 * Read transactions prevent reuse of pages freed by newer write transactions,
4769 * thus the database can grow quickly. This callback will be called when there
4770 * is not enough space in the database (i.e. before increasing the database size
4771 * or before \ref MDBX_MAP_FULL error) and thus can be used to resolve issues
4772 * with a "long-lived" read transactions.
4773 * \see long-lived-read
4774 *
4775 * Using this callback you can choose how to resolve the situation:
4776 * - abort the write transaction with an error;
4777 * - wait for the read transaction(s) to complete;
4778 * - notify a thread performing a long-lived read transaction
4779 * and wait for an effect;
4780 * - kill the thread or whole process that performs the long-lived read
4781 * transaction;
4782 *
4783 * Depending on the arguments and needs, your implementation may wait,
4784 * terminate a process or thread that is performing a long read, or perform
4785 * some other action. In doing so it is important that the returned code always
4786 * corresponds to the performed action.
4787 *
4788 * \param [in] env An environment handle returned by \ref mdbx_env_create().
4789 * \param [in] txn The current write transaction which internally at
4790 * the \ref MDBX_MAP_FULL condition.
4791 * \param [in] pid A pid of the reader process.
4792 * \param [in] tid A thread_id of the reader thread.
4793 * \param [in] laggard An oldest read transaction number on which stalled.
4794 * \param [in] gap A lag from the last committed txn.
4795 * \param [in] space A space that actually become available for reuse after
4796 * this reader finished. The callback function can take
4797 * this value into account to evaluate the impact that
4798 * a long-running transaction has.
4799 * \param [in] retry A retry number starting from 0.
4800 * If callback has returned 0 at least once, then at end
4801 * of current handling loop the callback function will be
4802 * called additionally with negative value to notify about
4803 * the end of loop. The callback function can use this value
4804 * to implement timeout logic while waiting for readers.
4805 *
4806 * \returns The RETURN CODE determines the further actions libmdbx and must
4807 * match the action which was executed by the callback:
4808 *
4809 * \retval -2 or less An error condition and the reader was not killed.
4810 *
4811 * \retval -1 The callback was unable to solve the problem and
4812 * agreed on \ref MDBX_MAP_FULL error;
4813 * libmdbx should increase the database size or
4814 * return \ref MDBX_MAP_FULL error.
4815 *
4816 * \retval 0 (zero) The callback solved the problem or just waited for
4817 * a while, libmdbx should rescan the reader lock table and
4818 * retry. This also includes a situation when corresponding
4819 * transaction terminated in normal way by
4820 * \ref mdbx_txn_abort() or \ref mdbx_txn_reset(),
4821 * and my be restarted. I.e. reader slot don't needed
4822 * to be cleaned from transaction.
4823 *
4824 * \retval 1 Transaction aborted asynchronous and reader slot
4825 * should be cleared immediately, i.e. read transaction
4826 * will not continue but \ref mdbx_txn_abort()
4827 * or \ref mdbx_txn_reset() will be called later.
4828 *
4829 * \retval 2 or great The reader process was terminated or killed,
4830 * and libmdbx should entirely reset reader registration.
4831 *
4832 * \see mdbx_env_set_hsr() \see mdbx_env_get_hsr()
4833 */
4834 typedef int(MDBX_hsr_func)(const MDBX_env *env, const MDBX_txn *txn,
4835 mdbx_pid_t pid, mdbx_tid_t tid, uint64_t laggard,
4836 unsigned gap, size_t space,
4837 int retry) MDBX_CXX17_NOEXCEPT;
4838
4839 /** \brief Sets a Handle-Slow-Readers callback to resolve database full/overflow
4840 * issue due to a reader(s) which prevents the old data from being recycled.
4841 * \ingroup c_err
4842 *
4843 * The callback will only be triggered when the database is full due to a
4844 * reader(s) prevents the old data from being recycled.
4845 *
4846 * \see mdbx_env_get_hsr()
4847 * \see long-lived-read
4848 *
4849 * \param [in] env An environment handle returned
4850 * by \ref mdbx_env_create().
4851 * \param [in] hsr_callback A \ref MDBX_hsr_func function
4852 * or NULL to disable.
4853 *
4854 * \returns A non-zero error value on failure and 0 on success. */
4855 LIBMDBX_API int mdbx_env_set_hsr(MDBX_env *env, MDBX_hsr_func *hsr_callback);
4856
4857 /** \brief Gets current Handle-Slow-Readers callback used to resolve database
4858 * full/overflow issue due to a reader(s) which prevents the old data from being
4859 * recycled.
4860 * \see mdbx_env_set_hsr()
4861 *
4862 * \param [in] env An environment handle returned by \ref mdbx_env_create().
4863 *
4864 * \returns A MDBX_hsr_func function or NULL if disabled
4865 * or something wrong. */
4866 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API MDBX_hsr_func *
4867 mdbx_env_get_hsr(const MDBX_env *env);
4868
4869 /** \defgroup btree_traversal B-tree Traversal
4870 * This is internal API for mdbx_chk tool. You should avoid to use it, except
4871 * some extremal special cases.
4872 * \ingroup c_extra
4873 * @{ */
4874
4875 /** \brief Page types for traverse the b-tree.
4876 * \see mdbx_env_pgwalk() \see MDBX_pgvisitor_func */
4877 enum MDBX_page_type_t {
4878 MDBX_page_broken,
4879 MDBX_page_meta,
4880 MDBX_page_large,
4881 MDBX_page_branch,
4882 MDBX_page_leaf,
4883 MDBX_page_dupfixed_leaf,
4884 MDBX_subpage_leaf,
4885 MDBX_subpage_dupfixed_leaf,
4886 MDBX_subpage_broken,
4887 };
4888 #ifndef __cplusplus
4889 typedef enum MDBX_page_type_t MDBX_page_type_t;
4890 #endif
4891
4892 /** \brief Pseudo-name for MainDB */
4893 #define MDBX_PGWALK_MAIN ((const char *)((ptrdiff_t)0))
4894 /** \brief Pseudo-name for GarbageCollectorDB */
4895 #define MDBX_PGWALK_GC ((const char *)((ptrdiff_t)-1))
4896 /** \brief Pseudo-name for MetaPages */
4897 #define MDBX_PGWALK_META ((const char *)((ptrdiff_t)-2))
4898
4899 /** \brief Callback function for traverse the b-tree. \see mdbx_env_pgwalk() */
4900 typedef int MDBX_pgvisitor_func(
4901 const uint64_t pgno, const unsigned number, void *const ctx, const int deep,
4902 const char *const dbi, const size_t page_size, const MDBX_page_type_t type,
4903 const MDBX_error_t err, const size_t nentries, const size_t payload_bytes,
4904 const size_t header_bytes, const size_t unused_bytes) MDBX_CXX17_NOEXCEPT;
4905
4906 /** \brief B-tree traversal function. */
4907 LIBMDBX_API int mdbx_env_pgwalk(MDBX_txn *txn, MDBX_pgvisitor_func *visitor,
4908 void *ctx, bool dont_check_keys_ordering);
4909
4910 /** \brief Open an environment instance using specific meta-page
4911 * for checking and recovery.
4912 *
4913 * This function mostly of internal API for `mdbx_chk` utility and subject to
4914 * change at any time. Do not use this function to avoid shooting your own
4915 * leg(s). */
4916 LIBMDBX_API int mdbx_env_open_for_recovery(MDBX_env *env, const char *pathname,
4917 unsigned target_meta,
4918 bool writeable);
4919
4920 /** \brief Turn database to the specified meta-page.
4921 *
4922 * This function mostly of internal API for `mdbx_chk` utility and subject to
4923 * change at any time. Do not use this function to avoid shooting your own
4924 * leg(s). */
4925 LIBMDBX_API int mdbx_env_turn_for_recovery(MDBX_env *env, unsigned target_meta);
4926
4927 /** @} B-tree Traversal */
4928
4929 /**** Attribute support functions for Nexenta (scheduled for removal)
4930 * *****************************************************************/
4931 #if defined(MDBX_NEXENTA_ATTRS) || defined(DOXYGEN)
4932 /** \defgroup nexenta Attribute support functions for Nexenta
4933 * \ingroup c_crud
4934 * @{ */
4935 typedef uint_fast64_t mdbx_attr_t;
4936
4937 /** Store by cursor with attribute.
4938 *
4939 * This function stores key/data pairs into the database. The cursor is
4940 * positioned at the new item, or on failure usually near it.
4941 *
4942 * \note Internally based on \ref MDBX_RESERVE feature,
4943 * therefore doesn't support \ref MDBX_DUPSORT.
4944 *
4945 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open()
4946 * \param [in] key The key operated on.
4947 * \param [in] data The data operated on.
4948 * \param [in] attr The attribute.
4949 * \param [in] flags Options for this operation. This parameter must be set
4950 * to 0 or one of the values described here:
4951 * - \ref MDBX_CURRENT
4952 * Replace the item at the current cursor position. The key parameter
4953 * must still be provided, and must match it, otherwise the function
4954 * return \ref MDBX_EKEYMISMATCH.
4955 *
4956 * - \ref MDBX_APPEND
4957 * Append the given key/data pair to the end of the database. No key
4958 * comparisons are performed. This option allows fast bulk loading when
4959 * keys are already known to be in the correct order. Loading unsorted
4960 * keys with this flag will cause a \ref MDBX_KEYEXIST error.
4961 *
4962 * \see \ref c_crud_hints "Quick reference for Insert/Update/Delete operations"
4963 *
4964 * \returns A non-zero error value on failure and 0 on success,
4965 * some possible errors are:
4966 * \retval MDBX_EKEYMISMATCH
4967 * \retval MDBX_MAP_FULL The database is full, see \ref mdbx_env_set_mapsize().
4968 * \retval MDBX_TXN_FULL The transaction has too many dirty pages.
4969 * \retval MDBX_EACCES An attempt was made to write in a read-only
4970 * transaction.
4971 * \retval MDBX_EINVAL an invalid parameter was specified. */
4972 LIBMDBX_API int mdbx_cursor_put_attr(MDBX_cursor *cursor, MDBX_val *key,
4973 MDBX_val *data, mdbx_attr_t attr,
4974 MDBX_put_flags_t flags);
4975
4976 /** Store items and attributes into a database.
4977 *
4978 * This function stores key/data pairs in the database. The default behavior
4979 * is to enter the new key/data pair, replacing any previously existing key
4980 * if duplicates are disallowed.
4981 *
4982 * \note Internally based on \ref MDBX_RESERVE feature,
4983 * therefore doesn't support \ref MDBX_DUPSORT.
4984 *
4985 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
4986 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
4987 * \param [in] key The key to store in the database.
4988 * \param [in] attr The attribute to store in the database.
4989 * \param [in,out] data The data to store.
4990 * \param [in] flags Special options for this operation. This parameter
4991 * must be set to 0 or by bitwise OR'ing together one or
4992 * more of the values described here:
4993 * - \ref MDBX_NOOVERWRITE
4994 * Enter the new key/data pair only if the key does not already appear
4995 * in the database. The function will return \ref MDBX_KEYEXIST if the key
4996 * already appears in the database. The data parameter will be set to
4997 * point to the existing item.
4998 *
4999 * - \ref MDBX_CURRENT
5000 * Update an single existing entry, but not add new ones. The function
5001 * will return \ref MDBX_NOTFOUND if the given key not exist in the
5002 * database. Or the \ref MDBX_EMULTIVAL in case duplicates for the given
5003 * key.
5004 *
5005 * - \ref MDBX_APPEND
5006 * Append the given key/data pair to the end of the database. This option
5007 * allows fast bulk loading when keys are already known to be in the
5008 * correct order. Loading unsorted keys with this flag will cause
5009 * a \ref MDBX_EKEYMISMATCH error.
5010 *
5011 * \see \ref c_crud_hints "Quick reference for Insert/Update/Delete operations"
5012 *
5013 * \returns A non-zero error value on failure and 0 on success,
5014 * some possible errors are:
5015 * \retval MDBX_KEYEXIST
5016 * \retval MDBX_MAP_FULL The database is full, see \ref mdbx_env_set_mapsize().
5017 * \retval MDBX_TXN_FULL The transaction has too many dirty pages.
5018 * \retval MDBX_EACCES An attempt was made to write
5019 * in a read-only transaction.
5020 * \retval MDBX_EINVAL An invalid parameter was specified. */
5021 LIBMDBX_API int mdbx_put_attr(MDBX_txn *txn, MDBX_dbi dbi, MDBX_val *key,
5022 MDBX_val *data, mdbx_attr_t attr,
5023 MDBX_put_flags_t flags);
5024
5025 /** Set items attribute from a database.
5026 *
5027 * This function stores key/data pairs attribute to the database.
5028 *
5029 * \note Internally based on \ref MDBX_RESERVE feature,
5030 * therefore doesn't support \ref MDBX_DUPSORT.
5031 *
5032 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
5033 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
5034 * \param [in] key The key to search for in the database.
5035 * \param [in] data The data to be stored or NULL to save previous value.
5036 * \param [in] attr The attribute to be stored.
5037 *
5038 * \returns A non-zero error value on failure and 0 on success,
5039 * some possible errors are:
5040 * \retval MDBX_NOTFOUND The key-value pair was not in the database.
5041 * \retval MDBX_EINVAL An invalid parameter was specified. */
5042 LIBMDBX_API int mdbx_set_attr(MDBX_txn *txn, MDBX_dbi dbi, MDBX_val *key,
5043 MDBX_val *data, mdbx_attr_t attr);
5044
5045 /** Get items attribute from a database cursor.
5046 *
5047 * This function retrieves key/data pairs from the database. The address and
5048 * length of the key are returned in the object to which key refers (except
5049 * for the case of the \ref MDBX_SET option, in which the key object is
5050 * unchanged), and the address and length of the data are returned in the object
5051 * to which data refers.
5052 * \see mdbx_get()
5053 *
5054 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open().
5055 * \param [in,out] key The key for a retrieved item.
5056 * \param [in,out] data The data of a retrieved item.
5057 * \param [out] pattr The pointer to retrieve attribute.
5058 * \param [in] op A cursor operation MDBX_cursor_op.
5059 *
5060 * \returns A non-zero error value on failure and 0 on success,
5061 * some possible errors are:
5062 * \retval MDBX_NOTFOUND No matching key found.
5063 * \retval MDBX_EINVAL An invalid parameter was specified. */
5064 LIBMDBX_API int mdbx_cursor_get_attr(MDBX_cursor *cursor, MDBX_val *key,
5065 MDBX_val *data, mdbx_attr_t *pattr,
5066 MDBX_cursor_op op);
5067
5068 /** Get items attribute from a database.
5069 *
5070 * This function retrieves key/data pairs from the database. The address
5071 * and length of the data associated with the specified key are returned
5072 * in the structure to which data refers.
5073 * If the database supports duplicate keys (see \ref MDBX_DUPSORT) then the
5074 * first data item for the key will be returned. Retrieval of other
5075 * items requires the use of \ref mdbx_cursor_get().
5076 *
5077 * \note The memory pointed to by the returned values is owned by the
5078 * database. The caller need not dispose of the memory, and may not
5079 * modify it in any way. For values returned in a read-only transaction
5080 * any modification attempts will cause a `SIGSEGV`.
5081 *
5082 * \note Values returned from the database are valid only until a
5083 * subsequent update operation, or the end of the transaction.
5084 *
5085 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin().
5086 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open().
5087 * \param [in] key The key to search for in the database.
5088 * \param [in,out] data The data corresponding to the key.
5089 * \param [out] pattr The pointer to retrieve attribute.
5090 *
5091 * \returns A non-zero error value on failure and 0 on success,
5092 * some possible errors are:
5093 * \retval MDBX_NOTFOUND The key was not in the database.
5094 * \retval MDBX_EINVAL An invalid parameter was specified. */
5095 LIBMDBX_API int mdbx_get_attr(MDBX_txn *txn, MDBX_dbi dbi, MDBX_val *key,
5096 MDBX_val *data, mdbx_attr_t *pattr);
5097 /** @} end of Attribute support functions for Nexenta */
5098 #endif /* MDBX_NEXENTA_ATTRS */
5099
5100 /** @} end of C API */
5101
5102 /*******************************************************************************
5103 * Workaround for mmaped-lookahead-cross-page-boundary bug
5104 * in an obsolete versions of Elbrus's libc and kernels. */
5105 #if defined(__e2k__) && defined(MDBX_E2K_MLHCPB_WORKAROUND) && \
5106 MDBX_E2K_MLHCPB_WORKAROUND
5107 LIBMDBX_API int mdbx_e2k_memcmp_bug_workaround(const void *s1, const void *s2,
5108 size_t n);
5109 LIBMDBX_API int mdbx_e2k_strcmp_bug_workaround(const char *s1, const char *s2);
5110 LIBMDBX_API int mdbx_e2k_strncmp_bug_workaround(const char *s1, const char *s2,
5111 size_t n);
5112 LIBMDBX_API size_t mdbx_e2k_strlen_bug_workaround(const char *s);
5113 LIBMDBX_API size_t mdbx_e2k_strnlen_bug_workaround(const char *s,
5114 size_t maxlen);
5115 #ifdef __cplusplus
5116 namespace std {
mdbx_e2k_memcmp_bug_workaround(const void * s1,const void * s2,size_t n)5117 inline int mdbx_e2k_memcmp_bug_workaround(const void *s1, const void *s2,
5118 size_t n) {
5119 return ::mdbx_e2k_memcmp_bug_workaround(s1, s2, n);
5120 }
mdbx_e2k_strcmp_bug_workaround(const char * s1,const char * s2)5121 inline int mdbx_e2k_strcmp_bug_workaround(const char *s1, const char *s2) {
5122 return ::mdbx_e2k_strcmp_bug_workaround(s1, s2);
5123 }
mdbx_e2k_strncmp_bug_workaround(const char * s1,const char * s2,size_t n)5124 inline int mdbx_e2k_strncmp_bug_workaround(const char *s1, const char *s2,
5125 size_t n) {
5126 return ::mdbx_e2k_strncmp_bug_workaround(s1, s2, n);
5127 }
mdbx_e2k_strlen_bug_workaround(const char * s)5128 inline size_t mdbx_e2k_strlen_bug_workaround(const char *s) {
5129 return ::mdbx_e2k_strlen_bug_workaround(s);
5130 }
mdbx_e2k_strnlen_bug_workaround(const char * s,size_t maxlen)5131 inline size_t mdbx_e2k_strnlen_bug_workaround(const char *s, size_t maxlen) {
5132 return ::mdbx_e2k_strnlen_bug_workaround(s, maxlen);
5133 }
5134 } // namespace std
5135 #endif /* __cplusplus */
5136
5137 #include <string.h>
5138 #include <strings.h>
5139 #undef memcmp
5140 #define memcmp mdbx_e2k_memcmp_bug_workaround
5141 #undef bcmp
5142 #define bcmp mdbx_e2k_memcmp_bug_workaround
5143 #undef strcmp
5144 #define strcmp mdbx_e2k_strcmp_bug_workaround
5145 #undef strncmp
5146 #define strncmp mdbx_e2k_strncmp_bug_workaround
5147 #undef strlen
5148 #define strlen mdbx_e2k_strlen_bug_workaround
5149 #undef strnlen
5150 #define strnlen mdbx_e2k_strnlen_bug_workaround
5151 #endif /* MDBX_E2K_MLHCPB_WORKAROUND */
5152
5153 #ifdef __cplusplus
5154 } /* extern "C" */
5155 #endif
5156
5157 #endif /* LIBMDBX_H */
5158