tdb: test for readonly locks mode on tdbbackup command
[samba.git] / lib / tdb / include / tdb.h
1 #ifndef __TDB_H__
2 #define __TDB_H__
3
4 /* 
5    Unix SMB/CIFS implementation.
6
7    trivial database library
8
9    Copyright (C) Andrew Tridgell 1999-2004
10    
11      ** NOTE! The following LGPL license applies to the tdb
12      ** library. This does NOT imply that all of Samba is released
13      ** under the LGPL
14    
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.
19
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.
24
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/>.
27 */
28
29 #ifdef  __cplusplus
30 extern "C" {
31 #endif
32
33 #include <signal.h>
34 #include <stdbool.h>
35
36 /**
37  * @defgroup tdb The tdb API
38  *
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
42  * extremely small.
43  *
44  * @section tdb_interface Interface
45  *
46  * The interface is very similar to gdbm except for the following:
47  *
48  * <ul>
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
53  *     anyway</li>
54  * <li>added a tdb_traverse() function for traversing the whole database</li>
55  * <li>added transactions support</li>
56  * </ul>
57  *
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.
61  *
62  * @{
63  */
64
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    */
69
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() */
87
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,
92                 TDB_ERR_NESTING};
93
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};
97
98 /** The tdb data structure */
99 typedef struct TDB_DATA {
100         unsigned char *dptr;
101         size_t dsize;
102 } TDB_DATA;
103
104 #ifndef PRINTF_ATTRIBUTE
105 #if (__GNUC__ >= 3)
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
109  * properly **/
110 #define PRINTF_ATTRIBUTE(a1, a2) __attribute__ ((format (__printf__, a1, a2)))
111 #else
112 #define PRINTF_ATTRIBUTE(a1, a2)
113 #endif
114 #endif
115
116 /** This is the context structure that is returned from a db open. */
117 typedef struct tdb_context TDB_CONTEXT;
118
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);
122
123 struct tdb_logging_context {
124         tdb_log_func log_fn;
125         void *log_private;
126 };
127
128 /**
129  * @brief Open the database and creating it if necessary.
130  *
131  * @param[in]  name     The name of the db to open.
132  *
133  * @param[in]  hash_size The hash size is advisory, use zero for a default
134  *                       value.
135  *
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,
147  *                                        default 5.\n
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
155  *
156  * @param[in]  open_flags Flags for the open(2) function.
157  *
158  * @param[in]  mode     The mode for the open(2) function.
159  *
160  * @return              A tdb context structure, NULL on error.
161  */
162 struct tdb_context *tdb_open(const char *name, int hash_size, int tdb_flags,
163                       int open_flags, mode_t mode);
164
165 /**
166  * @brief Open the database and creating it if necessary.
167  *
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.
171  *
172  * @param[in]  name     The name of the db to open.
173  *
174  * @param[in]  hash_size The hash size is advisory, use zero for a default
175  *                       value.
176  *
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,
188  *                                        default 5.\n
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
196  *
197  * @param[in]  open_flags Flags for the open(2) function.
198  *
199  * @param[in]  mode     The mode for the open(2) function.
200  *
201  * @param[in]  log_ctx  The logging function to use.
202  *
203  * @param[in]  hash_fn  The hash function you want to use.
204  *
205  * @return              A tdb context structure, NULL on error.
206  *
207  * @see tdb_open()
208  */
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);
213
214 /**
215  * @brief Set the maximum number of dead records per hash chain.
216  *
217  * @param[in]  tdb      The database handle to set the maximum.
218  *
219  * @param[in]  max_dead The maximum number of dead records per hash chain.
220  */
221 void tdb_set_max_dead(struct tdb_context *tdb, int max_dead);
222
223 /**
224  * @brief Reopen a tdb.
225  *
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.
228  *
229  * @param[in]  tdb      The database to reopen. It will be free'd on error!
230  *
231  * @return              0 on success, -1 on error.
232  *
233  * @note Don't call tdb_error() after this function cause the tdb context will
234  *       be freed on error.
235  */
236 int tdb_reopen(struct tdb_context *tdb);
237
238 /**
239  * @brief Reopen all tdb's
240  *
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.
246  *
247  * @param[in]  parent_longlived Wether the parent is longlived or not.
248  *
249  * @return              0 on success, -1 on error.
250  */
251 int tdb_reopen_all(int parent_longlived);
252
253 /**
254  * @brief Set a different tdb logging function.
255  *
256  * @param[in]  tdb      The tdb to set the logging function.
257  *
258  * @param[in]  log_ctx  The logging function to set.
259  */
260 void tdb_set_logging_function(struct tdb_context *tdb, const struct tdb_logging_context *log_ctx);
261
262 /**
263  * @brief Get the tdb last error code.
264  *
265  * @param[in]  tdb      The tdb to get the error code from.
266  *
267  * @return              A TDB_ERROR code.
268  *
269  * @see TDB_ERROR
270  */
271 enum TDB_ERROR tdb_error(struct tdb_context *tdb);
272
273 /**
274  * @brief Get a error string for the last tdb error
275  *
276  * @param[in]  tdb      The tdb to get the error code from.
277  *
278  * @return              An error string.
279  */
280 const char *tdb_errorstr(struct tdb_context *tdb);
281
282 /**
283  * @brief Fetch an entry in the database given a key.
284  *
285  * The caller must free the resulting data.
286  *
287  * @param[in]  tdb      The tdb to fetch the key.
288  *
289  * @param[in]  key      The key to fetch.
290  *
291  * @return              The key entry found in the database, NULL on error with
292  *                      TDB_ERROR set.
293  *
294  * @see tdb_error()
295  * @see tdb_errorstr()
296  */
297 TDB_DATA tdb_fetch(struct tdb_context *tdb, TDB_DATA key);
298
299 /**
300  * @brief Hand a record to a parser function without allocating it.
301  *
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.
305  *
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.
309  *
310  * @param[in]  tdb      The tdb to parse the record.
311  *
312  * @param[in]  key      The key to parse.
313  *
314  * @param[in]  parser   The parser to use to parse the data.
315  *
316  * @param[in]  private_data A private data pointer which is passed to the parser
317  *                          function.
318  *
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.
321  */
322 int tdb_parse_record(struct tdb_context *tdb, TDB_DATA key,
323                               int (*parser)(TDB_DATA key, TDB_DATA data,
324                                             void *private_data),
325                               void *private_data);
326
327 /**
328  * @brief Delete an entry in the database given a key.
329  *
330  * @param[in]  tdb      The tdb to delete the key.
331  *
332  * @param[in]  key      The key to delete.
333  *
334  * @return              0 on success, -1 if the key doesn't exist.
335  */
336 int tdb_delete(struct tdb_context *tdb, TDB_DATA key);
337
338 /**
339  * @brief Store an element in the database.
340  *
341  * This replaces any existing element with the same key.
342  *
343  * @param[in]  tdb      The tdb to store the entry.
344  *
345  * @param[in]  key      The key to use to store the entry.
346  *
347  * @param[in]  dbuf     The data to store under the key.
348  *
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
352  *
353  * @return              0 on success, -1 on error with error code set.
354  *
355  * @see tdb_error()
356  * @see tdb_errorstr()
357  */
358 int tdb_store(struct tdb_context *tdb, TDB_DATA key, TDB_DATA dbuf, int flag);
359
360
361 /**
362  * @brief Store an element in the database.
363  *
364  * This replaces any existing element with the same key.
365  *
366  * @param[in]  tdb      The tdb to store the entry.
367  *
368  * @param[in]  key      The key to use to store the entry.
369  *
370  * @param[in]  dbufs    A vector of memory chunks to write
371  *
372  * @param[in]  num_dbufs Length of the dbufs vector
373  *
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
377  *
378  * @return              0 on success, -1 on error with error code set.
379  *
380  * @see tdb_error()
381  * @see tdb_errorstr()
382  */
383 int tdb_storev(struct tdb_context *tdb, TDB_DATA key,
384                const TDB_DATA *dbufs, int num_dbufs, int flag);
385
386 /**
387  * @brief Append data to an entry.
388  *
389  * If the entry doesn't exist, it will create a new one.
390  *
391  * @param[in]  tdb      The database to use.
392  *
393  * @param[in]  key      The key to append the data.
394  *
395  * @param[in]  new_dbuf The data to append to the key.
396  *
397  * @return              0 on success, -1 on error with error code set.
398  *
399  * @see tdb_error()
400  * @see tdb_errorstr()
401  */
402 int tdb_append(struct tdb_context *tdb, TDB_DATA key, TDB_DATA new_dbuf);
403
404 /**
405  * @brief Close a database.
406  *
407  * @param[in]  tdb      The database to close. The context will be free'd.
408  *
409  * @return              0 for success, -1 on error.
410  *
411  * @note Don't call tdb_error() after this function cause the tdb context will
412  *       be freed on error.
413  */
414 int tdb_close(struct tdb_context *tdb);
415
416 /**
417  * @brief Find the first entry in the database and return its key.
418  *
419  * The caller must free the returned data.
420  *
421  * @param[in]  tdb      The database to use.
422  *
423  * @return              The first entry of the database, an empty TDB_DATA entry
424  *                      if the database is empty.
425  */
426 TDB_DATA tdb_firstkey(struct tdb_context *tdb);
427
428 /**
429  * @brief Find the next entry in the database, returning its key.
430  *
431  * The caller must free the returned data.
432  *
433  * @param[in]  tdb      The database to use.
434  *
435  * @param[in]  key      The key from which you want the next key.
436  *
437  * @return              The next entry of the current key, an empty TDB_DATA
438  *                      entry if there is no entry.
439  */
440 TDB_DATA tdb_nextkey(struct tdb_context *tdb, TDB_DATA key);
441
442 /**
443  * @brief Traverse the entire database.
444  *
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.
449  *
450  * @warning The data buffer given to the callback fn does NOT meet the alignment
451  * restrictions malloc gives you.
452  *
453  * @param[in]  tdb      The database to traverse.
454  *
455  * @param[in]  fn       The function to call on each entry.
456  *
457  * @param[in]  private_data The private data which should be passed to the
458  *                          traversing function.
459  *
460  * @return              The record count traversed, -1 on error.
461  */
462 int tdb_traverse(struct tdb_context *tdb, tdb_traverse_func fn, void *private_data);
463
464 /**
465  * @brief Traverse the entire database.
466  *
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.
471  *
472  * @param[in]  tdb      The database to traverse.
473  *
474  * @param[in]  fn       The function to call on each entry.
475  *
476  * @param[in]  private_data The private data which should be passed to the
477  *                          traversing function.
478  *
479  * @return              The record count traversed, -1 on error.
480  */
481 int tdb_traverse_read(struct tdb_context *tdb, tdb_traverse_func fn, void *private_data);
482
483 /**
484  * @brief Check if an entry in the database exists.
485  *
486  * @note 1 is returned if the key is found and 0 is returned if not found this
487  * doesn't match the conventions in the rest of this module, but is compatible
488  * with gdbm.
489  *
490  * @param[in]  tdb      The database to check if the entry exists.
491  *
492  * @param[in]  key      The key to check if the entry exists.
493  *
494  * @return              1 if the key is found, 0 if not.
495  */
496 int tdb_exists(struct tdb_context *tdb, TDB_DATA key);
497
498 /**
499  * @brief Lock entire database with a write lock.
500  *
501  * @param[in]  tdb      The database to lock.
502  *
503  * @return              0 on success, -1 on error with error code set.
504  *
505  * @see tdb_error()
506  * @see tdb_errorstr()
507  */
508 int tdb_lockall(struct tdb_context *tdb);
509
510 /**
511  * @brief Lock entire database with a write lock.
512  *
513  * This is the non-blocking call.
514  *
515  * @param[in]  tdb      The database to lock.
516  *
517  * @return              0 on success, -1 on error with error code set.
518  *
519  * @see tdb_lockall()
520  * @see tdb_error()
521  * @see tdb_errorstr()
522  */
523 int tdb_lockall_nonblock(struct tdb_context *tdb);
524
525 /**
526  * @brief Unlock entire database with write lock.
527  *
528  * @param[in]  tdb      The database to unlock.
529  *
530  * @return              0 on success, -1 on error with error code set.
531  *
532  * @see tdb_lockall()
533  * @see tdb_error()
534  * @see tdb_errorstr()
535  */
536 int tdb_unlockall(struct tdb_context *tdb);
537
538 /**
539  * @brief Lock entire database with a read lock.
540  *
541  * @param[in]  tdb      The database to lock.
542  *
543  * @return              0 on success, -1 on error with error code set.
544  *
545  * @see tdb_error()
546  * @see tdb_errorstr()
547  */
548 int tdb_lockall_read(struct tdb_context *tdb);
549
550 /**
551  * @brief Lock entire database with a read lock.
552  *
553  * This is the non-blocking call.
554  *
555  * @param[in]  tdb      The database to lock.
556  *
557  * @return              0 on success, -1 on error with error code set.
558  *
559  * @see tdb_lockall_read()
560  * @see tdb_error()
561  * @see tdb_errorstr()
562  */
563 int tdb_lockall_read_nonblock(struct tdb_context *tdb);
564
565 /**
566  * @brief Unlock entire database with read lock.
567  *
568  * @param[in]  tdb      The database to unlock.
569  *
570  * @return              0 on success, -1 on error with error code set.
571  *
572  * @see tdb_lockall_read()
573  * @see tdb_error()
574  * @see tdb_errorstr()
575  */
576 int tdb_unlockall_read(struct tdb_context *tdb);
577
578 /**
579  * @brief Lock entire database with write lock - mark only.
580  *
581  * @todo Add more details.
582  *
583  * @param[in]  tdb      The database to mark.
584  *
585  * @return              0 on success, -1 on error with error code set.
586  *
587  * @see tdb_error()
588  * @see tdb_errorstr()
589  */
590 int tdb_lockall_mark(struct tdb_context *tdb);
591
592 /**
593  * @brief Lock entire database with write lock - unmark only.
594  *
595  * @todo Add more details.
596  *
597  * @param[in]  tdb      The database to mark.
598  *
599  * @return              0 on success, -1 on error with error code set.
600  *
601  * @see tdb_error()
602  * @see tdb_errorstr()
603  */
604 int tdb_lockall_unmark(struct tdb_context *tdb);
605
606 /**
607  * @brief Get the name of the current tdb file.
608  *
609  * This is useful for external logging functions.
610  *
611  * @param[in]  tdb      The database to get the name from.
612  *
613  * @return              The name of the database.
614  */
615 const char *tdb_name(struct tdb_context *tdb);
616
617 /**
618  * @brief Get the underlying file descriptor being used by tdb.
619  *
620  * This is useful for external routines that want to check the device/inode
621  * of the fd.
622  *
623  * @param[in]  tdb      The database to get the fd from.
624  *
625  * @return              The file descriptor or -1.
626  */
627 int tdb_fd(struct tdb_context *tdb);
628
629 /**
630  * @brief Get the current logging function.
631  *
632  * This is useful for external tdb routines that wish to log tdb errors.
633  *
634  * @param[in]  tdb      The database to get the logging function from.
635  *
636  * @return              The logging function of the database.
637  *
638  * @see tdb_get_logging_private()
639  */
640 tdb_log_func tdb_log_fn(struct tdb_context *tdb);
641
642 /**
643  * @brief Get the private data of the logging function.
644  *
645  * @param[in]  tdb      The database to get the data from.
646  *
647  * @return              The private data pointer of the logging function.
648  *
649  * @see tdb_log_fn()
650  */
651 void *tdb_get_logging_private(struct tdb_context *tdb);
652
653 /**
654  * @brief Is a transaction active?
655  *
656  * It is helpful for the application to know if a transaction is
657  * active, rather than needing to maintain an application-level reference
658  * count.
659  *
660  * @param[in]  tdb      The database to start the transaction.
661  *
662  * @return              true if there is a transaction active, false otherwise
663  *
664  * @see tdb_transaction_start()
665  * @see tdb_transaction_prepare_commit()
666  * @see tdb_transaction_commit()
667  * @see tdb_transaction_cancel()
668  */
669 bool tdb_transaction_active(struct tdb_context *tdb);
670
671 /**
672  * @brief Start a transaction.
673  *
674  * All operations after the transaction start can either be committed with
675  * tdb_transaction_commit() or cancelled with tdb_transaction_cancel().
676  *
677  * If (the default) TDB_ALLOW_NESTING was specified or
678  * TDB_DISALLOW_NESTING was not specified as a flag via tdb_open() or
679  * tdb_open_ex(), you call tdb_transaction_start() again on the same
680  * tdb context while a transaction is in progress, then the same
681  * transaction buffer is re-used. The number of
682  * tdb_transaction_{commit,cancel} operations must match the number of
683  * successful tdb_transaction_start() calls.
684  *
685  * Note that transactions are by default disk synchronous, and use a recover
686  * area in the database to automatically recover the database on the next open
687  * if the system crashes during a transaction. You can disable the synchronous
688  * transaction recovery setup using the TDB_NOSYNC flag, which will greatly
689  * speed up operations at the risk of corrupting your database if the system
690  * crashes.
691  *
692  * Operations made within a transaction are not visible to other users of the
693  * database until a successful commit.
694  *
695  * @param[in]  tdb      The database to start the transaction.
696  *
697  * @return              0 on success, -1 on error with error code set.
698  *
699  * @see tdb_error()
700  * @see tdb_errorstr()
701  */
702 int tdb_transaction_start(struct tdb_context *tdb);
703
704 /**
705  * @brief Start a transaction, non-blocking.
706  *
707  * @param[in]  tdb      The database to start the transaction.
708  *
709  * @return              0 on success, -1 on error with error code set.
710  *
711  * @see tdb_error()
712  * @see tdb_errorstr()
713  * @see tdb_transaction_start()
714  */
715 int tdb_transaction_start_nonblock(struct tdb_context *tdb);
716
717 /**
718  * @brief Prepare to commit a current transaction, for two-phase commits.
719  *
720  * Once prepared for commit, the only allowed calls are tdb_transaction_commit()
721  * or tdb_transaction_cancel(). Preparing allocates disk space for the pending
722  * updates, so a subsequent commit should succeed (barring any hardware
723  * failures).
724  *
725  * @param[in]  tdb      The database to prepare the commit.
726  *
727  * @return              0 on success, -1 on error with error code set.
728  *
729  * @see tdb_error()
730  * @see tdb_errorstr()
731  */
732 int tdb_transaction_prepare_commit(struct tdb_context *tdb);
733
734 /**
735  * @brief Commit a current transaction.
736  *
737  * This updates the database and releases the current transaction locks.
738  *
739  * @param[in]  tdb      The database to commit the transaction.
740  *
741  * @return              0 on success, -1 on error with error code set.
742  *
743  * @see tdb_error()
744  * @see tdb_errorstr()
745  */
746 int tdb_transaction_commit(struct tdb_context *tdb);
747
748 /**
749  * @brief Cancel a current transaction.
750  *
751  * This discards all write and lock operations that have been made since the
752  * transaction started.
753  *
754  * @param[in]  tdb      The tdb to cancel the transaction on.
755  *
756  * @return              0 on success, -1 on error with error code set.
757  *
758  * @see tdb_error()
759  * @see tdb_errorstr()
760  */
761 int tdb_transaction_cancel(struct tdb_context *tdb);
762
763 /**
764  * @brief Get the tdb sequence number.
765  *
766  * Only makes sense if the writers opened with TDB_SEQNUM set. Note that this
767  * sequence number will wrap quite quickly, so it should only be used for a
768  * 'has something changed' test, not for code that relies on the count of the
769  * number of changes made. If you want a counter then use a tdb record.
770  *
771  * The aim of this sequence number is to allow for a very lightweight test of a
772  * possible tdb change.
773  *
774  * @param[in]  tdb      The database to get the sequence number from.
775  *
776  * @return              The sequence number or 0.
777  *
778  * @see tdb_open()
779  * @see tdb_enable_seqnum()
780  */
781 int tdb_get_seqnum(struct tdb_context *tdb);
782
783 /**
784  * @brief Get the hash size.
785  *
786  * @param[in]  tdb      The database to get the hash size from.
787  *
788  * @return              The hash size.
789  */
790 int tdb_hash_size(struct tdb_context *tdb);
791
792 /**
793  * @brief Get the map size.
794  *
795  * @param[in]  tdb     The database to get the map size from.
796  *
797  * @return             The map size.
798  */
799 size_t tdb_map_size(struct tdb_context *tdb);
800
801 /**
802  * @brief Get the tdb flags set during open.
803  *
804  * @param[in]  tdb      The database to get the flags form.
805  *
806  * @return              The flags set to on the database.
807  */
808 int tdb_get_flags(struct tdb_context *tdb);
809
810 /**
811  * @brief Add flags to the database.
812  *
813  * @param[in]  tdb      The database to add the flags.
814  *
815  * @param[in]  flag     The tdb flags to add.
816  */
817 void tdb_add_flags(struct tdb_context *tdb, unsigned flag);
818
819 /**
820  * @brief Remove flags from the database.
821  *
822  * @param[in]  tdb      The database to remove the flags.
823  *
824  * @param[in]  flag     The tdb flags to remove.
825  */
826 void tdb_remove_flags(struct tdb_context *tdb, unsigned flag);
827
828 /**
829  * @brief Enable sequence number handling on an open tdb.
830  *
831  * @param[in]  tdb      The database to enable sequence number handling.
832  *
833  * @see tdb_get_seqnum()
834  */
835 void tdb_enable_seqnum(struct tdb_context *tdb);
836
837 /**
838  * @brief Increment the tdb sequence number.
839  *
840  * This only works if the tdb has been opened using the TDB_SEQNUM flag or
841  * enabled using tdb_enable_seqnum().
842  *
843  * @param[in]  tdb      The database to increment the sequence number.
844  *
845  * @see tdb_enable_seqnum()
846  * @see tdb_get_seqnum()
847  */
848 void tdb_increment_seqnum_nonblock(struct tdb_context *tdb);
849
850 /**
851  * @brief Create a hash of the key.
852  *
853  * @param[in]  key      The key to hash
854  *
855  * @return              The hash.
856  */
857 unsigned int tdb_jenkins_hash(TDB_DATA *key);
858
859 /**
860  * @brief Check the consistency of the database.
861  *
862  * This check the consistency of the database calling back the check function
863  * (if non-NULL) on each record.  If some consistency check fails, or the
864  * supplied check function returns -1, tdb_check returns -1, otherwise 0.
865  *
866  * @note The logging function (if set) will be called with additional
867  * information on the corruption found.
868  *
869  * @param[in]  tdb      The database to check.
870  *
871  * @param[in]  check    The check function to use.
872  *
873  * @param[in]  private_data the private data to pass to the check function.
874  *
875  * @return              0 on success, -1 on error with error code set.
876  *
877  * @see tdb_error()
878  * @see tdb_errorstr()
879  */
880 int tdb_check(struct tdb_context *tdb,
881               int (*check) (TDB_DATA key, TDB_DATA data, void *private_data),
882               void *private_data);
883
884 /**
885  * @brief Dump all possible records in a corrupt database.
886  *
887  * This is the only way to get data out of a database where tdb_check() fails.
888  * It will call walk() with anything which looks like a database record; this
889  * may well include invalid, incomplete or duplicate records.
890  *
891  * @param[in]  tdb      The database to check.
892  *
893  * @param[in]  walk     The walk function to use.
894  *
895  * @param[in]  private_data the private data to pass to the walk function.
896  *
897  * @return              0 on success, -1 on error with error code set.
898  *
899  * @see tdb_error()
900  * @see tdb_errorstr()
901  */
902 int tdb_rescue(struct tdb_context *tdb,
903                void (*walk) (TDB_DATA key, TDB_DATA data, void *private_data),
904                void *private_data);
905
906 /**
907  * @brief Check if support for TDB_MUTEX_LOCKING is available at runtime.
908  *
909  * On some systems the API for pthread_mutexattr_setrobust() is not available.
910  * On other systems there are some bugs in the interaction between glibc and
911  * the linux kernel.
912  *
913  * This function provides a runtime check if robust mutexes are really
914  * available.
915  *
916  * This needs to be called and return true before TDB_MUTEX_LOCKING
917  * can be used at runtime.
918  *
919  * @note This calls fork(), but the SIGCHILD handling should be transparent.
920  *
921  * @return              true if supported, false otherwise.
922  *
923  * @see TDB_MUTEX_LOCKING
924  */
925 bool tdb_runtime_check_for_robust_mutexes(void);
926
927 /* @} ******************************************************************/
928
929 /* Low level locking functions: use with care */
930 int tdb_chainlock(struct tdb_context *tdb, TDB_DATA key);
931 int tdb_chainlock_nonblock(struct tdb_context *tdb, TDB_DATA key);
932 int tdb_chainunlock(struct tdb_context *tdb, TDB_DATA key);
933 int tdb_chainlock_read(struct tdb_context *tdb, TDB_DATA key);
934 int tdb_chainlock_read_nonblock(struct tdb_context *tdb, TDB_DATA key);
935 int tdb_chainunlock_read(struct tdb_context *tdb, TDB_DATA key);
936 int tdb_chainlock_mark(struct tdb_context *tdb, TDB_DATA key);
937 int tdb_chainlock_unmark(struct tdb_context *tdb, TDB_DATA key);
938
939 void tdb_setalarm_sigptr(struct tdb_context *tdb, volatile sig_atomic_t *sigptr);
940
941 /* wipe and repack */
942 int tdb_wipe_all(struct tdb_context *tdb);
943 int tdb_repack(struct tdb_context *tdb);
944
945 /* Debug functions. Not used in production. */
946 void tdb_dump_all(struct tdb_context *tdb);
947 int tdb_printfreelist(struct tdb_context *tdb);
948 int tdb_validate_freelist(struct tdb_context *tdb, int *pnum_entries);
949 int tdb_freelist_size(struct tdb_context *tdb);
950 char *tdb_summary(struct tdb_context *tdb);
951
952 extern TDB_DATA tdb_null;
953
954 #ifdef  __cplusplus
955 }
956 #endif
957
958 #endif /* tdb.h */