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