4 dbzinit, dbzfresh, dbzagain, dbzclose, dbzexists, dbzfetch, dbzstore, dbzsync, dbzsize, dbzgetoptions, dbzsetoptions, dbzdebug \- database routines
9 .B "bool dbzinit(const char *base)"
11 .B "bool dbzclose(void)"
13 .B "bool dbzfresh(const char *base, long size)"
15 .B "bool dbzagain(const char *base, const char *oldbase)"
17 .B "bool dbzexists(const HASH key)"
19 .B "off_t dbzfetch(const HASH key)"
20 .B "bool dbzfetch(const HASH key, void *ivalue)"
22 .B "bool dbzstore(const HASH key, off_t offset)"
23 .B "bool dbzstore(const HASH key, void *ivalue)"
25 .B "bool dbzsync(void)"
27 .B "long dbzsize(long nentries)"
29 .B "void dbzgetoptions(dbzoptions *opt)"
31 .B "void dbzsetoptions(const dbzoptions opt)"
34 These functions provide an indexing system for rapid random access to a
40 stores offsets into the base text file for rapid retrieval. All retrievals
41 are keyed on a hash value that is generated by the
47 an index into the base file
55 which must already exist.
56 (If the database is new, they should be zero-length files.)
57 Subsequent accesses go to that database until
59 is called to close the database.
62 searches the database for the specified
64 returning the corresponding
67 .I <\-\-enable\-tagged\-hash at configure>
69 .I <\-\-enable\-tagged\-hash at configure>
70 is not specified, it returns true and content of
76 pair in the database, if
77 .I <\-\-enable\-tagged\-hash at configure>
79 .I <\-\-enable\-tagged\-hash at configure>
80 is not specified, it stores the content of
83 will fail unless the database files are writable.
85 will verify whether or not the given hash exists or not. Dbz is
86 optimized for this operation and it may be significantly faster than
92 for creating a new database with more control over details.
96 parameter specifies the size of the first hash table within the database,
98 Performance will be best if the number of key-value pairs stored in the
99 database does not exceed about 2/3 of
103 function, given the expected number of key-value pairs,
104 will suggest a database size that meets these criteria.)
115 .I DBZ_INTERNAL_HASH_SIZE * size
119 file is tiny and roughly constant in size)
121 the number of key-value pairs exceeds about 80% of
123 (Nothing awful will happen if the database grows beyond 100% of
125 but accesses will slow down quite a bit and the
129 files will grow somewhat.)
133 .SM DBZ_INTERNAL_HASH_SIZE
134 bytes of the message-id's hash in the
136 file to confirm a hit. This eliminates the need to read the base file to
137 handle collisions. This replaces the tagmask feature in previous dbz
145 is synonymous with the local default;
146 the normal default is suitable for tables of 5,000,000
150 with the empty name is equivalent to calling
151 .IR dbzfresh(name,\ 0) .
153 When databases are regenerated periodically, as in news,
154 it is simplest to pick the parameters for a new database based on the old one.
155 This also permits some memory of past sizes of the old database, so that
156 a new database size can be chosen to cover expected fluctuations.
160 for creating a new database as a new generation of an old database.
161 The database files for
165 is equivalent to calling
169 equal to the result of applying
171 to the largest number of entries in the
173 database and its previous 10 generations.
175 When many accesses are being done by the same program,
177 is massively faster if its first hash table is in memory.
178 If the ``pag_incore'' flag is set to INCORE_MEM,
179 an attempt is made to read the table in when
180 the database is opened, and
182 writes it out to disk again (if it was read successfully and
185 can be used to set the
189 flag to new value which should be ``INCORE_NO'', ``INCORE_MEM'', or
190 \&``INCORE_MMAP'' for the
194 files separately; this does not affect the status of a database that has
195 already been opened. The default is ``INCORE_NO'' for the
197 file and ``INCORE_MMAP'' for the
199 file. The attempt to read the table in may fail due to memory shortage;
204 to an in-memory database are not (in general) written out to the file
209 so if robustness in the presence of crashes
210 or concurrent accesses is crucial, in-memory databases
211 should probably be avoided or the
213 option should be set to ``true'';
217 option is ``true'', then writes to the
221 files will be done using non-blocking I/O. This can be significantly faster if
222 your platform supports non-blocking I/O with files.
225 causes all buffers etc. to be flushed out to the files.
226 It is typically used as a precaution against crashes or concurrent accesses
229 process will be running for a long time.
230 It is a somewhat expensive operation,
232 for an in-memory database.
234 Concurrent reading of databases is fairly safe,
235 but there is no (inter)locking,
236 so concurrent updating is not.
238 An open database occupies three
240 streams and two file descriptors;
241 Memory consumption is negligible (except for
243 buffers) except for in-memory databases.
245 dbm(3), history(5), libinn(3)
249 values return ``true'' for success, ``false'' for failure.
252 values return a value with
258 set plausibly on return, but otherwise this is not guaranteed.
265 indicates that the database did not appear to be in
271 is defined at compile-time then a
273 function will be included. This will do performance tests and integrity test.
278 Jon Zeeff (zeeff@b-tech.ann-arbor.mi.us).
279 Later contributions by David Butler and Mark Moraes.
281 including this documentation,
282 by Henry Spencer (henry@zoo.toronto.edu) as
283 part of the C News project.
284 MD5 code borrowed from RSA. Extensive reworking to remove backwards
285 compatibility and to add hashes into dbz files by Clayton O'Neill (coneill@oneill.net)
294 with a key already in the database.
295 The user is responsible for avoiding this.
297 The RFC822 case mapper implements only a first approximation to the
298 hideously-complex RFC822 case rules.
301 no longer tries to be call-compatible with