source/tdb/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 TDB_DEBUG=1 for verbose debug info
  19 add NOLOCK=1 to disable locking code
  20
  21 Testing
  22 -------
  23
  24 Compile tdbtest.c and link with gdbm for testing. tdbtest will perform
  25 identical operations via tdb and gdbm then make sure the result is the
  26 same
  27
  28 Also included is tdbtool, which allows simple database manipulation
  29 on the commandline.
  30
  31 tdbtest and tdbtool are not built as part of Samba, but are included
  32 for completeness.
  33
  34 Interface
  35 ---------
  36
  37 The interface is very similar to gdbm except for the following:
  38
  39 - different open interface. The tdb_open call is more similar to a
  40   traditional open()
  41 - no tdbm_reorganise() function
  42 - no tdbm_sync() function. No operations are cached in the library anyway
  43 - added a tdb_traverse() function for traversing the whole database
  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, in which case errno is also set.  Don't
  64    try to call tdb_error or tdb_errname, just do strerror(errno).
  65
  66    possible tdb_flags are:
  67     TDB_CLEAR_IF_FIRST - clear database if we are the only one with it open
  68     TDB_INTERNAL - don't use a file, instaed store the data in
  69                    memory. The filename is ignored in this case.
  70     TDB_NOLOCK - don't do any locking
  71     TDB_NOMMAP - don't use mmap
  72
  73 ----------------------------------------------------------------------
  74 char *tdb_error(TDB_CONTEXT *tdb);
  75
  76      return a error string for the last tdb error
  77
  78 ----------------------------------------------------------------------
  79 int tdb_close(TDB_CONTEXT *tdb);
  80
  81    close a database
  82
  83 ----------------------------------------------------------------------
  84 int tdb_update(TDB_CONTEXT *tdb, TDB_DATA key, TDB_DATA dbuf);
  85
  86    update an entry in place - this only works if the new data size
  87    is <= the old data size and the key exists.
  88    on failure return -1
  89
  90 ----------------------------------------------------------------------
  91 TDB_DATA tdb_fetch(TDB_CONTEXT *tdb, TDB_DATA key);
  92
  93    fetch an entry in the database given a key
  94    if the return value has a null dptr then a error occurred
  95
  96    caller must free the resulting data
  97
  98 ----------------------------------------------------------------------
  99 int tdb_exists(TDB_CONTEXT *tdb, TDB_DATA key);
 100
 101    check if an entry in the database exists
 102
 103    note that 1 is returned if the key is found and 0 is returned if not found
 104    this doesn't match the conventions in the rest of this module, but is
 105    compatible with gdbm
 106
 107 ----------------------------------------------------------------------
 108 int tdb_traverse(TDB_CONTEXT *tdb, int (*fn)(TDB_CONTEXT *tdb,
 109                  TDB_DATA key, TDB_DATA dbuf, void *state), void *state);
 110
 111    traverse the entire database - calling fn(tdb, key, data, state) on each
 112    element.
 113
 114    return -1 on error or the record count traversed
 115
 116    if fn is NULL then it is not called
 117
 118    a non-zero return value from fn() indicates that the traversal should stop
 119
 120 ----------------------------------------------------------------------
 121 TDB_DATA tdb_firstkey(TDB_CONTEXT *tdb);
 122
 123    find the first entry in the database and return its key
 124
 125    the caller must free the returned data
 126
 127 ----------------------------------------------------------------------
 128 TDB_DATA tdb_nextkey(TDB_CONTEXT *tdb, TDB_DATA key);
 129
 130    find the next entry in the database, returning its key
 131
 132    the caller must free the returned data
 133
 134 ----------------------------------------------------------------------
 135 int tdb_delete(TDB_CONTEXT *tdb, TDB_DATA key);
 136
 137    delete an entry in the database given a key
 138
 139 ----------------------------------------------------------------------
 140 int tdb_store(TDB_CONTEXT *tdb, TDB_DATA key, TDB_DATA dbuf, int flag);
 141
 142    store an element in the database, replacing any existing element
 143    with the same key
 144
 145    If flag==TDB_INSERT then don't overwrite an existing entry
 146    If flag==TDB_MODIFY then don't create a new entry
 147
 148    return 0 on success, -1 on failure
 149
 150 ----------------------------------------------------------------------
 151 int tdb_writelock(TDB_CONTEXT *tdb);
 152
 153    lock the database. If we already have it locked then don't do anything
 154
 155 ----------------------------------------------------------------------
 156 int tdb_writeunlock(TDB_CONTEXT *tdb);
 157    unlock the database
 158
 159 ----------------------------------------------------------------------
 160 int tdb_lockchain(TDB_CONTEXT *tdb, TDB_DATA key);
 161
 162    lock one hash chain. This is meant to be used to reduce locking
 163    contention - it cannot guarantee how many records will be locked
 164
 165 ----------------------------------------------------------------------
 166 int tdb_unlockchain(TDB_CONTEXT *tdb, TDB_DATA key);
 167
 168    unlock one hash chain