tdb: update README a bit
[samba.git] / 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                          const struct tdb_logging_context *log_ctx,
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 TDB_DATA tdb_fetch(TDB_CONTEXT *tdb, TDB_DATA key);
97
98    fetch an entry in the database given a key 
99    if the return value has a null dptr then a error occurred
100
101    caller must free the resulting data
102
103 ----------------------------------------------------------------------
104 int tdb_exists(TDB_CONTEXT *tdb, TDB_DATA key);
105
106    check if an entry in the database exists 
107
108    note that 1 is returned if the key is found and 0 is returned if not found
109    this doesn't match the conventions in the rest of this module, but is
110    compatible with gdbm
111
112 ----------------------------------------------------------------------
113 int tdb_traverse(TDB_CONTEXT *tdb, int (*fn)(TDB_CONTEXT *tdb,
114                  TDB_DATA key, TDB_DATA dbuf, void *state), void *state);
115
116    traverse the entire database - calling fn(tdb, key, data, state) on each 
117    element.
118
119    return -1 on error or the record count traversed
120
121    if fn is NULL then it is not called
122
123    a non-zero return value from fn() indicates that the traversal
124    should stop. Traversal callbacks may not start transactions.
125
126    WARNING: The data buffer given to the callback fn does NOT meet the
127    alignment restrictions malloc gives you.
128
129 ----------------------------------------------------------------------
130 int tdb_traverse_read(TDB_CONTEXT *tdb, int (*fn)(TDB_CONTEXT *tdb,
131                      TDB_DATA key, TDB_DATA dbuf, void *state), void *state);
132
133    traverse the entire database - calling fn(tdb, key, data, state) on
134    each element, but marking the database read only during the
135    traversal, so any write operations will fail. This allows tdb to
136    use read locks, which increases the parallelism possible during the
137    traversal.
138
139    return -1 on error or the record count traversed
140
141    if fn is NULL then it is not called
142
143    a non-zero return value from fn() indicates that the traversal
144    should stop. Traversal callbacks may not start transactions.
145
146 ----------------------------------------------------------------------
147 TDB_DATA tdb_firstkey(TDB_CONTEXT *tdb);
148
149    find the first entry in the database and return its key
150
151    the caller must free the returned data
152
153 ----------------------------------------------------------------------
154 TDB_DATA tdb_nextkey(TDB_CONTEXT *tdb, TDB_DATA key);
155
156    find the next entry in the database, returning its key
157
158    the caller must free the returned data
159
160 ----------------------------------------------------------------------
161 int tdb_delete(TDB_CONTEXT *tdb, TDB_DATA key);
162
163    delete an entry in the database given a key
164
165 ----------------------------------------------------------------------
166 int tdb_store(TDB_CONTEXT *tdb, TDB_DATA key, TDB_DATA dbuf, int flag);
167
168    store an element in the database, replacing any existing element
169    with the same key 
170
171    If flag==TDB_INSERT then don't overwrite an existing entry
172    If flag==TDB_MODIFY then don't create a new entry
173
174    return 0 on success, -1 on failure
175
176 ----------------------------------------------------------------------
177 int tdb_writelock(TDB_CONTEXT *tdb);
178
179    lock the database. If we already have it locked then don't do anything
180
181 ----------------------------------------------------------------------
182 int tdb_writeunlock(TDB_CONTEXT *tdb);
183    unlock the database
184
185 ----------------------------------------------------------------------
186 int tdb_lockchain(TDB_CONTEXT *tdb, TDB_DATA key);
187
188    lock one hash chain. This is meant to be used to reduce locking
189    contention - it cannot guarantee how many records will be locked
190
191 ----------------------------------------------------------------------
192 int tdb_unlockchain(TDB_CONTEXT *tdb, TDB_DATA key);
193
194    unlock one hash chain
195
196 ----------------------------------------------------------------------
197 int tdb_transaction_start(TDB_CONTEXT *tdb)
198
199    start a transaction. All operations after the transaction start can
200    either be committed with tdb_transaction_commit() or cancelled with
201    tdb_transaction_cancel(). 
202
203    If you call tdb_transaction_start() again on the same tdb context
204    while a transaction is in progress, then the same transaction
205    buffer is re-used. The number of tdb_transaction_{commit,cancel}
206    operations must match the number of successful
207    tdb_transaction_start() calls.
208
209    Note that transactions are by default disk synchronous, and use a
210    recover area in the database to automatically recover the database
211    on the next open if the system crashes during a transaction. You
212    can disable the synchronous transaction recovery setup using the
213    TDB_NOSYNC flag, which will greatly speed up operations at the risk
214    of corrupting your database if the system crashes.
215
216    Operations made within a transaction are not visible to other users
217    of the database until a successful commit.
218
219 ----------------------------------------------------------------------
220 int tdb_transaction_cancel(TDB_CONTEXT *tdb)
221
222    cancel a current transaction, discarding all write and lock
223    operations that have been made since the transaction started.
224
225
226 ----------------------------------------------------------------------
227 int tdb_transaction_commit(TDB_CONTEXT *tdb)
228
229    commit a current transaction, updating the database and releasing
230    the transaction locks.
231
232 ----------------------------------------------------------------------
233 int tdb_transaction_prepare_commit(TDB_CONTEXT *tdb)
234
235    prepare to commit a current transaction, for two-phase commits.
236    Once prepared for commit, the only allowed calls are
237    tdb_transaction_commit() or tdb_transaction_cancel(). Preparing
238    allocates disk space for the pending updates, so a subsequent
239    commit should succeed (barring any hardware failures).
240
241 ----------------------------------------------------------------------
242 int tdb_check(TDB_CONTEXT *tdb,
243               int (*check)(TDB_DATA key, TDB_DATA data, void *private_data),
244               void *private_data);)
245
246    check the consistency of the database, calling back the check function
247    (if non-NULL) with each record.  If some consistency check fails, or
248    the supplied check function returns -1, tdb_check returns -1, otherwise
249    0.  Note that logging function (if set) will be called with additional
250    information on the corruption found.