+++ /dev/null
-.TH DBZ 3 "6 Sep 1997"
-.BY "INN"
-.SH NAME
-dbzinit, dbzfresh, dbzagain, dbzclose, dbzexists, dbzfetch, dbzstore, dbzsync, dbzsize, dbzgetoptions, dbzsetoptions, dbzdebug \- database routines
-.SH SYNOPSIS
-.nf
-.B #include <dbz.h>
-.PP
-.B "bool dbzinit(const char *base)"
-.PP
-.B "bool dbzclose(void)"
-.PP
-.B "bool dbzfresh(const char *base, long size)"
-.PP
-.B "bool dbzagain(const char *base, const char *oldbase)"
-.PP
-.B "bool dbzexists(const HASH key)"
-.PP
-.B "off_t dbzfetch(const HASH key)"
-.B "bool dbzfetch(const HASH key, void *ivalue)"
-.PP
-.B "bool dbzstore(const HASH key, off_t offset)"
-.B "bool dbzstore(const HASH key, void *ivalue)"
-.PP
-.B "bool dbzsync(void)"
-.PP
-.B "long dbzsize(long nentries)"
-.PP
-.B "void dbzgetoptions(dbzoptions *opt)"
-.PP
-.B "void dbzsetoptions(const dbzoptions opt)"
-.PP
-.SH DESCRIPTION
-These functions provide an indexing system for rapid random access to a
-text file (the
-.I base
-.IR file ).
-.PP
-.I Dbz
-stores offsets into the base text file for rapid retrieval. All retrievals
-are keyed on a hash value that is generated by the
-.I HashMessageID()
-function.
-.PP
-.I Dbzinit
-opens a database,
-an index into the base file
-.IR base ,
-consisting of files
-.IB base .dir
-,
-.IB base .index
-, and
-.IB base .hash
-which must already exist.
-(If the database is new, they should be zero-length files.)
-Subsequent accesses go to that database until
-.I dbzclose
-is called to close the database.
-.PP
-.I Dbzfetch
-searches the database for the specified
-.IR key ,
-returning the corresponding
-.I value
-if any, if
-.I <\-\-enable\-tagged\-hash at configure>
-is specified. If
-.I <\-\-enable\-tagged\-hash at configure>
-is not specified, it returns true and content of
-.I ivalue
-is set.
-.I Dbzstore
-stores the
-.I key - value
-pair in the database, if
-.I <\-\-enable\-tagged\-hash at configure>
-is specified. If
-.I <\-\-enable\-tagged\-hash at configure>
-is not specified, it stores the content of
-.IR ivalue .
-.I Dbzstore
-will fail unless the database files are writable.
-.I Dbzexists
-will verify whether or not the given hash exists or not. Dbz is
-optimized for this operation and it may be significantly faster than
-.IR dbzfetch() .
-.PP
-.I Dbzfresh
-is a variant of
-.I dbzinit
-for creating a new database with more control over details.
-.PP
-.IR Dbzfresh 's
-.I size
-parameter specifies the size of the first hash table within the database,
-in key-value pairs.
-Performance will be best if the number of key-value pairs stored in the
-database does not exceed about 2/3 of
-.IR size .
-(The
-.I dbzsize
-function, given the expected number of key-value pairs,
-will suggest a database size that meets these criteria.)
-Assuming that an
-.I fseek
-offset is 4 bytes,
-the
-.B .index
-file will be
-.I 4 * size
-bytes. The
-.B .hash
-file will be
-.I DBZ_INTERNAL_HASH_SIZE * size
-bytes
-(the
-.B .dir
-file is tiny and roughly constant in size)
-until
-the number of key-value pairs exceeds about 80% of
-.IR size .
-(Nothing awful will happen if the database grows beyond 100% of
-.IR size ,
-but accesses will slow down quite a bit and the
-.B .index
-and
-.B .hash
-files will grow somewhat.)
-.PP
-.I Dbz
-stores up to
-.SM DBZ_INTERNAL_HASH_SIZE
-bytes of the message-id's hash in the
-.B .hash
-file to confirm a hit. This eliminates the need to read the base file to
-handle collisions. This replaces the tagmask feature in previous dbz
-releases.
-.PP
-A
-.I size
-of ``0''
-given to
-.I dbzfresh
-is synonymous with the local default;
-the normal default is suitable for tables of 5,000,000
-key-value pairs.
-Calling
-.I dbzinit(name)
-with the empty name is equivalent to calling
-.IR dbzfresh(name,\ 0) .
-.PP
-When databases are regenerated periodically, as in news,
-it is simplest to pick the parameters for a new database based on the old one.
-This also permits some memory of past sizes of the old database, so that
-a new database size can be chosen to cover expected fluctuations.
-.I Dbzagain
-is a variant of
-.I dbzinit
-for creating a new database as a new generation of an old database.
-The database files for
-.I oldbase
-must exist.
-.I Dbzagain
-is equivalent to calling
-.I dbzfresh
-with a
-.I size
-equal to the result of applying
-.I dbzsize
-to the largest number of entries in the
-.I oldbase
-database and its previous 10 generations.
-.PP
-When many accesses are being done by the same program,
-.I dbz
-is massively faster if its first hash table is in memory.
-If the ``pag_incore'' flag is set to INCORE_MEM,
-an attempt is made to read the table in when
-the database is opened, and
-.I dbzclose
-writes it out to disk again (if it was read successfully and
-has been modified).
-.I Dbzsetoptions
-can be used to set the
-.B pag_incore
-and
-.B exists_incore
-flag to new value which should be ``INCORE_NO'', ``INCORE_MEM'', or
-\&``INCORE_MMAP'' for the
-.B .hash
-and
-.B .index
-files separately; this does not affect the status of a database that has
-already been opened. The default is ``INCORE_NO'' for the
-.B .index
-file and ``INCORE_MMAP'' for the
-.B .hash
-file. The attempt to read the table in may fail due to memory shortage;
-in this case
-.I dbz
-fails with an error.
-.IR Store s
-to an in-memory database are not (in general) written out to the file
-until
-.IR dbzclose
-or
-.IR dbzsync ,
-so if robustness in the presence of crashes
-or concurrent accesses is crucial, in-memory databases
-should probably be avoided or the
-.B writethrough
-option should be set to ``true'';
-.PP
-If the
-.B nonblock
-option is ``true'', then writes to the
-.B .hash
-and
-.B .index
-files will be done using non-blocking I/O. This can be significantly faster if
-your platform supports non-blocking I/O with files.
-.PP
-.I Dbzsync
-causes all buffers etc. to be flushed out to the files.
-It is typically used as a precaution against crashes or concurrent accesses
-when a
-.IR dbz -using
-process will be running for a long time.
-It is a somewhat expensive operation,
-especially
-for an in-memory database.
-.PP
-Concurrent reading of databases is fairly safe,
-but there is no (inter)locking,
-so concurrent updating is not.
-.PP
-An open database occupies three
-.I stdio
-streams and two file descriptors;
-Memory consumption is negligible (except for
-.I stdio
-buffers) except for in-memory databases.
-.SH SEE ALSO
-dbm(3), history(5), libinn(3)
-.SH DIAGNOSTICS
-Functions returning
-.I bool
-values return ``true'' for success, ``false'' for failure.
-Functions returning
-.I off_t
-values return a value with
-.I \-1
-for failure.
-.I Dbzinit
-attempts to have
-.I errno
-set plausibly on return, but otherwise this is not guaranteed.
-An
-.I errno
-of
-.B EDOM
-from
-.I dbzinit
-indicates that the database did not appear to be in
-.I dbz
-format.
-.PP
-If
-.SM DBZTEST
-is defined at compile-time then a
-.I main()
-function will be included. This will do performance tests and integrity test.
-.SH HISTORY
-The original
-.I dbz
-was written by
-Jon Zeeff (zeeff@b-tech.ann-arbor.mi.us).
-Later contributions by David Butler and Mark Moraes.
-Extensive reworking,
-including this documentation,
-by Henry Spencer (henry@zoo.toronto.edu) as
-part of the C News project.
-MD5 code borrowed from RSA. Extensive reworking to remove backwards
-compatibility and to add hashes into dbz files by Clayton O'Neill (coneill@oneill.net)
-.SH BUGS
-.PP
-Unlike
-.IR dbm ,
-.I dbz
-will refuse
-to
-.I dbzstore
-with a key already in the database.
-The user is responsible for avoiding this.
-.PP
-The RFC822 case mapper implements only a first approximation to the
-hideously-complex RFC822 case rules.
-.PP
-.I Dbz
-no longer tries to be call-compatible with
-.I dbm
-in any way.
~ian / innduct.git / blobdiff