← Back to branch summary

~vcs-imports/samba/main

« back to all changes in this revision

Viewing changes to source/tdb/README

  • Committer: jerry
  • Date: 2006-07-14 21:48:39 UTC
  • Revision ID: vcs-imports@canonical.com-20060714214839-586d8c489a8fcead
gutting trunk to move to svn:externals

Show diffs side-by-side

added added

removed removed

Lines of Context:
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