5 Unix SMB/CIFS implementation.
7 trivial database library
9 Copyright (C) Andrew Tridgell 1999-2004
11 ** NOTE! The following LGPL license applies to the tdb
12 ** library. This does NOT imply that all of Samba is released
15 This library is free software; you can redistribute it and/or
16 modify it under the terms of the GNU Lesser General Public
17 License as published by the Free Software Foundation; either
18 version 3 of the License, or (at your option) any later version.
20 This library is distributed in the hope that it will be useful,
21 but WITHOUT ANY WARRANTY; without even the implied warranty of
22 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
23 Lesser General Public License for more details.
25 You should have received a copy of the GNU Lesser General Public
26 License along with this library; if not, see <http://www.gnu.org/licenses/>.
37 * @defgroup tdb The tdb API
39 * tdb is a Trivial database. In concept, it is very much like GDBM, and BSD's
40 * DB except that it allows multiple simultaneous writers and uses locking
41 * internally to keep writers from trampling on each other. tdb is also
44 * @section tdb_interface Interface
46 * The interface is very similar to gdbm except for the following:
49 * <li>different open interface. The tdb_open call is more similar to a
50 * traditional open()</li>
51 * <li>no tdbm_reorganise() function</li>
52 * <li>no tdbm_sync() function. No operations are cached in the library
54 * <li>added a tdb_traverse() function for traversing the whole database</li>
55 * <li>added transactions support</li>
58 * A general rule for using tdb is that the caller frees any returned TDB_DATA
59 * structures. Just call free(p.dptr) to free a TDB_DATA return value called p.
60 * This is the same as gdbm.
65 /** Flags to tdb_store() */
66 #define TDB_REPLACE 1 /** Unused */
67 #define TDB_INSERT 2 /** Don't overwrite an existing entry */
68 #define TDB_MODIFY 3 /** Don't create an existing entry */
70 /** Flags for tdb_open() */
71 #define TDB_DEFAULT 0 /** just a readability place holder */
72 #define TDB_CLEAR_IF_FIRST 1 /** If this is the first open, wipe the db */
73 #define TDB_INTERNAL 2 /** Don't store on disk */
74 #define TDB_NOLOCK 4 /** Don't do any locking */
75 #define TDB_NOMMAP 8 /** Don't use mmap */
76 #define TDB_CONVERT 16 /** Convert endian (internal use) */
77 #define TDB_BIGENDIAN 32 /** Header is big-endian (internal use) */
78 #define TDB_NOSYNC 64 /** Don't use synchronous transactions */
79 #define TDB_SEQNUM 128 /** Maintain a sequence number */
80 #define TDB_VOLATILE 256 /** Activate the per-hashchain freelist, default 5 */
81 #define TDB_ALLOW_NESTING 512 /** Allow transactions to nest */
82 #define TDB_DISALLOW_NESTING 1024 /** Disallow transactions to nest */
83 #define TDB_INCOMPATIBLE_HASH 2048 /** Better hashing: can't be opened by tdb < 1.2.6. */
84 #define TDB_MUTEX_LOCKING 4096 /** optimized locking using robust mutexes if supported,
85 only with tdb >= 1.3.0 and TDB_CLEAR_IF_FIRST
86 after checking tdb_runtime_check_for_robust_mutexes() */
88 /** The tdb error codes */
89 enum TDB_ERROR {TDB_SUCCESS=0, TDB_ERR_CORRUPT, TDB_ERR_IO, TDB_ERR_LOCK,
90 TDB_ERR_OOM, TDB_ERR_EXISTS, TDB_ERR_NOLOCK, TDB_ERR_LOCK_TIMEOUT,
91 TDB_ERR_NOEXIST, TDB_ERR_EINVAL, TDB_ERR_RDONLY,
94 /** Debugging uses one of the following levels */
95 enum tdb_debug_level {TDB_DEBUG_FATAL = 0, TDB_DEBUG_ERROR,
96 TDB_DEBUG_WARNING, TDB_DEBUG_TRACE};
98 /** The tdb data structure */
99 typedef struct TDB_DATA {
104 #ifndef PRINTF_ATTRIBUTE
106 /** Use gcc attribute to check printf fns. a1 is the 1-based index of
107 * the parameter containing the format, and a2 the index of the first
108 * argument. Note that some gcc 2.x versions don't handle this
110 #define PRINTF_ATTRIBUTE(a1, a2) __attribute__ ((format (__printf__, a1, a2)))
112 #define PRINTF_ATTRIBUTE(a1, a2)
116 /** This is the context structure that is returned from a db open. */
117 typedef struct tdb_context TDB_CONTEXT;
119 typedef int (*tdb_traverse_func)(struct tdb_context *, TDB_DATA, TDB_DATA, void *);
120 typedef void (*tdb_log_func)(struct tdb_context *, enum tdb_debug_level, const char *, ...) PRINTF_ATTRIBUTE(3, 4);
121 typedef unsigned int (*tdb_hash_func)(TDB_DATA *key);
123 struct tdb_logging_context {
129 * @brief Open the database and creating it if necessary.
131 * @param[in] name The name of the db to open.
133 * @param[in] hash_size The hash size is advisory, use zero for a default
136 * @param[in] tdb_flags The flags to use to open the db:\n\n
137 * TDB_CLEAR_IF_FIRST - Clear database if we are the
138 * only one with it open\n
139 * TDB_INTERNAL - Don't use a file, instead store the
140 * data in memory. The filename is
141 * ignored in this case.\n
142 * TDB_NOLOCK - Don't do any locking\n
143 * TDB_NOMMAP - Don't use mmap\n
144 * TDB_NOSYNC - Don't synchronise transactions to disk\n
145 * TDB_SEQNUM - Maintain a sequence number\n
146 * TDB_VOLATILE - activate the per-hashchain freelist,
148 * TDB_ALLOW_NESTING - Allow transactions to nest.\n
149 * TDB_DISALLOW_NESTING - Disallow transactions to nest.\n
150 * TDB_INCOMPATIBLE_HASH - Better hashing: can't be opened by tdb < 1.2.6.\n
151 * TDB_MUTEX_LOCKING - Optimized locking using robust mutexes if supported,
152 * can't be opened by tdb < 1.3.0.
153 * Only valid in combination with TDB_CLEAR_IF_FIRST
154 * after checking tdb_runtime_check_for_robust_mutexes()\n
156 * @param[in] open_flags Flags for the open(2) function.
158 * @param[in] mode The mode for the open(2) function.
160 * @return A tdb context structure, NULL on error.
162 struct tdb_context *tdb_open(const char *name, int hash_size, int tdb_flags,
163 int open_flags, mode_t mode);
166 * @brief Open the database and creating it if necessary.
168 * This is like tdb_open(), but allows you to pass an initial logging and
169 * hash function. Be careful when passing a hash function - all users of the
170 * database must use the same hash function or you will get data corruption.
172 * @param[in] name The name of the db to open.
174 * @param[in] hash_size The hash size is advisory, use zero for a default
177 * @param[in] tdb_flags The flags to use to open the db:\n\n
178 * TDB_CLEAR_IF_FIRST - Clear database if we are the
179 * only one with it open\n
180 * TDB_INTERNAL - Don't use a file, instead store the
181 * data in memory. The filename is
182 * ignored in this case.\n
183 * TDB_NOLOCK - Don't do any locking\n
184 * TDB_NOMMAP - Don't use mmap\n
185 * TDB_NOSYNC - Don't synchronise transactions to disk\n
186 * TDB_SEQNUM - Maintain a sequence number\n
187 * TDB_VOLATILE - activate the per-hashchain freelist,
189 * TDB_ALLOW_NESTING - Allow transactions to nest.\n
190 * TDB_DISALLOW_NESTING - Disallow transactions to nest.\n
191 * TDB_INCOMPATIBLE_HASH - Better hashing: can't be opened by tdb < 1.2.6.\n
192 * TDB_MUTEX_LOCKING - Optimized locking using robust mutexes if supported,
193 * can't be opened by tdb < 1.3.0.
194 * Only valid in combination with TDB_CLEAR_IF_FIRST
195 * after checking tdb_runtime_check_for_robust_mutexes()\n
197 * @param[in] open_flags Flags for the open(2) function.
199 * @param[in] mode The mode for the open(2) function.
201 * @param[in] log_ctx The logging function to use.
203 * @param[in] hash_fn The hash function you want to use.
205 * @return A tdb context structure, NULL on error.
209 struct tdb_context *tdb_open_ex(const char *name, int hash_size, int tdb_flags,
210 int open_flags, mode_t mode,
211 const struct tdb_logging_context *log_ctx,
212 tdb_hash_func hash_fn);
215 * @brief Set the maximum number of dead records per hash chain.
217 * @param[in] tdb The database handle to set the maximum.
219 * @param[in] max_dead The maximum number of dead records per hash chain.
221 void tdb_set_max_dead(struct tdb_context *tdb, int max_dead);
224 * @brief Reopen a tdb.
226 * This can be used after a fork to ensure that we have an independent seek
227 * pointer from our parent and to re-establish locks.
229 * @param[in] tdb The database to reopen. It will be free'd on error!
231 * @return 0 on success, -1 on error.
233 * @note Don't call tdb_error() after this function cause the tdb context will
236 int tdb_reopen(struct tdb_context *tdb);
239 * @brief Reopen all tdb's
241 * If the parent is longlived (ie. a parent daemon architecture), we know it
242 * will keep it's active lock on a tdb opened with CLEAR_IF_FIRST. Thus for
243 * child processes we don't have to add an active lock. This is essential to
244 * improve performance on systems that keep POSIX locks as a non-scalable data
245 * structure in the kernel.
247 * @param[in] parent_longlived Wether the parent is longlived or not.
249 * @return 0 on success, -1 on error.
251 int tdb_reopen_all(int parent_longlived);
254 * @brief Set a different tdb logging function.
256 * @param[in] tdb The tdb to set the logging function.
258 * @param[in] log_ctx The logging function to set.
260 void tdb_set_logging_function(struct tdb_context *tdb, const struct tdb_logging_context *log_ctx);
263 * @brief Get the tdb last error code.
265 * @param[in] tdb The tdb to get the error code from.
267 * @return A TDB_ERROR code.
271 enum TDB_ERROR tdb_error(struct tdb_context *tdb);
274 * @brief Get a error string for the last tdb error
276 * @param[in] tdb The tdb to get the error code from.
278 * @return An error string.
280 const char *tdb_errorstr(struct tdb_context *tdb);
283 * @brief Fetch an entry in the database given a key.
285 * The caller must free the resulting data.
287 * @param[in] tdb The tdb to fetch the key.
289 * @param[in] key The key to fetch.
291 * @return The key entry found in the database, NULL on error with
295 * @see tdb_errorstr()
297 TDB_DATA tdb_fetch(struct tdb_context *tdb, TDB_DATA key);
300 * @brief Hand a record to a parser function without allocating it.
302 * This function is meant as a fast tdb_fetch alternative for large records
303 * that are frequently read. The "key" and "data" arguments point directly
304 * into the tdb shared memory, they are not aligned at any boundary.
306 * @warning The parser is called while tdb holds a lock on the record. DO NOT
307 * call other tdb routines from within the parser. Also, for good performance
308 * you should make the parser fast to allow parallel operations.
310 * @param[in] tdb The tdb to parse the record.
312 * @param[in] key The key to parse.
314 * @param[in] parser The parser to use to parse the data.
316 * @param[in] private_data A private data pointer which is passed to the parser
319 * @return -1 if the record was not found. If the record was found,
320 * the return value of "parser" is passed up to the caller.
322 int tdb_parse_record(struct tdb_context *tdb, TDB_DATA key,
323 int (*parser)(TDB_DATA key, TDB_DATA data,
328 * @brief Delete an entry in the database given a key.
330 * @param[in] tdb The tdb to delete the key.
332 * @param[in] key The key to delete.
334 * @return 0 on success, -1 if the key doesn't exist.
336 int tdb_delete(struct tdb_context *tdb, TDB_DATA key);
339 * @brief Store an element in the database.
341 * This replaces any existing element with the same key.
343 * @param[in] tdb The tdb to store the entry.
345 * @param[in] key The key to use to store the entry.
347 * @param[in] dbuf The data to store under the key.
349 * @param[in] flag The flags to store the key:\n\n
350 * TDB_INSERT: Don't overwrite an existing entry.\n
351 * TDB_MODIFY: Don't create a new entry\n
353 * @return 0 on success, -1 on error with error code set.
356 * @see tdb_errorstr()
358 int tdb_store(struct tdb_context *tdb, TDB_DATA key, TDB_DATA dbuf, int flag);
362 * @brief Store an element in the database.
364 * This replaces any existing element with the same key.
366 * @param[in] tdb The tdb to store the entry.
368 * @param[in] key The key to use to store the entry.
370 * @param[in] dbufs A vector of memory chunks to write
372 * @param[in] num_dbufs Length of the dbufs vector
374 * @param[in] flag The flags to store the key:\n\n
375 * TDB_INSERT: Don't overwrite an existing entry.\n
376 * TDB_MODIFY: Don't create a new entry\n
378 * @return 0 on success, -1 on error with error code set.
381 * @see tdb_errorstr()
383 int tdb_storev(struct tdb_context *tdb, TDB_DATA key,
384 const TDB_DATA *dbufs, int num_dbufs, int flag);
387 * @brief Append data to an entry.
389 * If the entry doesn't exist, it will create a new one.
391 * @param[in] tdb The database to use.
393 * @param[in] key The key to append the data.
395 * @param[in] new_dbuf The data to append to the key.
397 * @return 0 on success, -1 on error with error code set.
400 * @see tdb_errorstr()
402 int tdb_append(struct tdb_context *tdb, TDB_DATA key, TDB_DATA new_dbuf);
405 * @brief Close a database.
407 * @param[in] tdb The database to close. The context will be free'd.
409 * @return 0 for success, -1 on error.
411 * @note Don't call tdb_error() after this function cause the tdb context will
414 int tdb_close(struct tdb_context *tdb);
417 * @brief Find the first entry in the database and return its key.
419 * The caller must free the returned data.
421 * @param[in] tdb The database to use.
423 * @return The first entry of the database, an empty TDB_DATA entry
424 * if the database is empty.
426 TDB_DATA tdb_firstkey(struct tdb_context *tdb);
429 * @brief Find the next entry in the database, returning its key.
431 * The caller must free the returned data.
433 * @param[in] tdb The database to use.
435 * @param[in] key The key from which you want the next key.
437 * @return The next entry of the current key, an empty TDB_DATA
438 * entry if there is no entry.
440 TDB_DATA tdb_nextkey(struct tdb_context *tdb, TDB_DATA key);
443 * @brief Traverse the entire database.
445 * While traversing the function fn(tdb, key, data, state) is called on each
446 * element. If fn is NULL then it is not called. A non-zero return value from
447 * fn() indicates that the traversal should stop. Traversal callbacks may not
448 * start transactions.
450 * @warning The data buffer given to the callback fn does NOT meet the alignment
451 * restrictions malloc gives you.
453 * @param[in] tdb The database to traverse.
455 * @param[in] fn The function to call on each entry.
457 * @param[in] private_data The private data which should be passed to the
458 * traversing function.
460 * @return The record count traversed, -1 on error.
462 int tdb_traverse(struct tdb_context *tdb, tdb_traverse_func fn, void *private_data);
465 * @brief Traverse the entire database.
467 * While traversing the database the function fn(tdb, key, data, state) is
468 * called on each element, but marking the database read only during the
469 * traversal, so any write operations will fail. This allows tdb to use read
470 * locks, which increases the parallelism possible during the traversal.
472 * @param[in] tdb The database to traverse.
474 * @param[in] fn The function to call on each entry.
476 * @param[in] private_data The private data which should be passed to the
477 * traversing function.
479 * @return The record count traversed, -1 on error.
481 int tdb_traverse_read(struct tdb_context *tdb, tdb_traverse_func fn, void *private_data);
484 * @brief Traverse a single hash chain
486 * Traverse a single hash chain under a single lock operation. No
487 * database modification is possible in the callback.
489 * This exists for background cleanup of databases. In normal
490 * operations, traversing a complete database can be much too
491 * expensive. Databases can have many chains, which will all have to
492 * be looked at before tdb_traverse finishes. Also tdb_traverse does a
493 * lot of fcntl activity to protect against concurrent record deletes.
495 * With this you can walk a fraction of the whole tdb, collect the
496 * entries you want to prune, leave the traverse, and then modify or
497 * delete the records in a subsequent step.
499 * To walk the entire database, call this function tdb_hash_size()
500 * times, with 0<=chain<tdb_hash_size(tdb).
502 * @param[in] tdb The database to traverse.
504 * @param[in] chain The hash chain number to traverse.
506 * @param[in] fn The function to call on each entry.
508 * @param[in] private_data The private data which should be passed to the
509 * traversing function.
511 * @return The record count traversed, -1 on error.
514 int tdb_traverse_chain(struct tdb_context *tdb,
516 tdb_traverse_func fn,
520 * @brief Traverse a single hash chain
522 * This is like tdb_traverse_chain(), but for all records that are in
523 * the same chain as the record corresponding to the key parameter.
525 * Use it for ongoing database maintenance under a lock. Whenever you
526 * are about to modify a database, you know which record you are going
527 * to write to. For that tdb_store(), an exclusive chainlock is taken
528 * behind the scenes. To utilize this exclusive lock for incremental
529 * database cleanup as well, tdb_chainlock() the key you are about to
530 * modify, then tdb_traverse_key_chain() to do the incremental
531 * maintenance, modify your record and tdb_chainunlock() the key
534 * @param[in] tdb The database to traverse.
536 * @param[in] key The record key to walk the chain for.
538 * @param[in] fn The function to call on each entry.
540 * @param[in] private_data The private data which should be passed to the
541 * traversing function.
543 * @return The record count traversed, -1 on error.
546 int tdb_traverse_key_chain(struct tdb_context *tdb,
548 tdb_traverse_func fn,
551 * @brief Check if an entry in the database exists.
553 * @note 1 is returned if the key is found and 0 is returned if not found this
554 * doesn't match the conventions in the rest of this module, but is compatible
557 * @param[in] tdb The database to check if the entry exists.
559 * @param[in] key The key to check if the entry exists.
561 * @return 1 if the key is found, 0 if not.
563 int tdb_exists(struct tdb_context *tdb, TDB_DATA key);
566 * @brief Lock entire database with a write lock.
568 * @param[in] tdb The database to lock.
570 * @return 0 on success, -1 on error with error code set.
573 * @see tdb_errorstr()
575 int tdb_lockall(struct tdb_context *tdb);
578 * @brief Lock entire database with a write lock.
580 * This is the non-blocking call.
582 * @param[in] tdb The database to lock.
584 * @return 0 on success, -1 on error with error code set.
588 * @see tdb_errorstr()
590 int tdb_lockall_nonblock(struct tdb_context *tdb);
593 * @brief Unlock entire database with write lock.
595 * @param[in] tdb The database to unlock.
597 * @return 0 on success, -1 on error with error code set.
601 * @see tdb_errorstr()
603 int tdb_unlockall(struct tdb_context *tdb);
606 * @brief Lock entire database with a read lock.
608 * @param[in] tdb The database to lock.
610 * @return 0 on success, -1 on error with error code set.
613 * @see tdb_errorstr()
615 int tdb_lockall_read(struct tdb_context *tdb);
618 * @brief Lock entire database with a read lock.
620 * This is the non-blocking call.
622 * @param[in] tdb The database to lock.
624 * @return 0 on success, -1 on error with error code set.
626 * @see tdb_lockall_read()
628 * @see tdb_errorstr()
630 int tdb_lockall_read_nonblock(struct tdb_context *tdb);
633 * @brief Unlock entire database with read lock.
635 * @param[in] tdb The database to unlock.
637 * @return 0 on success, -1 on error with error code set.
639 * @see tdb_lockall_read()
641 * @see tdb_errorstr()
643 int tdb_unlockall_read(struct tdb_context *tdb);
646 * @brief Lock entire database with write lock - mark only.
648 * @todo Add more details.
650 * @param[in] tdb The database to mark.
652 * @return 0 on success, -1 on error with error code set.
655 * @see tdb_errorstr()
657 int tdb_lockall_mark(struct tdb_context *tdb);
660 * @brief Lock entire database with write lock - unmark only.
662 * @todo Add more details.
664 * @param[in] tdb The database to mark.
666 * @return 0 on success, -1 on error with error code set.
669 * @see tdb_errorstr()
671 int tdb_lockall_unmark(struct tdb_context *tdb);
674 * @brief Get the name of the current tdb file.
676 * This is useful for external logging functions.
678 * @param[in] tdb The database to get the name from.
680 * @return The name of the database.
682 const char *tdb_name(struct tdb_context *tdb);
685 * @brief Get the underlying file descriptor being used by tdb.
687 * This is useful for external routines that want to check the device/inode
690 * @param[in] tdb The database to get the fd from.
692 * @return The file descriptor or -1.
694 int tdb_fd(struct tdb_context *tdb);
697 * @brief Get the current logging function.
699 * This is useful for external tdb routines that wish to log tdb errors.
701 * @param[in] tdb The database to get the logging function from.
703 * @return The logging function of the database.
705 * @see tdb_get_logging_private()
707 tdb_log_func tdb_log_fn(struct tdb_context *tdb);
710 * @brief Get the private data of the logging function.
712 * @param[in] tdb The database to get the data from.
714 * @return The private data pointer of the logging function.
718 void *tdb_get_logging_private(struct tdb_context *tdb);
721 * @brief Is a transaction active?
723 * It is helpful for the application to know if a transaction is
724 * active, rather than needing to maintain an application-level reference
727 * @param[in] tdb The database to start the transaction.
729 * @return true if there is a transaction active, false otherwise
731 * @see tdb_transaction_start()
732 * @see tdb_transaction_prepare_commit()
733 * @see tdb_transaction_commit()
734 * @see tdb_transaction_cancel()
736 bool tdb_transaction_active(struct tdb_context *tdb);
739 * @brief Start a transaction.
741 * All operations after the transaction start can either be committed with
742 * tdb_transaction_commit() or cancelled with tdb_transaction_cancel().
744 * If (the default) TDB_ALLOW_NESTING was specified or
745 * TDB_DISALLOW_NESTING was not specified as a flag via tdb_open() or
746 * tdb_open_ex(), you call tdb_transaction_start() again on the same
747 * tdb context while a transaction is in progress, then the same
748 * transaction buffer is re-used. The number of
749 * tdb_transaction_{commit,cancel} operations must match the number of
750 * successful tdb_transaction_start() calls.
752 * Note that transactions are by default disk synchronous, and use a recover
753 * area in the database to automatically recover the database on the next open
754 * if the system crashes during a transaction. You can disable the synchronous
755 * transaction recovery setup using the TDB_NOSYNC flag, which will greatly
756 * speed up operations at the risk of corrupting your database if the system
759 * Operations made within a transaction are not visible to other users of the
760 * database until a successful commit.
762 * @param[in] tdb The database to start the transaction.
764 * @return 0 on success, -1 on error with error code set.
767 * @see tdb_errorstr()
769 int tdb_transaction_start(struct tdb_context *tdb);
772 * @brief Start a transaction, non-blocking.
774 * @param[in] tdb The database to start the transaction.
776 * @return 0 on success, -1 on error with error code set.
779 * @see tdb_errorstr()
780 * @see tdb_transaction_start()
782 int tdb_transaction_start_nonblock(struct tdb_context *tdb);
785 * @brief Prepare to commit a current transaction, for two-phase commits.
787 * Once prepared for commit, the only allowed calls are tdb_transaction_commit()
788 * or tdb_transaction_cancel(). Preparing allocates disk space for the pending
789 * updates, so a subsequent commit should succeed (barring any hardware
792 * @param[in] tdb The database to prepare the commit.
794 * @return 0 on success, -1 on error with error code set.
797 * @see tdb_errorstr()
799 int tdb_transaction_prepare_commit(struct tdb_context *tdb);
802 * @brief Commit a current transaction.
804 * This updates the database and releases the current transaction locks.
806 * @param[in] tdb The database to commit the transaction.
808 * @return 0 on success, -1 on error with error code set.
811 * @see tdb_errorstr()
813 int tdb_transaction_commit(struct tdb_context *tdb);
816 * @brief Cancel a current transaction.
818 * This discards all write and lock operations that have been made since the
819 * transaction started.
821 * @param[in] tdb The tdb to cancel the transaction on.
823 * @return 0 on success, -1 on error with error code set.
826 * @see tdb_errorstr()
828 int tdb_transaction_cancel(struct tdb_context *tdb);
831 * @brief Get the tdb sequence number.
833 * Only makes sense if the writers opened with TDB_SEQNUM set. Note that this
834 * sequence number will wrap quite quickly, so it should only be used for a
835 * 'has something changed' test, not for code that relies on the count of the
836 * number of changes made. If you want a counter then use a tdb record.
838 * The aim of this sequence number is to allow for a very lightweight test of a
839 * possible tdb change.
841 * @param[in] tdb The database to get the sequence number from.
843 * @return The sequence number or 0.
846 * @see tdb_enable_seqnum()
848 int tdb_get_seqnum(struct tdb_context *tdb);
851 * @brief Get the hash size.
853 * @param[in] tdb The database to get the hash size from.
855 * @return The hash size.
857 int tdb_hash_size(struct tdb_context *tdb);
860 * @brief Get the map size.
862 * @param[in] tdb The database to get the map size from.
864 * @return The map size.
866 size_t tdb_map_size(struct tdb_context *tdb);
869 * @brief Get the tdb flags set during open.
871 * @param[in] tdb The database to get the flags form.
873 * @return The flags set to on the database.
875 int tdb_get_flags(struct tdb_context *tdb);
878 * @brief Add flags to the database.
880 * @param[in] tdb The database to add the flags.
882 * @param[in] flag The tdb flags to add.
884 void tdb_add_flags(struct tdb_context *tdb, unsigned flag);
887 * @brief Remove flags from the database.
889 * @param[in] tdb The database to remove the flags.
891 * @param[in] flag The tdb flags to remove.
893 void tdb_remove_flags(struct tdb_context *tdb, unsigned flag);
896 * @brief Enable sequence number handling on an open tdb.
898 * @param[in] tdb The database to enable sequence number handling.
900 * @see tdb_get_seqnum()
902 void tdb_enable_seqnum(struct tdb_context *tdb);
905 * @brief Increment the tdb sequence number.
907 * This only works if the tdb has been opened using the TDB_SEQNUM flag or
908 * enabled using tdb_enable_seqnum().
910 * @param[in] tdb The database to increment the sequence number.
912 * @see tdb_enable_seqnum()
913 * @see tdb_get_seqnum()
915 void tdb_increment_seqnum_nonblock(struct tdb_context *tdb);
918 * @brief Create a hash of the key.
920 * @param[in] key The key to hash
924 unsigned int tdb_jenkins_hash(TDB_DATA *key);
927 * @brief Check the consistency of the database.
929 * This check the consistency of the database calling back the check function
930 * (if non-NULL) on each record. If some consistency check fails, or the
931 * supplied check function returns -1, tdb_check returns -1, otherwise 0.
933 * @note The logging function (if set) will be called with additional
934 * information on the corruption found.
936 * @param[in] tdb The database to check.
938 * @param[in] check The check function to use.
940 * @param[in] private_data the private data to pass to the check function.
942 * @return 0 on success, -1 on error with error code set.
945 * @see tdb_errorstr()
947 int tdb_check(struct tdb_context *tdb,
948 int (*check) (TDB_DATA key, TDB_DATA data, void *private_data),
952 * @brief Dump all possible records in a corrupt database.
954 * This is the only way to get data out of a database where tdb_check() fails.
955 * It will call walk() with anything which looks like a database record; this
956 * may well include invalid, incomplete or duplicate records.
958 * @param[in] tdb The database to check.
960 * @param[in] walk The walk function to use.
962 * @param[in] private_data the private data to pass to the walk function.
964 * @return 0 on success, -1 on error with error code set.
967 * @see tdb_errorstr()
969 int tdb_rescue(struct tdb_context *tdb,
970 void (*walk) (TDB_DATA key, TDB_DATA data, void *private_data),
974 * @brief Check if support for TDB_MUTEX_LOCKING is available at runtime.
976 * On some systems the API for pthread_mutexattr_setrobust() is not available.
977 * On other systems there are some bugs in the interaction between glibc and
980 * This function provides a runtime check if robust mutexes are really
983 * This needs to be called and return true before TDB_MUTEX_LOCKING
984 * can be used at runtime.
986 * @note This calls fork(), but the SIGCHILD handling should be transparent.
988 * @return true if supported, false otherwise.
990 * @see TDB_MUTEX_LOCKING
992 bool tdb_runtime_check_for_robust_mutexes(void);
994 /* @} ******************************************************************/
996 /* Low level locking functions: use with care */
997 int tdb_chainlock(struct tdb_context *tdb, TDB_DATA key);
998 int tdb_chainlock_nonblock(struct tdb_context *tdb, TDB_DATA key);
999 int tdb_chainunlock(struct tdb_context *tdb, TDB_DATA key);
1000 int tdb_chainlock_read(struct tdb_context *tdb, TDB_DATA key);
1001 int tdb_chainlock_read_nonblock(struct tdb_context *tdb, TDB_DATA key);
1002 int tdb_chainunlock_read(struct tdb_context *tdb, TDB_DATA key);
1003 int tdb_chainlock_mark(struct tdb_context *tdb, TDB_DATA key);
1004 int tdb_chainlock_unmark(struct tdb_context *tdb, TDB_DATA key);
1006 void tdb_setalarm_sigptr(struct tdb_context *tdb, volatile sig_atomic_t *sigptr);
1008 /* wipe and repack */
1009 int tdb_wipe_all(struct tdb_context *tdb);
1010 int tdb_repack(struct tdb_context *tdb);
1012 /* Debug functions. Not used in production. */
1013 void tdb_dump_all(struct tdb_context *tdb);
1014 int tdb_printfreelist(struct tdb_context *tdb);
1015 int tdb_validate_freelist(struct tdb_context *tdb, int *pnum_entries);
1016 int tdb_freelist_size(struct tdb_context *tdb);
1017 char *tdb_summary(struct tdb_context *tdb);
1019 extern TDB_DATA tdb_null;