/**	@file	dk3dbi.h	Database interface.

The module provides a unique API to access different databases
(Berkeley DB, NDBM, and an in-memory database).

The Berkeley database and NDBM databases are accessed using
the libraries provided for these databases.

The code for the in-memory database is implemented in the module.

There are two methods to open a database:

* The file name passed as @a fn to the dk3dbi_open() or dk3dbi_open_app()
  function contains just the file name, the @a tp argument specifies
  a database type.

* The @a tp argument is set to DK3_DB_TYPE_UNKNOWN, the file name contains
  a leading database type with options separated from the file name
  by two colons like "mem::/var/run/mydb.dat".
  In the example we use the in-memory database with synchronization on
  each modification, the database is stored in the
  "/var/run/mydb.dat" file.
  The two colons are used because one colon can occur in file names on
  Windows systems to specify the drive letter.
  This method allows to specifiy both type and name of a database in
  configuration files or as command line option.
  Other database type names are "bdb" or "ndbm".

The in-memory database is written to file as stream of entries. For each
entry we have an entry header (8 bytes), key data and value data.
In the entry header we have the key size (number of bytes in key data)
and value size (number of bytes in value data). Both numbers
are 4 byte unsigned integer values, most significant byte first.

Use dk3dbi_open_app(), dk3dbi_open() dk3dbi_open_truncate_app(), or
dk3dbi_open_truncate() to open a database. The functions
return a pointer to a database structure.

The dk3dbi_set(), dk3dbi_get(), and dk3dbi_delete() functions can be used to
save, retrieve, or delete binary data in the database.

The dk3dbi_traverse() function can be used to walk through all records
in the database. While traversing the database you must not apply
modifications to the database.

The dk3dbi_set_string(), dk3dbi_get_string(), and dk3dbi_delete_string()
can be used to save, retrieve, or delete string pairs in the database.
Strings must be in the systems default character width (2 byte on Windows,
1 byte on Unix/Linux).

Variants of these functions are available to deal with 8-bit, 16-bit and
32-bit character strings.

The dk3dbi_get_error() function retrieves the error code of the last error
occured. Optionally it also resets the error code.

The dk3dbi_sync() function can be used to synchronize the database to disk
if this operation is supported by the underlaying database library
(Berkeley DB and in-memory database). Note: Synchronizing data to disk
is a multi-stage process in modern operating systems. From the applications
point of view a write operation succeeds if data is passed to the operating
system for further handling. This is what dk3dbi_sync() does. Most
operating systems collect data in file buffers which are flushed
"in suitable situations", i.e. buffer full, after specific time intervals,
or in moments of low load.
The buffering behaviour of the OS is outside of dk3dbi_sync()'s scope.

The dk3dbi_close() function must be used to close a database when it is not
longer needed. If the database was modified, dk3dbi_close() invokes
dk3dbi_sync() automatically.

The dk3dbi_dbfile_delete_app() and dk3dbi_dbfile_delete() functions can be
used to delete the file(s) for a database.

The dk3dbi_dbfile_truncate_app() and dk3dbi_dbfile_truncate() functions can
be used to remove all contents from a database. The file(s) are not removed.
*/