README
1tdb - a trivial database system
2tridge@linuxcare.com December 1999
3==================================
4
5This is a simple database API. It was inspired by the realisation that
6in Samba we have several ad-hoc bits of code that essentially
7implement small databases for sharing structures between parts of
8Samba. As I was about to add another I realised that a generic
9database module was called for to replace all the ad-hoc bits.
10
11I based the interface on gdbm. I couldn't use gdbm as we need to be
12able to have multiple writers to the databases at one time.
13
14Compilation
15-----------
16
17add HAVE_MMAP=1 to use mmap instead of read/write
18add TDB_DEBUG=1 for verbose debug info
19add NOLOCK=1 to disable locking code
20
21Testing
22-------
23
24Compile tdbtest.c and link with gdbm for testing. tdbtest will perform
25identical operations via tdb and gdbm then make sure the result is the
26same
27
28Also included is tdbtool, which allows simple database manipulation
29on the commandline.
30
31tdbtest and tdbtool are not built as part of Samba, but are included
32for completeness.
33
34Interface
35---------
36
37The 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
45A general rule for using tdb is that the caller frees any returned
46TDB_DATA structures. Just call free(p.dptr) to free a TDB_DATA
47return value called p. This is the same as gdbm.
48
49here is a full list of tdb functions with brief descriptions.
50
51
52----------------------------------------------------------------------
53TDB_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
72----------------------------------------------------------------------
73char *tdb_error(TDB_CONTEXT *tdb);
74
75 return a error string for the last tdb error
76
77----------------------------------------------------------------------
78int tdb_close(TDB_CONTEXT *tdb);
79
80 close a database
81
82----------------------------------------------------------------------
83int tdb_update(TDB_CONTEXT *tdb, TDB_DATA key, TDB_DATA dbuf);
84
85 update an entry in place - this only works if the new data size
86 is <= the old data size and the key exists.
87 on failure return -1
88
89----------------------------------------------------------------------
90TDB_DATA tdb_fetch(TDB_CONTEXT *tdb, TDB_DATA key);
91
92 fetch an entry in the database given a key
93 if the return value has a null dptr then a error occurred
94
95 caller must free the resulting data
96
97----------------------------------------------------------------------
98int tdb_exists(TDB_CONTEXT *tdb, TDB_DATA key);
99
100 check if an entry in the database exists
101
102 note that 1 is returned if the key is found and 0 is returned if not found
103 this doesn't match the conventions in the rest of this module, but is
104 compatible with gdbm
105
106----------------------------------------------------------------------
107int tdb_traverse(TDB_CONTEXT *tdb, int (*fn)(TDB_CONTEXT *tdb,
108 TDB_DATA key, TDB_DATA dbuf, void *state), void *state);
109
110 traverse the entire database - calling fn(tdb, key, data, state) on each
111 element.
112
113 return -1 on error or the record count traversed
114
115 if fn is NULL then it is not called
116
117 a non-zero return value from fn() indicates that the traversal should stop
118
119----------------------------------------------------------------------
120TDB_DATA tdb_firstkey(TDB_CONTEXT *tdb);
121
122 find the first entry in the database and return its key
123
124 the caller must free the returned data
125
126----------------------------------------------------------------------
127TDB_DATA tdb_nextkey(TDB_CONTEXT *tdb, TDB_DATA key);
128
129 find the next entry in the database, returning its key
130
131 the caller must free the returned data
132
133----------------------------------------------------------------------
134int tdb_delete(TDB_CONTEXT *tdb, TDB_DATA key);
135
136 delete an entry in the database given a key
137
138----------------------------------------------------------------------
139int tdb_store(TDB_CONTEXT *tdb, TDB_DATA key, TDB_DATA dbuf, int flag);
140
141 store an element in the database, replacing any existing element
142 with the same key
143
144 If flag==TDB_INSERT then don't overwrite an existing entry
145 If flag==TDB_MODIFY then don't create a new entry
146
147 return 0 on success, -1 on failure
148
149----------------------------------------------------------------------
150int tdb_writelock(TDB_CONTEXT *tdb);
151
152 lock the database. If we already have it locked then don't do anything
153
154----------------------------------------------------------------------
155int tdb_writeunlock(TDB_CONTEXT *tdb);
156 unlock the database
157
158----------------------------------------------------------------------
159int tdb_lockchain(TDB_CONTEXT *tdb, TDB_DATA key);
160
161 lock one hash chain. This is meant to be used to reduce locking
162 contention - it cannot guarantee how many records will be locked
163
164----------------------------------------------------------------------
165int tdb_unlockchain(TDB_CONTEXT *tdb, TDB_DATA key);
166
167 unlock one hash chain
168