1 .TH DBZ 3Z "3 Feb 1991"
4 dbminit, fetch, store, dbmclose \- somewhat dbm-compatible database routines
6 dbzfresh, dbzagain, dbzfetch, dbzstore \- database routines
8 dbzsync, dbzsize, dbzincore, dbzcancel, dbzdebug \- database routines
26 .B dbzfresh(base, size, fieldsep, cmap, tagmask)
33 .B dbzagain(base, oldbase)
41 .B dbzstore(key, value)
51 .B dbzincore(newvalue)
57 These functions provide an indexing system for rapid random access to a
61 Subject to certain constraints, they are call-compatible with
63 although they also provide some extensions.
68 or any variant thereof.)
72 stores key-value pairs, where both key and value are arbitrary sequences
73 of bytes, specified to the functions by
76 typedefed in the header file to be a structure with members
80 pointing to the bytes)
85 indicating how long the byte sequence is).
89 is more restricted than
94 must be an index into a base file,
99 offsets into the base file.
102 must ``point to'' a place in the base file where the corresponding
105 A key can be no longer than
107 (a constant defined in the header file) bytes.
108 No key can be an initial subsequence of another,
109 which in most applications requires that keys be
110 either bracketed or terminated in some way (see the
116 for a fine point on terminators).
120 an index into the base file
126 which must already exist.
127 (If the database is new, they should be zero-length files.)
128 Subsequent accesses go to that database until
130 is called to close the database.
131 The base file need not exist at the time of the
133 but it must exist before accesses are attempted.
136 searches the database for the specified
138 returning the corresponding
144 pair in the database.
146 will fail unless the database files are writeable.
147 See below for a complication arising from case mapping.
152 for creating a new database with more control over details.
155 the database files need not exist:
156 they will be created if necessary,
157 and truncated in any case.
161 parameter specifies the size of the first hash table within the database,
163 Performance will be best if
165 is a prime number and
166 the number of key-value pairs stored in the database does not exceed
171 function, given the expected number of key-value pairs,
172 will suggest a database size that meets these criteria.)
183 file is tiny and roughly constant in size)
185 the number of key-value pairs exceeds about 80% of
187 (Nothing awful will happen if the database grows beyond 100% of
189 but accesses will slow down somewhat and the
191 file will grow somewhat.)
195 parameter specifies the field separator in the base file.
197 NUL (0), and the last character of a
199 argument is NUL, that NUL compares equal to either a NUL or a
202 This permits use of NUL to terminate key strings without requiring that
203 NULs appear in the base file.
206 of a database created with
208 is the horizontal-tab character.
210 For use in news systems, various forms of case mapping (e.g. uppercase to
211 lowercase) in keys are available.
216 is a single character specifying which of several mapping algorithms to use.
217 Available algorithms are:
221 case-sensitive: no case mapping
232 case-insensitive: uppercase and lowercase equivalent
239 RFC822 message-ID rules, case-sensitive before `@' (with certain exceptions)
240 and case-insensitive after
243 whatever the local default is, normally
249 (no mapping) is faster than the others and is overwhelmingly the correct
250 choice for most applications.
251 Unless compatibility constraints interfere, it is more efficient to pre-map
252 the keys, storing mapped keys in the base file, than to have
254 do the mapping on every search.
256 For historical reasons,
262 arguments to be pre-mapped, but expect unmapped keys in the base file.
266 do the same jobs but handle all case mapping internally,
267 so the customer need not worry about it.
270 stores only the database
272 in its files, relying on reference to the base file to confirm a hit on a key.
273 References to the base file can be minimized, greatly speeding up searches,
274 if a little bit of information about the keys can be stored in the
277 This is ``free'' if there are some unused bits in an
280 so that the offset can be
282 with some information about the key.
287 allows specifying the location of unused bits.
289 should be a mask with
294 The bits in the mask should
298 The bit immediately above the mask (the
300 bit) should be unused (0) in
304 will reject attempts to store a key-value pair in which the
307 Apart from this restriction, tagging is invisible to the user.
310 of 1 means ``no tagging'', for use with enormous base files or
311 on systems with unusual offset representations.
318 is synonymous with the local default;
319 the normal default is suitable for tables of 90-100,000
323 of 0 (NUL) is synonymous with the character
325 signifying no case mapping
326 (note that the character
328 specifies the local default mapping,
333 of 0 is synonymous with the local default tag mask,
334 normally 0x7f000000 (specifying the top bit in a 32-bit offset
335 as the flag bit, and the next 7 bits as the mask,
336 which is suitable for base files up to circa 24MB).
339 with the database files empty is equivalent to calling
340 .IR dbzfresh(name,0,'\et','?',0) .
342 When databases are regenerated periodically, as in news,
343 it is simplest to pick the parameters for a new database based on the old one.
344 This also permits some memory of past sizes of the old database, so that
345 a new database size can be chosen to cover expected fluctuations.
349 for creating a new database as a new generation of an old database.
350 The database files for
354 is equivalent to calling
356 with the same field separator, case mapping, and tag mask as the old database,
359 equal to the result of applying
361 to the largest number of entries in the
363 database and its previous 10 generations.
365 When many accesses are being done by the same program,
367 is massively faster if its first hash table is in memory.
368 If an internal flag is 1,
369 an attempt is made to read the table in when
370 the database is opened, and
372 writes it out to disk again (if it was read successfully and
377 (which should be 0 or 1)
378 and returns the previous value;
379 this does not affect the status of a database that has already been opened.
381 The attempt to read the table in may fail due to memory shortage;
384 quietly falls back on its default behavior.
386 to an in-memory database are not (in general) written out to the file
391 so if robustness in the presence of crashes
392 or concurrent accesses
393 is crucial, in-memory databases
394 should probably be avoided.
397 causes all buffers etc. to be flushed out to the files.
398 It is typically used as a precaution against crashes or concurrent accesses
401 process will be running for a long time.
402 It is a somewhat expensive operation,
404 for an in-memory database.
407 cancels any pending writes from buffers.
408 This is typically useful only for in-core databases, since writes are
409 otherwise done immediately.
410 Its main purpose is to let a child process, in the wake of a
414 without writing its parent's data to disk.
418 has been compiled with debugging facilities available (which makes it
419 bigger and a bit slower),
421 alters the value (and returns the previous value) of an internal flag
422 which (when 1; default is 0) causes
423 verbose and cryptic debugging output on standard output.
425 Concurrent reading of databases is fairly safe,
426 but there is no (inter)locking,
427 so concurrent updating is not.
429 The database files include a record of the byte order of the processor
430 creating the database, and accesses by processors with different byte
431 order will work, although they will be slightly slower.
432 Byte order is preserved by
435 agreement on the size and internal structure of an
437 offset is necessary, as is consensus on
440 An open database occupies three
442 streams and their corresponding file descriptors;
443 a fourth is needed for an in-memory database.
444 Memory consumption is negligible (except for
446 buffers) except for in-memory databases.
452 values return 0 for success, \-1 for failure.
455 values return a value with
457 set to NULL for failure.
461 set plausibly on return, but otherwise this is not guaranteed.
468 indicates that the database did not appear to be in
475 Jon Zeeff (zeeff@b-tech.ann-arbor.mi.us).
476 Later contributions by David Butler and Mark Moraes.
478 including this documentation,
479 by Henry Spencer (henry@zoo.toronto.edu) as
480 part of the C News project.
481 Hashing function by Peter Honeyman.
487 values point to static storage which is overwritten by later calls.
492 will misbehave if an existing key-value pair is `overwritten' by
496 The user is responsible for avoiding this by using
498 first to check for duplicates;
499 an internal optimization remembers the result of the
500 first search so there is minimal overhead in this.
504 to bring the base file into existence
507 has been used meanwhile.
509 The RFC822 case mapper implements only a first approximation to the
510 hideously-complex RFC822 case rules.
514 is not particularly quick.
524 On C implementations which trap integer overflow,
530 offset equal to the greatest
533 as this would cause overflow in the biased representation used.
536 perhaps ought to notice when many offsets
537 in the old database were
539 tagging, and shrink the tag mask to match.
545 would be a better approach to the problem
547 tries to address, but that's harder to do portably.