5 NTDB: trivial database library version 2
7 Copyright (C) Andrew Tridgell 1999-2004
8 Copyright (C) Rusty Russell 2010-2012
10 ** NOTE! The following LGPL license applies to the ntdb
11 ** library. This does NOT imply that all of Samba is released
14 This library is free software; you can redistribute it and/or
15 modify it under the terms of the GNU Lesser General Public
16 License as published by the Free Software Foundation; either
17 version 3 of the License, or (at your option) any later version.
19 This library is distributed in the hope that it will be useful,
20 but WITHOUT ANY WARRANTY; without even the implied warranty of
21 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22 Lesser General Public License for more details.
24 You should have received a copy of the GNU Lesser General Public
25 License along with this library; if not, see <http://www.gnu.org/licenses/>.
32 #ifdef HAVE_LIBREPLACE
34 #include <system/filesys.h>
37 #if HAVE_FILE_OFFSET_BITS
38 #define _FILE_OFFSET_BITS 64
42 #ifdef HAVE_VISIBILITY_ATTR
43 #define _PUBLIC_ __attribute__((visibility("default")))
50 #include <sys/types.h>
53 /* For sig_atomic_t. */
63 #include <ccan/compiler/compiler.h>
64 #include <ccan/typesafe_cb/typesafe_cb.h>
65 #include <ccan/cast/cast.h>
71 * struct TDB_DATA - (n)tdb data blob
73 * To ease compatibility, we use 'struct TDB_DATA' from tdb.h, so if
74 * you want to include both tdb.h and ntdb.h, you need to #include
84 typedef struct TDB_DATA NTDB_DATA;
87 * ntdb_open - open a database file
88 * @name: the file name (or database name if flags contains NTDB_INTERNAL)
89 * @ntdb_flags: options for this database
90 * @open_flags: flags argument for ntdb's open() call.
91 * @mode: mode argument for ntdb's open() call.
92 * @attributes: linked list of extra attributes for this ntdb.
94 * This call opens (and potentially creates) a database file.
95 * Multiple processes can have the NTDB file open at once.
97 * On failure it will return NULL, and set errno: it may also call
98 * any log attribute found in @attributes.
101 * union ntdb_attribute
103 struct ntdb_context *ntdb_open(const char *name, int ntdb_flags,
104 int open_flags, mode_t mode,
105 union ntdb_attribute *attributes);
108 /* flags for ntdb_open() */
109 #define NTDB_DEFAULT 0 /* just a readability place holder */
110 #define NTDB_INTERNAL 2 /* don't store on disk */
111 #define NTDB_NOLOCK 4 /* don't do any locking */
112 #define NTDB_NOMMAP 8 /* don't use mmap */
113 #define NTDB_CONVERT 16 /* convert endian */
114 #define NTDB_NOSYNC 64 /* don't use synchronous transactions */
115 #define NTDB_SEQNUM 128 /* maintain a sequence number */
116 #define NTDB_ALLOW_NESTING 256 /* fake nested transactions */
117 #define NTDB_RDONLY 512 /* implied by O_RDONLY */
118 #define NTDB_CANT_CHECK 2048 /* has a feature which we don't understand */
121 * ntdb_close - close and free a ntdb.
122 * @ntdb: the ntdb context returned from ntdb_open()
124 * This always succeeds, in that @ntdb is unusable after this call. But if
125 * some unexpected error occurred while closing, it will return non-zero
126 * (the only clue as to cause will be via the log attribute).
128 int ntdb_close(struct ntdb_context *ntdb);
131 * enum NTDB_ERROR - error returns for NTDB
137 NTDB_SUCCESS = 0, /* No error. */
138 NTDB_ERR_CORRUPT = -1, /* We read the db, and it was bogus. */
139 NTDB_ERR_IO = -2, /* We couldn't read/write the db. */
140 NTDB_ERR_LOCK = -3, /* Locking failed. */
141 NTDB_ERR_OOM = -4, /* Out of Memory. */
142 NTDB_ERR_EXISTS = -5, /* The key already exists. */
143 NTDB_ERR_NOEXIST = -6, /* The key does not exist. */
144 NTDB_ERR_EINVAL = -7, /* You're using it wrong. */
145 NTDB_ERR_RDONLY = -8, /* The database is read-only. */
146 NTDB_ERR_LAST = NTDB_ERR_RDONLY
150 * ntdb_store - store a key/value pair in a ntdb.
151 * @ntdb: the ntdb context returned from ntdb_open()
153 * @dbuf: the data to associate with the key.
154 * @flag: NTDB_REPLACE, NTDB_INSERT or NTDB_MODIFY.
156 * This inserts (or overwrites) a key/value pair in the NTDB. If flag
157 * is NTDB_REPLACE, it doesn't matter whether the key exists or not;
158 * NTDB_INSERT means it must not exist (returns NTDB_ERR_EXISTS otherwise),
159 * and NTDB_MODIFY means it must exist (returns NTDB_ERR_NOEXIST otherwise).
161 * On success, this returns NTDB_SUCCESS.
164 * ntdb_fetch, ntdb_transaction_start, ntdb_append, ntdb_delete.
166 enum NTDB_ERROR ntdb_store(struct ntdb_context *ntdb,
171 /* flags to ntdb_store() */
172 #define NTDB_REPLACE 1 /* A readability place holder */
173 #define NTDB_INSERT 2 /* Don't overwrite an existing entry */
174 #define NTDB_MODIFY 3 /* Don't create an existing entry */
177 * ntdb_fetch - fetch a value from a ntdb.
178 * @ntdb: the ntdb context returned from ntdb_open()
180 * @data: pointer to data.
182 * This looks up a key in the database and sets it in @data.
184 * If it returns NTDB_SUCCESS, the key was found: it is your
185 * responsibility to call free() on @data->dptr.
187 * Otherwise, it returns an error (usually, NTDB_ERR_NOEXIST) and @data is
190 enum NTDB_ERROR ntdb_fetch(struct ntdb_context *ntdb, NTDB_DATA key,
194 * ntdb_errorstr - map the ntdb error onto a constant readable string
195 * @ecode: the enum NTDB_ERROR to map.
197 * This is useful for displaying errors to users.
199 const char *ntdb_errorstr(enum NTDB_ERROR ecode);
202 * ntdb_append - append a value to a key/value pair in a ntdb.
203 * @ntdb: the ntdb context returned from ntdb_open()
205 * @dbuf: the data to append.
207 * This is equivalent to fetching a record, reallocating .dptr to add the
208 * data, and writing it back, only it's much more efficient. If the key
209 * doesn't exist, it's equivalent to ntdb_store (with an additional hint that
210 * you expect to expand the record in future).
213 * ntdb_fetch(), ntdb_store()
215 enum NTDB_ERROR ntdb_append(struct ntdb_context *ntdb,
216 NTDB_DATA key, NTDB_DATA dbuf);
219 * ntdb_delete - delete a key from a ntdb.
220 * @ntdb: the ntdb context returned from ntdb_open()
221 * @key: the key to delete.
223 * Returns NTDB_SUCCESS on success, or an error (usually NTDB_ERR_NOEXIST).
226 * ntdb_fetch(), ntdb_store()
228 enum NTDB_ERROR ntdb_delete(struct ntdb_context *ntdb, NTDB_DATA key);
231 * ntdb_exists - does a key exist in the database?
232 * @ntdb: the ntdb context returned from ntdb_open()
233 * @key: the key to search for.
235 * Returns true if it exists, or false if it doesn't or any other error.
237 bool ntdb_exists(struct ntdb_context *ntdb, NTDB_DATA key);
240 * ntdb_deq - are NTDB_DATA equal?
242 * @b: another NTDB_DATA
244 static inline bool ntdb_deq(NTDB_DATA a, NTDB_DATA b)
246 return a.dsize == b.dsize && memcmp(a.dptr, b.dptr, a.dsize) == 0;
250 * ntdb_mkdata - make a NTDB_DATA from const data
251 * @p: the constant pointer
254 * As the dptr member of NTDB_DATA is not constant, you need to
255 * cast it. This function keeps thost casts in one place, as well as
256 * suppressing the warning some compilers give when casting away a
257 * qualifier (eg. gcc with -Wcast-qual)
259 static inline NTDB_DATA ntdb_mkdata(const void *p, size_t len)
262 d.dptr = cast_const(void *, p);
268 * ntdb_transaction_start - start a transaction
269 * @ntdb: the ntdb context returned from ntdb_open()
271 * This begins a series of atomic operations. Other processes will be able
272 * to read the ntdb, but not alter it (they will block), nor will they see
273 * any changes until ntdb_transaction_commit() is called.
275 * Note that if the NTDB_ALLOW_NESTING flag is set, a ntdb_transaction_start()
276 * within a transaction will succeed, but it's not a real transaction:
277 * (1) An inner transaction which is committed is not actually committed until
278 * the outer transaction is; if the outer transaction is cancelled, the
279 * inner ones are discarded.
280 * (2) ntdb_transaction_cancel() marks the outer transaction as having an error,
281 * so the final ntdb_transaction_commit() will fail.
282 * (3) the outer transaction will see the results of the inner transaction.
285 * ntdb_transaction_cancel, ntdb_transaction_commit.
287 enum NTDB_ERROR ntdb_transaction_start(struct ntdb_context *ntdb);
290 * ntdb_transaction_cancel - abandon a transaction
291 * @ntdb: the ntdb context returned from ntdb_open()
293 * This aborts a transaction, discarding any changes which were made.
294 * ntdb_close() does this implicitly.
296 void ntdb_transaction_cancel(struct ntdb_context *ntdb);
299 * ntdb_transaction_commit - commit a transaction
300 * @ntdb: the ntdb context returned from ntdb_open()
302 * This completes a transaction, writing any changes which were made.
304 * fsync() is used to commit the transaction (unless NTDB_NOSYNC is set),
305 * making it robust against machine crashes, but very slow compared to
306 * other NTDB operations.
308 * A failure can only be caused by unexpected errors (eg. I/O or
309 * memory); this is no point looping on transaction failure.
312 * ntdb_transaction_prepare_commit()
314 enum NTDB_ERROR ntdb_transaction_commit(struct ntdb_context *ntdb);
317 * ntdb_transaction_prepare_commit - prepare to commit a transaction
318 * @ntdb: the ntdb context returned from ntdb_open()
320 * This ensures we have the resources to commit a transaction (using
321 * ntdb_transaction_commit): if this succeeds then a transaction will only
322 * fail if the write() or fsync() calls fail.
324 * If this fails you must still call ntdb_transaction_cancel() to cancel
328 * ntdb_transaction_commit()
330 enum NTDB_ERROR ntdb_transaction_prepare_commit(struct ntdb_context *ntdb);
333 * ntdb_traverse - traverse a NTDB
334 * @ntdb: the ntdb context returned from ntdb_open()
335 * @fn: the function to call for every key/value pair (or NULL)
336 * @p: the pointer to hand to @f
338 * This walks the NTDB until all they keys have been traversed, or @fn
339 * returns non-zero. If the traverse function or other processes are
340 * changing data or adding or deleting keys, the traverse may be
341 * unreliable: keys may be skipped or (rarely) visited twice.
343 * There is one specific exception: the special case of deleting the
344 * current key does not undermine the reliability of the traversal.
346 * On success, returns the number of keys iterated. On error returns
347 * a negative enum NTDB_ERROR value.
349 #define ntdb_traverse(ntdb, fn, p) \
350 ntdb_traverse_(ntdb, typesafe_cb_preargs(int, void *, (fn), (p), \
351 struct ntdb_context *, \
352 NTDB_DATA, NTDB_DATA), (p))
354 int64_t ntdb_traverse_(struct ntdb_context *ntdb,
355 int (*fn)(struct ntdb_context *,
356 NTDB_DATA, NTDB_DATA, void *), void *p);
359 * ntdb_parse_record - operate directly on data in the database.
360 * @ntdb: the ntdb context returned from ntdb_open()
361 * @key: the key whose record we should hand to @parse
362 * @parse: the function to call for the data
363 * @data: the private pointer to hand to @parse (types must match).
365 * This avoids a copy for many cases, by handing you a pointer into
366 * the memory-mapped database. It also locks the record to prevent
367 * other accesses at the same time, so it won't change.
369 * Within the @parse callback you can perform read operations on the
370 * database, but no write operations: no ntdb_store() or
371 * ntdb_delete(), for example. The exception is if you call
372 * ntdb_lockall() before ntdb_parse_record().
374 * Never alter the data handed to parse()!
376 #define ntdb_parse_record(ntdb, key, parse, data) \
377 ntdb_parse_record_((ntdb), (key), \
378 typesafe_cb_preargs(enum NTDB_ERROR, void *, \
380 NTDB_DATA, NTDB_DATA), (data))
382 enum NTDB_ERROR ntdb_parse_record_(struct ntdb_context *ntdb,
384 enum NTDB_ERROR (*parse)(NTDB_DATA k,
390 * ntdb_get_seqnum - get a database sequence number
391 * @ntdb: the ntdb context returned from ntdb_open()
393 * This returns a sequence number: any change to the database from a
394 * ntdb context opened with the NTDB_SEQNUM flag will cause that number
395 * to increment. Note that the incrementing is unreliable (it is done
396 * without locking), so this is only useful as an optimization.
398 * For example, you may have a regular database backup routine which
399 * does not operate if the sequence number is unchanged. In the
400 * unlikely event of a failed increment, it will be backed up next
403 * Returns an enum NTDB_ERROR (ie. negative) on error.
405 int64_t ntdb_get_seqnum(struct ntdb_context *ntdb);
408 * ntdb_firstkey - get the "first" key in a NTDB
409 * @ntdb: the ntdb context returned from ntdb_open()
410 * @key: pointer to key.
412 * This returns an arbitrary key in the database; with ntdb_nextkey() it allows
413 * open-coded traversal of the database, though it is slightly less efficient
414 * than ntdb_traverse.
416 * It is your responsibility to free @key->dptr on success.
418 * Returns NTDB_ERR_NOEXIST if the database is empty.
420 enum NTDB_ERROR ntdb_firstkey(struct ntdb_context *ntdb, NTDB_DATA *key);
423 * ntdb_nextkey - get the "next" key in a NTDB
424 * @ntdb: the ntdb context returned from ntdb_open()
425 * @key: a key returned by ntdb_firstkey() or ntdb_nextkey().
427 * This returns another key in the database; it will free @key.dptr for
430 * Returns NTDB_ERR_NOEXIST if there are no more keys.
432 enum NTDB_ERROR ntdb_nextkey(struct ntdb_context *ntdb, NTDB_DATA *key);
435 * ntdb_chainlock - lock a record in the NTDB
436 * @ntdb: the ntdb context returned from ntdb_open()
437 * @key: the key to lock.
439 * This prevents any access occurring to a group of keys including @key,
440 * even if @key does not exist. This allows primitive atomic updates of
441 * records without using transactions.
443 * You cannot begin a transaction while holding a ntdb_chainlock(), nor can
444 * you do any operations on any other keys in the database. This also means
445 * that you cannot hold more than one ntdb_chainlock() at a time.
450 enum NTDB_ERROR ntdb_chainlock(struct ntdb_context *ntdb, NTDB_DATA key);
453 * ntdb_chainunlock - unlock a record in the NTDB
454 * @ntdb: the ntdb context returned from ntdb_open()
455 * @key: the key to unlock.
457 * The key must have previously been locked by ntdb_chainlock().
459 void ntdb_chainunlock(struct ntdb_context *ntdb, NTDB_DATA key);
462 * ntdb_chainlock_read - lock a record in the NTDB, for reading
463 * @ntdb: the ntdb context returned from ntdb_open()
464 * @key: the key to lock.
466 * This prevents any changes from occurring to a group of keys including @key,
467 * even if @key does not exist. This allows primitive atomic updates of
468 * records without using transactions.
470 * You cannot begin a transaction while holding a ntdb_chainlock_read(), nor can
471 * you do any operations on any other keys in the database. This also means
472 * that you cannot hold more than one ntdb_chainlock()/read() at a time.
477 enum NTDB_ERROR ntdb_chainlock_read(struct ntdb_context *ntdb, NTDB_DATA key);
480 * ntdb_chainunlock_read - unlock a record in the NTDB for reading
481 * @ntdb: the ntdb context returned from ntdb_open()
482 * @key: the key to unlock.
484 * The key must have previously been locked by ntdb_chainlock_read().
486 void ntdb_chainunlock_read(struct ntdb_context *ntdb, NTDB_DATA key);
489 * ntdb_lockall - lock the entire NTDB
490 * @ntdb: the ntdb context returned from ntdb_open()
492 * You cannot hold a ntdb_chainlock while calling this. It nests, so you
493 * must call ntdb_unlockall as many times as you call ntdb_lockall.
495 enum NTDB_ERROR ntdb_lockall(struct ntdb_context *ntdb);
498 * ntdb_unlockall - unlock the entire NTDB
499 * @ntdb: the ntdb context returned from ntdb_open()
501 void ntdb_unlockall(struct ntdb_context *ntdb);
504 * ntdb_lockall_read - lock the entire NTDB for reading
505 * @ntdb: the ntdb context returned from ntdb_open()
507 * This prevents others writing to the database, eg. ntdb_delete, ntdb_store,
508 * ntdb_append, but not ntdb_fetch.
510 * You cannot hold a ntdb_chainlock while calling this. It nests, so you
511 * must call ntdb_unlockall_read as many times as you call ntdb_lockall_read.
513 enum NTDB_ERROR ntdb_lockall_read(struct ntdb_context *ntdb);
516 * ntdb_unlockall_read - unlock the entire NTDB for reading
517 * @ntdb: the ntdb context returned from ntdb_open()
519 void ntdb_unlockall_read(struct ntdb_context *ntdb);
522 * ntdb_wipe_all - wipe the database clean
523 * @ntdb: the ntdb context returned from ntdb_open()
525 * Completely erase the database. This is faster than iterating through
526 * each key and doing ntdb_delete.
528 enum NTDB_ERROR ntdb_wipe_all(struct ntdb_context *ntdb);
531 * ntdb_repack - repack the database
532 * @ntdb: the ntdb context returned from ntdb_open()
534 * This repacks the database; if it is suffering from a great deal of
535 * fragmentation this might help. However, it can take twice the
536 * memory of the existing NTDB.
538 enum NTDB_ERROR ntdb_repack(struct ntdb_context *ntdb);
541 * ntdb_check - check a NTDB for consistency
542 * @ntdb: the ntdb context returned from ntdb_open()
543 * @check: function to check each key/data pair (or NULL)
544 * @data: argument for @check, must match type.
546 * This performs a consistency check of the open database, optionally calling
547 * a check() function on each record so you can do your own data consistency
548 * checks as well. If check() returns an error, that is returned from
551 * Note that the NTDB uses a feature which we don't understand which
552 * indicates we can't run ntdb_check(), this will log a warning to that
553 * effect and return NTDB_SUCCESS. You can detect this condition by
554 * looking for NTDB_CANT_CHECK in ntdb_get_flags().
556 * Returns NTDB_SUCCESS or an error.
558 #define ntdb_check(ntdb, check, data) \
559 ntdb_check_((ntdb), typesafe_cb_preargs(enum NTDB_ERROR, void *, \
565 enum NTDB_ERROR ntdb_check_(struct ntdb_context *ntdb,
566 enum NTDB_ERROR (*check)(NTDB_DATA k,
572 * enum ntdb_summary_flags - flags for ntdb_summary.
574 enum ntdb_summary_flags {
575 NTDB_SUMMARY_HISTOGRAMS = 1 /* Draw graphs in the summary. */
579 * ntdb_summary - return a string describing the NTDB state
580 * @ntdb: the ntdb context returned from ntdb_open()
581 * @flags: flags to control the summary output.
582 * @summary: pointer to string to allocate.
584 * This returns a developer-readable string describing the overall
585 * state of the ntdb, such as the percentage used and sizes of records.
586 * It is designed to provide information about the ntdb at a glance
587 * without displaying any keys or data in the database.
589 * On success, sets @summary to point to a malloc()'ed nul-terminated
590 * multi-line string. It is your responsibility to free() it.
592 enum NTDB_ERROR ntdb_summary(struct ntdb_context *ntdb,
593 enum ntdb_summary_flags flags,
598 * ntdb_get_flags - return the flags for a ntdb
599 * @ntdb: the ntdb context returned from ntdb_open()
601 * This returns the flags on the current ntdb. Some of these are caused by
602 * the flags argument to ntdb_open(), others (such as NTDB_CONVERT) are
605 unsigned int ntdb_get_flags(struct ntdb_context *ntdb);
608 * ntdb_add_flag - set a flag for a ntdb
609 * @ntdb: the ntdb context returned from ntdb_open()
610 * @flag: one of NTDB_NOLOCK, NTDB_NOMMAP, NTDB_NOSYNC or NTDB_ALLOW_NESTING.
612 * You can use this to set a flag on the NTDB. You cannot set these flags
613 * on a NTDB_INTERNAL ntdb.
615 void ntdb_add_flag(struct ntdb_context *ntdb, unsigned flag);
618 * ntdb_remove_flag - unset a flag for a ntdb
619 * @ntdb: the ntdb context returned from ntdb_open()
620 * @flag: one of NTDB_NOLOCK, NTDB_NOMMAP, NTDB_NOSYNC or NTDB_ALLOW_NESTING.
622 * You can use this to clear a flag on the NTDB. You cannot clear flags
623 * on a NTDB_INTERNAL ntdb.
625 void ntdb_remove_flag(struct ntdb_context *ntdb, unsigned flag);
628 * enum ntdb_attribute_type - descriminator for union ntdb_attribute.
630 enum ntdb_attribute_type {
631 NTDB_ATTRIBUTE_LOG = 0,
632 NTDB_ATTRIBUTE_HASH = 1,
633 NTDB_ATTRIBUTE_SEED = 2,
634 NTDB_ATTRIBUTE_STATS = 3,
635 NTDB_ATTRIBUTE_OPENHOOK = 4,
636 NTDB_ATTRIBUTE_FLOCK = 5,
637 NTDB_ATTRIBUTE_ALLOCATOR = 6,
638 NTDB_ATTRIBUTE_HASHSIZE = 7
642 * ntdb_get_attribute - get an attribute for an existing ntdb
643 * @ntdb: the ntdb context returned from ntdb_open()
644 * @attr: the union ntdb_attribute to set.
646 * This gets an attribute from a NTDB which has previously been set (or
647 * may return the default values). Set @attr.base.attr to the
648 * attribute type you want get.
650 enum NTDB_ERROR ntdb_get_attribute(struct ntdb_context *ntdb,
651 union ntdb_attribute *attr);
654 * ntdb_set_attribute - set an attribute for an existing ntdb
655 * @ntdb: the ntdb context returned from ntdb_open()
656 * @attr: the union ntdb_attribute to set.
658 * This sets an attribute on a NTDB, overriding any previous attribute
659 * of the same type. It returns NTDB_ERR_EINVAL if the attribute is
660 * unknown or invalid.
662 * Note that NTDB_ATTRIBUTE_HASH, NTDB_ATTRIBUTE_SEED, and
663 * NTDB_ATTRIBUTE_OPENHOOK cannot currently be set after ntdb_open.
665 enum NTDB_ERROR ntdb_set_attribute(struct ntdb_context *ntdb,
666 const union ntdb_attribute *attr);
669 * ntdb_unset_attribute - reset an attribute for an existing ntdb
670 * @ntdb: the ntdb context returned from ntdb_open()
671 * @type: the attribute type to unset.
673 * This unsets an attribute on a NTDB, returning it to the defaults
674 * (where applicable).
676 * Note that it only makes sense for NTDB_ATTRIBUTE_LOG and NTDB_ATTRIBUTE_FLOCK
679 void ntdb_unset_attribute(struct ntdb_context *ntdb,
680 enum ntdb_attribute_type type);
683 * ntdb_name - get the name of a ntdb
684 * @ntdb: the ntdb context returned from ntdb_open()
686 * This returns a copy of the name string, made at ntdb_open() time.
688 * This is mostly useful for logging.
690 const char *ntdb_name(const struct ntdb_context *ntdb);
693 * ntdb_fd - get the file descriptor of a ntdb
694 * @ntdb: the ntdb context returned from ntdb_open()
696 * This returns the file descriptor for the underlying database file, or -1
699 int ntdb_fd(const struct ntdb_context *ntdb);
702 * ntdb_foreach - iterate through every open NTDB.
703 * @fn: the function to call for every NTDB
704 * @p: the pointer to hand to @fn
706 * NTDB internally keeps track of all open TDBs; this function allows you to
707 * iterate through them. If @fn returns non-zero, traversal stops.
709 #define ntdb_foreach(fn, p) \
710 ntdb_foreach_(typesafe_cb_preargs(int, void *, (fn), (p), \
711 struct ntdb_context *), (p))
713 void ntdb_foreach_(int (*fn)(struct ntdb_context *, void *), void *p);
716 * struct ntdb_attribute_base - common fields for all ntdb attributes.
718 struct ntdb_attribute_base {
719 enum ntdb_attribute_type attr;
720 union ntdb_attribute *next;
724 * enum ntdb_log_level - log levels for ntdb_attribute_log
725 * @NTDB_LOG_ERROR: used to log unrecoverable errors such as I/O errors
726 * or internal consistency failures.
727 * @NTDB_LOG_USE_ERROR: used to log usage errors such as invalid parameters
728 * or writing to a read-only database.
729 * @NTDB_LOG_WARNING: used for informational messages on issues which
730 * are unusual but handled by NTDB internally, such
731 * as a failure to mmap or failure to open /dev/urandom.
732 * It's also used when ntdb_open() fails without O_CREAT
733 * because a file does not exist.
735 enum ntdb_log_level {
742 * struct ntdb_attribute_log - log function attribute
744 * This attribute provides a hook for you to log errors.
746 struct ntdb_attribute_log {
747 struct ntdb_attribute_base base; /* .attr = NTDB_ATTRIBUTE_LOG */
748 void (*fn)(struct ntdb_context *ntdb,
749 enum ntdb_log_level level,
750 enum NTDB_ERROR ecode,
757 * struct ntdb_attribute_hash - hash function attribute
759 * This attribute allows you to provide an alternative hash function.
760 * This hash function will be handed keys from the database; it will also
761 * be handed the 8-byte NTDB_HASH_MAGIC value for checking the header (the
762 * ntdb_open() will fail if the hash value doesn't match the header).
764 * Note that if your hash function gives different results on
765 * different machine endians, your ntdb will no longer work across
766 * different architectures!
768 struct ntdb_attribute_hash {
769 struct ntdb_attribute_base base; /* .attr = NTDB_ATTRIBUTE_HASH */
770 uint32_t (*fn)(const void *key, size_t len, uint32_t seed,
776 * struct ntdb_attribute_seed - hash function seed attribute
778 * The hash function seed is normally taken from /dev/urandom (or equivalent)
779 * but can be set manually here. This is mainly for testing purposes.
781 struct ntdb_attribute_seed {
782 struct ntdb_attribute_base base; /* .attr = NTDB_ATTRIBUTE_SEED */
787 * struct ntdb_attribute_stats - ntdb operational statistics
789 * This attribute records statistics of various low-level NTDB operations.
790 * This can be used to assist performance evaluation. This is only
791 * useful for ntdb_get_attribute().
793 * New fields will be added at the end, hence the "size" argument which
794 * indicates how large your structure is: it must be filled in before
795 * calling ntdb_get_attribute(), which will overwrite it with the size
798 struct ntdb_attribute_stats {
799 struct ntdb_attribute_base base; /* .attr = NTDB_ATTRIBUTE_STATS */
800 size_t size; /* = sizeof(struct ntdb_attribute_stats) */
802 uint64_t alloc_subhash;
803 uint64_t alloc_chain;
804 uint64_t alloc_bucket_exact;
805 uint64_t alloc_bucket_max;
806 uint64_t alloc_leftover;
807 uint64_t alloc_coalesce_tried;
808 uint64_t alloc_coalesce_iterate_clash;
809 uint64_t alloc_coalesce_lockfail;
810 uint64_t alloc_coalesce_race;
811 uint64_t alloc_coalesce_succeeded;
812 uint64_t alloc_coalesce_num_merged;
814 uint64_t compare_wrong_offsetbits;
815 uint64_t compare_wrong_keylen;
816 uint64_t compare_wrong_rechash;
817 uint64_t compare_wrong_keycmp;
818 uint64_t transactions;
819 uint64_t transaction_cancel;
820 uint64_t transaction_nest;
821 uint64_t transaction_expand_file;
822 uint64_t transaction_read_direct;
823 uint64_t transaction_read_direct_fail;
824 uint64_t transaction_write_direct;
825 uint64_t transaction_write_direct_fail;
827 uint64_t traverse_val_vanished;
831 uint64_t lock_lowlevel;
832 uint64_t lock_nonblock;
833 uint64_t lock_nonblock_fail;
837 * struct ntdb_attribute_openhook - ntdb special effects hook for open
839 * This attribute contains a function to call once we have the OPEN_LOCK
840 * for the ntdb, but before we've examined its contents. If this succeeds,
841 * the ntdb will be populated if it's then zero-length.
843 * This is a hack to allow support for TDB-style TDB_CLEAR_IF_FIRST
846 struct ntdb_attribute_openhook {
847 struct ntdb_attribute_base base; /* .attr = NTDB_ATTRIBUTE_OPENHOOK */
848 enum NTDB_ERROR (*fn)(int fd, void *data);
853 * struct ntdb_attribute_flock - ntdb special effects hook for file locking
855 * This attribute contains function to call to place locks on a file; it can
856 * be used to support non-blocking operations or lock proxying.
858 * They should return 0 on success, -1 on failure and set errno.
860 * An error will be logged on error if errno is neither EAGAIN nor EINTR
861 * (normally it would only return EAGAIN if waitflag is false, and
862 * loop internally on EINTR).
864 struct ntdb_attribute_flock {
865 struct ntdb_attribute_base base; /* .attr = NTDB_ATTRIBUTE_FLOCK */
866 int (*lock)(int fd,int rw, off_t off, off_t len, bool waitflag, void *);
867 int (*unlock)(int fd, int rw, off_t off, off_t len, void *);
872 * struct ntdb_attribute_hashsize - ntdb hashsize setting.
874 * This attribute is only settable on ntdb_open; it indicates that we create
875 * a hashtable of the given size, rather than the default.
877 struct ntdb_attribute_hashsize {
878 struct ntdb_attribute_base base; /* .attr = NTDB_ATTRIBUTE_HASHSIZE */
883 * struct ntdb_attribute_allocator - allocator for ntdb to use.
885 * You can replace malloc/free with your own allocation functions.
886 * The allocator takes an "owner" pointer, which is either NULL (for
887 * the initial struct ntdb_context and struct ntdb_file), or a
888 * previously allocated pointer. This is useful for relationship
889 * tracking, such as the talloc library.
891 * The expand function is realloc, but only ever used to expand an
892 * existing allocation.
894 * Be careful mixing allocators: two ntdb_contexts which have the same file
895 * open will share the same struct ntdb_file. This may be allocated by one
896 * ntdb's allocator, and freed by the other.
898 struct ntdb_attribute_allocator {
899 struct ntdb_attribute_base base; /* .attr = NTDB_ATTRIBUTE_ALLOCATOR */
900 void *(*alloc)(const void *owner, size_t len, void *priv_data);
901 void *(*expand)(void *old, size_t newlen, void *priv_data);
902 void (*free)(void *old, void *priv_data);
907 * union ntdb_attribute - ntdb attributes.
909 * This represents all the known attributes.
912 * struct ntdb_attribute_log, struct ntdb_attribute_hash,
913 * struct ntdb_attribute_seed, struct ntdb_attribute_stats,
914 * struct ntdb_attribute_openhook, struct ntdb_attribute_flock,
915 * struct ntdb_attribute_allocator alloc.
917 union ntdb_attribute {
918 struct ntdb_attribute_base base;
919 struct ntdb_attribute_log log;
920 struct ntdb_attribute_hash hash;
921 struct ntdb_attribute_seed seed;
922 struct ntdb_attribute_stats stats;
923 struct ntdb_attribute_openhook openhook;
924 struct ntdb_attribute_flock flock;
925 struct ntdb_attribute_allocator alloc;
926 struct ntdb_attribute_hashsize hashsize;