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