import HEAD into svn+ssh://svn.samba.org/home/svn/samba/trunk
[metze/old/v3-2-winbind-ndr.git] / 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
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 ----------------------------------------------------------------------
73 char *tdb_error(TDB_CONTEXT *tdb);
74
75      return a error string for the last tdb error
76
77 ----------------------------------------------------------------------
78 int tdb_close(TDB_CONTEXT *tdb);
79
80    close a database
81
82 ----------------------------------------------------------------------
83 int 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 ----------------------------------------------------------------------
90 TDB_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 ----------------------------------------------------------------------
98 int 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 ----------------------------------------------------------------------
107 int 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 ----------------------------------------------------------------------
120 TDB_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 ----------------------------------------------------------------------
127 TDB_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 ----------------------------------------------------------------------
134 int tdb_delete(TDB_CONTEXT *tdb, TDB_DATA key);
135
136    delete an entry in the database given a key
137
138 ----------------------------------------------------------------------
139 int 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 ----------------------------------------------------------------------
150 int tdb_writelock(TDB_CONTEXT *tdb);
151
152    lock the database. If we already have it locked then don't do anything
153
154 ----------------------------------------------------------------------
155 int tdb_writeunlock(TDB_CONTEXT *tdb);
156    unlock the database
157
158 ----------------------------------------------------------------------
159 int 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 ----------------------------------------------------------------------
165 int tdb_unlockchain(TDB_CONTEXT *tdb, TDB_DATA key);
166
167    unlock one hash chain