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
  35 /**
  36  * @defgroup tdb The tdb API
  37  *
  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
  41  * extremely small.
  42  *
  43  * @section tdb_interface Interface
  44  *
  45  * The interface is very similar to gdbm except for the following:
  46  *
  47  * <ul>
  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
  52  *     anyway</li>
  53  * <li>added a tdb_traverse() function for traversing the whole database</li>
  54  * <li>added transactions support</li>
  55  * </ul>
  56  *
  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.
  60  *
  61  * @{
  62  */
  63
  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    */
  68
  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. */
  83 #define TDB_MUTEX_LOCKING 4096 /** optimized locking using robust mutexes if supported,
  84                                    only with tdb >= 1.3.0 and TDB_CLEAR_IF_FIRST
  85                                    after checking tdb_runtime_check_for_robust_mutexes() */
  86
  87 /** The tdb error codes */
  88 enum TDB_ERROR {TDB_SUCCESS=0, TDB_ERR_CORRUPT, TDB_ERR_IO, TDB_ERR_LOCK,
  89                 TDB_ERR_OOM, TDB_ERR_EXISTS, TDB_ERR_NOLOCK, TDB_ERR_LOCK_TIMEOUT,
  90                 TDB_ERR_NOEXIST, TDB_ERR_EINVAL, TDB_ERR_RDONLY,
  91                 TDB_ERR_NESTING};
  92
  93 /** Debugging uses one of the following levels */
  94 enum tdb_debug_level {TDB_DEBUG_FATAL = 0, TDB_DEBUG_ERROR,
  95                       TDB_DEBUG_WARNING, TDB_DEBUG_TRACE};
  96
  97 /** The tdb data structure */
  98 typedef struct TDB_DATA {
  99         unsigned char *dptr;
 100         size_t dsize;
 101 } TDB_DATA;
 102
 103 #ifndef PRINTF_ATTRIBUTE
 104 #if (__GNUC__ >= 3)
 105 /** Use gcc attribute to check printf fns.  a1 is the 1-based index of
 106  * the parameter containing the format, and a2 the index of the first
 107  * argument. Note that some gcc 2.x versions don't handle this
 108  * properly **/
 109 #define PRINTF_ATTRIBUTE(a1, a2) __attribute__ ((format (__printf__, a1, a2)))
 110 #else
 111 #define PRINTF_ATTRIBUTE(a1, a2)
 112 #endif
 113 #endif
 114
 115 /** This is the context structure that is returned from a db open. */
 116 typedef struct tdb_context TDB_CONTEXT;
 117
 118 typedef int (*tdb_traverse_func)(struct tdb_context *, TDB_DATA, TDB_DATA, void *);
 119 typedef void (*tdb_log_func)(struct tdb_context *, enum tdb_debug_level, const char *, ...) PRINTF_ATTRIBUTE(3, 4);
 120 typedef unsigned int (*tdb_hash_func)(TDB_DATA *key);
 121
 122 struct tdb_logging_context {
 123         tdb_log_func log_fn;
 124         void *log_private;
 125 };
 126
 127 /**
 128  * @brief Open the database and creating it if necessary.
 129  *
 130  * @param[in]  name     The name of the db to open.
 131  *
 132  * @param[in]  hash_size The hash size is advisory, use zero for a default
 133  *                       value.
 134  *
 135  * @param[in]  tdb_flags The flags to use to open the db:\n\n
 136  *                         TDB_CLEAR_IF_FIRST - Clear database if we are the
 137  *                                              only one with it open\n
 138  *                         TDB_INTERNAL - Don't use a file, instead store the
 139  *                                        data in memory. The filename is
 140  *                                        ignored in this case.\n
 141  *                         TDB_NOLOCK - Don't do any locking\n
 142  *                         TDB_NOMMAP - Don't use mmap\n
 143  *                         TDB_NOSYNC - Don't synchronise transactions to disk\n
 144  *                         TDB_SEQNUM - Maintain a sequence number\n
 145  *                         TDB_VOLATILE - activate the per-hashchain freelist,
 146  *                                        default 5.\n
 147  *                         TDB_ALLOW_NESTING - Allow transactions to nest.\n
 148  *                         TDB_DISALLOW_NESTING - Disallow transactions to nest.\n
 149  *                         TDB_INCOMPATIBLE_HASH - Better hashing: can't be opened by tdb < 1.2.6.\n
 150  *                         TDB_MUTEX_LOCKING - Optimized locking using robust mutexes if supported,
 151  *                                             can't be opened by tdb < 1.3.0.
 152  *                                             Only valid in combination with TDB_CLEAR_IF_FIRST
 153  *                                             after checking tdb_runtime_check_for_robust_mutexes()\n
 154  *
 155  * @param[in]  open_flags Flags for the open(2) function.
 156  *
 157  * @param[in]  mode     The mode for the open(2) function.
 158  *
 159  * @return              A tdb context structure, NULL on error.
 160  */
 161 struct tdb_context *tdb_open(const char *name, int hash_size, int tdb_flags,
 162                       int open_flags, mode_t mode);
 163
 164 /**
 165  * @brief Open the database and creating it if necessary.
 166  *
 167  * This is like tdb_open(), but allows you to pass an initial logging and
 168  * hash function. Be careful when passing a hash function - all users of the
 169  * database must use the same hash function or you will get data corruption.
 170  *
 171  * @param[in]  name     The name of the db to open.
 172  *
 173  * @param[in]  hash_size The hash size is advisory, use zero for a default
 174  *                       value.
 175  *
 176  * @param[in]  tdb_flags The flags to use to open the db:\n\n
 177  *                         TDB_CLEAR_IF_FIRST - Clear database if we are the
 178  *                                              only one with it open\n
 179  *                         TDB_INTERNAL - Don't use a file, instead store the
 180  *                                        data in memory. The filename is
 181  *                                        ignored in this case.\n
 182  *                         TDB_NOLOCK - Don't do any locking\n
 183  *                         TDB_NOMMAP - Don't use mmap\n
 184  *                         TDB_NOSYNC - Don't synchronise transactions to disk\n
 185  *                         TDB_SEQNUM - Maintain a sequence number\n
 186  *                         TDB_VOLATILE - activate the per-hashchain freelist,
 187  *                                        default 5.\n
 188  *                         TDB_ALLOW_NESTING - Allow transactions to nest.\n
 189  *                         TDB_DISALLOW_NESTING - Disallow transactions to nest.\n
 190  *                         TDB_INCOMPATIBLE_HASH - Better hashing: can't be opened by tdb < 1.2.6.\n
 191  *                         TDB_MUTEX_LOCKING - Optimized locking using robust mutexes if supported,
 192  *                                             can't be opened by tdb < 1.3.0.
 193  *                                             Only valid in combination with TDB_CLEAR_IF_FIRST
 194  *                                             after checking tdb_runtime_check_for_robust_mutexes()\n
 195  *
 196  * @param[in]  open_flags Flags for the open(2) function.
 197  *
 198  * @param[in]  mode     The mode for the open(2) function.
 199  *
 200  * @param[in]  log_ctx  The logging function to use.
 201  *
 202  * @param[in]  hash_fn  The hash function you want to use.
 203  *
 204  * @return              A tdb context structure, NULL on error.
 205  *
 206  * @see tdb_open()
 207  */
 208 struct tdb_context *tdb_open_ex(const char *name, int hash_size, int tdb_flags,
 209                          int open_flags, mode_t mode,
 210                          const struct tdb_logging_context *log_ctx,
 211                          tdb_hash_func hash_fn);
 212
 213 /**
 214  * @brief Set the maximum number of dead records per hash chain.
 215  *
 216  * @param[in]  tdb      The database handle to set the maximum.
 217  *
 218  * @param[in]  max_dead The maximum number of dead records per hash chain.
 219  */
 220 void tdb_set_max_dead(struct tdb_context *tdb, int max_dead);
 221
 222 /**
 223  * @brief Reopen a tdb.
 224  *
 225  * This can be used after a fork to ensure that we have an independent seek
 226  * pointer from our parent and to re-establish locks.
 227  *
 228  * @param[in]  tdb      The database to reopen. It will be free'd on error!
 229  *
 230  * @return              0 on success, -1 on error.
 231  *
 232  * @note Don't call tdb_error() after this function cause the tdb context will
 233  *       be freed on error.
 234  */
 235 int tdb_reopen(struct tdb_context *tdb);
 236
 237 /**
 238  * @brief Reopen all tdb's
 239  *
 240  * If the parent is longlived (ie. a parent daemon architecture), we know it
 241  * will keep it's active lock on a tdb opened with CLEAR_IF_FIRST. Thus for
 242  * child processes we don't have to add an active lock. This is essential to
 243  * improve performance on systems that keep POSIX locks as a non-scalable data
 244  * structure in the kernel.
 245  *
 246  * @param[in]  parent_longlived Wether the parent is longlived or not.
 247  *
 248  * @return              0 on success, -1 on error.
 249  */
 250 int tdb_reopen_all(int parent_longlived);
 251
 252 /**
 253  * @brief Set a different tdb logging function.
 254  *
 255  * @param[in]  tdb      The tdb to set the logging function.
 256  *
 257  * @param[in]  log_ctx  The logging function to set.
 258  */
 259 void tdb_set_logging_function(struct tdb_context *tdb, const struct tdb_logging_context *log_ctx);
 260
 261 /**
 262  * @brief Get the tdb last error code.
 263  *
 264  * @param[in]  tdb      The tdb to get the error code from.
 265  *
 266  * @return              A TDB_ERROR code.
 267  *
 268  * @see TDB_ERROR
 269  */
 270 enum TDB_ERROR tdb_error(struct tdb_context *tdb);
 271
 272 /**
 273  * @brief Get a error string for the last tdb error
 274  *
 275  * @param[in]  tdb      The tdb to get the error code from.
 276  *
 277  * @return              An error string.
 278  */
 279 const char *tdb_errorstr(struct tdb_context *tdb);
 280
 281 /**
 282  * @brief Fetch an entry in the database given a key.
 283  *
 284  * The caller must free the resulting data.
 285  *
 286  * @param[in]  tdb      The tdb to fetch the key.
 287  *
 288  * @param[in]  key      The key to fetch.
 289  *
 290  * @return              The key entry found in the database, NULL on error with
 291  *                      TDB_ERROR set.
 292  *
 293  * @see tdb_error()
 294  * @see tdb_errorstr()
 295  */
 296 TDB_DATA tdb_fetch(struct tdb_context *tdb, TDB_DATA key);
 297
 298 /**
 299  * @brief Hand a record to a parser function without allocating it.
 300  *
 301  * This function is meant as a fast tdb_fetch alternative for large records
 302  * that are frequently read. The "key" and "data" arguments point directly
 303  * into the tdb shared memory, they are not aligned at any boundary.
 304  *
 305  * @warning The parser is called while tdb holds a lock on the record. DO NOT
 306  * call other tdb routines from within the parser. Also, for good performance
 307  * you should make the parser fast to allow parallel operations.
 308  *
 309  * @param[in]  tdb      The tdb to parse the record.
 310  *
 311  * @param[in]  key      The key to parse.
 312  *
 313  * @param[in]  parser   The parser to use to parse the data.
 314  *
 315  * @param[in]  private_data A private data pointer which is passed to the parser
 316  *                          function.
 317  *
 318  * @return              -1 if the record was not found. If the record was found,
 319  *                      the return value of "parser" is passed up to the caller.
 320  */
 321 int tdb_parse_record(struct tdb_context *tdb, TDB_DATA key,
 322                               int (*parser)(TDB_DATA key, TDB_DATA data,
 323                                             void *private_data),
 324                               void *private_data);
 325
 326 /**
 327  * @brief Delete an entry in the database given a key.
 328  *
 329  * @param[in]  tdb      The tdb to delete the key.
 330  *
 331  * @param[in]  key      The key to delete.
 332  *
 333  * @return              0 on success, -1 if the key doesn't exist.
 334  */
 335 int tdb_delete(struct tdb_context *tdb, TDB_DATA key);
 336
 337 /**
 338  * @brief Store an element in the database.
 339  *
 340  * This replaces any existing element with the same key.
 341  *
 342  * @param[in]  tdb      The tdb to store the entry.
 343  *
 344  * @param[in]  key      The key to use to store the entry.
 345  *
 346  * @param[in]  dbuf     The data to store under the key.
 347  *
 348  * @param[in]  flag     The flags to store the key:\n\n
 349  *                      TDB_INSERT: Don't overwrite an existing entry.\n
 350  *                      TDB_MODIFY: Don't create a new entry\n
 351  *
 352  * @return              0 on success, -1 on error with error code set.
 353  *
 354  * @see tdb_error()
 355  * @see tdb_errorstr()
 356  */
 357 int tdb_store(struct tdb_context *tdb, TDB_DATA key, TDB_DATA dbuf, int flag);
 358
 359 /**
 360  * @brief Append data to an entry.
 361  *
 362  * If the entry doesn't exist, it will create a new one.
 363  *
 364  * @param[in]  tdb      The database to use.
 365  *
 366  * @param[in]  key      The key to append the data.
 367  *
 368  * @param[in]  new_dbuf The data to append to the key.
 369  *
 370  * @return              0 on success, -1 on error with error code set.
 371  *
 372  * @see tdb_error()
 373  * @see tdb_errorstr()
 374  */
 375 int tdb_append(struct tdb_context *tdb, TDB_DATA key, TDB_DATA new_dbuf);
 376
 377 /**
 378  * @brief Close a database.
 379  *
 380  * @param[in]  tdb      The database to close. The context will be free'd.
 381  *
 382  * @return              0 for success, -1 on error.
 383  *
 384  * @note Don't call tdb_error() after this function cause the tdb context will
 385  *       be freed on error.
 386  */
 387 int tdb_close(struct tdb_context *tdb);
 388
 389 /**
 390  * @brief Find the first entry in the database and return its key.
 391  *
 392  * The caller must free the returned data.
 393  *
 394  * @param[in]  tdb      The database to use.
 395  *
 396  * @return              The first entry of the database, an empty TDB_DATA entry
 397  *                      if the database is empty.
 398  */
 399 TDB_DATA tdb_firstkey(struct tdb_context *tdb);
 400
 401 /**
 402  * @brief Find the next entry in the database, returning its key.
 403  *
 404  * The caller must free the returned data.
 405  *
 406  * @param[in]  tdb      The database to use.
 407  *
 408  * @param[in]  key      The key from which you want the next key.
 409  *
 410  * @return              The next entry of the current key, an empty TDB_DATA
 411  *                      entry if there is no entry.
 412  */
 413 TDB_DATA tdb_nextkey(struct tdb_context *tdb, TDB_DATA key);
 414
 415 /**
 416  * @brief Traverse the entire database.
 417  *
 418  * While traversing the function fn(tdb, key, data, state) is called on each
 419  * element. If fn is NULL then it is not called. A non-zero return value from
 420  * fn() indicates that the traversal should stop. Traversal callbacks may not
 421  * start transactions.
 422  *
 423  * @warning The data buffer given to the callback fn does NOT meet the alignment
 424  * restrictions malloc gives you.
 425  *
 426  * @param[in]  tdb      The database to traverse.
 427  *
 428  * @param[in]  fn       The function to call on each entry.
 429  *
 430  * @param[in]  private_data The private data which should be passed to the
 431  *                          traversing function.
 432  *
 433  * @return              The record count traversed, -1 on error.
 434  */
 435 int tdb_traverse(struct tdb_context *tdb, tdb_traverse_func fn, void *private_data);
 436
 437 /**
 438  * @brief Traverse the entire database.
 439  *
 440  * While traversing the database the function fn(tdb, key, data, state) is
 441  * called on each element, but marking the database read only during the
 442  * traversal, so any write operations will fail. This allows tdb to use read
 443  * locks, which increases the parallelism possible during the traversal.
 444  *
 445  * @param[in]  tdb      The database to traverse.
 446  *
 447  * @param[in]  fn       The function to call on each entry.
 448  *
 449  * @param[in]  private_data The private data which should be passed to the
 450  *                          traversing function.
 451  *
 452  * @return              The record count traversed, -1 on error.
 453  */
 454 int tdb_traverse_read(struct tdb_context *tdb, tdb_traverse_func fn, void *private_data);
 455
 456 /**
 457  * @brief Check if an entry in the database exists.
 458  *
 459  * @note 1 is returned if the key is found and 0 is returned if not found this
 460  * doesn't match the conventions in the rest of this module, but is compatible
 461  * with gdbm.
 462  *
 463  * @param[in]  tdb      The database to check if the entry exists.
 464  *
 465  * @param[in]  key      The key to check if the entry exists.
 466  *
 467  * @return              1 if the key is found, 0 if not.
 468  */
 469 int tdb_exists(struct tdb_context *tdb, TDB_DATA key);
 470
 471 /**
 472  * @brief Lock entire database with a write lock.
 473  *
 474  * @param[in]  tdb      The database to lock.
 475  *
 476  * @return              0 on success, -1 on error with error code set.
 477  *
 478  * @see tdb_error()
 479  * @see tdb_errorstr()
 480  */
 481 int tdb_lockall(struct tdb_context *tdb);
 482
 483 /**
 484  * @brief Lock entire database with a write lock.
 485  *
 486  * This is the non-blocking call.
 487  *
 488  * @param[in]  tdb      The database to lock.
 489  *
 490  * @return              0 on success, -1 on error with error code set.
 491  *
 492  * @see tdb_lockall()
 493  * @see tdb_error()
 494  * @see tdb_errorstr()
 495  */
 496 int tdb_lockall_nonblock(struct tdb_context *tdb);
 497
 498 /**
 499  * @brief Unlock entire database with write lock.
 500  *
 501  * @param[in]  tdb      The database to unlock.
 502  *
 503  * @return              0 on success, -1 on error with error code set.
 504  *
 505  * @see tdb_lockall()
 506  * @see tdb_error()
 507  * @see tdb_errorstr()
 508  */
 509 int tdb_unlockall(struct tdb_context *tdb);
 510
 511 /**
 512  * @brief Lock entire database with a read lock.
 513  *
 514  * @param[in]  tdb      The database to lock.
 515  *
 516  * @return              0 on success, -1 on error with error code set.
 517  *
 518  * @see tdb_error()
 519  * @see tdb_errorstr()
 520  */
 521 int tdb_lockall_read(struct tdb_context *tdb);
 522
 523 /**
 524  * @brief Lock entire database with a read lock.
 525  *
 526  * This is the non-blocking call.
 527  *
 528  * @param[in]  tdb      The database to lock.
 529  *
 530  * @return              0 on success, -1 on error with error code set.
 531  *
 532  * @see tdb_lockall_read()
 533  * @see tdb_error()
 534  * @see tdb_errorstr()
 535  */
 536 int tdb_lockall_read_nonblock(struct tdb_context *tdb);
 537
 538 /**
 539  * @brief Unlock entire database with read lock.
 540  *
 541  * @param[in]  tdb      The database to unlock.
 542  *
 543  * @return              0 on success, -1 on error with error code set.
 544  *
 545  * @see tdb_lockall_read()
 546  * @see tdb_error()
 547  * @see tdb_errorstr()
 548  */
 549 int tdb_unlockall_read(struct tdb_context *tdb);
 550
 551 /**
 552  * @brief Lock entire database with write lock - mark only.
 553  *
 554  * @todo Add more details.
 555  *
 556  * @param[in]  tdb      The database to mark.
 557  *
 558  * @return              0 on success, -1 on error with error code set.
 559  *
 560  * @see tdb_error()
 561  * @see tdb_errorstr()
 562  */
 563 int tdb_lockall_mark(struct tdb_context *tdb);
 564
 565 /**
 566  * @brief Lock entire database with write lock - unmark only.
 567  *
 568  * @todo Add more details.
 569  *
 570  * @param[in]  tdb      The database to mark.
 571  *
 572  * @return              0 on success, -1 on error with error code set.
 573  *
 574  * @see tdb_error()
 575  * @see tdb_errorstr()
 576  */
 577 int tdb_lockall_unmark(struct tdb_context *tdb);
 578
 579 /**
 580  * @brief Get the name of the current tdb file.
 581  *
 582  * This is useful for external logging functions.
 583  *
 584  * @param[in]  tdb      The database to get the name from.
 585  *
 586  * @return              The name of the database.
 587  */
 588 const char *tdb_name(struct tdb_context *tdb);
 589
 590 /**
 591  * @brief Get the underlying file descriptor being used by tdb.
 592  *
 593  * This is useful for external routines that want to check the device/inode
 594  * of the fd.
 595  *
 596  * @param[in]  tdb      The database to get the fd from.
 597  *
 598  * @return              The file descriptor or -1.
 599  */
 600 int tdb_fd(struct tdb_context *tdb);
 601
 602 /**
 603  * @brief Get the current logging function.
 604  *
 605  * This is useful for external tdb routines that wish to log tdb errors.
 606  *
 607  * @param[in]  tdb      The database to get the logging function from.
 608  *
 609  * @return              The logging function of the database.
 610  *
 611  * @see tdb_get_logging_private()
 612  */
 613 tdb_log_func tdb_log_fn(struct tdb_context *tdb);
 614
 615 /**
 616  * @brief Get the private data of the logging function.
 617  *
 618  * @param[in]  tdb      The database to get the data from.
 619  *
 620  * @return              The private data pointer of the logging function.
 621  *
 622  * @see tdb_log_fn()
 623  */
 624 void *tdb_get_logging_private(struct tdb_context *tdb);
 625
 626 /**
 627  * @brief Start a transaction.
 628  *
 629  * All operations after the transaction start can either be committed with
 630  * tdb_transaction_commit() or cancelled with tdb_transaction_cancel().
 631  *
 632  * If you call tdb_transaction_start() again on the same tdb context while a
 633  * transaction is in progress, then the same transaction buffer is re-used. The
 634  * number of tdb_transaction_{commit,cancel} operations must match the number
 635  * of successful tdb_transaction_start() calls.
 636  *
 637  * Note that transactions are by default disk synchronous, and use a recover
 638  * area in the database to automatically recover the database on the next open
 639  * if the system crashes during a transaction. You can disable the synchronous
 640  * transaction recovery setup using the TDB_NOSYNC flag, which will greatly
 641  * speed up operations at the risk of corrupting your database if the system
 642  * crashes.
 643  *
 644  * Operations made within a transaction are not visible to other users of the
 645  * database until a successful commit.
 646  *
 647  * @param[in]  tdb      The database to start the transaction.
 648  *
 649  * @return              0 on success, -1 on error with error code set.
 650  *
 651  * @see tdb_error()
 652  * @see tdb_errorstr()
 653  */
 654 int tdb_transaction_start(struct tdb_context *tdb);
 655
 656 /**
 657  * @brief Start a transaction, non-blocking.
 658  *
 659  * @param[in]  tdb      The database to start the transaction.
 660  *
 661  * @return              0 on success, -1 on error with error code set.
 662  *
 663  * @see tdb_error()
 664  * @see tdb_errorstr()
 665  * @see tdb_transaction_start()
 666  */
 667 int tdb_transaction_start_nonblock(struct tdb_context *tdb);
 668
 669 /**
 670  * @brief Prepare to commit a current transaction, for two-phase commits.
 671  *
 672  * Once prepared for commit, the only allowed calls are tdb_transaction_commit()
 673  * or tdb_transaction_cancel(). Preparing allocates disk space for the pending
 674  * updates, so a subsequent commit should succeed (barring any hardware
 675  * failures).
 676  *
 677  * @param[in]  tdb      The database to prepare the commit.
 678  *
 679  * @return              0 on success, -1 on error with error code set.
 680  *
 681  * @see tdb_error()
 682  * @see tdb_errorstr()
 683  */
 684 int tdb_transaction_prepare_commit(struct tdb_context *tdb);
 685
 686 /**
 687  * @brief Commit a current transaction.
 688  *
 689  * This updates the database and releases the current transaction locks.
 690  *
 691  * @param[in]  tdb      The database to commit the transaction.
 692  *
 693  * @return              0 on success, -1 on error with error code set.
 694  *
 695  * @see tdb_error()
 696  * @see tdb_errorstr()
 697  */
 698 int tdb_transaction_commit(struct tdb_context *tdb);
 699
 700 /**
 701  * @brief Cancel a current transaction.
 702  *
 703  * This discards all write and lock operations that have been made since the
 704  * transaction started.
 705  *
 706  * @param[in]  tdb      The tdb to cancel the transaction on.
 707  *
 708  * @return              0 on success, -1 on error with error code set.
 709  *
 710  * @see tdb_error()
 711  * @see tdb_errorstr()
 712  */
 713 int tdb_transaction_cancel(struct tdb_context *tdb);
 714
 715 /**
 716  * @brief Get the tdb sequence number.
 717  *
 718  * Only makes sense if the writers opened with TDB_SEQNUM set. Note that this
 719  * sequence number will wrap quite quickly, so it should only be used for a
 720  * 'has something changed' test, not for code that relies on the count of the
 721  * number of changes made. If you want a counter then use a tdb record.
 722  *
 723  * The aim of this sequence number is to allow for a very lightweight test of a
 724  * possible tdb change.
 725  *
 726  * @param[in]  tdb      The database to get the sequence number from.
 727  *
 728  * @return              The sequence number or 0.
 729  *
 730  * @see tdb_open()
 731  * @see tdb_enable_seqnum()
 732  */
 733 int tdb_get_seqnum(struct tdb_context *tdb);
 734
 735 /**
 736  * @brief Get the hash size.
 737  *
 738  * @param[in]  tdb      The database to get the hash size from.
 739  *
 740  * @return              The hash size.
 741  */
 742 int tdb_hash_size(struct tdb_context *tdb);
 743
 744 /**
 745  * @brief Get the map size.
 746  *
 747  * @param[in]  tdb     The database to get the map size from.
 748  *
 749  * @return             The map size.
 750  */
 751 size_t tdb_map_size(struct tdb_context *tdb);
 752
 753 /**
 754  * @brief Get the tdb flags set during open.
 755  *
 756  * @param[in]  tdb      The database to get the flags form.
 757  *
 758  * @return              The flags set to on the database.
 759  */
 760 int tdb_get_flags(struct tdb_context *tdb);
 761
 762 /**
 763  * @brief Add flags to the database.
 764  *
 765  * @param[in]  tdb      The database to add the flags.
 766  *
 767  * @param[in]  flag     The tdb flags to add.
 768  */
 769 void tdb_add_flags(struct tdb_context *tdb, unsigned flag);
 770
 771 /**
 772  * @brief Remove flags from the database.
 773  *
 774  * @param[in]  tdb      The database to remove the flags.
 775  *
 776  * @param[in]  flag     The tdb flags to remove.
 777  */
 778 void tdb_remove_flags(struct tdb_context *tdb, unsigned flag);
 779
 780 /**
 781  * @brief Enable sequence number handling on an open tdb.
 782  *
 783  * @param[in]  tdb      The database to enable sequence number handling.
 784  *
 785  * @see tdb_get_seqnum()
 786  */
 787 void tdb_enable_seqnum(struct tdb_context *tdb);
 788
 789 /**
 790  * @brief Increment the tdb sequence number.
 791  *
 792  * This only works if the tdb has been opened using the TDB_SEQNUM flag or
 793  * enabled using tdb_enable_seqnum().
 794  *
 795  * @param[in]  tdb      The database to increment the sequence number.
 796  *
 797  * @see tdb_enable_seqnum()
 798  * @see tdb_get_seqnum()
 799  */
 800 void tdb_increment_seqnum_nonblock(struct tdb_context *tdb);
 801
 802 /**
 803  * @brief Create a hash of the key.
 804  *
 805  * @param[in]  key      The key to hash
 806  *
 807  * @return              The hash.
 808  */
 809 unsigned int tdb_jenkins_hash(TDB_DATA *key);
 810
 811 /**
 812  * @brief Check the consistency of the database.
 813  *
 814  * This check the consistency of the database calling back the check function
 815  * (if non-NULL) on each record.  If some consistency check fails, or the
 816  * supplied check function returns -1, tdb_check returns -1, otherwise 0.
 817  *
 818  * @note The logging function (if set) will be called with additional
 819  * information on the corruption found.
 820  *
 821  * @param[in]  tdb      The database to check.
 822  *
 823  * @param[in]  check    The check function to use.
 824  *
 825  * @param[in]  private_data the private data to pass to the check function.
 826  *
 827  * @return              0 on success, -1 on error with error code set.
 828  *
 829  * @see tdb_error()
 830  * @see tdb_errorstr()
 831  */
 832 int tdb_check(struct tdb_context *tdb,
 833               int (*check) (TDB_DATA key, TDB_DATA data, void *private_data),
 834               void *private_data);
 835
 836 /**
 837  * @brief Dump all possible records in a corrupt database.
 838  *
 839  * This is the only way to get data out of a database where tdb_check() fails.
 840  * It will call walk() with anything which looks like a database record; this
 841  * may well include invalid, incomplete or duplicate records.
 842  *
 843  * @param[in]  tdb      The database to check.
 844  *
 845  * @param[in]  walk     The walk function to use.
 846  *
 847  * @param[in]  private_data the private data to pass to the walk function.
 848  *
 849  * @return              0 on success, -1 on error with error code set.
 850  *
 851  * @see tdb_error()
 852  * @see tdb_errorstr()
 853  */
 854 int tdb_rescue(struct tdb_context *tdb,
 855                void (*walk) (TDB_DATA key, TDB_DATA data, void *private_data),
 856                void *private_data);
 857
 858 /**
 859  * @brief Check if support for TDB_MUTEX_LOCKING is available at runtime.
 860  *
 861  * On some systems the API for pthread_mutexattr_setrobust() is not available.
 862  * On other systems there are some bugs in the interaction between glibc and
 863  * the linux kernel.
 864  *
 865  * This function provides a runtime check if robust mutexes are really
 866  * available.
 867  *
 868  * This needs to be called and return true before TDB_MUTEX_LOCKING
 869  * can be used at runtime.
 870  *
 871  * @note This calls fork(), but the SIGCHILD handling should be transparent.
 872  *
 873  * @return              true if supported, false otherwise.
 874  *
 875  * @see TDB_MUTEX_LOCKING
 876  */
 877 bool tdb_runtime_check_for_robust_mutexes(void);
 878
 879 /* @} ******************************************************************/
 880
 881 /* Low level locking functions: use with care */
 882 int tdb_chainlock(struct tdb_context *tdb, TDB_DATA key);
 883 int tdb_chainlock_nonblock(struct tdb_context *tdb, TDB_DATA key);
 884 int tdb_chainunlock(struct tdb_context *tdb, TDB_DATA key);
 885 int tdb_chainlock_read(struct tdb_context *tdb, TDB_DATA key);
 886 int tdb_chainunlock_read(struct tdb_context *tdb, TDB_DATA key);
 887 int tdb_chainlock_mark(struct tdb_context *tdb, TDB_DATA key);
 888 int tdb_chainlock_unmark(struct tdb_context *tdb, TDB_DATA key);
 889
 890 void tdb_setalarm_sigptr(struct tdb_context *tdb, volatile sig_atomic_t *sigptr);
 891
 892 /* wipe and repack */
 893 int tdb_wipe_all(struct tdb_context *tdb);
 894 int tdb_repack(struct tdb_context *tdb);
 895
 896 /* Debug functions. Not used in production. */
 897 void tdb_dump_all(struct tdb_context *tdb);
 898 int tdb_printfreelist(struct tdb_context *tdb);
 899 int tdb_validate_freelist(struct tdb_context *tdb, int *pnum_entries);
 900 int tdb_freelist_size(struct tdb_context *tdb);
 901 char *tdb_summary(struct tdb_context *tdb);
 902
 903 extern TDB_DATA tdb_null;
 904
 905 #ifdef  __cplusplus
 906 }
 907 #endif
 908
 909 #endif /* tdb.h */