This repository has been archived by the owner on Sep 22, 2022. It is now read-only.
-
-
Notifications
You must be signed in to change notification settings - Fork 108
/
mdbx.h
1973 lines (1835 loc) · 84.7 KB
/
mdbx.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/* LICENSE AND COPYRUSTING *****************************************************
*
* Copyright 2015-2019 Leonid Yuriev <leo@yuriev.ru>
* and other libmdbx authors: please see AUTHORS file.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted only as authorized by the OpenLDAP
* Public License.
*
* A copy of this license is available in the file LICENSE in the
* top-level directory of the distribution or, alternatively, at
* <http://www.OpenLDAP.org/license.html>.
*
* ---
*
* This code is derived from "LMDB engine" written by
* Howard Chu (Symas Corporation), which itself derived from btree.c
* written by Martin Hedenfalk.
*
* ---
*
* Portions Copyright 2011-2015 Howard Chu, Symas Corp. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted only as authorized by the OpenLDAP
* Public License.
*
* A copy of this license is available in the file LICENSE in the
* top-level directory of the distribution or, alternatively, at
* <http://www.OpenLDAP.org/license.html>.
*
* ---
*
* Portions Copyright (c) 2009, 2010 Martin Hedenfalk <martin@bzero.se>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
/* ACKNOWLEDGEMENTS ************************************************************
*
* Howard Chu (Symas Corporation) - the author of LMDB,
* from which originated the MDBX in 2015.
*
* Martin Hedenfalk <martin@bzero.se> - the author of `btree.c` code,
* which was used for begin development of LMDB. */
#pragma once
#ifndef LIBMDBX_H
#define LIBMDBX_H
/* IMPENDING CHANGES WARNING ***************************************************
*
* MDBX is under active non-public development, database format and API
* will be refined. New version won't be backwards compatible. Main focus
* of the rework is to provide clear and robust API and new features.
*
******************************************************************************/
#ifdef _MSC_VER
#pragma warning(push, 1)
#pragma warning(disable : 4548) /* expression before comma has no effect; \
expected expression with side - effect */
#pragma warning(disable : 4530) /* C++ exception handler used, but unwind \
* semantics are not enabled. Specify /EHsc */
#pragma warning(disable : 4577) /* 'noexcept' used with no exception handling \
* mode specified; termination on exception is \
* not guaranteed. Specify /EHsc */
#endif /* _MSC_VER (warnings) */
#include <stdarg.h>
#include <stddef.h>
#include <stdint.h>
#if defined(_WIN32) || defined(_WIN64)
#include <windows.h>
#include <winnt.h>
#ifndef __mode_t_defined
typedef unsigned short mode_t;
#endif
typedef HANDLE mdbx_filehandle_t;
typedef DWORD mdbx_pid_t;
typedef DWORD mdbx_tid_t;
#define MDBX_ENODATA ERROR_HANDLE_EOF
#define MDBX_EINVAL ERROR_INVALID_PARAMETER
#define MDBX_EACCESS ERROR_ACCESS_DENIED
#define MDBX_ENOMEM ERROR_OUTOFMEMORY
#define MDBX_EROFS ERROR_FILE_READ_ONLY
#define MDBX_ENOSYS ERROR_NOT_SUPPORTED
#define MDBX_EIO ERROR_WRITE_FAULT
#define MDBX_EPERM ERROR_INVALID_FUNCTION
#define MDBX_EINTR ERROR_CANCELLED
#define MDBX_ENOFILE ERROR_FILE_NOT_FOUND
#else
#include <errno.h> /* for error codes */
#include <pthread.h> /* for pthread_t */
#include <sys/types.h> /* for pid_t */
#include <sys/uio.h> /* for truct iovec */
#define HAVE_STRUCT_IOVEC 1
typedef int mdbx_filehandle_t;
typedef pid_t mdbx_pid_t;
typedef pthread_t mdbx_tid_t;
#ifdef ENODATA
#define MDBX_ENODATA ENODATA
#else
#define MDBX_ENODATA -1
#endif
#define MDBX_EINVAL EINVAL
#define MDBX_EACCESS EACCES
#define MDBX_ENOMEM ENOMEM
#define MDBX_EROFS EROFS
#define MDBX_ENOSYS ENOSYS
#define MDBX_EIO EIO
#define MDBX_EPERM EPERM
#define MDBX_EINTR EINTR
#define MDBX_ENOFILE ENOENT
#endif
#ifdef _MSC_VER
#pragma warning(pop)
#endif
/*--------------------------------------------------------------------------*/
#ifndef __has_attribute
#define __has_attribute(x) (0)
#endif
#ifndef __dll_export
#if defined(_WIN32) || defined(__CYGWIN__)
#if defined(__GNUC__) || __has_attribute(dllexport)
#define __dll_export __attribute__((dllexport))
#elif defined(_MSC_VER)
#define __dll_export __declspec(dllexport)
#else
#define __dll_export
#endif
#elif defined(__GNUC__) || __has_attribute(visibility)
#define __dll_export __attribute__((visibility("default")))
#else
#define __dll_export
#endif
#endif /* __dll_export */
#ifndef __dll_import
#if defined(_WIN32) || defined(__CYGWIN__)
#if defined(__GNUC__) || __has_attribute(dllimport)
#define __dll_import __attribute__((dllimport))
#elif defined(_MSC_VER)
#define __dll_import __declspec(dllimport)
#else
#define __dll_import
#endif
#else
#define __dll_import
#endif
#endif /* __dll_import */
/*--------------------------------------------------------------------------*/
#define MDBX_VERSION_MAJOR 0
#define MDBX_VERSION_MINOR 3
#if defined(LIBMDBX_EXPORTS)
#define LIBMDBX_API __dll_export
#elif defined(LIBMDBX_IMPORTS)
#define LIBMDBX_API __dll_import
#else
#define LIBMDBX_API
#endif /* LIBMDBX_API */
#ifdef __cplusplus
extern "C" {
#endif
typedef struct mdbx_version_info {
uint8_t major;
uint8_t minor;
uint16_t release;
uint32_t revision;
struct {
const char *datetime;
const char *tree;
const char *commit;
const char *describe;
} git;
} mdbx_version_info;
typedef struct mdbx_build_info {
const char *datetime;
const char *target;
const char *options;
const char *compiler;
const char *flags;
} mdbx_build_info;
extern LIBMDBX_API const mdbx_version_info mdbx_version;
extern LIBMDBX_API const mdbx_build_info mdbx_build;
#if defined(_WIN32) || defined(_WIN64)
#ifndef MDBX_BUILD_DLL
/* Dll initialization callback for ability to dynamically load MDBX DLL by
* LoadLibrary() on Windows versions before Windows Vista. This function MUST be
* called once from DllMain() for each reason (DLL_PROCESS_ATTACH,
* DLL_PROCESS_DETACH, DLL_THREAD_ATTACH and DLL_THREAD_DETACH). Do this
* carefully and ONLY when actual Windows version don't support initialization
* via "TLS Directory" (e.g .CRT$XL[A-Z] sections in executable or dll file). */
#ifndef MDBX_CONFIG_MANUAL_TLS_CALLBACK
#define MDBX_CONFIG_MANUAL_TLS_CALLBACK 0
#endif
#if MDBX_CONFIG_MANUAL_TLS_CALLBACK
void LIBMDBX_API NTAPI mdbx_dll_callback(PVOID module, DWORD reason,
PVOID reserved);
#endif /* MDBX_CONFIG_MANUAL_TLS_CALLBACK */
#endif /* MDBX_BUILD_DLL */
#endif /* Windows */
/* The name of the lock file in the DB environment */
#define MDBX_LOCKNAME "/mdbx.lck"
/* The name of the data file in the DB environment */
#define MDBX_DATANAME "/mdbx.dat"
/* The suffix of the lock file when no subdir is used */
#define MDBX_LOCK_SUFFIX "-lck"
/* Opaque structure for a database environment.
*
* A DB environment supports multiple databases, all residing in the same
* shared-memory map. */
typedef struct MDBX_env MDBX_env;
/* Opaque structure for a transaction handle.
*
* All database operations require a transaction handle. Transactions may be
* read-only or read-write. */
typedef struct MDBX_txn MDBX_txn;
/* A handle for an individual database in the DB environment. */
typedef uint32_t MDBX_dbi;
/* Opaque structure for navigating through a database */
typedef struct MDBX_cursor MDBX_cursor;
/* Generic structure used for passing keys and data in and out
* of the database.
*
* Values returned from the database are valid only until a subsequent
* update operation, or the end of the transaction. Do not modify or
* free them, they commonly point into the database itself.
*
* Key sizes must be between 1 and mdbx_env_get_maxkeysize() inclusive.
* The same applies to data sizes in databases with the MDBX_DUPSORT flag.
* Other data items can in theory be from 0 to 0xffffffff bytes long. */
#ifndef HAVE_STRUCT_IOVEC
struct iovec {
void *iov_base;
size_t iov_len;
};
#define HAVE_STRUCT_IOVEC
#endif /* HAVE_STRUCT_IOVEC */
typedef struct iovec MDBX_val;
/* The maximum size of a data item.
* MDBX only store a 32 bit value for node sizes. */
#define MDBX_MAXDATASIZE INT32_MAX
/* A callback function used to compare two keys in a database */
typedef int(MDBX_cmp_func)(const MDBX_val *a, const MDBX_val *b);
/* Environment Flags */
/* no environment directory */
#define MDBX_NOSUBDIR 0x4000u
/* don't fsync after commit */
#define MDBX_NOSYNC 0x10000u
/* read only */
#define MDBX_RDONLY 0x20000u
/* don't fsync metapage after commit */
#define MDBX_NOMETASYNC 0x40000u
/* use writable mmap */
#define MDBX_WRITEMAP 0x80000u
/* use asynchronous msync when MDBX_WRITEMAP is used */
#define MDBX_MAPASYNC 0x100000u
/* tie reader locktable slots to MDBX_txn objects instead of to threads */
#define MDBX_NOTLS 0x200000u
/* open DB in exclusive/monopolistic mode. */
#define MDBX_EXCLUSIVE 0x400000u
/* don't do readahead */
#define MDBX_NORDAHEAD 0x800000u
/* don't initialize malloc'd memory before writing to datafile */
#define MDBX_NOMEMINIT 0x1000000u
/* aim to coalesce FreeDB records */
#define MDBX_COALESCE 0x2000000u
/* LIFO policy for reclaiming FreeDB records */
#define MDBX_LIFORECLAIM 0x4000000u
/* make a steady-sync only on close and explicit env-sync */
#define MDBX_UTTERLY_NOSYNC (MDBX_NOSYNC | MDBX_MAPASYNC)
/* debuging option, fill/perturb released pages */
#define MDBX_PAGEPERTURB 0x8000000u
/* Database Flags */
/* use reverse string keys */
#define MDBX_REVERSEKEY 0x02u
/* use sorted duplicates */
#define MDBX_DUPSORT 0x04u
/* numeric keys in native byte order, either uint32_t or uint64_t.
* The keys must all be of the same size. */
#define MDBX_INTEGERKEY 0x08u
/* with MDBX_DUPSORT, sorted dup items have fixed size */
#define MDBX_DUPFIXED 0x10u
/* with MDBX_DUPSORT, dups are MDBX_INTEGERKEY-style integers */
#define MDBX_INTEGERDUP 0x20u
/* with MDBX_DUPSORT, use reverse string dups */
#define MDBX_REVERSEDUP 0x40u
/* create DB if not already existing */
#define MDBX_CREATE 0x40000u
/* Write Flags */
/* For put: Don't write if the key already exists. */
#define MDBX_NOOVERWRITE 0x10u
/* Only for MDBX_DUPSORT
* For put: don't write if the key and data pair already exist.
* For mdbx_cursor_del: remove all duplicate data items. */
#define MDBX_NODUPDATA 0x20u
/* For mdbx_cursor_put: overwrite the current key/data pair
* MDBX allows this flag for mdbx_put() for explicit overwrite/update without
* insertion. */
#define MDBX_CURRENT 0x40u
/* For put: Just reserve space for data, don't copy it. Return a
* pointer to the reserved space. */
#define MDBX_RESERVE 0x10000u
/* Data is being appended, don't split full pages. */
#define MDBX_APPEND 0x20000u
/* Duplicate data is being appended, don't split full pages. */
#define MDBX_APPENDDUP 0x40000u
/* Store multiple data items in one call. Only for MDBX_DUPFIXED. */
#define MDBX_MULTIPLE 0x80000u
/* Transaction Flags */
/* Do not block when starting a write transaction */
#define MDBX_TRYTXN 0x10000000u
/* Copy Flags */
/* Compacting copy: Omit free space from copy, and renumber all
* pages sequentially. */
#define MDBX_CP_COMPACT 1u
/* Cursor Get operations.
*
* This is the set of all operations for retrieving data
* using a cursor. */
typedef enum MDBX_cursor_op {
MDBX_FIRST, /* Position at first key/data item */
MDBX_FIRST_DUP, /* MDBX_DUPSORT-only: Position at first data item
* of current key. */
MDBX_GET_BOTH, /* MDBX_DUPSORT-only: Position at key/data pair. */
MDBX_GET_BOTH_RANGE, /* MDBX_DUPSORT-only: position at key, nearest data. */
MDBX_GET_CURRENT, /* Return key/data at current cursor position */
MDBX_GET_MULTIPLE, /* MDBX_DUPFIXED-only: Return up to a page of duplicate
* data items from current cursor position.
* Move cursor to prepare for MDBX_NEXT_MULTIPLE. */
MDBX_LAST, /* Position at last key/data item */
MDBX_LAST_DUP, /* MDBX_DUPSORT-only: Position at last data item
* of current key. */
MDBX_NEXT, /* Position at next data item */
MDBX_NEXT_DUP, /* MDBX_DUPSORT-only: Position at next data item
* of current key. */
MDBX_NEXT_MULTIPLE, /* MDBX_DUPFIXED-only: Return up to a page of duplicate
* data items from next cursor position.
* Move cursor to prepare for MDBX_NEXT_MULTIPLE. */
MDBX_NEXT_NODUP, /* Position at first data item of next key */
MDBX_PREV, /* Position at previous data item */
MDBX_PREV_DUP, /* MDBX_DUPSORT-only: Position at previous data item
* of current key. */
MDBX_PREV_NODUP, /* Position at last data item of previous key */
MDBX_SET, /* Position at specified key */
MDBX_SET_KEY, /* Position at specified key, return both key and data */
MDBX_SET_RANGE, /* Position at first key greater than or equal to
* specified key. */
MDBX_PREV_MULTIPLE /* MDBX_DUPFIXED-only: Position at previous page and
* return up to a page of duplicate data items. */
} MDBX_cursor_op;
/* Return Codes
* BerkeleyDB uses -30800 to -30999, we'll go under them */
/* Successful result */
#define MDBX_SUCCESS 0
#define MDBX_RESULT_FALSE MDBX_SUCCESS
#define MDBX_RESULT_TRUE (-1)
/* key/data pair already exists */
#define MDBX_KEYEXIST (-30799)
/* key/data pair not found (EOF) */
#define MDBX_NOTFOUND (-30798)
/* Requested page not found - this usually indicates corruption */
#define MDBX_PAGE_NOTFOUND (-30797)
/* Located page was wrong type */
#define MDBX_CORRUPTED (-30796)
/* Update of meta page failed or environment had fatal error */
#define MDBX_PANIC (-30795)
/* DB file version mismatch with libmdbx */
#define MDBX_VERSION_MISMATCH (-30794)
/* File is not a valid MDBX file */
#define MDBX_INVALID (-30793)
/* Environment mapsize reached */
#define MDBX_MAP_FULL (-30792)
/* Environment maxdbs reached */
#define MDBX_DBS_FULL (-30791)
/* Environment maxreaders reached */
#define MDBX_READERS_FULL (-30790)
/* Txn has too many dirty pages */
#define MDBX_TXN_FULL (-30788)
/* Cursor stack too deep - internal error */
#define MDBX_CURSOR_FULL (-30787)
/* Page has not enough space - internal error */
#define MDBX_PAGE_FULL (-30786)
/* Database contents grew beyond environment mapsize */
#define MDBX_MAP_RESIZED (-30785)
/* Operation and DB incompatible, or DB type changed. This can mean:
* - The operation expects an MDBX_DUPSORT / MDBX_DUPFIXED database.
* - Opening a named DB when the unnamed DB has MDBX_DUPSORT/MDBX_INTEGERKEY.
* - Accessing a data record as a database, or vice versa.
* - The database was dropped and recreated with different flags. */
#define MDBX_INCOMPATIBLE (-30784)
/* Invalid reuse of reader locktable slot */
#define MDBX_BAD_RSLOT (-30783)
/* Transaction must abort, has a child, or is invalid */
#define MDBX_BAD_TXN (-30782)
/* Unsupported size of key/DB name/data, or wrong DUPFIXED size */
#define MDBX_BAD_VALSIZE (-30781)
/* The specified DBI was changed unexpectedly */
#define MDBX_BAD_DBI (-30780)
/* Unexpected problem - txn should abort */
#define MDBX_PROBLEM (-30779)
/* Another write transaction is running */
#define MDBX_BUSY (-30778)
/* The last defined error code */
#define MDBX_LAST_ERRCODE MDBX_BUSY
/* The mdbx_put() or mdbx_replace() was called for key,
that has more that one associated value. */
#define MDBX_EMULTIVAL (-30421)
/* Bad signature of a runtime object(s), this can mean:
* - memory corruption or double-free;
* - ABI version mismatch (rare case); */
#define MDBX_EBADSIGN (-30420)
/* Database should be recovered, but this could NOT be done automatically
* right now (e.g. in readonly mode and so forth). */
#define MDBX_WANNA_RECOVERY (-30419)
/* The given key value is mismatched to the current cursor position,
* when mdbx_cursor_put() called with MDBX_CURRENT option. */
#define MDBX_EKEYMISMATCH (-30418)
/* Database is too large for current system,
* e.g. could NOT be mapped into RAM. */
#define MDBX_TOO_LARGE (-30417)
/* A thread has attempted to use a not owned object,
* e.g. a transaction that started by another thread. */
#define MDBX_THREAD_MISMATCH (-30416)
/* Statistics for a database in the environment */
typedef struct MDBX_stat {
uint32_t ms_psize; /* Size of a database page.
* This is currently the same for all databases. */
uint32_t ms_depth; /* Depth (height) of the B-tree */
uint64_t ms_branch_pages; /* Number of internal (non-leaf) pages */
uint64_t ms_leaf_pages; /* Number of leaf pages */
uint64_t ms_overflow_pages; /* Number of overflow pages */
uint64_t ms_entries; /* Number of data items */
} MDBX_stat;
/* Information about the environment */
typedef struct MDBX_envinfo {
struct {
uint64_t lower; /* lower limit for datafile size */
uint64_t upper; /* upper limit for datafile size */
uint64_t current; /* current datafile size */
uint64_t shrink; /* shrink threshold for datafile */
uint64_t grow; /* growth step for datafile */
} mi_geo;
uint64_t mi_mapsize; /* Size of the data memory map */
uint64_t mi_last_pgno; /* ID of the last used page */
uint64_t mi_recent_txnid; /* ID of the last committed transaction */
uint64_t mi_latter_reader_txnid; /* ID of the last reader transaction */
uint64_t mi_self_latter_reader_txnid; /* ID of the last reader transaction of
caller process */
uint64_t mi_meta0_txnid, mi_meta0_sign;
uint64_t mi_meta1_txnid, mi_meta1_sign;
uint64_t mi_meta2_txnid, mi_meta2_sign;
uint32_t mi_maxreaders; /* max reader slots in the environment */
uint32_t mi_numreaders; /* max reader slots used in the environment */
uint32_t mi_dxb_pagesize; /* database pagesize */
uint32_t mi_sys_pagesize; /* system pagesize */
} MDBX_envinfo;
/* Return a string describing a given error code.
*
* This function is a superset of the ANSI C X3.159-1989 (ANSI C) strerror(3)
* function. If the error code is greater than or equal to 0, then the string
* returned by the system function strerror(3) is returned. If the error code
* is less than 0, an error string corresponding to the MDBX library error is
* returned. See errors for a list of MDBX-specific error codes.
*
* [in] err The error code
*
* Returns "error message" The description of the error */
LIBMDBX_API const char *mdbx_strerror(int errnum);
LIBMDBX_API const char *mdbx_strerror_r(int errnum, char *buf, size_t buflen);
/* Create an MDBX environment handle.
*
* This function allocates memory for a MDBX_env structure. To release
* the allocated memory and discard the handle, call mdbx_env_close().
* Before the handle may be used, it must be opened using mdbx_env_open().
* Various other options may also need to be set before opening the handle,
* e.g. mdbx_env_set_mapsize(), mdbx_env_set_maxreaders(),
* mdbx_env_set_maxdbs(), depending on usage requirements.
*
* [out] env The address where the new handle will be stored
*
* Returns A non-zero error value on failure and 0 on success. */
LIBMDBX_API int mdbx_env_create(MDBX_env **penv);
/* Open an environment handle.
*
* If this function fails, mdbx_env_close() must be called to discard
* the MDBX_env handle.
*
* [in] env An environment handle returned by mdbx_env_create()
* [in] path The directory in which the database files reside.
* This directory must already exist and be writable.
* [in] flags Special options for this environment. This parameter
* must be set to 0 or by bitwise OR'ing together one
* or more of the values described here.
*
* Flags set by mdbx_env_set_flags() are also used:
* - MDBX_NOSUBDIR
* By default, MDBX creates its environment in a directory whose
* pathname is given in path, and creates its data and lock files
* under that directory. With this option, path is used as-is for
* the database main data file. The database lock file is the path
* with "-lock" appended.
*
* - MDBX_RDONLY
* Open the environment in read-only mode. No write operations will
* be allowed. MDBX will still modify the lock file - except on
* read-only filesystems, where MDBX does not use locks.
*
* - MDBX_WRITEMAP
* Use a writeable memory map unless MDBX_RDONLY is set. This uses fewer
* mallocs but loses protection from application bugs like wild pointer
* writes and other bad updates into the database.
* This may be slightly faster for DBs that fit entirely in RAM,
* but is slower for DBs larger than RAM.
* Incompatible with nested transactions.
* Do not mix processes with and without MDBX_WRITEMAP on the same
* environment. This can defeat durability (mdbx_env_sync etc).
*
* - MDBX_NOMETASYNC
* Flush system buffers to disk only once per transaction, omit the
* metadata flush. Defer that until the system flushes files to disk,
* or next non-MDBX_RDONLY commit or mdbx_env_sync(). This optimization
* maintains database integrity, but a system crash may undo the last
* committed transaction. I.e. it preserves the ACI (atomicity,
* consistency, isolation) but not D (durability) database property.
* This flag may be changed at any time using mdbx_env_set_flags().
*
* - MDBX_NOSYNC
* Don't flush system buffers to disk when committing a transaction.
* This optimization means a system crash can corrupt the database or
* lose the last transactions if buffers are not yet flushed to disk.
* The risk is governed by how often the system flushes dirty buffers
* to disk and how often mdbx_env_sync() is called. However, if the
* filesystem preserves write order and the MDBX_WRITEMAP and/or
* MDBX_LIFORECLAIM flags are not used, transactions exhibit ACI
* (atomicity, consistency, isolation) properties and only lose D
* (durability). I.e. database integrity is maintained, but a system
* crash may undo the final transactions.
*
* Note that (MDBX_NOSYNC | MDBX_WRITEMAP) leaves the system with no
* hint for when to write transactions to disk.
* Therefore the (MDBX_MAPASYNC | MDBX_WRITEMAP) may be preferable.
* This flag may be changed at any time using mdbx_env_set_flags().
*
* - MDBX_UTTERLY_NOSYNC (internally MDBX_NOSYNC | MDBX_MAPASYNC)
* FIXME: TODO
*
* - MDBX_MAPASYNC
* When using MDBX_WRITEMAP, use asynchronous flushes to disk. As with
* MDBX_NOSYNC, a system crash can then corrupt the database or lose
* the last transactions. Calling mdbx_env_sync() ensures on-disk
* database integrity until next commit. This flag may be changed at
* any time using mdbx_env_set_flags().
*
* - MDBX_NOTLS
* Don't use Thread-Local Storage. Tie reader locktable slots to
* MDBX_txn objects instead of to threads. I.e. mdbx_txn_reset() keeps
* the slot reserved for the MDBX_txn object. A thread may use parallel
* read-only transactions. A read-only transaction may span threads if
* the user synchronizes its use. Applications that multiplex many
* user threads over individual OS threads need this option. Such an
* application must also serialize the write transactions in an OS
* thread, since MDBX's write locking is unaware of the user threads.
*
* - MDBX_NOLOCK (don't supported by MDBX)
* Don't do any locking. If concurrent access is anticipated, the
* caller must manage all concurrency itself. For proper operation
* the caller must enforce single-writer semantics, and must ensure
* that no readers are using old transactions while a writer is
* active. The simplest approach is to use an exclusive lock so that
* no readers may be active at all when a writer begins.
*
* - MDBX_NORDAHEAD
* Turn off readahead. Most operating systems perform readahead on
* read requests by default. This option turns it off if the OS
* supports it. Turning it off may help random read performance
* when the DB is larger than RAM and system RAM is full.
*
* - MDBX_NOMEMINIT
* Don't initialize malloc'd memory before writing to unused spaces
* in the data file. By default, memory for pages written to the data
* file is obtained using malloc. While these pages may be reused in
* subsequent transactions, freshly malloc'd pages will be initialized
* to zeroes before use. This avoids persisting leftover data from other
* code (that used the heap and subsequently freed the memory) into the
* data file. Note that many other system libraries may allocate and free
* memory from the heap for arbitrary uses. E.g., stdio may use the heap
* for file I/O buffers. This initialization step has a modest performance
* cost so some applications may want to disable it using this flag. This
* option can be a problem for applications which handle sensitive data
* like passwords, and it makes memory checkers like Valgrind noisy. This
* flag is not needed with MDBX_WRITEMAP, which writes directly to the
* mmap instead of using malloc for pages. The initialization is also
* skipped if MDBX_RESERVE is used; the caller is expected to overwrite
* all of the memory that was reserved in that case. This flag may be
* changed at any time using mdbx_env_set_flags().
*
* - MDBX_COALESCE
* Aim to coalesce records while reclaiming FreeDB. This flag may be
* changed at any time using mdbx_env_set_flags().
* FIXME: TODO
*
* - MDBX_LIFORECLAIM
* LIFO policy for reclaiming FreeDB records. This significantly reduce
* write IPOs in case MDBX_NOSYNC with periodically checkpoints.
* FIXME: TODO
*
* [in] mode The UNIX permissions to set on created files.
*
* Returns A non-zero error value on failure and 0 on success, some
* possible errors are:
* - MDBX_VERSION_MISMATCH - the version of the MDBX library doesn't match the
* version that created the database environment.
* - MDBX_INVALID - the environment file headers are corrupted.
* - MDBX_ENOENT - the directory specified by the path parameter
* doesn't exist.
* - MDBX_EACCES - the user didn't have permission to access
* the environment files.
* - MDBX_EAGAIN - the environment was locked by another process. */
LIBMDBX_API int mdbx_env_open(MDBX_env *env, const char *path, unsigned flags,
mode_t mode);
/* Copy an MDBX environment to the specified path, with options.
*
* This function may be used to make a backup of an existing environment.
* No lockfile is created, since it gets recreated at need.
* NOTE: This call can trigger significant file size growth if run in
* parallel with write transactions, because it employs a read-only
* transaction. See long-lived transactions under "Caveats" section.
*
* [in] env An environment handle returned by mdbx_env_create(). It must
* have already been opened successfully.
* [in] path The directory in which the copy will reside. This directory
* must already exist and be writable but must otherwise be empty.
* [in] flags Special options for this operation. This parameter must be set
* to 0 or by bitwise OR'ing together one or more of the values
* described here:
*
* - MDBX_CP_COMPACT
* Perform compaction while copying: omit free pages and sequentially
* renumber all pages in output. This option consumes little bit more
* CPU for processing, but may running quickly than the default, on
* account skipping free pages.
*
* NOTE: Currently it fails if the environment has suffered a page leak.
*
* Returns A non-zero error value on failure and 0 on success. */
LIBMDBX_API int mdbx_env_copy(MDBX_env *env, const char *dest_path,
unsigned flags);
/* Copy an MDBX environment to the specified file descriptor,
* with options.
*
* This function may be used to make a backup of an existing environment.
* No lockfile is created, since it gets recreated at need. See
* mdbx_env_copy() for further details.
*
* NOTE: This call can trigger significant file size growth if run in
* parallel with write transactions, because it employs a read-only
* transaction. See long-lived transactions under "Caveats" section.
*
* [in] env An environment handle returned by mdbx_env_create(). It must
* have already been opened successfully.
* [in] fd The filedescriptor to write the copy to. It must have already
* been opened for Write access.
* [in] flags Special options for this operation. See mdbx_env_copy() for
* options.
*
* Returns A non-zero error value on failure and 0 on success. */
LIBMDBX_API int mdbx_env_copy2fd(MDBX_env *env, mdbx_filehandle_t fd,
unsigned flags);
/* Return statistics about the MDBX environment.
*
* [in] env An environment handle returned by mdbx_env_create()
* [out] stat The address of an MDBX_stat structure where the statistics
* will be copied */
LIBMDBX_API int mdbx_env_stat(MDBX_env *env, MDBX_stat *stat, size_t bytes);
/* Return information about the MDBX environment.
*
* [in] env An environment handle returned by mdbx_env_create()
* [out] stat The address of an MDBX_envinfo structure
* where the information will be copied */
LIBMDBX_API int mdbx_env_info(MDBX_env *env, MDBX_envinfo *info, size_t bytes);
/* Flush the data buffers to disk.
*
* Data is always written to disk when mdbx_txn_commit() is called,
* but the operating system may keep it buffered. MDBX always flushes
* the OS buffers upon commit as well, unless the environment was
* opened with MDBX_NOSYNC or in part MDBX_NOMETASYNC. This call is
* not valid if the environment was opened with MDBX_RDONLY.
*
* [in] env An environment handle returned by mdbx_env_create()
* [in] force If non-zero, force a synchronous flush. Otherwise if the
* environment has the MDBX_NOSYNC flag set the flushes will be
* omitted, and with MDBX_MAPASYNC they will be asynchronous.
*
* Returns A non-zero error value on failure and 0 on success, some
* possible errors are:
* - MDBX_EACCES - the environment is read-only.
* - MDBX_EINVAL - an invalid parameter was specified.
* - MDBX_EIO - an error occurred during synchronization. */
LIBMDBX_API int mdbx_env_sync(MDBX_env *env, int force);
/* Close the environment and release the memory map.
*
* Only a single thread may call this function. All transactions, databases,
* and cursors must already be closed before calling this function. Attempts
* to use any such handles after calling this function will cause a SIGSEGV.
* The environment handle will be freed and must not be used again after this
* call.
*
* [in] env An environment handle returned by mdbx_env_create()
* [in] dont_sync A dont'sync flag, if non-zero the last checkpoint (meta-page
* update) will be kept "as is" and may be still "weak" in the
* NOSYNC/MAPASYNC modes. Such "weak" checkpoint will be
* ignored on opening next time, and transactions since the
* last non-weak checkpoint (meta-page update) will rolledback
* for consistency guarantee. */
LIBMDBX_API int mdbx_env_close(MDBX_env *env);
/* Set environment flags.
*
* This may be used to set some flags in addition to those from
* mdbx_env_open(), or to unset these flags. If several threads
* change the flags at the same time, the result is undefined.
*
* [in] env An environment handle returned by mdbx_env_create()
* [in] flags The flags to change, bitwise OR'ed together
* [in] onoff A non-zero value sets the flags, zero clears them.
*
* Returns A non-zero error value on failure and 0 on success, some
* possible errors are:
* - MDBX_EINVAL - an invalid parameter was specified. */
LIBMDBX_API int mdbx_env_set_flags(MDBX_env *env, unsigned flags, int onoff);
/* Get environment flags.
*
* [in] env An environment handle returned by mdbx_env_create()
* [out] flags The address of an integer to store the flags
*
* Returns A non-zero error value on failure and 0 on success, some
* possible errors are:
* - MDBX_EINVAL - an invalid parameter was specified. */
LIBMDBX_API int mdbx_env_get_flags(MDBX_env *env, unsigned *flags);
/* Return the path that was used in mdbx_env_open().
*
* [in] env An environment handle returned by mdbx_env_create()
* [out] path Address of a string pointer to contain the path.
* This is the actual string in the environment, not a copy.
* It should not be altered in any way.
*
* Returns A non-zero error value on failure and 0 on success, some
* possible errors are:
* - MDBX_EINVAL - an invalid parameter was specified. */
LIBMDBX_API int mdbx_env_get_path(MDBX_env *env, const char **path);
/* Return the file descriptor for the given environment.
*
* NOTE: All MDBX file descriptors have FD_CLOEXEC and
* could't be used after exec() and or fork().
*
* [in] env An environment handle returned by mdbx_env_create()
* [out] fd Address of a int to contain the descriptor.
*
* Returns A non-zero error value on failure and 0 on success, some
* possible errors are:
* - MDBX_EINVAL - an invalid parameter was specified. */
LIBMDBX_API int mdbx_env_get_fd(MDBX_env *env, mdbx_filehandle_t *fd);
/* Set the size of the memory map to use for this environment.
*
* The size should be a multiple of the OS page size. The default is
* 10485760 bytes. The size of the memory map is also the maximum size
* of the database. The value should be chosen as large as possible,
* to accommodate future growth of the database.
* This function should be called after mdbx_env_create() and before
* mdbx_env_open(). It may be called at later times if no transactions
* are active in this process. Note that the library does not check for
* this condition, the caller must ensure it explicitly.
*
* The new size takes effect immediately for the current process but
* will not be persisted to any others until a write transaction has been
* committed by the current process. Also, only mapsize increases are
* persisted into the environment.
*
* If the mapsize is increased by another process, and data has grown
* beyond the range of the current mapsize, mdbx_txn_begin() will
* return MDBX_MAP_RESIZED. This function may be called with a size
* of zero to adopt the new size.
*
* Any attempt to set a size smaller than the space already consumed by the
* environment will be silently changed to the current size of the used space.
*
* [in] env An environment handle returned by mdbx_env_create()
* [in] size The size in bytes
*
* Returns A non-zero error value on failure and 0 on success, some
* possible errors are:
* - MDBX_EINVAL - an invalid parameter was specified,
* or the environment has an active write transaction. */
LIBMDBX_API int mdbx_env_set_mapsize(MDBX_env *env, size_t size);
LIBMDBX_API int mdbx_env_set_geometry(MDBX_env *env, intptr_t size_lower,
intptr_t size_now, intptr_t size_upper,
intptr_t growth_step,
intptr_t shrink_threshold,
intptr_t pagesize);
/* Set the maximum number of threads/reader slots for the environment.
*
* This defines the number of slots in the lock table that is used to track
* readers in the the environment. The default is 61.
* Starting a read-only transaction normally ties a lock table slot to the
* current thread until the environment closes or the thread exits. If
* MDBX_NOTLS is in use, mdbx_txn_begin() instead ties the slot to the
* MDBX_txn object until it or the MDBX_env object is destroyed.
* This function may only be called after mdbx_env_create() and before
* mdbx_env_open().
*
* [in] env An environment handle returned by mdbx_env_create()
* [in] readers The maximum number of reader lock table slots
*
* Returns A non-zero error value on failure and 0 on success, some
* possible errors are:
* - MDBX_EINVAL - an invalid parameter was specified,
* or the environment is already open. */
LIBMDBX_API int mdbx_env_set_maxreaders(MDBX_env *env, unsigned readers);
/* Get the maximum number of threads/reader slots for the environment.
*
* [in] env An environment handle returned by mdbx_env_create()
* [out] readers Address of an integer to store the number of readers
*
* Returns A non-zero error value on failure and 0 on success, some
* possible errors are:
* - MDBX_EINVAL - an invalid parameter was specified. */
LIBMDBX_API int mdbx_env_get_maxreaders(MDBX_env *env, unsigned *readers);
/* Set the maximum number of named databases for the environment.
*
* This function is only needed if multiple databases will be used in the
* environment. Simpler applications that use the environment as a single
* unnamed database can ignore this option.
* This function may only be called after mdbx_env_create() and before
* mdbx_env_open().
*
* Currently a moderate number of slots are cheap but a huge number gets
* expensive: 7-120 words per transaction, and every mdbx_dbi_open()
* does a linear search of the opened slots.
*
* [in] env An environment handle returned by mdbx_env_create()
* [in] dbs The maximum number of databases
*
* Returns A non-zero error value on failure and 0 on success, some
* possible errors are:
* - MDBX_EINVAL - an invalid parameter was specified,
* or the environment is already open. */
LIBMDBX_API int mdbx_env_set_maxdbs(MDBX_env *env, MDBX_dbi dbs);
/* Get the maximum size of keys and MDBX_DUPSORT data we can write.
*
* [in] env An environment handle returned by mdbx_env_create()
*
* Returns The maximum size of a key we can write. */
LIBMDBX_API int mdbx_env_get_maxkeysize(MDBX_env *env);
/* Set application information associated with the MDBX_env.
*
* [in] env An environment handle returned by mdbx_env_create()
* [in] ctx An arbitrary pointer for whatever the application needs.
*
* Returns A non-zero error value on failure and 0 on success. */
LIBMDBX_API int mdbx_env_set_userctx(MDBX_env *env, void *ctx);
/* Get the application information associated with the MDBX_env.
*
* [in] env An environment handle returned by mdbx_env_create()
* Returns The pointer set by mdbx_env_set_userctx(). */
LIBMDBX_API void *mdbx_env_get_userctx(MDBX_env *env);
/* A callback function for most MDBX assert() failures,
* called before printing the message and aborting.
*
* [in] env An environment handle returned by mdbx_env_create().
* [in] msg The assertion message, not including newline. */
typedef void MDBX_assert_func(const MDBX_env *env, const char *msg,
const char *function, unsigned line);
/* Set or reset the assert() callback of the environment.
*
* Disabled if libmdbx is buillt with MDBX_DEBUG=0.
* NOTE: This hack should become obsolete as mdbx's error handling matures.
*
* [in] env An environment handle returned by mdbx_env_create().
* [in] func An MDBX_assert_func function, or 0.
*
* Returns A non-zero error value on failure and 0 on success. */
LIBMDBX_API int mdbx_env_set_assert(MDBX_env *env, MDBX_assert_func *func);
/* Create a transaction for use with the environment.
*
* The transaction handle may be discarded using mdbx_txn_abort()
* or mdbx_txn_commit().
* NOTE: A transaction and its cursors must only be used by a single
* thread, and a thread may only have a single transaction at a time.
* If MDBX_NOTLS is in use, this does not apply to read-only transactions.
* NOTE: Cursors may not span transactions.
*
* [in] env An environment handle returned by mdbx_env_create()
* [in] parent If this parameter is non-NULL, the new transaction will be
* a nested transaction, with the transaction indicated by parent
* as its parent. Transactions may be nested to any level.
* A parent transaction and its cursors may not issue any other
* operations than mdbx_txn_commit and mdbx_txn_abort while it
* has active child transactions.
* [in] flags Special options for this transaction. This parameter
* must be set to 0 or by bitwise OR'ing together one or more
* of the values described here.
*
* - MDBX_RDONLY
* This transaction will not perform any write operations.
*
* - MDBX_TRYTXN
* Do not block when starting a write transaction
*
* [out] txn Address where the new MDBX_txn handle will be stored
*
* Returns A non-zero error value on failure and 0 on success, some
* possible errors are:
* - MDBX_PANIC - a fatal error occurred earlier and the environment
* must be shut down.
* - MDBX_MAP_RESIZED - another process wrote data beyond this MDBX_env's
* mapsize and this environment's map must be resized
* as well. See mdbx_env_set_mapsize().
* - MDBX_READERS_FULL - a read-only transaction was requested and the reader
* lock table is full. See mdbx_env_set_maxreaders().
* - MDBX_ENOMEM - out of memory.
* - MDBX_BUSY - a write transaction is already started. */