· 9 years ago · Nov 20, 2016, 10:00 AM
1```crystal
2# @[Include("lmdb.h")]
3@[Link("lmdb")]
4
5lib LibLmdb
6 # NOTE: See the included limbmdb.h file for detailed comments and explanations
7 alias SizeT = UInt64
8 alias Int = LibC::Int
9 alias Char = LibC::Char
10 alias UInt = LibC::UInt
11
12 alias CmpFunc = MDB_val*, MDB_val* -> Int
13 # ** @brief Opaque structure for a database environment.
14 # *
15 # * A DB environment supports multiple databases, all residing in the same
16 # * shared-memory map.
17 # */
18 alias MDB_env = Void*
19
20 # /** @brief Opaque structure for a transaction handle.
21 # *
22 # * All database operations require a transaction handle. Transactions may be
23 # * read-only or read-write.
24 # */
25 # typedef struct MDB_txn MDB_txn;
26
27 alias MDB_txn = Void*
28
29 # /** @brief A handle for an individual database in the DB environment. */
30 # typedef unsigned int MDB_dbi;
31 alias MDB_dbi = UInt
32
33 # /** @brief Opaque structure for navigating through a database */
34 # typedef struct MDB_cursor MDB_cursor;
35 alias MDB_cursor = Void*
36
37 struct MDB_val
38 mv_size : SizeT # #/**< size of the data item */
39 mv_data : Void* # ; #/**< address of the data item */
40 end
41
42 # /** Unix permissions for creating files, or dummy definition for Windows */
43 # ifdef _MSC_VER
44 # typedef int mdb_mode_t;
45 # else
46 # typedef mode_t mdb_mode_t;
47 # endif
48 # not sure what to do with this one need to look up ifdefs
49 alias MDB_mode_t = Int
50
51 # ##/**@defgroup mdb_env Environment Flags
52 # * @{
53 # */
54
55 # NOTE: We could move these out of here and into higher level classes
56 # But I am leaving them here for now. Might be more futureproof this way.
57 # ##/**mmap at a fixed address (experimental) */
58 MDB_FIXEDMAP = 0x01
59 # #/**no environment directory */
60 MDB_NOSUBDIR = 0x4000
61 # #/**don't fsync after commit */
62 MDB_NOSYNC = 0x10000
63 # #/**read only */
64 MDB_RDONLY = 0x20000
65 # #/**don't fsync metapage after commit */
66 MDB_NOMETASYNC = 0x40000
67 # #/**use writable mmap */
68 MDB_WRITEMAP = 0x80000
69 # #/**use asynchronous msync when #MDB_WRITEMAP is used */
70 MDB_MAPASYNC = 0x100000
71 # #/**tie reader locktable slots to #MDB_txn objects instead of to threads */
72 MDB_NOTLS = 0x200000
73 # #/**don't do any locking, caller must manage their own locks */
74 MDB_NOLOCK = 0x400000
75 # #/**don't do readahead (no effect on Windows) */
76 MDB_NORDAHEAD = 0x800000
77 # #/**don't initialize malloc'd memory before writing to datafile */
78 MDB_NOMEMINIT = 0x1000000
79 # #/**@} */
80
81 # #/** @defgroup mdb_dbi_open Database Flags
82 # * @{
83 # */
84 # #/**use reverse string keys */
85 MDB_REVERSEKEY = 0x02
86 # #/**use sorted duplicates */
87 MDB_DUPSORT = 0x04
88 # #/**numeric keys in native byte order: either unsigned int or size_t.
89 # * The keys must all be of the same size. */
90 MDB_INTEGERKEY = 0x08
91 # #/**with #MDB_DUPSORT, sorted dup items have fixed size */
92 MDB_DUPFIXED = 0x10
93 # #/**with #MDB_DUPSORT, dups are #MDB_INTEGERKEY-style integers */
94 MDB_INTEGERDUP = 0x20
95 # #/**with #MDB_DUPSORT, use reverse string dups */
96 MDB_REVERSEDUP = 0x40
97 # #/**create DB if not already existing */
98 MDB_CREATE = 0x40000
99 # #/**@} */
100
101 # #/** @defgroup mdb_put Write Flags
102 # * @{
103 # */
104 # #/**For put: Don't write if the key already exists. */
105 MDB_NOOVERWRITE = 0x10
106 # #/**Only for #MDB_DUPSORT<br>
107 # * For put: don't write if the key and data pair already exist.<br>
108 # * For mdb_cursor_del: remove all duplicate data items.
109 # */
110 MDB_NODUPDATA = 0x20
111 # #/**For mdb_cursor_put: overwrite the current key/data pair */
112 MDB_CURRENT = 0x40
113 # #/**For put: Just reserve space for data, don't copy it. Return a
114 # * pointer to the reserved space.
115 # */
116 MDB_RESERVE = 0x10000
117 # #/**Data is being appended, don't split full pages. */
118 MDB_APPEND = 0x20000
119 # #/**Duplicate data is being appended, don't split full pages. */
120 MDB_APPENDDUP = 0x40000
121 # #/**Store multiple data items in one call. Only for #MDB_DUPFIXED. */
122 MDB_MULTIPLE = 0x80000
123 # /* @} */
124
125 # #/** @defgroup mdb_copy Copy Flags
126 # * @{
127 # */
128 # #/**Compacting copy: Omit free space from copy, and renumber all
129 # * pages sequentially.
130 # */
131 MDB_CP_COMPACT = 0x01
132 # /* @} */
133
134 # #/**@brief Cursor Get operations.
135 # *
136 # * This is the set of all operations for retrieving data
137 # * using a cursor.
138 # */
139 enum MDB_cursor_op
140 MDB_FIRST # #/**< Position at first key/data item */
141 MDB_FIRST_DUP # #/**< Position at first data item of current key.
142 # Only for #MDB_DUPSORT */
143 MDB_GET_BOTH # #/**< Position at key/data pair. Only for #MDB_DUPSORT */
144 MDB_GET_BOTH_RANGE # #/**< position at key nearest data. Only for #MDB_DUPSORT */
145 MDB_GET_CURRENT # #/**< Return key/data at current cursor position */
146 MDB_GET_MULTIPLE # #/**< Return key and up to a page of duplicate data items
147 # from current cursor position. Move cursor to prepare
148 # for #MDB_NEXT_MULTIPLE. Only for #MDB_DUPFIXED */
149 MDB_LAST # #/**< Position at last key/data item */
150 MDB_LAST_DUP # #/**< Position at last data item of current key.
151 # Only for #MDB_DUPSORT */
152 MDB_NEXT # #/**< Position at next data item */
153 MDB_NEXT_DUP # #/**< Position at next data item of current key.
154 # Only for #MDB_DUPSORT */
155 MDB_NEXT_MULTIPLE # #/**< Return key and up to a page of duplicate data items
156 # from next cursor position. Move cursor to prepare
157 # for #MDB_NEXT_MULTIPLE. Only for #MDB_DUPFIXED */
158 MDB_NEXT_NODUP # #/**< Position at first data item of next key */
159 MDB_PREV # #/**< Position at previous data item */
160 MDB_PREV_DUP # #/**< Position at previous data item of current key.
161 # Only for #MDB_DUPSORT */
162 MDB_PREV_NODUP # #/**< Position at last data item of previous key */
163 MDB_SET # #/**< Position at specified key */
164 MDB_SET_KEY # #/**< Position at specified key return key + data */
165 MDB_SET_RANGE # #/**< Position at first key greater than or equal to specified key. */
166 end
167
168 # #/**@} */
169
170 # #/**@brief Statistics for a database in the environment */
171 struct MDB_stat
172 ms_psize : UInt # /**< Size of a database page.
173 # This is currently the same for all databases. */
174 ms_depth : UInt # /**< Depth (height) of the B-tree */
175 ms_branch_pages : SizeT # /**< Number of internal (non-leaf) pages */
176 ms_leaf_pages : SizeT # /**< Number of leaf pages */
177 ms_overflow_pages : SizeT # /**< Number of overflow pages */
178 ms_entries : SizeT # /**< Number of data items */
179 end
180
181 # #/**@brief Information about the environment */
182 struct MDB_envinfo
183 me_mapaddr : Void* # /**< Address of map, if fixed */
184 me_mapsize : SizeT # /**< Size of the data memory map */
185 me_last_pgno : SizeT # /**< ID of the last used page */
186 me_last_txnid : SizeT # /**< ID of the last committed transaction */
187 me_maxreaders : UInt # /**< max reader slots in the environment */
188 me_numreaders : UInt # /**< max reader slots used in the environment */
189 end
190
191 # ##/**@brief Return the LMDB library version information.
192 # *
193 # * @param[out] major if non-NULL, the library major version number is copied here
194 # * @param[out] minor if non-NULL, the library minor version number is copied here
195 # * @param[out] patch if non-NULL, the library patch version number is copied here
196 # * @retval "version string" The library version as a string
197 # */
198
199 # -----char *mdb_version(int *major, int *minor, int *patch);
200 fun mdb_version(major : Int*, minor : Int*, patch : Int*) : Char*
201
202 # ##/**@brief Return a string describing a given error code.
203 # *
204 # * This function is a superset of the ANSI C X3.159-1989 (ANSI C) strerror(3)
205 # * function. If the error code is greater than or equal to 0, then the string
206 # * returned by the system function strerror(3) is returned. If the error code
207 # * is less than 0, an error string corresponding to the LMDB library error is
208 # * returned. See @ref errors for a list of LMDB-specific error codes.
209 # * @param[in] err The error code
210 # * @retval "error message" The description of the error
211 # */
212
213 # ----------char *mdb_strerror(int err);
214 fun mdb_strerror(err : Int) : Char*
215 # ##/**@brief Create an LMDB environment handle.
216 # *
217 # * This function allocates memory for a #MDB_env structure. To release
218 # * the allocated memory and discard the handle, call #mdb_env_close().
219 # * Before the handle may be used, it must be opened using #mdb_env_open().
220 # * Various other options may also need to be set before opening the handle,
221 # * e.g. #mdb_env_set_mapsize(), #mdb_env_set_maxreaders(), #mdb_env_set_maxdbs(),
222 # * depending on usage requirements.
223 # * @param[out] env The address where the new handle will be stored
224 # * @return A non-zero error value on failure and 0 on success.
225 # */
226
227 # ----------- int mdb_env_create(MDB_env **env);
228 fun mdb_env_create(Pointer(MDB_env*)) : Int
229
230 # ##/**@brief Open an environment handle.
231 # *
232 # * If this function fails, #mdb_env_close() must be called to discard the #MDB_env handle.
233 # * @param[in] env An environment handle returned by #mdb_env_create()
234 # * @param[in] path The directory in which the database files reside. This
235 # * directory must already exist and be writable.
236 # * @param[in] flags Special options for this environment. This parameter
237 # * must be set to 0 or by bitwise OR'ing together one or more of the
238 # * values described here.
239 # * Flags set by mdb_env_set_flags() are also used.
240 # * <ul>
241 # * <li>#MDB_FIXEDMAP
242 # * use a fixed address for the mmap region. This flag must be specified
243 # * when creating the environment, and is stored persistently in the environment.
244 # * If successful, the memory map will always reside at the same virtual address
245 # * and pointers used to reference data items in the database will be constant
246 # * across multiple invocations. This option may not always work, depending on
247 # * how the operating system has allocated memory to shared libraries and other uses.
248 # * The feature is highly experimental.
249 # * <li>#MDB_NOSUBDIR
250 # * By default, LMDB creates its environment in a directory whose
251 # * pathname is given in \b path, and creates its data and lock files
252 # * under that directory. With this option, \b path is used as-is for
253 # * the database main data file. The database lock file is the \b path
254 # * with "-lock" appended.
255 # * <li>#MDB_RDONLY
256 # * Open the environment in read-only mode. No write operations will be
257 # * allowed. LMDB will still modify the lock file - except on read-only
258 # * filesystems, where LMDB does not use locks.
259 # * <li>#MDB_WRITEMAP
260 # * Use a writeable memory map unless MDB_RDONLY is set. This uses
261 # * fewer mallocs but loses protection from application bugs
262 # * like wild pointer writes and other bad updates into the database.
263 # * This may be slightly faster for DBs that fit entirely in RAM, but
264 # * is slower for DBs larger than RAM.
265 # * Incompatible with nested transactions.
266 # * Do not mix processes with and without MDB_WRITEMAP on the same
267 # * environment. This can defeat durability (#mdb_env_sync etc).
268 # * <li>#MDB_NOMETASYNC
269 # * Flush system buffers to disk only once per transaction, omit the
270 # * metadata flush. Defer that until the system flushes files to disk,
271 # * or next non-MDB_RDONLY commit or #mdb_env_sync(). This optimization
272 # * maintains database integrity, but a system crash may undo the last
273 # * committed transaction. I.e. it preserves the ACI (atomicity,
274 # * consistency, isolation) but not D (durability) database property.
275 # * This flag may be changed at any time using #mdb_env_set_flags().
276 # * <li>#MDB_NOSYNC
277 # * Don't flush system buffers to disk when committing a transaction.
278 # * This optimization means a system crash can corrupt the database or
279 # * lose the last transactions if buffers are not yet flushed to disk.
280 # * The risk is governed by how often the system flushes dirty buffers
281 # * to disk and how often #mdb_env_sync() is called. However, if the
282 # * filesystem preserves write order and the #MDB_WRITEMAP flag is not
283 # * used, transactions exhibit ACI (atomicity, consistency, isolation)
284 # * properties and only lose D (durability). I.e. database integrity
285 # * is maintained, but a system crash may undo the final transactions.
286 # * Note that (#MDB_NOSYNC | #MDB_WRITEMAP) leaves the system with no
287 # * hint for when to write transactions to disk, unless #mdb_env_sync()
288 # * is called. (#MDB_MAPASYNC | #MDB_WRITEMAP) may be preferable.
289 # * This flag may be changed at any time using #mdb_env_set_flags().
290 # * <li>#MDB_MAPASYNC
291 # * When using #MDB_WRITEMAP, use asynchronous flushes to disk.
292 # * As with #MDB_NOSYNC, a system crash can then corrupt the
293 # * database or lose the last transactions. Calling #mdb_env_sync()
294 # * ensures on-disk database integrity until next commit.
295 # * This flag may be changed at any time using #mdb_env_set_flags().
296 # * <li>#MDB_NOTLS
297 # * Don't use Thread-Local Storage. Tie reader locktable slots to
298 # * #MDB_txn objects instead of to threads. I.e. #mdb_txn_reset() keeps
299 # * the slot reseved for the #MDB_txn object. A thread may use parallel
300 # * read-only transactions. A read-only transaction may span threads if
301 # * the user synchronizes its use. Applications that multiplex many
302 # * user threads over individual OS threads need this option. Such an
303 # * application must also serialize the write transactions in an OS
304 # * thread, since LMDB's write locking is unaware of the user threads.
305 # * <li>#MDB_NOLOCK
306 # * Don't do any locking. If concurrent access is anticipated, the
307 # * caller must manage all concurrency itself. For proper operation
308 # * the caller must enforce single-writer semantics, and must ensure
309 # * that no readers are using old transactions while a writer is
310 # * active. The simplest approach is to use an exclusive lock so that
311 # * no readers may be active at all when a writer begins.
312 # * <li>#MDB_NORDAHEAD
313 # * Turn off readahead. Most operating systems perform readahead on
314 # * read requests by default. This option turns it off if the OS
315 # * supports it. Turning it off may help random read performance
316 # * when the DB is larger than RAM and system RAM is full.
317 # * The option is not implemented on Windows.
318 # * <li>#MDB_NOMEMINIT
319 # * Don't initialize malloc'd memory before writing to unused spaces
320 # * in the data file. By default, memory for pages written to the data
321 # * file is obtained using malloc. While these pages may be reused in
322 # * subsequent transactions, freshly malloc'd pages will be initialized
323 # * to zeroes before use. This avoids persisting leftover data from other
324 # * code (that used the heap and subsequently freed the memory) into the
325 # * data file. Note that many other system libraries may allocate
326 # * and free memory from the heap for arbitrary uses. E.g., stdio may
327 # * use the heap for file I/O buffers. This initialization step has a
328 # * modest performance cost so some applications may want to disable
329 # * it using this flag. This option can be a problem for applications
330 # * which handle sensitive data like passwords, and it makes memory
331 # * checkers like Valgrind noisy. This flag is not needed with #MDB_WRITEMAP,
332 # * which writes directly to the mmap instead of using malloc for pages. The
333 # * initialization is also skipped if #MDB_RESERVE is used; the
334 # * caller is expected to overwrite all of the memory that was
335 # * reserved in that case.
336 # * This flag may be changed at any time using #mdb_env_set_flags().
337 # * </ul>
338 # * @param[in] mode The UNIX permissions to set on created files and semaphores.
339 # * This parameter is ignored on Windows.
340 # * @return A non-zero error value on failure and 0 on success. Some possible
341 # * errors are:
342 # * <ul>
343 # * <li>#MDB_VERSION_MISMATCH - the version of the LMDB library doesn't match the
344 # * version that created the database environment.
345 # * <li>#MDB_INVALID - the environment file headers are corrupted.
346 # * <li>ENOENT - the directory specified by the path parameter doesn't exist.
347 # * <li>EACCES - the user didn't have permission to access the environment files.
348 # * <li>EAGAIN - the environment was locked by another process.
349 # * </ul>
350 # */
351
352 # --------int mdb_env_open(MDB_env *env, const char *path, unsigned int flags, mdb_mode_t mode);
353 fun mdb_env_open(env : MDB_env, path : Char*, flags : UInt, mode : MDB_mode_t) : Int
354
355 # ##/**@brief Copy an LMDB environment to the specified path, with options.
356 # *
357 # * This function may be used to make a backup of an existing environment.
358 # * No lockfile is created, since it gets recreated at need.
359 # * @note This call can trigger significant file size growth if run in
360 # * parallel with write transactions, because it employs a read-only
361 # * transaction. See long-lived transactions under @ref caveats_sec.
362 # * @param[in] env An environment handle returned by #mdb_env_create(). It
363 # * must have already been opened successfully.
364 # * @param[in] path The directory in which the copy will reside. This
365 # * directory must already exist and be writable but must otherwise be
366 # * empty.
367 # * @param[in] flags Special options for this operation. This parameter
368 # * must be set to 0 or by bitwise OR'ing together one or more of the
369 # * values described here.
370 # * <ul>
371 # * <li>#MDB_CP_COMPACT - Perform compaction while copying: omit free
372 # * pages and sequentially renumber all pages in output. This option
373 # * consumes more CPU and runs more slowly than the default.
374 # * </ul>
375 # * @return A non-zero error value on failure and 0 on success.
376 # */
377
378 # ---------- int mdb_env_copy2(MDB_env *env, const char *path, unsigned int flags);
379 fun mdb_env_copy2(env : MDB_env, path : Char*, flags : UInt) : Int
380
381 # ##/**@brief Return statistics about the LMDB environment.
382 # *
383 # * @param[in] env An environment handle returned by #mdb_env_create()
384 # * @param[out] stat The address of an #MDB_stat structure
385 # * where the statistics will be copied
386 # */
387
388 # --------- int mdb_env_stat(MDB_env *env, MDB_stat *stat);
389 fun mdb_env_stat(env : MDB_env, stats : MDB_stat*) : Int
390
391 # ##/**@brief Return information about the LMDB environment.
392 # *
393 # * @param[in] env An environment handle returned by #mdb_env_create()
394 # * @param[out] stat The address of an #MDB_envinfo structure
395 # * where the information will be copied
396 # */
397
398 # ---------- int mdb_env_info(MDB_env *env, MDB_envinfo *stat);
399 fun mdb_env_info(env : MDB_env, stat : MDB_envinfo*) : Int
400
401 # ##/**@brief Flush the data buffers to disk.
402 # *
403 # * Data is always written to disk when #mdb_txn_commit() is called,
404 # * but the operating system may keep it buffered. LMDB always flushes
405 # * the OS buffers upon commit as well, unless the environment was
406 # * opened with #MDB_NOSYNC or in part #MDB_NOMETASYNC. This call is
407 # * not valid if the environment was opened with #MDB_RDONLY.
408 # * @param[in] env An environment handle returned by #mdb_env_create()
409 # * @param[in] force If non-zero, force a synchronous flush. Otherwise
410 # * if the environment has the #MDB_NOSYNC flag set the flushes
411 # * will be omitted, and with #MDB_MAPASYNC they will be asynchronous.
412 # * @return A non-zero error value on failure and 0 on success. Some possible
413 # * errors are:
414 # * <ul>
415 # * <li>EACCES - the environment is read-only.
416 # * <li>EINVAL - an invalid parameter was specified.
417 # * <li>EIO - an error occurred during synchronization.
418 # * </ul>
419 # */
420
421 # --------- int mdb_env_sync(MDB_env *env, int force);
422 fun mdb_env_sync(env : MDB_env, force : Int) : Int
423 # ##/**@brief Close the environment and release the memory map.
424 # *
425 # * Only a single thread may call this function. All transactions, databases,
426 # * and cursors must already be closed before calling this function. Attempts to
427 # * use any such handles after calling this function will cause a SIGSEGV.
428 # * The environment handle will be freed and must not be used again after this call.
429 # * @param[in] env An environment handle returned by #mdb_env_create()
430 # */
431
432 # ----- void mdb_env_close(MDB_env *env);
433 fun mdb_env_close(MDB_env)
434 # ##/**@brief Set environment flags.
435 # *
436 # * This may be used to set some flags in addition to those from
437 # * #mdb_env_open(), or to unset these flags. If several threads
438 # * change the flags at the same time, the result is undefined.
439 # * @param[in] env An environment handle returned by #mdb_env_create()
440 # * @param[in] flags The flags to change, bitwise OR'ed together
441 # * @param[in] onoff A non-zero value sets the flags, zero clears them.
442 # * @return A non-zero error value on failure and 0 on success. Some possible
443 # * errors are:
444 # * <ul>
445 # * <li>EINVAL - an invalid parameter was specified.
446 # * </ul>
447 # */
448
449 # ------- int mdb_env_set_flags(MDB_env *env, unsigned int flags, int onoff);
450 fun mdb_env_set_flags(env : MDB_env, flags : UInt, on_or_off : Int) : Int
451 # ##/**@brief Get environment flags.
452 # *
453 # * @param[in] env An environment handle returned by #mdb_env_create()
454 # * @param[out] flags The address of an integer to store the flags
455 # * @return A non-zero error value on failure and 0 on success. Some possible
456 # * errors are:
457 # * <ul>
458 # * <li>EINVAL - an invalid parameter was specified.
459 # * </ul>
460 # */
461
462 # -------- int mdb_env_get_flags(MDB_env *env, unsigned int *flags);
463 fun mdb_env_get_flags(env : MDB_env, flags : UInt*) : Int
464 # ##/**@brief Return the path that was used in #mdb_env_open().
465 # *
466 # * @param[in] env An environment handle returned by #mdb_env_create()
467 # * @param[out] path Address of a string pointer to contain the path. This
468 # * is the actual string in the environment, not a copy. It should not be
469 # * altered in any way.
470 # * @return A non-zero error value on failure and 0 on success. Some possible
471 # * errors are:
472 # * <ul>
473 # * <li>EINVAL - an invalid parameter was specified.
474 # * </ul>
475 # */
476
477 # ------- int mdb_env_get_path(MDB_env *env, const char **path);
478 fun mdb_env_get_path(env : MDB_env, path : Pointer(Char*)) : Int
479
480 # ##/**@brief Return the filedescriptor for the given environment.
481 # *
482 # * @param[in] env An environment handle returned by #mdb_env_create()
483 # * @param[out] fd Address of a mdb_filehandle_t to contain the descriptor.
484 # * @return A non-zero error value on failure and 0 on success. Some possible
485 # * errors are:
486 # * <ul>
487 # * <li>EINVAL - an invalid parameter was specified.
488 # * </ul>
489 # */
490
491 # -------int mdb_env_get_fd(MDB_env *env, mdb_filehandle_t *fd);
492
493 # ##/**@brief Set the size of the memory map to use for this environment.
494 # *
495 # * The size should be a multiple of the OS page size. The default is
496 # * 10485760 bytes. The size of the memory map is also the maximum size
497 # * of the database. The value should be chosen as large as possible,
498 # * to accommodate future growth of the database.
499 # * This function should be called after #mdb_env_create() and before #mdb_env_open().
500 # * It may be called at later times if no transactions are active in
501 # * this process. Note that the library does not check for this condition,
502 # * the caller must ensure it explicitly.
503 # *
504 # * The new size takes effect immediately for the current process but
505 # * will not be persisted to any others until a write transaction has been
506 # * committed by the current process. Also, only mapsize increases are
507 # * persisted into the environment.
508 # *
509 # * If the mapsize is increased by another process, and data has grown
510 # * beyond the range of the current mapsize, #mdb_txn_begin() will
511 # * return #MDB_MAP_RESIZED. This function may be called with a size
512 # * of zero to adopt the new size.
513 # *
514 # * Any attempt to set a size smaller than the space already consumed
515 # * by the environment will be silently changed to the current size of the used space.
516 # * @param[in] env An environment handle returned by #mdb_env_create()
517 # * @param[in] size The size in bytes
518 # * @return A non-zero error value on failure and 0 on success. Some possible
519 # * errors are:
520 # * <ul>
521 # * <li>EINVAL - an invalid parameter was specified, or the environment has
522 # * an active write transaction.
523 # * </ul>
524 # */
525 # ------- int mdb_env_set_mapsize(MDB_env *env, size_t size);
526 fun mdb_env_set_mapsize(env : MDB_env, size : SizeT) : Int
527
528 # ##/**@brief Set the maximum number of threads/reader slots for the environment.
529 # *
530 # * This defines the number of slots in the lock table that is used to track readers in the
531 # * the environment. The default is 126.
532 # * Starting a read-only transaction normally ties a lock table slot to the
533 # * current thread until the environment closes or the thread exits. If
534 # * MDB_NOTLS is in use, #mdb_txn_begin() instead ties the slot to the
535 # * MDB_txn object until it or the #MDB_env object is destroyed.
536 # * This function may only be called after #mdb_env_create() and before #mdb_env_open().
537 # * @param[in] env An environment handle returned by #mdb_env_create()
538 # * @param[in] readers The maximum number of reader lock table slots
539 # * @return A non-zero error value on failure and 0 on success. Some possible
540 # * errors are:
541 # * <ul>
542 # * <li>EINVAL - an invalid parameter was specified, or the environment is already open.
543 # * </ul>
544 # */
545
546 # -------- int mdb_env_set_maxreaders(MDB_env *env, unsigned int readers);
547 fun mdb_env_set_maxreaders(env : MDB_env, readers : UInt) : Int
548
549 # ##/**@brief Get the maximum number of threads/reader slots for the environment.
550 # *
551 # * @param[in] env An environment handle returned by #mdb_env_create()
552 # * @param[out] readers Address of an integer to store the number of readers
553 # * @return A non-zero error value on failure and 0 on success. Some possible
554 # * errors are:
555 # * <ul>
556 # * <li>EINVAL - an invalid parameter was specified.
557 # * </ul>
558 # */
559
560 # --------- int mdb_env_get_maxreaders(MDB_env *env, unsigned int *readers);
561 fun mdb_env_get_maxreaders(env : MDB_env, readers : UInt*) : Int
562
563 # ##/**@brief Set the maximum number of named databases for the environment.
564 # *
565 # * This function is only needed if multiple databases will be used in the
566 # * environment. Simpler applications that use the environment as a single
567 # * unnamed database can ignore this option.
568 # * This function may only be called after #mdb_env_create() and before #mdb_env_open().
569 # *
570 # * Currently a moderate number of slots are cheap but a huge number gets
571 # * expensive: 7-120 words per transaction, and every #mdb_dbi_open()
572 # * does a linear search of the opened slots.
573 # * @param[in] env An environment handle returned by #mdb_env_create()
574 # * @param[in] dbs The maximum number of databases
575 # * @return A non-zero error value on failure and 0 on success. Some possible
576 # * errors are:
577 # * <ul>
578 # * <li>EINVAL - an invalid parameter was specified, or the environment is already open.
579 # * </ul>
580 # */
581
582 # ------- int mdb_env_set_maxdbs(MDB_env *env, MDB_dbi dbs);
583 fun mdb_env_set_maxdbs(env : MDB_env, dbs : MDB_dbi) : Int
584 # ##/**@brief Get the maximum size of keys and #MDB_DUPSORT data we can write.
585 # *
586 # * Depends on the compile-time constant #MDB_MAXKEYSIZE. Default 511.
587 # * See @ref MDB_val.
588 # * @param[in] env An environment handle returned by #mdb_env_create()
589 # * @return The maximum size of a key we can write
590 # */
591
592 # --------- int mdb_env_get_maxkeysize(MDB_env *env);
593 fun mdb_env_get_maxkeysize(env : MDB_env) : Int
594 # ##/**@brief Set application information associated with the #MDB_env.
595 # *
596 # * @param[in] env An environment handle returned by #mdb_env_create()
597 # * @param[in] ctx An arbitrary pointer for whatever the application needs.
598 # * @return A non-zero error value on failure and 0 on success.
599 # */
600
601 # --------- int mdb_env_set_userctx(MDB_env *env, void *ctx);
602
603 # ##/**@brief Get the application information associated with the #MDB_env.
604 # *
605 # * @param[in] env An environment handle returned by #mdb_env_create()
606 # * @return The pointer set by #mdb_env_set_userctx().
607 # */
608
609 # ------- void *mdb_env_get_userctx(MDB_env *env);
610
611 # ##/**@brief A callback function for most LMDB assert() failures,
612 # * called before printing the message and aborting.
613 # *
614 # * @param[in] env An environment handle returned by #mdb_env_create().
615 # * @param[in] msg The assertion message, not including newline.
616 # */
617
618 # -------- typedef void MDB_assert_func(MDB_env *env, const char *msg);
619
620 #
621 # ##/**Set or reset the assert() callback of the environment.
622 # * Disabled if liblmdb is buillt with NDEBUG.
623 # * @note This hack should become obsolete as lmdb's error handling matures.
624 # * @param[in] env An environment handle returned by #mdb_env_create().
625 # * @param[in] func An #MDB_assert_func function, or 0.
626 # * @return A non-zero error value on failure and 0 on success.
627 # */
628
629 # --------- int mdb_env_set_assert(MDB_env *env, MDB_assert_func *func);
630
631 # ##/**@brief Create a transaction for use with the environment.
632 # *
633 # * The transaction handle may be discarded using #mdb_txn_abort() or #mdb_txn_commit().
634 # * @note A transaction and its cursors must only be used by a single
635 # * thread, and a thread may only have a single transaction at a time.
636 # * If #MDB_NOTLS is in use, this does not apply to read-only transactions.
637 # * @note Cursors may not span transactions.
638 # * @param[in] env An environment handle returned by #mdb_env_create()
639 # * @param[in] parent If this parameter is non-NULL, the new transaction
640 # * will be a nested transaction, with the transaction indicated by \b parent
641 # * as its parent. Transactions may be nested to any level. A parent
642 # * transaction and its cursors may not issue any other operations than
643 # * mdb_txn_commit and mdb_txn_abort while it has active child transactions.
644 # * @param[in] flags Special options for this transaction. This parameter
645 # * must be set to 0 or by bitwise OR'ing together one or more of the
646 # * values described here.
647 # * <ul>
648 # * <li>#MDB_RDONLY
649 # * This transaction will not perform any write operations.
650 # * </ul>
651 # * @param[out] txn Address where the new #MDB_txn handle will be stored
652 # * @return A non-zero error value on failure and 0 on success. Some possible
653 # * errors are:
654 # * <ul>
655 # * <li>#MDB_PANIC - a fatal error occurred earlier and the environment
656 # * must be shut down.
657 # * <li>#MDB_MAP_RESIZED - another process wrote data beyond this MDB_env's
658 # * mapsize and this environment's map must be resized as well.
659 # * See #mdb_env_set_mapsize().
660 # * <li>#MDB_READERS_FULL - a read-only transaction was requested and
661 # * the reader lock table is full. See #mdb_env_set_maxreaders().
662 # * <li>ENOMEM - out of memory.
663 # * </ul>
664 # */
665
666 # --------int mdb_txn_begin(MDB_env *env, MDB_txn *parent, unsigned int flags, MDB_txn **txn);
667 fun mdb_txn_begin(env : MDB_env, parent : MDB_txn, flags : UInt, txn : MDB_txn*) : Int
668 # ##/**@brief Returns the transaction's #MDB_env
669 # *
670 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
671 # */
672
673 # ------MDB_env *mdb_txn_env(MDB_txn *txn);
674
675 # ##/**@brief Return the transaction's ID.
676 # *
677 # * This returns the identifier associated with this transaction. For a
678 # * read-only transaction, this corresponds to the snapshot being read;
679 # * concurrent readers will frequently have the same transaction ID.
680 # *
681 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
682 # * @return A transaction ID, valid if input is an active transaction.
683 # */
684
685 # ----- size_t mdb_txn_id(MDB_txn *txn);
686 fun mdb_txn_id(txn : MDB_txn) : SizeT
687 # ##/**@brief Commit all the operations of a transaction into the database.
688 # *
689 # * The transaction handle is freed. It and its cursors must not be used
690 # * again after this call, except with #mdb_cursor_renew().
691 # * @note Earlier documentation incorrectly said all cursors would be freed.
692 # * Only write-transactions free cursors.
693 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
694 # * @return A non-zero error value on failure and 0 on success. Some possible
695 # * errors are:
696 # * <ul>
697 # * <li>EINVAL - an invalid parameter was specified.
698 # * <li>ENOSPC - no more disk space.
699 # * <li>EIO - a low-level I/O error occurred while writing.
700 # * <li>ENOMEM - out of memory.
701 # * </ul>
702 # */
703
704 # ------ int mdb_txn_commit(MDB_txn *txn);
705 fun mdb_txn_commit(txn : MDB_txn) : Int
706 # ##/**@brief Abandon all the operations of the transaction instead of saving them.
707 # *
708 # * The transaction handle is freed. It and its cursors must not be used
709 # * again after this call, except with #mdb_cursor_renew().
710 # * @note Earlier documentation incorrectly said all cursors would be freed.
711 # * Only write-transactions free cursors.
712 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
713 # */
714
715 # ------- void mdb_txn_abort(MDB_txn *txn);
716 fun mdb_txn_abort(txn : MDB_txn)
717
718 # ##/**@brief Reset a read-only transaction.
719 # *
720 # * Abort the transaction like #mdb_txn_abort(), but keep the transaction
721 # * handle. #mdb_txn_renew() may reuse the handle. This saves allocation
722 # * overhead if the process will start a new read-only transaction soon,
723 # * and also locking overhead if #MDB_NOTLS is in use. The reader table
724 # * lock is released, but the table slot stays tied to its thread or
725 # * #MDB_txn. Use mdb_txn_abort() to discard a reset handle, and to free
726 # * its lock table slot if MDB_NOTLS is in use.
727 # * Cursors opened within the transaction must not be used
728 # * again after this call, except with #mdb_cursor_renew().
729 # * Reader locks generally don't interfere with writers, but they keep old
730 # * versions of database pages allocated. Thus they prevent the old pages
731 # * from being reused when writers commit new data, and so under heavy load
732 # * the database size may grow much more rapidly than otherwise.
733 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
734 # */
735
736 # -------- void mdb_txn_reset(MDB_txn *txn);
737
738 # ##/**@brief Renew a read-only transaction.
739 # *
740 # * This acquires a new reader lock for a transaction handle that had been
741 # * released by #mdb_txn_reset(). It must be called before a reset transaction
742 # * may be used again.
743 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
744 # * @return A non-zero error value on failure and 0 on success. Some possible
745 # * errors are:
746 # * <ul>
747 # * <li>#MDB_PANIC - a fatal error occurred earlier and the environment
748 # * must be shut down.
749 # * <li>EINVAL - an invalid parameter was specified.
750 # * </ul>
751 # */
752
753 # ------- int mdb_txn_renew(MDB_txn *txn);
754
755 # ##/**Compat with version <= 0.9.4, avoid clash with libmdb from MDB Tools project */
756 # mdb_open(txn,name,flags,dbi) mdb_dbi_open(txn,name,flags,dbi)
757 # ##/**Compat with version <= 0.9.4, avoid clash with libmdb from MDB Tools project */
758 # mdb_close(env,dbi) mdb_dbi_close(env,dbi)
759 #
760 # ##/**@brief Open a database in the environment.
761 # *
762 # * A database handle denotes the name and parameters of a database,
763 # * independently of whether such a database exists.
764 # * The database handle may be discarded by calling #mdb_dbi_close().
765 # * The old database handle is returned if the database was already open.
766 # * The handle may only be closed once.
767 # *
768 # * The database handle will be private to the current transaction until
769 # * the transaction is successfully committed. If the transaction is
770 # * aborted the handle will be closed automatically.
771 # * After a successful commit the handle will reside in the shared
772 # * environment, and may be used by other transactions.
773 # *
774 # * This function must not be called from multiple concurrent
775 # * transactions in the same process. A transaction that uses
776 # * this function must finish (either commit or abort) before
777 # * any other transaction in the process may use this function.
778 # *
779 # * To use named databases (with name != NULL), #mdb_env_set_maxdbs()
780 # * must be called before opening the environment. Database names are
781 # * keys in the unnamed database, and may be read but not written.
782 # *
783 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
784 # * @param[in] name The name of the database to open. If only a single
785 # * database is needed in the environment, this value may be NULL.
786 # * @param[in] flags Special options for this database. This parameter
787 # * must be set to 0 or by bitwise OR'ing together one or more of the
788 # * values described here.
789 # * <ul>
790 # * <li>#MDB_REVERSEKEY
791 # * Keys are strings to be compared in reverse order, from the end
792 # * of the strings to the beginning. By default, Keys are treated as strings and
793 # * compared from beginning to end.
794 # * <li>#MDB_DUPSORT
795 # * Duplicate keys may be used in the database. (Or, from another perspective,
796 # * keys may have multiple data items, stored in sorted order.) By default
797 # * keys must be unique and may have only a single data item.
798 # * <li>#MDB_INTEGERKEY
799 # * Keys are binary integers in native byte order, either unsigned int
800 # * or size_t, and will be sorted as such.
801 # * The keys must all be of the same size.
802 # * <li>#MDB_DUPFIXED
803 # * This flag may only be used in combination with #MDB_DUPSORT. This option
804 # * tells the library that the data items for this database are all the same
805 # * size, which allows further optimizations in storage and retrieval. When
806 # * all data items are the same size, the #MDB_GET_MULTIPLE and #MDB_NEXT_MULTIPLE
807 # * cursor operations may be used to retrieve multiple items at once.
808 # * <li>#MDB_INTEGERDUP
809 # * This option specifies that duplicate data items are binary integers,
810 # * similar to #MDB_INTEGERKEY keys.
811 # * <li>#MDB_REVERSEDUP
812 # * This option specifies that duplicate data items should be compared as
813 # * strings in reverse order.
814 # * <li>#MDB_CREATE
815 # * Create the named database if it doesn't exist. This option is not
816 # * allowed in a read-only transaction or a read-only environment.
817 # * </ul>
818 # * @param[out] dbi Address where the new #MDB_dbi handle will be stored
819 # * @return A non-zero error value on failure and 0 on success. Some possible
820 # * errors are:
821 # * <ul>
822 # * <li>#MDB_NOTFOUND - the specified database doesn't exist in the environment
823 # * and #MDB_CREATE was not specified.
824 # * <li>#MDB_DBS_FULL - too many databases have been opened. See #mdb_env_set_maxdbs().
825 # * </ul>
826 # */
827
828 # ------- int mdb_dbi_open(MDB_txn *txn, const char *name, unsigned int flags, MDB_dbi *dbi);
829 fun mdb_dbi_open(txn : MDB_txn, name : Char* | Nil, flags : UInt, dbi : MDB_dbi*) : Int
830 # ##/**@brief Retrieve statistics for a database.
831 # *
832 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
833 # * @param[in] dbi A database handle returned by #mdb_dbi_open()
834 # * @param[out] stat The address of an #MDB_stat structure
835 # * where the statistics will be copied
836 # * @return A non-zero error value on failure and 0 on success. Some possible
837 # * errors are:
838 # * <ul>
839 # * <li>EINVAL - an invalid parameter was specified.
840 # * </ul>
841 # */
842
843 # -------- int mdb_stat(MDB_txn *txn, MDB_dbi dbi, MDB_stat *stat);
844 fun mdb_stat(txn : MDB_txn, db : MDB_dbi, stats : MDB_stat*) : Int
845
846 # ##/**@brief Retrieve the DB flags for a database handle.
847 # *
848 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
849 # * @param[in] dbi A database handle returned by #mdb_dbi_open()
850 # * @param[out] flags Address where the flags will be returned.
851 # * @return A non-zero error value on failure and 0 on success.
852 # */
853
854 # -------- int mdb_dbi_flags(MDB_txn *txn, MDB_dbi dbi, unsigned int *flags);
855
856 # ##/**@brief Close a database handle. Normally unnecessary. Use with care:
857 # *
858 # * This call is not mutex protected. Handles should only be closed by
859 # * a single thread, and only if no other threads are going to reference
860 # * the database handle or one of its cursors any further. Do not close
861 # * a handle if an existing transaction has modified its database.
862 # * Doing so can cause misbehavior from database corruption to errors
863 # * like MDB_BAD_VALSIZE (since the DB name is gone).
864 # *
865 # * Closing a database handle is not necessary, but lets #mdb_dbi_open()
866 # * reuse the handle value. Usually it's better to set a bigger
867 # * #mdb_env_set_maxdbs(), unless that value would be large.
868 # *
869 # * @param[in] env An environment handle returned by #mdb_env_create()
870 # * @param[in] dbi A database handle returned by #mdb_dbi_open()
871 # */
872
873 # -------- void mdb_dbi_close(MDB_env *env, MDB_dbi dbi);
874
875 # ##/**@brief Empty or delete+close a database.
876 # *
877 # * See #mdb_dbi_close() for restrictions about closing the DB handle.
878 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
879 # * @param[in] dbi A database handle returned by #mdb_dbi_open()
880 # * @param[in] del 0 to empty the DB, 1 to delete it from the
881 # * environment and close the DB handle.
882 # * @return A non-zero error value on failure and 0 on success.
883 # */
884
885 # ------- int mdb_drop(MDB_txn *txn, MDB_dbi dbi, int del);
886
887 # ##/**@brief Set a custom key comparison function for a database.
888 # *
889 # * The comparison function is called whenever it is necessary to compare a
890 # * key specified by the application with a key currently stored in the database.
891 # * If no comparison function is specified, and no special key flags were specified
892 # * with #mdb_dbi_open(), the keys are compared lexically, with shorter keys collating
893 # * before longer keys.
894 # * @warning This function must be called before any data access functions are used,
895 # * otherwise data corruption may occur. The same comparison function must be used by every
896 # * program accessing the database, every time the database is used.
897 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
898 # * @param[in] dbi A database handle returned by #mdb_dbi_open()
899 # * @param[in] cmp A #MDB_cmp_func function
900 # * @return A non-zero error value on failure and 0 on success. Some possible
901 # * errors are:
902 # * <ul>
903 # * <li>EINVAL - an invalid parameter was specified.
904 # * </ul>
905 # */
906
907 # ------- int mdb_set_compare(MDB_txn *txn, MDB_dbi dbi, MDB_cmp_func *cmp);
908
909 # ##/**@brief Set a custom data comparison function for a #MDB_DUPSORT database.
910 # *
911 # * This comparison function is called whenever it is necessary to compare a data
912 # * item specified by the application with a data item currently stored in the database.
913 # * This function only takes effect if the database was opened with the #MDB_DUPSORT
914 # * flag.
915 # * If no comparison function is specified, and no special key flags were specified
916 # * with #mdb_dbi_open(), the data items are compared lexically, with shorter items collating
917 # * before longer items.
918 # * @warning This function must be called before any data access functions are used,
919 # * otherwise data corruption may occur. The same comparison function must be used by every
920 # * program accessing the database, every time the database is used.
921 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
922 # * @param[in] dbi A database handle returned by #mdb_dbi_open()
923 # * @param[in] cmp A #MDB_cmp_func function
924 # * @return A non-zero error value on failure and 0 on success. Some possible
925 # * errors are:
926 # * <ul>
927 # * <li>EINVAL - an invalid parameter was specified.
928 # * </ul>
929 # */
930
931 # -------- int mdb_set_dupsort(MDB_txn *txn, MDB_dbi dbi, MDB_cmp_func *cmp);
932
933 # ##/**@brief Set a relocation function for a #MDB_FIXEDMAP database.
934 # *
935 # * @todo The relocation function is called whenever it is necessary to move the data
936 # * of an item to a different position in the database (e.g. through tree
937 # * balancing operations, shifts as a result of adds or deletes, etc.). It is
938 # * intended to allow address/position-dependent data items to be stored in
939 # * a database in an environment opened with the #MDB_FIXEDMAP option.
940 # * Currently the relocation feature is unimplemented and setting
941 # * this function has no effect.
942 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
943 # * @param[in] dbi A database handle returned by #mdb_dbi_open()
944 # * @param[in] rel A #MDB_rel_func function
945 # * @return A non-zero error value on failure and 0 on success. Some possible
946 # * errors are:
947 # * <ul>
948 # * <li>EINVAL - an invalid parameter was specified.
949 # * </ul>
950 # */
951
952 # -------- int mdb_set_relfunc(MDB_txn *txn, MDB_dbi dbi, MDB_rel_func *rel);
953
954 # ##/**@brief Set a context pointer for a #MDB_FIXEDMAP database's relocation function.
955 # *
956 # * See #mdb_set_relfunc and #MDB_rel_func for more details.
957 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
958 # * @param[in] dbi A database handle returned by #mdb_dbi_open()
959 # * @param[in] ctx An arbitrary pointer for whatever the application needs.
960 # * It will be passed to the callback function set by #mdb_set_relfunc
961 # * as its \b relctx parameter whenever the callback is invoked.
962 # * @return A non-zero error value on failure and 0 on success. Some possible
963 # * errors are:
964 # * <ul>
965 # * <li>EINVAL - an invalid parameter was specified.
966 # * </ul>
967 # */
968
969 # ------- int mdb_set_relctx(MDB_txn *txn, MDB_dbi dbi, void *ctx);
970
971 # ##/**@brief Get items from a database.
972 # *
973 # * This function retrieves key/data pairs from the database. The address
974 # * and length of the data associated with the specified \b key are returned
975 # * in the structure to which \b data refers.
976 # * If the database supports duplicate keys (#MDB_DUPSORT) then the
977 # * first data item for the key will be returned. Retrieval of other
978 # * items requires the use of #mdb_cursor_get().
979 # *
980 # * @note The memory pointed to by the returned values is owned by the
981 # * database. The caller need not dispose of the memory, and may not
982 # * modify it in any way. For values returned in a read-only transaction
983 # * any modification attempts will cause a SIGSEGV.
984 # * @note Values returned from the database are valid only until a
985 # * subsequent update operation, or the end of the transaction.
986 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
987 # * @param[in] dbi A database handle returned by #mdb_dbi_open()
988 # * @param[in] key The key to search for in the database
989 # * @param[out] data The data corresponding to the key
990 # * @return A non-zero error value on failure and 0 on success. Some possible
991 # * errors are:
992 # * <ul>
993 # * <li>#MDB_NOTFOUND - the key was not in the database.
994 # * <li>EINVAL - an invalid parameter was specified.
995 # * </ul>
996 # */
997
998 # ---int mdb_get(MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data);
999
1000 # ##/**@brief Store items into a database.
1001 # *
1002 # * This function stores key/data pairs in the database. The default behavior
1003 # * is to enter the new key/data pair, replacing any previously existing key
1004 # * if duplicates are disallowed, or adding a duplicate data item if
1005 # * duplicates are allowed (#MDB_DUPSORT).
1006 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
1007 # * @param[in] dbi A database handle returned by #mdb_dbi_open()
1008 # * @param[in] key The key to store in the database
1009 # * @param[in,out] data The data to store
1010 # * @param[in] flags Special options for this operation. This parameter
1011 # * must be set to 0 or by bitwise OR'ing together one or more of the
1012 # * values described here.
1013 # * <ul>
1014 # * <li>#MDB_NODUPDATA - enter the new key/data pair only if it does not
1015 # * already appear in the database. This flag may only be specified
1016 # * if the database was opened with #MDB_DUPSORT. The function will
1017 # * return #MDB_KEYEXIST if the key/data pair already appears in the
1018 # * database.
1019 # * <li>#MDB_NOOVERWRITE - enter the new key/data pair only if the key
1020 # * does not already appear in the database. The function will return
1021 # * #MDB_KEYEXIST if the key already appears in the database, even if
1022 # * the database supports duplicates (#MDB_DUPSORT). The \b data
1023 # * parameter will be set to point to the existing item.
1024 # * <li>#MDB_RESERVE - reserve space for data of the given size, but
1025 # * don't copy the given data. Instead, return a pointer to the
1026 # * reserved space, which the caller can fill in later - before
1027 # * the next update operation or the transaction ends. This saves
1028 # * an extra memcpy if the data is being generated later.
1029 # * LMDB does nothing else with this memory, the caller is expected
1030 # * to modify all of the space requested. This flag must not be
1031 # * specified if the database was opened with #MDB_DUPSORT.
1032 # * <li>#MDB_APPEND - append the given key/data pair to the end of the
1033 # * database. This option allows fast bulk loading when keys are
1034 # * already known to be in the correct order. Loading unsorted keys
1035 # * with this flag will cause a #MDB_KEYEXIST error.
1036 # * <li>#MDB_APPENDDUP - as above, but for sorted dup data.
1037 # * </ul>
1038 # * @return A non-zero error value on failure and 0 on success. Some possible
1039 # * errors are:
1040 # * <ul>
1041 # * <li>#MDB_MAP_FULL - the database is full, see #mdb_env_set_mapsize().
1042 # * <li>#MDB_TXN_FULL - the transaction has too many dirty pages.
1043 # * <li>EACCES - an attempt was made to write in a read-only transaction.
1044 # * <li>EINVAL - an invalid parameter was specified.
1045 # * </ul>
1046 # */
1047
1048 # ---- int mdb_put(MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data, unsigned int flags);
1049
1050 # ##/**@brief Delete items from a database.
1051 # *
1052 # * This function removes key/data pairs from the database.
1053 # * If the database does not support sorted duplicate data items
1054 # * (#MDB_DUPSORT) the data parameter is ignored.
1055 # * If the database supports sorted duplicates and the data parameter
1056 # * is NULL, all of the duplicate data items for the key will be
1057 # * deleted. Otherwise, if the data parameter is non-NULL
1058 # * only the matching data item will be deleted.
1059 # * This function will return #MDB_NOTFOUND if the specified key/data
1060 # * pair is not in the database.
1061 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
1062 # * @param[in] dbi A database handle returned by #mdb_dbi_open()
1063 # * @param[in] key The key to delete from the database
1064 # * @param[in] data The data to delete
1065 # * @return A non-zero error value on failure and 0 on success. Some possible
1066 # * errors are:
1067 # * <ul>
1068 # * <li>EACCES - an attempt was made to write in a read-only transaction.
1069 # * <li>EINVAL - an invalid parameter was specified.
1070 # * </ul>
1071 # */
1072
1073 # ---- int mdb_del(MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data);
1074
1075 # ##/**@brief Create a cursor handle.
1076 # *
1077 # * A cursor is associated with a specific transaction and database.
1078 # * A cursor cannot be used when its database handle is closed. Nor
1079 # * when its transaction has ended, except with #mdb_cursor_renew().
1080 # * It can be discarded with #mdb_cursor_close().
1081 # * A cursor in a write-transaction can be closed before its transaction
1082 # * ends, and will otherwise be closed when its transaction ends.
1083 # * A cursor in a read-only transaction must be closed explicitly, before
1084 # * or after its transaction ends. It can be reused with
1085 # * #mdb_cursor_renew() before finally closing it.
1086 # * @note Earlier documentation said that cursors in every transaction
1087 # * were closed when the transaction committed or aborted.
1088 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
1089 # * @param[in] dbi A database handle returned by #mdb_dbi_open()
1090 # * @param[out] cursor Address where the new #MDB_cursor handle will be stored
1091 # * @return A non-zero error value on failure and 0 on success. Some possible
1092 # * errors are:
1093 # * <ul>
1094 # * <li>EINVAL - an invalid parameter was specified.
1095 # * </ul>
1096 # */
1097
1098 # ---- int mdb_cursor_open(MDB_txn *txn, MDB_dbi dbi, MDB_cursor **cursor);
1099
1100 # ##/**@brief Close a cursor handle.
1101 # *
1102 # * The cursor handle will be freed and must not be used again after this call.
1103 # * Its transaction must still be live if it is a write-transaction.
1104 # * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
1105 # */
1106
1107 # -------- void mdb_cursor_close(MDB_cursor *cursor);
1108
1109 # ##/**@brief Renew a cursor handle.
1110 # *
1111 # * A cursor is associated with a specific transaction and database.
1112 # * Cursors that are only used in read-only
1113 # * transactions may be re-used, to avoid unnecessary malloc/free overhead.
1114 # * The cursor may be associated with a new read-only transaction, and
1115 # * referencing the same database handle as it was created with.
1116 # * This may be done whether the previous transaction is live or dead.
1117 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
1118 # * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
1119 # * @return A non-zero error value on failure and 0 on success. Some possible
1120 # * errors are:
1121 # * <ul>
1122 # * <li>EINVAL - an invalid parameter was specified.
1123 # * </ul>
1124 # */
1125
1126 # -------int mdb_cursor_renew(MDB_txn *txn, MDB_cursor *cursor);
1127
1128 # ##/**@brief Return the cursor's transaction handle.
1129 # *
1130 # * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
1131 # */
1132 # ----------MDB_txn *mdb_cursor_txn(MDB_cursor *cursor);
1133 #
1134 # ##/**@brief Return the cursor's database handle.
1135 # *
1136 # * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
1137 # */
1138 # ----------MDB_dbi mdb_cursor_dbi(MDB_cursor *cursor);
1139
1140 # ##/**@brief Retrieve by cursor.
1141 # *
1142 # * This function retrieves key/data pairs from the database. The address and length
1143 # * of the key are returned in the object to which \b key refers (except for the
1144 # * case of the #MDB_SET option, in which the \b key object is unchanged), and
1145 # * the address and length of the data are returned in the object to which \b data
1146 # * refers.
1147 # * See #mdb_get() for restrictions on using the output values.
1148 # * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
1149 # * @param[in,out] key The key for a retrieved item
1150 # * @param[in,out] data The data of a retrieved item
1151 # * @param[in] op A cursor operation #MDB_cursor_op
1152 # * @return A non-zero error value on failure and 0 on success. Some possible
1153 # * errors are:
1154 # * <ul>
1155 # * <li>#MDB_NOTFOUND - no matching key found.
1156 # * <li>EINVAL - an invalid parameter was specified.
1157 # * </ul>
1158 # */
1159 # --------int mdb_cursor_get(MDB_cursor *cursor, MDB_val *key, MDB_val *data, MDB_cursor_op op);
1160
1161 # ##/**@brief Store by cursor.
1162 # *
1163 # * This function stores key/data pairs into the database.
1164 # * The cursor is positioned at the new item, or on failure usually near it.
1165 # * @note Earlier documentation incorrectly said errors would leave the
1166 # * state of the cursor unchanged.
1167 # * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
1168 # * @param[in] key The key operated on.
1169 # * @param[in] data The data operated on.
1170 # * @param[in] flags Options for this operation. This parameter
1171 # * must be set to 0 or one of the values described here.
1172 # * <ul>
1173 # * <li>#MDB_CURRENT - replace the item at the current cursor position.
1174 # * The \b key parameter must still be provided, and must match it.
1175 # * If using sorted duplicates (#MDB_DUPSORT) the data item must still
1176 # * sort into the same place. This is intended to be used when the
1177 # * new data is the same size as the old. Otherwise it will simply
1178 # * perform a delete of the old record followed by an insert.
1179 # * <li>#MDB_NODUPDATA - enter the new key/data pair only if it does not
1180 # * already appear in the database. This flag may only be specified
1181 # * if the database was opened with #MDB_DUPSORT. The function will
1182 # * return #MDB_KEYEXIST if the key/data pair already appears in the
1183 # * database.
1184 # * <li>#MDB_NOOVERWRITE - enter the new key/data pair only if the key
1185 # * does not already appear in the database. The function will return
1186 # * #MDB_KEYEXIST if the key already appears in the database, even if
1187 # * the database supports duplicates (#MDB_DUPSORT).
1188 # * <li>#MDB_RESERVE - reserve space for data of the given size, but
1189 # * don't copy the given data. Instead, return a pointer to the
1190 # * reserved space, which the caller can fill in later - before
1191 # * the next update operation or the transaction ends. This saves
1192 # * an extra memcpy if the data is being generated later. This flag
1193 # * must not be specified if the database was opened with #MDB_DUPSORT.
1194 # * <li>#MDB_APPEND - append the given key/data pair to the end of the
1195 # * database. No key comparisons are performed. This option allows
1196 # * fast bulk loading when keys are already known to be in the
1197 # * correct order. Loading unsorted keys with this flag will cause
1198 # * a #MDB_KEYEXIST error.
1199 # * <li>#MDB_APPENDDUP - as above, but for sorted dup data.
1200 # * <li>#MDB_MULTIPLE - store multiple contiguous data elements in a
1201 # * single request. This flag may only be specified if the database
1202 # * was opened with #MDB_DUPFIXED. The \b data argument must be an
1203 # * array of two MDB_vals. The mv_size of the first MDB_val must be
1204 # * the size of a single data element. The mv_data of the first MDB_val
1205 # * must point to the beginning of the array of contiguous data elements.
1206 # * The mv_size of the second MDB_val must be the count of the number
1207 # * of data elements to store. On return this field will be set to
1208 # * the count of the number of elements actually written. The mv_data
1209 # * of the second MDB_val is unused.
1210 # * </ul>
1211 # * @return A non-zero error value on failure and 0 on success. Some possible
1212 # * errors are:
1213 # * <ul>
1214 # * <li>#MDB_MAP_FULL - the database is full, see #mdb_env_set_mapsize().
1215 # * <li>#MDB_TXN_FULL - the transaction has too many dirty pages.
1216 # * <li>EACCES - an attempt was made to write in a read-only transaction.
1217 # * <li>EINVAL - an invalid parameter was specified.
1218 # * </ul>
1219 # */
1220 # ----- int mdb_cursor_put(MDB_cursor *cursor, MDB_val *key, MDB_val *data, unsigned int flags);
1221
1222 # ##/**@brief Delete current key/data pair
1223 # *
1224 # * This function deletes the key/data pair to which the cursor refers.
1225 # * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
1226 # * @param[in] flags Options for this operation. This parameter
1227 # * must be set to 0 or one of the values described here.
1228 # * <ul>
1229 # * <li>#MDB_NODUPDATA - delete all of the data items for the current key.
1230 # * This flag may only be specified if the database was opened with #MDB_DUPSORT.
1231 # * </ul>
1232 # * @return A non-zero error value on failure and 0 on success. Some possible
1233 # * errors are:
1234 # * <ul>
1235 # * <li>EACCES - an attempt was made to write in a read-only transaction.
1236 # * <li>EINVAL - an invalid parameter was specified.
1237 # * </ul>
1238 # */
1239 # -------int mdb_cursor_del(MDB_cursor *cursor, unsigned int flags);
1240
1241 # ##/**@brief Return count of duplicates for current key.
1242 # *
1243 # * This call is only valid on databases that support sorted duplicate
1244 # * data items #MDB_DUPSORT.
1245 # * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
1246 # * @param[out] countp Address where the count will be stored
1247 # * @return A non-zero error value on failure and 0 on success. Some possible
1248 # * errors are:
1249 # * <ul>
1250 # * <li>EINVAL - cursor is not initialized, or an invalid parameter was specified.
1251 # * </ul>
1252 # */
1253 # ------ int mdb_cursor_count(MDB_cursor *cursor, size_t *countp);
1254
1255 # ##/**@brief Compare two data items according to a particular database.
1256 # *
1257 # * This returns a comparison as if the two data items were keys in the
1258 # * specified database.
1259 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
1260 # * @param[in] dbi A database handle returned by #mdb_dbi_open()
1261 # * @param[in] a The first item to compare
1262 # * @param[in] b The second item to compare
1263 # * @return < 0 if a < b, 0 if a == b, > 0 if a > b
1264 # */
1265 # --------int mdb_cmp(MDB_txn *txn, MDB_dbi dbi, const MDB_val *a, const MDB_val *b);
1266
1267 # ##/**@brief Compare two data items according to a particular database.
1268 # *
1269 # * This returns a comparison as if the two items were data items of
1270 # * the specified database. The database must have the #MDB_DUPSORT flag.
1271 # * @param[in] txn A transaction handle returned by #mdb_txn_begin()
1272 # * @param[in] dbi A database handle returned by #mdb_dbi_open()
1273 # * @param[in] a The first item to compare
1274 # * @param[in] b The second item to compare
1275 # * @return < 0 if a < b, 0 if a == b, > 0 if a > b
1276 # */
1277 # -------int mdb_dcmp(MDB_txn *txn, MDB_dbi dbi, const MDB_val *a, const MDB_val *b);
1278
1279 # ##/**@brief A callback function used to print a message from the library.
1280 # *
1281 # * @param[in] msg The string to be printed.
1282 # * @param[in] ctx An arbitrary context pointer for the callback.
1283 # * @return < 0 on failure, >= 0 on success.
1284 # */
1285 # -----typedef int (MDB_msg_func)(const char *msg, void *ctx);
1286
1287 # ##/**@brief Dump the entries in the reader lock table.
1288 # *
1289 # * @param[in] env An environment handle returned by #mdb_env_create()
1290 # * @param[in] func A #MDB_msg_func function
1291 # * @param[in] ctx Anything the message function needs
1292 # * @return < 0 on failure, >= 0 on success.
1293 # */
1294 # ------int mdb_reader_list(MDB_env *env, MDB_msg_func *func, void *ctx);
1295
1296 # ##/**@brief Check for stale entries in the reader lock table.
1297 # *
1298 # * @param[in] env An environment handle returned by #mdb_env_create()
1299 # * @param[out] dead Number of stale slots that were cleared
1300 # * @return 0 on success, non-zero on failure.
1301 # */
1302 # ------- int mdb_reader_check(MDB_env *env, int *dead);
1303 # #/** @} */
1304
1305 # MDB_SUCCESS = 0
1306 # # key/data pair already exists */
1307 # MDB_KEYEXIST = -30799
1308 # # key/data pair not found (EOF) */
1309 # MDB_NOTFOUND = -30798
1310 # # Requested page not found - this usually indicates corruption */
1311 # MDB_PAGE_NOTFOUND = -30797
1312 # # Located page was wrong type */
1313 # MDB_CORRUPTED = -30796
1314 # # Update of meta page failed or environment had fatal error */
1315 # MDB_PANIC = -30795
1316 # # Environment version mismatch */
1317 # MDB_VERSION_MISMATCH = -30794
1318 # # File is not a valid LMDB file */
1319 # MDB_INVALID = -30793
1320 # # Environment mapsize reached */
1321 # MDB_MAP_FULL = -30792
1322 # # Environment maxdbs reached */
1323 # MDB_DBS_FULL = -30791
1324 # # Environment maxreaders reached */
1325 # MDB_READERS_FULL = -30790
1326 # # Too many TLS keys in use - Windows only */
1327 # MDB_TLS_FULL = -30789
1328 # # Txn has too many dirty pages */
1329 # MDB_TXN_FULL = -30788
1330 # # Cursor stack too deep - internal error */
1331 # MDB_CURSOR_FULL = -30787
1332 # # Page has not enough space - internal error */
1333 # MDB_PAGE_FULL = -30786
1334 # # Database contents grew beyond environment mapsize */
1335 # MDB_MAP_RESIZED = -30785
1336 # # #Operation and DB incompatible, or DB type changed. This can mean:
1337 # # * <ul>
1338 # # * <li>The operation expects an #MDB_DUPSORT / #MDB_DUPFIXED database.
1339 # # * <li>Opening a named DB when the unnamed DB has #MDB_DUPSORT / #MDB_INTEGERKEY.
1340 # # * <li>Accessing a data record as a database, or vice versa.
1341 # # * <li>The database was dropped and recreated with different flags.
1342 # # * </ul>
1343 # # */
1344 # MDB_INCOMPATIBLE = -30784
1345 # # Invalid reuse of reader locktable slot */
1346 # MDB_BAD_RSLOT = -30783
1347 # # Transaction must abort, has a child, or is invalid */
1348 # MDB_BAD_TXN = -30782
1349 # # Unsupported size of key/DB name/data, or wrong DUPFIXED size */
1350 # MDB_BAD_VALSIZE = -30781
1351 # # The specified DBI was changed unexpectedly */
1352 # MDB_BAD_DBI = -30780
1353 # # The last defined error code */
1354 # MDB_LAST_ERRCODE = MDB_BAD_DBI
1355 # # @} */
1356end
1357
1358# ## might not need these
1359# #/**@defgroup errors Return Codes
1360# *
1361# * BerkeleyDB uses -30800 to -30999, we'll go under them
1362# * @{
1363# */
1364# #/** Successful result */
1365# MDB_SUCCESS = 0
1366# # #/**key/data pair already exists */
1367# MDB_KEYEXIST = -30799
1368# # #/**key/data pair not found (EOF) */
1369# MDB_NOTFOUND = -30798
1370# # #/**Requested page not found - this usually indicates corruption */
1371# MDB_PAGE_NOTFOUND = -30797
1372# # #/**Located page was wrong type */
1373# MDB_CORRUPTED = -30796
1374# # #/**Update of meta page failed or environment had fatal error */
1375# MDB_PANIC = -30795
1376# # #/**Environment version mismatch */
1377# MDB_VERSION_MISMATCH = -30794
1378# # #/**File is not a valid LMDB file */
1379# MDB_INVALID = -30793
1380# # #/**Environment mapsize reached */
1381# MDB_MAP_FULL = -30792
1382# # #/**Environment maxdbs reached */
1383# MDB_DBS_FULL = -30791
1384# # #/**Environment maxreaders reached */
1385# MDB_READERS_FULL = -30790
1386# # #/**Too many TLS keys in use - Windows only */
1387# MDB_TLS_FULL = -30789
1388# # #/**Txn has too many dirty pages */
1389# MDB_TXN_FULL = -30788
1390# # #/**Cursor stack too deep - internal error */
1391# MDB_CURSOR_FULL = -30787
1392# # #/**Page has not enough space - internal error */
1393# MDB_PAGE_FULL = -30786
1394# # #/**Database contents grew beyond environment mapsize */
1395# MDB_MAP_RESIZED = -30785
1396# # #/**Operation and DB incompatible, or DB type changed. This can mean:
1397# # * <ul>
1398# # * <li>The operation expects an #MDB_DUPSORT / #MDB_DUPFIXED database.
1399# # * <li>Opening a named DB when the unnamed DB has #MDB_DUPSORT / #MDB_INTEGERKEY.
1400# # * <li>Accessing a data record as a database, or vice versa.
1401# # * <li>The database was dropped and recreated with different flags.
1402# # * </ul>
1403# # */
1404# MDB_INCOMPATIBLE = -30784
1405# # #/**Invalid reuse of reader locktable slot */
1406# MDB_BAD_RSLOT = -30783
1407# # #/**Transaction must abort, has a child, or is invalid */
1408# MDB_BAD_TXN = -30782
1409# # #/**Unsupported size of key/DB name/data, or wrong DUPFIXED size */
1410# MDB_BAD_VALSIZE = -30781
1411# # #/**The specified DBI was changed unexpectedly */
1412# MDB_BAD_DBI = -30780
1413# # #/**The last defined error code */
1414# MDB_LAST_ERRCODE = MDB_BAD_DBI
1415```