]> git.sur5r.net Git - openldap/blob - libraries/libmdb/mdb.h
API cleanup, doxygen docs for public API
[openldap] / libraries / libmdb / mdb.h
1 /** @file mdb.h
2  *      @brief memory-mapped database library
3  *
4  *      @mainpage       MDB Memory-Mapped Database Manager
5  *      MDB is a Btree-based database management library modeled loosely on the
6  *      BerkeleyDB API, but much simplified. The entire database is exposed
7  *      in a read-only memory map, and all data fetches return data directly
8  *      from the mapped memory, so no malloc's or memcpy's occur during
9  *      data fetches. As such, the library is extremely simple because it
10  *      requires no page caching layer of its own, and it is extremely high
11  *      performance and memory-efficient. It is also fully transactional with
12  *      full ACID semantics, and because the memory map is read-only, the
13  *      database integrity cannot be corrupted by stray pointer writes from
14  *      application code.
15  *
16  *      The library is fully thread-aware and supports concurrent read/write
17  *      access from multiple processes and threads. Data pages use a copy-on-
18  *      write strategy so no active data pages are ever overwritten, which
19  *      also provides resistance to corruption and eliminates the need of any
20  *      special recovery procedures after a system crash. Writes are fully
21  *      serialized; only one write transaction may be active at a time, which
22  *      guarantees that writers can never deadlock. The database structure is
23  *      multi-versioned so readers run with no locks; writers cannot block
24  *      readers, and readers don't block writers.
25  *
26  *      Unlike other well-known database mechanisms which use either write-ahead
27  *      transaction logs or append-only data writes, MDB requires no maintenance
28  *      during operation. Both write-ahead loggers and append-only databases
29  *      require periodic checkpointing and/or compaction of their log or database
30  *      files otherwise they grow without bound. MDB tracks free pages within
31  *      the database and re-uses them for new write operations, so the database
32  *      size does not grow without bound in normal use.
33  *
34  *      @author Howard Chu, Symas Corporation.
35  *
36  *      @copyright Copyright 2011 Howard Chu, Symas Corp. All rights reserved.
37  *
38  * Redistribution and use in source and binary forms, with or without
39  * modification, are permitted only as authorized by the OpenLDAP
40  * Public License.
41  *
42  * A copy of this license is available in the file LICENSE in the
43  * top-level directory of the distribution or, alternatively, at
44  * <http://www.OpenLDAP.org/license.html>.
45  *
46  *      @par Derived From:
47  * This code is derived from btree.c written by Martin Hedenfalk.
48  *
49  * Copyright (c) 2009, 2010 Martin Hedenfalk <martin@bzero.se>
50  *
51  * Permission to use, copy, modify, and distribute this software for any
52  * purpose with or without fee is hereby granted, provided that the above
53  * copyright notice and this permission notice appear in all copies.
54  *
55  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
56  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
57  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
58  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
59  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
60  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
61  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
62  */
63 #ifndef _MDB_H_
64 #define _MDB_H_
65
66 #include <sys/types.h>
67
68 /** @defgroup Version Version Macros
69  *      @{
70  */
71 /** Library major version */
72 #define MDB_VERSION_MAJOR       0
73 /** Library minor version */
74 #define MDB_VERSION_MINOR       8
75 /** Library patch version */
76 #define MDB_VERSION_PATCH       0
77
78 /** Combine args a,b,c into a single integer for easy version comparisons */
79 #define MDB_VERINT(a,b,c)       (((a) << 24) | ((b) << 16) | (c))
80
81 /** The full library version as a single integer */
82 #define MDB_VERSION_FULL        \
83         MDB_VERINT(MDB_VERSION_MAJOR,MDB_VERSION_MINOR,MDB_VERSION_PATCH)
84
85 /** The release date of this library version */
86 #define MDB_VERSION_DATE        "August 11, 2011"
87
88 /** A stringifier for the version info */
89 #define MDB_VERSTR(a,b,c,d)     "MDB " #a "." #b "." #c ": (" #d ")"
90
91 /** A helper for the stringifier macro */
92 #define MDB_VERFOO(a,b,c,d)     MDB_VERSTR(a,b,c,d)
93
94 /** The full library version as a C string */
95 #define MDB_VERSION_STRING      \
96         MDB_VERFOO(MDB_VERSION_MAJOR,MDB_VERSION_MINOR,MDB_VERSION_PATCH,MDB_VERSION_DATE)
97 /**     @} */
98
99 /** Opaque structure for navigating through a database */
100 typedef struct MDB_cursor MDB_cursor;
101
102 /** Opaque structure for a transaction handle. All database operations require
103  * a transaction handle. Transactions may be read-only or read-write.
104  */
105 typedef struct MDB_txn MDB_txn;
106
107 /** Opaque structure for a database environment. A DB environment supports multiple
108  * databases, all residing in the same shared-memory map.
109  */
110 typedef struct MDB_env MDB_env;
111
112 /** A handle for an individual database in the DB environment. */
113 typedef unsigned int    MDB_dbi;
114
115 /** Generic structure used for passing keys and data in and out of the database. */
116 typedef struct MDB_val {
117         size_t           mv_size;       /**< size of the data item */
118         void            *mv_data;       /**< address of the data item */
119 } MDB_val;
120
121 /** A callback function used to compare two keys in a database */
122 typedef int  (MDB_cmp_func)(const MDB_val *a, const MDB_val *b);
123
124 /** A callback function used to relocate a position-dependent data item
125  * in a fixed-address database. This feature is currently unimplemented.
126  */
127 typedef void (MDB_rel_func)(void *ptr, void *oldptr);
128
129 /**     @defgroup mdb_put       mdb_put flags
130  *      @{
131  */
132 /** For mdb_put: don't write if the key already exists. */
133 #define MDB_NOOVERWRITE 0x10
134 /** For mdb_put: don't write if the key and data pair already exist.
135  * Only for #MDB_DUPSORT
136  */
137 #define MDB_NODUPDATA   0x20
138 /*      @} */
139
140 /** Cursor operations */
141 typedef enum MDB_cursor_op {
142         MDB_FIRST,                              /**< Position at first key/data item */
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_MULTIPLE,               /**< Return all the duplicate data items at the current
146                                                                  cursor position. Only for #MDB_DUPFIXED */
147         MDB_LAST,                               /**< Position at last key/data item */
148         MDB_NEXT,                               /**< Position at next data item */
149         MDB_NEXT_DUP,                   /**< Position at next data item of current key.
150                                                                 Only for #MDB_DUPSORT */
151         MDB_NEXT_MULTIPLE,              /**< Return all duplicate data items at the next
152                                                                 cursor position. Only for #MDB_DUPFIXED */
153         MDB_NEXT_NODUP,                 /**< Position at first data item of next key.
154                                                                 Only for #MDB_DUPSORT */
155         MDB_PREV,                               /**< Position at previous data item */
156         MDB_PREV_DUP,                   /**< Position at previous data item of current key.
157                                                                 Only for #MDB_DUPSORT */
158         MDB_PREV_NODUP,                 /**< Position at last data item of previous key.
159                                                                 only for #MDB_DUPSORT */
160         MDB_SET,                                /**< Position at specified key */
161         MDB_SET_RANGE                   /**< Position at first key greater than or equal to specified key. */
162 } MDB_cursor_op;
163
164 /** @defgroup  errors   Return Codes
165  *
166  *      BerkeleyDB uses -30800 to -30999, we'll go under them
167  *      @{
168  */
169         /**     Successful result */
170 #define MDB_SUCCESS      0
171         /** key/data pair already exists */
172 #define MDB_KEYEXIST    (-30799)
173         /** key/data pair not found (EOF) */
174 #define MDB_NOTFOUND    (-30798)
175         /** Requested page not found - this usually indicates corruption */
176 #define MDB_PAGE_NOTFOUND       (-30797)
177         /** Located page was wrong type */
178 #define MDB_CORRUPTED   (-30796)
179         /** Update of meta page failed, probably I/O error */
180 #define MDB_PANIC               (-30795)
181         /** Environment version mismatch */
182 #define MDB_VERSION_MISMATCH    (-30794)
183 /** @} */
184
185 /**     @defgroup       mdb_open         mdb_open flags
186  *      @{
187  */
188         /** use reverse string keys */
189 #define MDB_REVERSEKEY  0x02
190         /** use sorted duplicates */
191 #define MDB_DUPSORT             0x04
192         /** numeric keys in native byte order */
193 #define MDB_INTEGERKEY  0x08
194         /** with #MDB_DUPSORT, sorted dup items have fixed size */
195 #define MDB_DUPFIXED    0x10
196         /** with #MDB_DUPSORT, dups are numeric in native byte order */
197 #define MDB_INTEGERDUP  0x20
198 /** @} */
199
200 /** @defgroup   mdb_env  environment flags
201  *      @{
202  */
203         /** mmap at a fixed address */
204 #define MDB_FIXEDMAP    0x01
205         /** don't fsync after commit */
206 #define MDB_NOSYNC              0x10000
207         /** read only */
208 #define MDB_RDONLY              0x20000
209 /** @} */
210
211         /** create env or DB if not already existing */
212 #define MDB_CREATE              0x40000
213
214 /** Statistics for a database in the environment */
215 typedef struct MDB_stat {
216         unsigned int    ms_psize;                       /**< Size of a database page.
217                                                                                         This is currently the same for all databases. */
218         unsigned int    ms_depth;                       /**< Depth (height) of the B-tree */
219         unsigned long   ms_branch_pages;        /**< Number of internal (non-leaf) pages */
220         unsigned long   ms_leaf_pages;          /**< Number of leaf pages */
221         unsigned long   ms_overflow_pages;      /**< Number of overflow pages */
222         unsigned long   ms_entries;                     /**< Number of data items */
223 } MDB_stat;
224
225         /** Return the mdb library version information.
226          * @param[out] major if non-NULL, the library major version number is copied here
227          * @param[out] minor if non-NULL, the library minor version number is copied here
228          * @param[out] patch if non-NULL, the library patch version number is copied here
229          * @retval "version string" The library version as a string
230          */
231 char *mdb_version(int *major, int *minor, int *patch);
232
233         /** Return a string describing a given error code.
234          * This function is a superset of the ANSI C X3.159-1989 (ANSI C) strerror(3)
235          * function. If the error code is greater than or equal to 0, then the string
236          * returned by the system function strerror(3) is returned. If the error code
237          * is less than 0, an error string corresponding to the MDB library error is
238          * returned. See @ref errors for a list of MDB-specific error codes.
239          * @param[in] err The error code
240          * @retval "error message" The description of the error
241          */
242 char *mdb_strerror(int err);
243
244         /** Create an MDB environment handle.
245          * This function allocates memory for a #MDB_env structure. To release
246          * the allocated memory and discard the handle, call #mdb_env_close().
247          * Before the handle may be used, it must be opened using #mdb_env_open().
248          * Various other options may also need to be set before opening the handle,
249          * e.g. #mdb_env_set_mapsize(), #mdb_env_set_maxreaders(), #mdb_env_set_maxdbs(),
250          * depending on usage requirements.
251          * @param[out] env The address where the new handle will be stored
252          * @return A non-zero error value on failure and 0 on success.
253          */
254 int  mdb_env_create(MDB_env **env);
255
256         /** Open an environment handle.
257          * If this function fails, #mdb_env_close() must be called to discard the #MDB_env handle.
258          * @param[in] env An environment handle returned by #mdb_env_create()
259          * @param[in] path The directory in which the database files reside
260          * @param[in] flags Special options for this environment. This parameter
261          * must be set to 0 or by bitwise OR'ing together one or more of the
262          * values described here.
263          * <ul>
264          *      <li>#MDB_FIXEDMAP
265          *      use a fixed address for the mmap region. This flag must be specified
266          *      when creating the environment, and is stored persistently in the environment.
267          *              If successful, the memory map will always reside at the same virtual address
268          *              and pointers used to reference data items in the database will be constant
269          *              across multiple invocations. This option may not always work, depending on
270          *              how the operating system has allocated memory to shared libraries and other uses.
271          *              The feature is highly experimental.
272          *      <li>#MDB_NOSYNC
273          *              Don't perform a synchronous flush after committing a transaction. This means
274          *              transactions will exhibit the ACI (atomicity, consistency, and isolation)
275          *              properties, but not D (durability); that is database integrity will be
276          *              maintained but it is possible some number of the most recently committed
277          *              transactions may be undone after a system crash. The number of transactions
278          *              at risk is governed by how often the system flushes dirty buffers to disk
279          *              and how often #mdb_env_sync() is called. This flag may be changed
280          *              at any time using #mdb_env_set_flags().
281          *      <li>#MDB_RDONLY
282          *              Open the environment in read-only mode. No write operations will be allowed.
283          *      <li>#MDB_CREATE
284          *              Create the environment if it doesn't already exist.
285          * </ul>
286          * @param[in] mode The UNIX permissions to set on created files.
287          * @return A non-zero error value on failure and 0 on success. Some possible
288          * errors are:
289          * <ul>
290          *      <li>#MDB_VERSION_MISMATCH - the version of the MDB library doesn't match the
291          *      version that created the database environment.
292          *      <li>EINVAL - the environment file headers are corrupted.
293          *      <li>ENOENT - the directory specified by the path parameter doesn't exist.
294          *      <li>EACCES - the user didn't have permission to access the environment files.
295          *      <li>EAGAIN - the environment was locked by another process.
296          * </ul>
297          */
298 int  mdb_env_open(MDB_env *env, const char *path, unsigned int flags, mode_t mode);
299
300         /** Return statistics about the MDB environment.
301          * @param[in] env An environment handle returned by #mdb_env_create()
302          * @param[out] stat The address of an #MDB_stat structure
303          *      where the statistics will be copied
304          */
305 int  mdb_env_stat(MDB_env *env, MDB_stat *stat);
306
307         /** Flush the data buffers to disk.
308          * Data is always written to disk when #mdb_txn_commit() is called,
309          * but the operating system may keep it buffered. MDB always flushes
310          * the OS buffers upon commit as well, unless the environment was
311          * opened with #MDB_NOSYNC.
312          * @param[in] env An environment handle returned by #mdb_env_create()
313          * @param[in] force If non-zero, force the flush to occur. Otherwise
314          *  if the environment has the #MDB_NOSYNC flag set the flushes
315          *      will be omitted.
316          * @return A non-zero error value on failure and 0 on success. Some possible
317          * errors are:
318          * <ul>
319          *      <li>EINVAL - an invalid parameter was specified.
320          *      <li>EIO - an error occurred during synchronization.
321          * </ul>
322          */
323 int  mdb_env_sync(MDB_env *env, int force);
324
325         /** Close the environment and release the memory map.
326          * Only a single thread may call this function. All transactions, databases,
327          * and cursors must already be closed before calling this function. Attempts to
328          * use any such handles after calling this function will cause a SIGSEGV.
329          * The environment handle will be freed and must not be used again after this call.
330          * @param[in] env An environment handle returned by #mdb_env_create()
331          */
332 void mdb_env_close(MDB_env *env);
333
334         /** Set environment flags.
335          * This may be used to set some flags that weren't already set during
336          * #mdb_env_open(), or to unset these flags. Currently only the
337          * #MDB_NOSYNC flag setting may be changed with this function.
338          * @param[in] env An environment handle returned by #mdb_env_create()
339          * @param[in] flags The flags to change, bitwise OR'ed together
340          * @param[in] onoff A non-zero value sets the flags, zero clears them.
341          * @return A non-zero error value on failure and 0 on success. Some possible
342          * errors are:
343          * <ul>
344          *      <li>EINVAL - an invalid parameter was specified.
345          * </ul>
346          */
347 int  mdb_env_set_flags(MDB_env *env, unsigned int flags, int onoff);
348
349         /** Get environment flags.
350          * @param[in] env An environment handle returned by #mdb_env_create()
351          * @param[out] flags The address of an integer to store the flags
352          * @return A non-zero error value on failure and 0 on success. Some possible
353          * errors are:
354          * <ul>
355          *      <li>EINVAL - an invalid parameter was specified.
356          * </ul>
357          */
358 int  mdb_env_get_flags(MDB_env *env, unsigned int *flags);
359
360         /** Return the path that was used in #mdb_env_open().
361          * @param[in] env An environment handle returned by #mdb_env_create()
362          * @param[out] path Address of a string pointer to contain the path. This
363          * is the actual string in the environment, not a copy. It should not be
364          * altered in any way.
365          * @return A non-zero error value on failure and 0 on success. Some possible
366          * errors are:
367          * <ul>
368          *      <li>EINVAL - an invalid parameter was specified.
369          * </ul>
370          */
371 int  mdb_env_get_path(MDB_env *env, const char **path);
372
373         /** Set the size of the memory map to use for this environment.
374          * The size should be a multiple of the OS page size. The default is
375          * 10485760 bytes. The value should be chosen as large as possible,
376          * to accomodate future growth of the database.
377          * This function may only be called after #mdb_env_create() and before #mdb_env_open().
378          * @param[in] env An environment handle returned by #mdb_env_create()
379          * @param[in] size The size in bytes
380          * @return A non-zero error value on failure and 0 on success. Some possible
381          * errors are:
382          * <ul>
383          *      <li>EINVAL - an invalid parameter was specified, or the environment is already open.
384          * </ul>
385          */
386 int  mdb_env_set_mapsize(MDB_env *env, size_t size);
387
388         /** Set the maximum number of threads for the environment.
389          * This defines the number of slots in the lock table that is used to track readers in the
390          * the environment. The default is 126.
391          * This function may only be called after #mdb_env_create() and before #mdb_env_open().
392          * @param[in] env An environment handle returned by #mdb_env_create()
393          * @param[in] readers The maximum number of threads
394          * @return A non-zero error value on failure and 0 on success. Some possible
395          * errors are:
396          * <ul>
397          *      <li>EINVAL - an invalid parameter was specified, or the environment is already open.
398          * </ul>
399          */
400 int  mdb_env_set_maxreaders(MDB_env *env, int readers);
401
402         /** Get the maximum number of threads for the environment.
403          * @param[in] env An environment handle returned by #mdb_env_create()
404          * @param[out] readers Address of an integer to store the number of readers
405          * @return A non-zero error value on failure and 0 on success. Some possible
406          * errors are:
407          * <ul>
408          *      <li>EINVAL - an invalid parameter was specified.
409          * </ul>
410          */
411 int  mdb_env_get_maxreaders(MDB_env *env, int *readers);
412
413         /** Set the maximum number of databases for the environment.
414          * This function is only needed if multiple databases will be used in the
415          * environment. Simpler applications that only use a single database can ignore
416          * this option.
417          * This function may only be called after #mdb_env_create() and before #mdb_env_open().
418          * @param[in] env An environment handle returned by #mdb_env_create()
419          * @param[in] dbs The maximum number of databases
420          * @return A non-zero error value on failure and 0 on success. Some possible
421          * errors are:
422          * <ul>
423          *      <li>EINVAL - an invalid parameter was specified, or the environment is already open.
424          * </ul>
425          */
426 int  mdb_env_set_maxdbs(MDB_env *env, int dbs);
427
428         /** Create a transaction for use with the environment.
429          * The transaction handle may be discarded using #mdb_txn_abort() or #mdb_txn_commit().
430          * @note Transactions may not span threads, a transaction must only be used by a
431          * single thread.
432          * @note Cursors may not span transactions; each cursor must be opened and closed
433          * within a single transaction.
434          * @param[in] env An environment handle returned by #mdb_env_create()
435          * @param[in] flags Special options for this transaction. This parameter
436          * must be set to 0 or by bitwise OR'ing together one or more of the
437          * values described here.
438          * <ul>
439          *      <li>#MDB_RDONLY
440          *              This transaction will not perform any write operations.
441          * </ul>
442          * @param[out] txn Address where the new #MDB_txn handle will be stored
443          * @return A non-zero error value on failure and 0 on success. Some possible
444          * errors are:
445          * <ul>
446          *      <li>#MDB_PANIC - a fatal error occurred earlier and the environment
447          *              must be shut down.
448          *      <li>ENOMEM - out of memory, or a read-only transaction was requested and
449          *              the reader lock table is full. See #mdb_env_set_maxreaders().
450          * </ul>
451          */
452 int  mdb_txn_begin(MDB_env *env, unsigned int flags, MDB_txn **txn);
453
454         /** Commit all the operations of a transaction into the database.
455          * All cursors opened within the transaction must be closed before the transaction
456          * is committed.
457          * The transaction handle will be freed and must not be used again after this call.
458          * @param[in] txn A transaction handle returned by #mdb_txn_begin()
459          * @return A non-zero error value on failure and 0 on success. Some possible
460          * errors are:
461          * <ul>
462          *      <li>EINVAL - an invalid parameter was specified.
463          *      <li>ENOSPC - no more disk space.
464          *      <li>EIO - a low-level I/O error occurred while writing.
465          * </ul>
466          */
467 int  mdb_txn_commit(MDB_txn *txn);
468
469         /** Abandon all the operations of the transaction instead of saving them.
470          * All cursors opened within the transaction must be closed before the transaction
471          * is aborted.
472          * The transaction handle will be freed and must not be used again after this call.
473          * @param[in] txn A transaction handle returned by #mdb_txn_begin()
474          */
475 void mdb_txn_abort(MDB_txn *txn);
476
477         /** Reset a read-only transaction.
478          * This releases the current reader lock but doesn't free the
479          * transaction handle, allowing it to be used again later by #mdb_txn_renew().
480          * It otherwise has the same affect as #mdb_txn_abort() but saves some memory
481          * allocation/deallocation overhead if a thread is going to start a new
482          * read-only transaction again soon.
483          * All cursors opened within the transaction must be closed before the transaction
484          * is reset.
485          * Reader locks generally don't interfere with writers, but they keep old
486          * versions of database pages allocated. Thus they prevent the old pages
487          * from being reused when writers commit new data, and so under heavy load
488          * the database size may grow much more rapidly than otherwise.
489          * @param[in] txn A transaction handle returned by #mdb_txn_begin()
490          */
491 void mdb_txn_reset(MDB_txn *txn);
492
493         /** Renew a read-only transaction.
494          * This acquires a new reader lock for a transaction handle that had been
495          * released by #mdb_txn_reset(). It must be called before a reset transaction
496          * may be used again.
497          * @param[in] txn A transaction handle returned by #mdb_txn_begin()
498          * @return A non-zero error value on failure and 0 on success. Some possible
499          * errors are:
500          * <ul>
501          *      <li>#MDB_PANIC - a fatal error occurred earlier and the environment
502          *              must be shut down.
503          *      <li>EINVAL - an invalid parameter was specified.
504          * </ul>
505          */
506 int  mdb_txn_renew(MDB_txn *txn);
507
508         /** Open a database in the environment.
509          * The database handle may be discarded by calling #mdb_close().
510          * @param[in] txn A transaction handle returned by #mdb_txn_begin()
511          * @param[in] name The name of the database to open. If only a single
512          *      database is needed in the enviroment, this value may be NULL.
513          * @param[in] flags Special options for this database. This parameter
514          * must be set to 0 or by bitwise OR'ing together one or more of the
515          * values described here.
516          * <ul>
517          *      <li>#MDB_REVERSEKEY
518          *              Keys are strings to be compared in reverse order, from the end
519          *              of the strings to the beginning. By default, Keys are treated as strings and
520          *              compared from beginning to end.
521          *      <li>#MDB_DUPSORT
522          *              Duplicate keys may be used in the database. (Or, from another perspective,
523          *              keys may have multiple data items, stored in sorted order.) By default
524          *              keys must be unique and may have only a single data item.
525          *      <li>#MDB_INTEGERKEY
526          *              Keys are binary integers in native byte order. On Big-Endian systems
527          *              this flag has no effect. On Little-Endian systems this flag behaves
528          *              the same as #MDB_REVERSEKEY. This flag is simply provided as a
529          *              convenience so that applications don't need to detect Endianness themselves
530          *              when using integers as keys.
531          *      <li>#MDB_DUPFIXED
532          *              This flag may only be used in combination with #MDB_DUPSORT. This option
533          *              tells the library that the data items for this database are all the same
534          *              size, which allows further optimizations in storage and retrieval. When
535          *              all data items are the same size, the #MDB_GET_MULTIPLE and #MDB_NEXT_MULTIPLE
536          *              cursor operations may be used to retrieve multiple items at once.
537          *      <li>#MDB_INTEGERDUP
538          *              This option specifies that duplicate data items are also integers, and
539          *              should be sorted as such.
540          *      <li>#MDB_CREATE
541          *              Create the named database if it doesn't exist. This option is not
542          *              allowed in a read-only transaction or a read-only environment.
543          * </ul>
544          * @param[out] dbi Address where the new #MDB_dbi handle will be stored
545          * @return A non-zero error value on failure and 0 on success. Some possible
546          * errors are:
547          * <ul>
548          *      <li>#MDB_NOTFOUND - the specified database doesn't exist in the environment
549          *              and #MDB_CREATE was not specified.
550          *      <li>ENFILE - too many databases have been opened. See #mdb_env_set_maxdbs().
551          * </ul>
552          */
553 int  mdb_open(MDB_txn *txn, const char *name, unsigned int flags, MDB_dbi *dbi);
554
555         /** Retrieve statistics for a database.
556          * @param[in] txn A transaction handle returned by #mdb_txn_begin()
557          * @param[in] dbi A database handle returned by #mdb_open()
558          * @param[out] stat The address of an #MDB_stat structure
559          *      where the statistics will be copied
560          * @return A non-zero error value on failure and 0 on success. Some possible
561          * errors are:
562          * <ul>
563          *      <li>EINVAL - an invalid parameter was specified.
564          * </ul>
565          */
566 int  mdb_stat(MDB_txn *txn, MDB_dbi dbi, MDB_stat *stat);
567
568         /** Close a database handle.
569          * @param[in] txn A transaction handle returned by #mdb_txn_begin()
570          * @param[in] dbi A database handle returned by #mdb_open()
571          */
572 void mdb_close(MDB_txn *txn, MDB_dbi dbi);
573
574         /** Set a custom key comparison function for a database.
575          * The comparison function is called whenever it is necessary to compare a
576          * key specified by the application with a key currently stored in the database.
577          * If no comparison function is specified, and no special key flags were specified
578          * with #mdb_open(), the keys are compared lexically, with shorter keys collating
579          * before longer keys.
580          * @warning This function must be called before any data access functions are used,
581          * otherwise data corruption may occur. The same function must be used by every
582          * process accessing the database, every time the database is used.
583          * @param[in] txn A transaction handle returned by #mdb_txn_begin()
584          * @param[in] dbi A database handle returned by #mdb_open()
585          * @param[in] cmp A #MDB_cmp_func function
586          * @return A non-zero error value on failure and 0 on success. Some possible
587          * errors are:
588          * <ul>
589          *      <li>EINVAL - an invalid parameter was specified.
590          * </ul>
591          */
592 int  mdb_set_compare(MDB_txn *txn, MDB_dbi dbi, MDB_cmp_func *cmp);
593
594         /** Set a custom data comparison function for a #MDB_DUPSORT database.
595          * This comparison function is called whenever it is necessary to compare a data
596          * item specified by the application with a data item currently stored in the database.
597          * This function only takes effect if the database was opened with the #MDB_DUPSORT
598          * flag.
599          * If no comparison function is specified, and no special key flags were specified
600          * with #mdb_open(), the data items are compared lexically, with shorter items collating
601          * before longer items.
602          * @warning This function must be called before any data access functions are used,
603          * otherwise data corruption may occur. The same function must be used by every
604          * process accessing the database, every time the database is used.
605          * @param[in] txn A transaction handle returned by #mdb_txn_begin()
606          * @param[in] dbi A database handle returned by #mdb_open()
607          * @param[in] cmp A #MDB_cmp_func function
608          * @return A non-zero error value on failure and 0 on success. Some possible
609          * errors are:
610          * <ul>
611          *      <li>EINVAL - an invalid parameter was specified.
612          * </ul>
613          */
614 int  mdb_set_dupsort(MDB_txn *txn, MDB_dbi dbi, MDB_cmp_func *cmp);
615
616         /** Set a relocation function for a #MDB_FIXEDMAP database.
617          * @todo The relocation function is called whenever it is necessary to move the data
618          * of an item to a different position in the database (e.g. through tree
619          * balancing operations, shifts as a result of adds or deletes, etc.). It is
620          * intended to allow address/position-dependent data items to be stored in
621          * a database in an environment opened with the #MDB_FIXEDMAP option.
622          * Currently the relocation feature is unimplemented and setting
623          * this function has no effect.
624          * @param[in] txn A transaction handle returned by #mdb_txn_begin()
625          * @param[in] dbi A database handle returned by #mdb_open()
626          * @param[in] rel A #MDB_rel_func function
627          * @return A non-zero error value on failure and 0 on success. Some possible
628          * errors are:
629          * <ul>
630          *      <li>EINVAL - an invalid parameter was specified.
631          * </ul>
632          */
633 int  mdb_set_relfunc(MDB_txn *txn, MDB_dbi dbi, MDB_rel_func *rel);
634
635         /** Get items from a database.
636          * This function retrieves key/data pairs from the database. The address
637          * and length of the data associated with the specified \b key are returned
638          * in the structure to which \b data refers.
639          * If the database supports duplicate keys (#MDB_DUPSORT) then the
640          * first data item for the key will be returned. Retrieval of other
641          * items requires the use of #mdb_cursor_get().
642          * @param[in] txn A transaction handle returned by #mdb_txn_begin()
643          * @param[in] dbi A database handle returned by #mdb_open()
644          * @param[in] key The key to search for in the database
645          * @param[out] data The data corresponding to the key
646          * @return A non-zero error value on failure and 0 on success. Some possible
647          * errors are:
648          * <ul>
649          *      <li>#MDB_NOTFOUND - the key was not in the database.
650          *      <li>EINVAL - an invalid parameter was specified.
651          * </ul>
652          */
653 int  mdb_get(MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data);
654
655         /** Store items into a database.
656          * This function stores key/data pairs in the database. The default behavior
657          * is to enter the new key/data pair, replacing any previously existing key
658          * if duplicates are disallowed, or adding a duplicate data item if
659          * duplicates are allowed (#MDB_DUPSORT).
660          * @param[in] txn A transaction handle returned by #mdb_txn_begin()
661          * @param[in] dbi A database handle returned by #mdb_open()
662          * @param[in] key The key to store in the database
663          * @param[in] data The data to store
664          * @param[in] flags Special options for this operation. This parameter
665          * must be set to 0 or by bitwise OR'ing together one or more of the
666          * values described here.
667          * <ul>
668          *      <li>#MDB_NODUPDATA - enter the new key/data pair only if it does not
669          *              already appear in the database. This flag may only be specified
670          *              if the database was opened with #MDB_DUPSORT. The function will
671          *              return #MDB_KEYEXIST if the key/data pair already appears in the
672          *              database.
673          *      <li>#MDB_NOOVERWRITE - enter the new key/data pair only if the key
674          *              does not already appear in the database. The function will return
675          *              #MDB_KEYEXIST if the key already appears in the database, even if
676          *              the database supports duplicates (#MDB_DUPSORT).
677          * </ul>
678          * @return A non-zero error value on failure and 0 on success. Some possible
679          * errors are:
680          * <ul>
681          *      <li>EACCESS - an attempt was made to write in a read-only transaction.
682          *      <li>EINVAL - an invalid parameter was specified.
683          *      <li>ENOMEM - the database is full, see #mdb_env_set_mapsize().
684          * </ul>
685          */
686 int  mdb_put(MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data,
687                             unsigned int flags);
688
689         /** Delete items from a database.
690          * This function removes key/data pairs from the database.
691          * If the database does not support sorted duplicate data items
692          * (#MDB_DUPSORT) the data parameter is ignored.
693          * If the database supports sorted duplicates and the data parameter
694          * is NULL, all of the duplicate data items for the key will be
695          * deleted. Otherwise, if the data parameter is non-NULL
696          * only the matching data item will be deleted.
697          * This function will return #MDB_NOTFOUND if the specified key/data
698          * pair is not in the database.
699          * @param[in] txn A transaction handle returned by #mdb_txn_begin()
700          * @param[in] dbi A database handle returned by #mdb_open()
701          * @param[in] key The key to delete from the database
702          * @param[in] data The data to delete
703          * @return A non-zero error value on failure and 0 on success. Some possible
704          * errors are:
705          * <ul>
706          *      <li>EACCESS - an attempt was made to write in a read-only transaction.
707          *      <li>EINVAL - an invalid parameter was specified.
708          * </ul>
709          */
710 int  mdb_del(MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data);
711
712         /** Create a cursor handle.
713          * Cursors are associated with a specific transaction and database and
714          * may not span threads.
715          * @todo Cursors only support read operations. Support for cursor_put() and
716          * cursor_del() needs to be added.
717          * @param[in] txn A transaction handle returned by #mdb_txn_begin()
718          * @param[in] dbi A database handle returned by #mdb_open()
719          * @param[out] cursor Address where the new #MDB_cursor handle will be stored
720          * @return A non-zero error value on failure and 0 on success. Some possible
721          * errors are:
722          * <ul>
723          *      <li>EINVAL - an invalid parameter was specified.
724          * </ul>
725          */
726 int  mdb_cursor_open(MDB_txn *txn, MDB_dbi dbi, MDB_cursor **cursor);
727
728         /** Close a cursor handle.
729          * The cursor handle will be freed and must not be used again after this call.
730          * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
731          */
732 void mdb_cursor_close(MDB_cursor *cursor);
733
734         /** Retrieve by cursor.
735          * This function retrieves key/data pairs from the database. The address and length
736          * of the key are returned in the object to which \b key refers (except for the
737          * case of the #MDB_SET option, in which the \b key object is unchanged), and
738          * the address and length of the data are returned in the object to which \b data
739          * refers.
740          * @bug Cursors are not coordinated with write operations. If a cursor in a
741          * write transaction is performing a sequential scan while records are being
742          * inserted or deleted in the same transaction, the cursor will be corrupted.
743          * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
744          * @param[in,out] key The key for a retrieved item
745          * @param[in,out] data The data of a retrieved item
746          * @param[in] op A cursor operation #MDB_cursor_op
747          * @return A non-zero error value on failure and 0 on success. Some possible
748          * errors are:
749          * <ul>
750          *      <li>#MDB_NOTFOUND - no matching key found.
751          *      <li>EINVAL - an invalid parameter was specified.
752          * </ul>
753          */
754 int  mdb_cursor_get(MDB_cursor *cursor, MDB_val *key, MDB_val *data,
755                             MDB_cursor_op op);
756
757         /** Return count of duplicates for current key.
758          * This call is only valid on databases that support sorted duplicate
759          * data items #MDB_DUPSORT.
760          * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
761          * @param[out] countp Address where the count will be stored
762          * @return A non-zero error value on failure and 0 on success. Some possible
763          * errors are:
764          * <ul>
765          *      <li>EINVAL - cursor is not initialized, or an invalid parameter was specified.
766          * </ul>
767          */
768 int  mdb_cursor_count(MDB_cursor *cursor, unsigned long *countp);
769
770         /** Compare two data items according to a particular database.
771          * This returns a comparison as if the two data items were keys in the
772          * specified database.
773          * @param[in] txn A transaction handle returned by #mdb_txn_begin()
774          * @param[in] dbi A database handle returned by #mdb_open()
775          * @param[in] a The first item to compare
776          * @param[in] b The second item to compare
777          * @return < 0 if a < b, 0 if a == b, > 0 if a > b
778          */
779 int  mdb_cmp(MDB_txn *txn, MDB_dbi dbi, const MDB_val *a, const MDB_val *b);
780
781 #endif /* _MDB_H_ */