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/>.
36 * @defgroup tdb The tdb API
38 * tdb is a Trivial database. In concept, it is very much like GDBM, and BSD's
39 * DB except that it allows multiple simultaneous writers and uses locking
40 * internally to keep writers from trampling on each other. tdb is also
43 * @section tdb_interface Interface
45 * The interface is very similar to gdbm except for the following:
48 * <li>different open interface. The tdb_open call is more similar to a
49 * traditional open()</li>
50 * <li>no tdbm_reorganise() function</li>
51 * <li>no tdbm_sync() function. No operations are cached in the library
53 * <li>added a tdb_traverse() function for traversing the whole database</li>
54 * <li>added transactions support</li>
57 * A general rule for using tdb is that the caller frees any returned TDB_DATA
58 * structures. Just call free(p.dptr) to free a TDB_DATA return value called p.
59 * This is the same as gdbm.
64 /** Flags to tdb_store() */
65 #define TDB_REPLACE 1 /** Unused */
66 #define TDB_INSERT 2 /** Don't overwrite an existing entry */
67 #define TDB_MODIFY 3 /** Don't create an existing entry */
69 /** Flags for tdb_open() */
70 #define TDB_DEFAULT 0 /** just a readability place holder */
71 #define TDB_CLEAR_IF_FIRST 1 /** If this is the first open, wipe the db */
72 #define TDB_INTERNAL 2 /** Don't store on disk */
73 #define TDB_NOLOCK 4 /** Don't do any locking */
74 #define TDB_NOMMAP 8 /** Don't use mmap */
75 #define TDB_CONVERT 16 /** Convert endian (internal use) */
76 #define TDB_BIGENDIAN 32 /** Header is big-endian (internal use) */
77 #define TDB_NOSYNC 64 /** Don't use synchronous transactions */
78 #define TDB_SEQNUM 128 /** Maintain a sequence number */
79 #define TDB_VOLATILE 256 /** Activate the per-hashchain freelist, default 5 */
80 #define TDB_ALLOW_NESTING 512 /** Allow transactions to nest */
81 #define TDB_DISALLOW_NESTING 1024 /** Disallow transactions to nest */
82 #define TDB_INCOMPATIBLE_HASH 2048 /** Better hashing: can't be opened by tdb < 1.2.6. */
84 /** The tdb error codes */
85 enum TDB_ERROR
{TDB_SUCCESS
=0, TDB_ERR_CORRUPT
, TDB_ERR_IO
, TDB_ERR_LOCK
,
86 TDB_ERR_OOM
, TDB_ERR_EXISTS
, TDB_ERR_NOLOCK
, TDB_ERR_LOCK_TIMEOUT
,
87 TDB_ERR_NOEXIST
, TDB_ERR_EINVAL
, TDB_ERR_RDONLY
,
90 /** Debugging uses one of the following levels */
91 enum tdb_debug_level
{TDB_DEBUG_FATAL
= 0, TDB_DEBUG_ERROR
,
92 TDB_DEBUG_WARNING
, TDB_DEBUG_TRACE
};
94 /** The tdb data structure */
95 typedef struct TDB_DATA
{
100 #ifndef PRINTF_ATTRIBUTE
102 /** Use gcc attribute to check printf fns. a1 is the 1-based index of
103 * the parameter containing the format, and a2 the index of the first
104 * argument. Note that some gcc 2.x versions don't handle this
106 #define PRINTF_ATTRIBUTE(a1, a2) __attribute__ ((format (__printf__, a1, a2)))
108 #define PRINTF_ATTRIBUTE(a1, a2)
112 /** This is the context structure that is returned from a db open. */
113 typedef struct tdb_context TDB_CONTEXT
;
115 typedef int (*tdb_traverse_func
)(struct tdb_context
*, TDB_DATA
, TDB_DATA
, void *);
116 typedef void (*tdb_log_func
)(struct tdb_context
*, enum tdb_debug_level
, const char *, ...) PRINTF_ATTRIBUTE(3, 4);
117 typedef unsigned int (*tdb_hash_func
)(TDB_DATA
*key
);
119 struct tdb_logging_context
{
125 * @brief Open the database and creating it if necessary.
127 * @param[in] name The name of the db to open.
129 * @param[in] hash_size The hash size is advisory, use zero for a default
132 * @param[in] tdb_flags The flags to use to open the db:\n\n
133 * TDB_CLEAR_IF_FIRST - Clear database if we are the
134 * only one with it open\n
135 * TDB_INTERNAL - Don't use a file, instaed store the
136 * data in memory. The filename is
137 * ignored in this case.\n
138 * TDB_NOLOCK - Don't do any locking\n
139 * TDB_NOMMAP - Don't use mmap\n
140 * TDB_NOSYNC - Don't synchronise transactions to disk\n
141 * TDB_SEQNUM - Maintain a sequence number\n
142 * TDB_VOLATILE - activate the per-hashchain freelist,
144 * TDB_ALLOW_NESTING - Allow transactions to nest.\n
145 * TDB_DISALLOW_NESTING - Disallow transactions to nest.\n
147 * @param[in] open_flags Flags for the open(2) function.
149 * @param[in] mode The mode for the open(2) function.
151 * @return A tdb context structure, NULL on error.
153 struct tdb_context
*tdb_open(const char *name
, int hash_size
, int tdb_flags
,
154 int open_flags
, mode_t mode
);
157 * @brief Open the database and creating it if necessary.
159 * This is like tdb_open(), but allows you to pass an initial logging and
160 * hash function. Be careful when passing a hash function - all users of the
161 * database must use the same hash function or you will get data corruption.
163 * @param[in] name The name of the db to open.
165 * @param[in] hash_size The hash size is advisory, use zero for a default
168 * @param[in] tdb_flags The flags to use to open the db:\n\n
169 * TDB_CLEAR_IF_FIRST - Clear database if we are the
170 * only one with it open\n
171 * TDB_INTERNAL - Don't use a file, instaed store the
172 * data in memory. The filename is
173 * ignored in this case.\n
174 * TDB_NOLOCK - Don't do any locking\n
175 * TDB_NOMMAP - Don't use mmap\n
176 * TDB_NOSYNC - Don't synchronise transactions to disk\n
177 * TDB_SEQNUM - Maintain a sequence number\n
178 * TDB_VOLATILE - activate the per-hashchain freelist,
180 * TDB_ALLOW_NESTING - Allow transactions to nest.\n
181 * TDB_DISALLOW_NESTING - Disallow transactions to nest.\n
183 * @param[in] open_flags Flags for the open(2) function.
185 * @param[in] mode The mode for the open(2) function.
187 * @param[in] log_ctx The logging function to use.
189 * @param[in] hash_fn The hash function you want to use.
191 * @return A tdb context structure, NULL on error.
195 struct tdb_context
*tdb_open_ex(const char *name
, int hash_size
, int tdb_flags
,
196 int open_flags
, mode_t mode
,
197 const struct tdb_logging_context
*log_ctx
,
198 tdb_hash_func hash_fn
);
201 * @brief Set the maximum number of dead records per hash chain.
203 * @param[in] tdb The database handle to set the maximum.
205 * @param[in] max_dead The maximum number of dead records per hash chain.
207 void tdb_set_max_dead(struct tdb_context
*tdb
, int max_dead
);
210 * @brief Reopen a tdb.
212 * This can be used after a fork to ensure that we have an independent seek
213 * pointer from our parent and to re-establish locks.
215 * @param[in] tdb The database to reopen.
217 * @return 0 on success, -1 on error.
219 int tdb_reopen(struct tdb_context
*tdb
);
222 * @brief Reopen all tdb's
224 * If the parent is longlived (ie. a parent daemon architecture), we know it
225 * will keep it's active lock on a tdb opened with CLEAR_IF_FIRST. Thus for
226 * child processes we don't have to add an active lock. This is essential to
227 * improve performance on systems that keep POSIX locks as a non-scalable data
228 * structure in the kernel.
230 * @param[in] parent_longlived Wether the parent is longlived or not.
232 * @return 0 on success, -1 on error.
234 int tdb_reopen_all(int parent_longlived
);
237 * @brief Set a different tdb logging function.
239 * @param[in] tdb The tdb to set the logging function.
241 * @param[in] log_ctx The logging function to set.
243 void tdb_set_logging_function(struct tdb_context
*tdb
, const struct tdb_logging_context
*log_ctx
);
246 * @brief Get the tdb last error code.
248 * @param[in] tdb The tdb to get the error code from.
250 * @return A TDB_ERROR code.
254 enum TDB_ERROR
tdb_error(struct tdb_context
*tdb
);
257 * @brief Get a error string for the last tdb error
259 * @param[in] tdb The tdb to get the error code from.
261 * @return An error string.
263 const char *tdb_errorstr(struct tdb_context
*tdb
);
266 * @brief Fetch an entry in the database given a key.
268 * The caller must free the resulting data.
270 * @param[in] tdb The tdb to fetch the key.
272 * @param[in] key The key to fetch.
274 * @return The key entry found in the database, NULL on error with
278 * @see tdb_errorstr()
280 TDB_DATA
tdb_fetch(struct tdb_context
*tdb
, TDB_DATA key
);
283 * @brief Hand a record to a parser function without allocating it.
285 * This function is meant as a fast tdb_fetch alternative for large records
286 * that are frequently read. The "key" and "data" arguments point directly
287 * into the tdb shared memory, they are not aligned at any boundary.
289 * @warning The parser is called while tdb holds a lock on the record. DO NOT
290 * call other tdb routines from within the parser. Also, for good performance
291 * you should make the parser fast to allow parallel operations.
293 * @param[in] tdb The tdb to parse the record.
295 * @param[in] key The key to parse.
297 * @param[in] parser The parser to use to parse the data.
299 * @param[in] private_data A private data pointer which is passed to the parser
302 * @return -1 if the record was not found. If the record was found,
303 * the return value of "parser" is passed up to the caller.
305 int tdb_parse_record(struct tdb_context
*tdb
, TDB_DATA key
,
306 int (*parser
)(TDB_DATA key
, TDB_DATA data
,
311 * @brief Delete an entry in the database given a key.
313 * @param[in] tdb The tdb to delete the key.
315 * @param[in] key The key to delete.
317 * @return 0 on success, -1 if the key doesn't exist.
319 int tdb_delete(struct tdb_context
*tdb
, TDB_DATA key
);
322 * @brief Store an element in the database.
324 * This replaces any existing element with the same key.
326 * @param[in] tdb The tdb to store the entry.
328 * @param[in] key The key to use to store the entry.
330 * @param[in] dbuf The data to store under the key.
332 * @param[in] flag The flags to store the key:\n\n
333 * TDB_INSERT: Don't overwrite an existing entry.\n
334 * TDB_MODIFY: Don't create a new entry\n
336 * @return 0 on success, -1 on error with error code set.
339 * @see tdb_errorstr()
341 int tdb_store(struct tdb_context
*tdb
, TDB_DATA key
, TDB_DATA dbuf
, int flag
);
344 * @brief Append data to an entry.
346 * If the entry doesn't exist, it will create a new one.
348 * @param[in] tdb The database to use.
350 * @param[in] key The key to append the data.
352 * @param[in] new_dbuf The data to append to the key.
354 * @return 0 on success, -1 on error with error code set.
357 * @see tdb_errorstr()
359 int tdb_append(struct tdb_context
*tdb
, TDB_DATA key
, TDB_DATA new_dbuf
);
362 * @brief Close a database.
364 * @param[in] tdb The database to close.
366 * @return 0 for success, -1 on error.
368 int tdb_close(struct tdb_context
*tdb
);
371 * @brief Find the first entry in the database and return its key.
373 * The caller must free the returned data.
375 * @param[in] tdb The database to use.
377 * @return The first entry of the database, an empty TDB_DATA entry
378 * if the database is empty.
380 TDB_DATA
tdb_firstkey(struct tdb_context
*tdb
);
383 * @brief Find the next entry in the database, returning its key.
385 * The caller must free the returned data.
387 * @param[in] tdb The database to use.
389 * @param[in] key The key from which you want the next key.
391 * @return The next entry of the current key, an empty TDB_DATA
392 * entry if there is no entry.
394 TDB_DATA
tdb_nextkey(struct tdb_context
*tdb
, TDB_DATA key
);
397 * @brief Traverse the entire database.
399 * While travering the function fn(tdb, key, data, state) is called on each
400 * element. If fn is NULL then it is not called. A non-zero return value from
401 * fn() indicates that the traversal should stop. Traversal callbacks may not
402 * start transactions.
404 * @warning The data buffer given to the callback fn does NOT meet the alignment
405 * restrictions malloc gives you.
407 * @param[in] tdb The database to traverse.
409 * @param[in] fn The function to call on each entry.
411 * @param[in] private_data The private data which should be passed to the
412 * traversing function.
414 * @return The record count traversed, -1 on error.
416 int tdb_traverse(struct tdb_context
*tdb
, tdb_traverse_func fn
, void *private_data
);
419 * @brief Traverse the entire database.
421 * While traversing the database the function fn(tdb, key, data, state) is
422 * called on each element, but marking the database read only during the
423 * traversal, so any write operations will fail. This allows tdb to use read
424 * locks, which increases the parallelism possible during the traversal.
426 * @param[in] tdb The database to traverse.
428 * @param[in] fn The function to call on each entry.
430 * @param[in] private_data The private data which should be passed to the
431 * traversing function.
433 * @return The record count traversed, -1 on error.
435 int tdb_traverse_read(struct tdb_context
*tdb
, tdb_traverse_func fn
, void *private_data
);
438 * @brief Check if an entry in the database exists.
440 * @note 1 is returned if the key is found and 0 is returned if not found this
441 * doesn't match the conventions in the rest of this module, but is compatible
444 * @param[in] tdb The database to check if the entry exists.
446 * @param[in] key The key to check if the entry exists.
448 * @return 1 if the key is found, 0 if not.
450 int tdb_exists(struct tdb_context
*tdb
, TDB_DATA key
);
453 * @brief Lock entire database with a write lock.
455 * @param[in] tdb The database to lock.
457 * @return 0 on success, -1 on error with error code set.
460 * @see tdb_errorstr()
462 int tdb_lockall(struct tdb_context
*tdb
);
465 * @brief Lock entire database with a write lock.
467 * This is the non-blocking call.
469 * @param[in] tdb The database to lock.
471 * @return 0 on success, -1 on error with error code set.
475 * @see tdb_errorstr()
477 int tdb_lockall_nonblock(struct tdb_context
*tdb
);
480 * @brief Unlock entire database with write lock.
482 * @param[in] tdb The database to unlock.
484 * @return 0 on success, -1 on error with error code set.
488 * @see tdb_errorstr()
490 int tdb_unlockall(struct tdb_context
*tdb
);
493 * @brief Lock entire database with a read lock.
495 * @param[in] tdb The database to lock.
497 * @return 0 on success, -1 on error with error code set.
500 * @see tdb_errorstr()
502 int tdb_lockall_read(struct tdb_context
*tdb
);
505 * @brief Lock entire database with a read lock.
507 * This is the non-blocking call.
509 * @param[in] tdb The database to lock.
511 * @return 0 on success, -1 on error with error code set.
513 * @see tdb_lockall_read()
515 * @see tdb_errorstr()
517 int tdb_lockall_read_nonblock(struct tdb_context
*tdb
);
520 * @brief Unlock entire database with read lock.
522 * @param[in] tdb The database to unlock.
524 * @return 0 on success, -1 on error with error code set.
526 * @see tdb_lockall_read()
528 * @see tdb_errorstr()
530 int tdb_unlockall_read(struct tdb_context
*tdb
);
533 * @brief Lock entire database with write lock - mark only.
535 * @todo Add more details.
537 * @param[in] tdb The database to mark.
539 * @return 0 on success, -1 on error with error code set.
542 * @see tdb_errorstr()
544 int tdb_lockall_mark(struct tdb_context
*tdb
);
547 * @brief Lock entire database with write lock - unmark only.
549 * @todo Add more details.
551 * @param[in] tdb The database to mark.
553 * @return 0 on success, -1 on error with error code set.
556 * @see tdb_errorstr()
558 int tdb_lockall_unmark(struct tdb_context
*tdb
);
561 * @brief Get the name of the current tdb file.
563 * This is useful for external logging functions.
565 * @param[in] tdb The database to get the name from.
567 * @return The name of the database.
569 const char *tdb_name(struct tdb_context
*tdb
);
572 * @brief Get the underlying file descriptor being used by tdb.
574 * This is useful for external routines that want to check the device/inode
577 * @param[in] tdb The database to get the fd from.
579 * @return The file descriptor or -1.
581 int tdb_fd(struct tdb_context
*tdb
);
584 * @brief Get the current logging function.
586 * This is useful for external tdb routines that wish to log tdb errors.
588 * @param[in] tdb The database to get the logging function from.
590 * @return The logging function of the database.
592 * @see tdb_get_logging_private()
594 tdb_log_func
tdb_log_fn(struct tdb_context
*tdb
);
597 * @brief Get the private data of the logging function.
599 * @param[in] tdb The database to get the data from.
601 * @return The private data pointer of the logging function.
605 void *tdb_get_logging_private(struct tdb_context
*tdb
);
608 * @brief Start a transaction.
610 * All operations after the transaction start can either be committed with
611 * tdb_transaction_commit() or cancelled with tdb_transaction_cancel().
613 * If you call tdb_transaction_start() again on the same tdb context while a
614 * transaction is in progress, then the same transaction buffer is re-used. The
615 * number of tdb_transaction_{commit,cancel} operations must match the number
616 * of successful tdb_transaction_start() calls.
618 * Note that transactions are by default disk synchronous, and use a recover
619 * area in the database to automatically recover the database on the next open
620 * if the system crashes during a transaction. You can disable the synchronous
621 * transaction recovery setup using the TDB_NOSYNC flag, which will greatly
622 * speed up operations at the risk of corrupting your database if the system
625 * Operations made within a transaction are not visible to other users of the
626 * database until a successful commit.
628 * @param[in] tdb The database to start the transaction.
630 * @return 0 on success, -1 on error with error code set.
633 * @see tdb_errorstr()
635 int tdb_transaction_start(struct tdb_context
*tdb
);
638 * @brief Start a transaction, non-blocking.
640 * @param[in] tdb The database to start the transaction.
642 * @return 0 on success, -1 on error with error code set.
645 * @see tdb_errorstr()
646 * @see tdb_transaction_start()
648 int tdb_transaction_start_nonblock(struct tdb_context
*tdb
);
651 * @brief Prepare to commit a current transaction, for two-phase commits.
653 * Once prepared for commit, the only allowed calls are tdb_transaction_commit()
654 * or tdb_transaction_cancel(). Preparing allocates disk space for the pending
655 * updates, so a subsequent commit should succeed (barring any hardware
658 * @param[in] tdb The database to prepare the commit.
660 * @return 0 on success, -1 on error with error code set.
663 * @see tdb_errorstr()
665 int tdb_transaction_prepare_commit(struct tdb_context
*tdb
);
668 * @brief Commit a current transaction.
670 * This updates the database and releases the current transaction locks.
672 * @param[in] tdb The database to commit the transaction.
674 * @return 0 on success, -1 on error with error code set.
677 * @see tdb_errorstr()
679 int tdb_transaction_commit(struct tdb_context
*tdb
);
682 * @brief Cancel a current transaction.
684 * This discards all write and lock operations that have been made since the
685 * transaction started.
687 * @param[in] tdb The tdb to cancel the transaction on.
689 * @return 0 on success, -1 on error with error code set.
692 * @see tdb_errorstr()
694 int tdb_transaction_cancel(struct tdb_context
*tdb
);
697 * @brief Get the tdb sequence number.
699 * Only makes sense if the writers opened with TDB_SEQNUM set. Note that this
700 * sequence number will wrap quite quickly, so it should only be used for a
701 * 'has something changed' test, not for code that relies on the count of the
702 * number of changes made. If you want a counter then use a tdb record.
704 * The aim of this sequence number is to allow for a very lightweight test of a
705 * possible tdb change.
707 * @param[in] tdb The database to get the sequence number from.
709 * @return The sequence number or 0.
712 * @see tdb_enable_seqnum()
714 int tdb_get_seqnum(struct tdb_context
*tdb
);
717 * @brief Get the hash size.
719 * @param[in] tdb The database to get the hash size from.
721 * @return The hash size.
723 int tdb_hash_size(struct tdb_context
*tdb
);
726 * @brief Get the map size.
728 * @param[in] tdb The database to get the map size from.
730 * @return The map size.
732 size_t tdb_map_size(struct tdb_context
*tdb
);
735 * @brief Get the tdb flags set during open.
737 * @param[in] tdb The database to get the flags form.
739 * @return The flags set to on the database.
741 int tdb_get_flags(struct tdb_context
*tdb
);
744 * @brief Add flags to the database.
746 * @param[in] tdb The database to add the flags.
748 * @param[in] flag The tdb flags to add.
750 void tdb_add_flags(struct tdb_context
*tdb
, unsigned flag
);
753 * @brief Remove flags from the database.
755 * @param[in] tdb The database to remove the flags.
757 * @param[in] flag The tdb flags to remove.
759 void tdb_remove_flags(struct tdb_context
*tdb
, unsigned flag
);
762 * @brief Enable sequence number handling on an open tdb.
764 * @param[in] tdb The database to enable sequence number handling.
766 * @see tdb_get_seqnum()
768 void tdb_enable_seqnum(struct tdb_context
*tdb
);
771 * @brief Increment the tdb sequence number.
773 * This only works if the tdb has been opened using the TDB_SEQNUM flag or
774 * enabled useing tdb_enable_seqnum().
776 * @param[in] tdb The database to increment the sequence number.
778 * @see tdb_enable_seqnum()
779 * @see tdb_get_seqnum()
781 void tdb_increment_seqnum_nonblock(struct tdb_context
*tdb
);
784 * @brief Create a hash of the key.
786 * @param[in] key The key to hash
790 unsigned int tdb_jenkins_hash(TDB_DATA
*key
);
793 * @brief Check the consistency of the database.
795 * This check the consistency of the database calling back the check function
796 * (if non-NULL) on each record. If some consistency check fails, or the
797 * supplied check function returns -1, tdb_check returns -1, otherwise 0.
799 * @note The logging function (if set) will be called with additional
800 * information on the corruption found.
802 * @param[in] tdb The database to check.
804 * @param[in] check The check function to use.
806 * @param[in] private_data the private data to pass to the check function.
808 * @return 0 on success, -1 on error with error code set.
811 * @see tdb_errorstr()
813 int tdb_check(struct tdb_context
*tdb
,
814 int (*check
) (TDB_DATA key
, TDB_DATA data
, void *private_data
),
817 /* @} ******************************************************************/
819 /* Low level locking functions: use with care */
820 int tdb_chainlock(struct tdb_context
*tdb
, TDB_DATA key
);
821 int tdb_chainlock_nonblock(struct tdb_context
*tdb
, TDB_DATA key
);
822 int tdb_chainunlock(struct tdb_context
*tdb
, TDB_DATA key
);
823 int tdb_chainlock_read(struct tdb_context
*tdb
, TDB_DATA key
);
824 int tdb_chainunlock_read(struct tdb_context
*tdb
, TDB_DATA key
);
825 int tdb_chainlock_mark(struct tdb_context
*tdb
, TDB_DATA key
);
826 int tdb_chainlock_unmark(struct tdb_context
*tdb
, TDB_DATA key
);
828 void tdb_setalarm_sigptr(struct tdb_context
*tdb
, volatile sig_atomic_t *sigptr
);
830 /* wipe and repack */
831 int tdb_wipe_all(struct tdb_context
*tdb
);
832 int tdb_repack(struct tdb_context
*tdb
);
834 /* Debug functions. Not used in production. */
835 void tdb_dump_all(struct tdb_context
*tdb
);
836 int tdb_printfreelist(struct tdb_context
*tdb
);
837 int tdb_validate_freelist(struct tdb_context
*tdb
, int *pnum_entries
);
838 int tdb_freelist_size(struct tdb_context
*tdb
);
839 char *tdb_summary(struct tdb_context
*tdb
);
841 extern TDB_DATA tdb_null
;