source/lib/tdb/docs/README

   1 tdb - a trivial database system
   2 tridge@linuxcare.com December 1999
   3 ==================================
   4
   5 This is a simple database API. It was inspired by the realisation that
   6 in Samba we have several ad-hoc bits of code that essentially
   7 implement small databases for sharing structures between parts of
   8 Samba. As I was about to add another I realised that a generic
   9 database module was called for to replace all the ad-hoc bits.
  10
  11 I based the interface on gdbm. I couldn't use gdbm as we need to be
  12 able to have multiple writers to the databases at one time.
  13
  14 Compilation
  15 -----------
  16
  17 add HAVE_MMAP=1 to use mmap instead of read/write
  18 add NOLOCK=1 to disable locking code
  19
  20 Testing
  21 -------
  22
  23 Compile tdbtest.c and link with gdbm for testing. tdbtest will perform
  24 identical operations via tdb and gdbm then make sure the result is the
  25 same
  26
  27 Also included is tdbtool, which allows simple database manipulation
  28 on the commandline.
  29
  30 tdbtest and tdbtool are not built as part of Samba, but are included
  31 for completeness.
  32
  33 Interface
  34 ---------
  35
  36 The interface is very similar to gdbm except for the following:
  37
  38 - different open interface. The tdb_open call is more similar to a
  39   traditional open()
  40 - no tdbm_reorganise() function
  41 - no tdbm_sync() function. No operations are cached in the library anyway
  42 - added a tdb_traverse() function for traversing the whole database
  43 - added transactions support
  44
  45 A general rule for using tdb is that the caller frees any returned
  46 TDB_DATA structures. Just call free(p.dptr) to free a TDB_DATA
  47 return value called p. This is the same as gdbm.
  48
  49 here is a full list of tdb functions with brief descriptions.
  50
  51
  52 ----------------------------------------------------------------------
  53 TDB_CONTEXT *tdb_open(char *name, int hash_size, int tdb_flags,
  54                       int open_flags, mode_t mode)
  55
  56    open the database, creating it if necessary
  57
  58    The open_flags and mode are passed straight to the open call on the database
  59    file. A flags value of O_WRONLY is invalid
  60
  61    The hash size is advisory, use zero for a default value.
  62
  63    return is NULL on error
  64
  65    possible tdb_flags are:
  66     TDB_CLEAR_IF_FIRST - clear database if we are the only one with it open
  67     TDB_INTERNAL - don't use a file, instaed store the data in
  68                    memory. The filename is ignored in this case.
  69     TDB_NOLOCK - don't do any locking
  70     TDB_NOMMAP - don't use mmap
  71     TDB_NOSYNC - don't synchronise transactions to disk
  72
  73 ----------------------------------------------------------------------
  74 TDB_CONTEXT *tdb_open_ex(char *name, int hash_size, int tdb_flags,
  75                          int open_flags, mode_t mode,
  76                          tdb_log_func log_fn,
  77                          tdb_hash_func hash_fn)
  78
  79 This is like tdb_open(), but allows you to pass an initial logging and
  80 hash function. Be careful when passing a hash function - all users of
  81 the database must use the same hash function or you will get data
  82 corruption.
  83
  84
  85 ----------------------------------------------------------------------
  86 char *tdb_error(TDB_CONTEXT *tdb);
  87
  88      return a error string for the last tdb error
  89
  90 ----------------------------------------------------------------------
  91 int tdb_close(TDB_CONTEXT *tdb);
  92
  93    close a database
  94
  95 ----------------------------------------------------------------------
  96 int tdb_update(TDB_CONTEXT *tdb, TDB_DATA key, TDB_DATA dbuf);
  97
  98    update an entry in place - this only works if the new data size
  99    is <= the old data size and the key exists.
 100    on failure return -1
 101
 102 ----------------------------------------------------------------------
 103 TDB_DATA tdb_fetch(TDB_CONTEXT *tdb, TDB_DATA key);
 104
 105    fetch an entry in the database given a key
 106    if the return value has a null dptr then a error occurred
 107
 108    caller must free the resulting data
 109
 110 ----------------------------------------------------------------------
 111 int tdb_exists(TDB_CONTEXT *tdb, TDB_DATA key);
 112
 113    check if an entry in the database exists
 114
 115    note that 1 is returned if the key is found and 0 is returned if not found
 116    this doesn't match the conventions in the rest of this module, but is
 117    compatible with gdbm
 118
 119 ----------------------------------------------------------------------
 120 int tdb_traverse(TDB_CONTEXT *tdb, int (*fn)(TDB_CONTEXT *tdb,
 121                  TDB_DATA key, TDB_DATA dbuf, void *state), void *state);
 122
 123    traverse the entire database - calling fn(tdb, key, data, state) on each
 124    element.
 125
 126    return -1 on error or the record count traversed
 127
 128    if fn is NULL then it is not called
 129
 130    a non-zero return value from fn() indicates that the traversal
 131    should stop. Traversal callbacks may not start transactions.
 132
 133 ----------------------------------------------------------------------
 134 int tdb_traverse_read(TDB_CONTEXT *tdb, int (*fn)(TDB_CONTEXT *tdb,
 135                      TDB_DATA key, TDB_DATA dbuf, void *state), void *state);
 136
 137    traverse the entire database - calling fn(tdb, key, data, state) on
 138    each element, but marking the database read only during the
 139    traversal, so any write operations will fail. This allows tdb to
 140    use read locks, which increases the parallelism possible during the
 141    traversal.
 142
 143    return -1 on error or the record count traversed
 144
 145    if fn is NULL then it is not called
 146
 147    a non-zero return value from fn() indicates that the traversal
 148    should stop. Traversal callbacks may not start transactions.
 149
 150 ----------------------------------------------------------------------
 151 TDB_DATA tdb_firstkey(TDB_CONTEXT *tdb);
 152
 153    find the first entry in the database and return its key
 154
 155    the caller must free the returned data
 156
 157 ----------------------------------------------------------------------
 158 TDB_DATA tdb_nextkey(TDB_CONTEXT *tdb, TDB_DATA key);
 159
 160    find the next entry in the database, returning its key
 161
 162    the caller must free the returned data
 163
 164 ----------------------------------------------------------------------
 165 int tdb_delete(TDB_CONTEXT *tdb, TDB_DATA key);
 166
 167    delete an entry in the database given a key
 168
 169 ----------------------------------------------------------------------
 170 int tdb_store(TDB_CONTEXT *tdb, TDB_DATA key, TDB_DATA dbuf, int flag);
 171
 172    store an element in the database, replacing any existing element
 173    with the same key
 174
 175    If flag==TDB_INSERT then don't overwrite an existing entry
 176    If flag==TDB_MODIFY then don't create a new entry
 177
 178    return 0 on success, -1 on failure
 179
 180 ----------------------------------------------------------------------
 181 int tdb_writelock(TDB_CONTEXT *tdb);
 182
 183    lock the database. If we already have it locked then don't do anything
 184
 185 ----------------------------------------------------------------------
 186 int tdb_writeunlock(TDB_CONTEXT *tdb);
 187    unlock the database
 188
 189 ----------------------------------------------------------------------
 190 int tdb_lockchain(TDB_CONTEXT *tdb, TDB_DATA key);
 191
 192    lock one hash chain. This is meant to be used to reduce locking
 193    contention - it cannot guarantee how many records will be locked
 194
 195 ----------------------------------------------------------------------
 196 int tdb_unlockchain(TDB_CONTEXT *tdb, TDB_DATA key);
 197
 198    unlock one hash chain
 199
 200 ----------------------------------------------------------------------
 201 int tdb_transaction_start(TDB_CONTEXT *tdb)
 202
 203    start a transaction. All operations after the transaction start can
 204    either be committed with tdb_transaction_commit() or cancelled with
 205    tdb_transaction_cancel().
 206
 207    If you call tdb_transaction_start() again on the same tdb context
 208    while a transaction is in progress, then the same transaction
 209    buffer is re-used. The number of tdb_transaction_{commit,cancel}
 210    operations must match the number of successful
 211    tdb_transaction_start() calls.
 212
 213    Note that transactions are by default disk synchronous, and use a
 214    recover area in the database to automatically recover the database
 215    on the next open if the system crashes during a transaction. You
 216    can disable the synchronous transaction recovery setup using the
 217    TDB_NOSYNC flag, which will greatly speed up operations at the risk
 218    of corrupting your database if the system crashes.
 219
 220    Operations made within a transaction are not visible to other users
 221    of the database until a successful commit.
 222
 223 ----------------------------------------------------------------------
 224 int tdb_transaction_cancel(TDB_CONTEXT *tdb)
 225
 226    cancel a current transaction, discarding all write and lock
 227    operations that have been made since the transaction started.
 228
 229
 230 ----------------------------------------------------------------------
 231 int tdb_transaction_commit(TDB_CONTEXT *tdb)
 232
 233    commit a current transaction, updating the database and releasing
 234    the transaction locks.
 235