Provided by: libqdbm-dev_1.8.78-6.1ubuntu2_amd64 bug

NAME

       Relic - the NDBM-compatible API of QDBM

SYNOPSIS

       #include <relic.h>
       #include <stdlib.h>
       #include <sys/types.h>
       #include <sys/stat.h>
       #include <fcntl.h>

       typedef struct { void *dptr; size_t dsize; } datum;

       DBM *dbm_open(char *name, int flags, int mode);

       void dbm_close(DBM *db);

       int dbm_store(DBM *db, datum key, datum content, int flags);

       int dbm_delete(DBM *db, datum key);

       datum dbm_fetch(DBM *db, datum key);

       datum dbm_firstkey(DBM *db);

       datum dbm_nextkey(DBM *db);

       int dbm_error(DBM *db);

       int dbm_clearerr(DBM *db);

       int dbm_rdonly(DBM *db);

       int dbm_dirfno(DBM *db);

       int dbm_pagfno(DBM *db);

DESCRIPTION

       Relic is the API which is compatible with NDBM.  So, Relic wraps functions of Depot as API
       of NDBM.  It is easy to port an application from NDBM to QDBM.  In most cases, you  should
       only  replace  the  includings  of  `ndbm.h' with `relic.h' and replace the linking option
       `-lndbm' with `-lqdbm'.

       The original NDBM treats a database as a pair of files.  One, `a directory  file',  has  a
       name  with  suffix  `.dir'  and stores a bit map of keys.  The other, `a data file', has a
       name with suffix `.pag' and stores entities of each records.  Relic creates the  directory
       file  as  a  mere  dummy  file  and  creates  the  data  file as a database.  Relic has no
       restriction about the size of each record.  Relic cannot handle database files made by the
       original NDBM.

       In   order  to  use  Relic,  you  should  include  `relic.h',  `stdlib.h',  `sys/types.h',
       `sys/stat.h' and `fcntl.h' in the source files.  Usually, the following  description  will
       be near the beginning of a source file.

              #include <relic.h>
              #include <stdlib.h>
              #include <sys/types.h>
              #include <sys/stat.h>
              #include <fcntl.h>

       A  pointer  to  `DBM'  is used as a database handle.  A database handle is opened with the
       function `dbm_open' and closed with `dbm_close'.  You should not  refer  directly  to  any
       member of a handle.

       Structures  of  `datum'  type is used in order to give and receive data of keys and values
       with functions of Relic.

       typedef struct { void *dptr; size_t dsize; } datum;
              `dptr' specifies the pointer to the region of a key or a value.  `dsize'  specifies
              the size of the region.

       The function `dbm_open' is used in order to get a database handle.

       DBM *dbm_open(char *name, int flags, int mode);
              `name'  specifies  the  name  of  a database.  The file names are concatenated with
              suffixes.  `flags' is the same as  one  of  `open'  call,  although  `O_WRONLY'  is
              treated as `O_RDWR' and additional flags except for `O_CREAT' and `O_TRUNC' have no
              effect.  `mode' specifies the mode of the database file as one of `open' call does.
              The return value is the database handle or `NULL' if it is not successful.

       The function `dbm_close' is used in order to close a database handle.

       void dbm_close(DBM *db);
              `db'  specifies  a  database  handle.   Because  the region of the closed handle is
              released, it becomes impossible to use the handle.

       The function `dbm_store' is used in order to store a record.

       int dbm_store(DBM *db, datum key, datum content, int flags);
              `db' specifies a database handle.  `key' specifies a structure of a key.  `content'
              specifies  a  structure  of  a  value.   `flags'  specifies  behavior  when the key
              overlaps, by the following values: `DBM_REPLACE', which means the  specified  value
              overwrites  the existing one, `DBM_INSERT', which means the existing value is kept.
              The return value is 0 if it is successful, 1 if it gives up because of overlaps  of
              the key, -1 if other error occurs.

       The function `dbm_delete' is used in order to delete a record.

       int dbm_delete(DBM *db, datum key);
              `db'  specifies  a  database  handle.   `key'  specifies a structure of a key.  The
              return value is 0 if it is successful, -1 if some errors occur.

       The function `dbm_fetch' is used in order to retrieve a record.

       datum dbm_fetch(DBM *db, datum key);
              `db' specifies a database handle.  `key' specifies  a  structure  of  a  key.   The
              return  value  is  a  structure of the result.  If a record corresponds, the member
              `dptr' of the structure is the pointer to the region of the value.   If  no  record
              corresponds  or  some  errors occur, `dptr' is `NULL'.  `dptr' points to the region
              related with the handle.  The region is available until the next  time  of  calling
              this function with the same handle.

       The function `dbm_firstkey' is used in order to get the first key of a database.

       datum dbm_firstkey(DBM *db);
              `db'  specifies  a database handle.  The return value is a structure of the result.
              If a record corresponds, the member `dptr' of the structure is the pointer  to  the
              region  of the first key.  If no record corresponds or some errors occur, `dptr' is
              `NULL'.  `dptr' points to the region  related  with  the  handle.   The  region  is
              available   until   the  next  time  of  calling  this  function  or  the  function
              `dbm_nextkey' with the same handle.

       The function `dbm_nextkey' is used in order to get the next key of a database.

       datum dbm_nextkey(DBM *db);
              `db' specifies a database handle.  The return value is a structure of  the  result.
              If  a  record corresponds, the member `dptr' of the structure is the pointer to the
              region of the next key.  If no record corresponds or some errors occur,  `dptr'  is
              `NULL'.   `dptr'  points  to  the  region  related  with the handle.  The region is
              available  until  the  next  time  of  calling  this  function  or   the   function
              `dbm_firstkey' with the same handle.

       The function `dbm_error' is used in order to check whether a database has a fatal error or
       not.

       int dbm_error(DBM *db);
              `db' specifies a database handle.  The return value is true if the database  has  a
              fatal error, false if not.

       The function `dbm_clearerr' has no effect.

       int dbm_clearerr(DBM *db);
              `db' specifies a database handle.  The return value is 0.  The function is only for
              compatibility.

       The function `dbm_rdonly' is used in order to check whether a handle is read-only or not.

       int dbm_rdonly(DBM *db);
              `db' specifies a database handle.  The return  value  is  true  if  the  handle  is
              read-only, or false if not read-only.

       The function `dbm_dirfno' is used in order to get the file descriptor of a directory file.

       int dbm_dirfno(DBM *db);
              `db'  specifies  a database handle.  The return value is the file descriptor of the
              directory file.

       The function `dbm_pagfno' is used in order to get the file descriptor of a data file.

       int dbm_pagfno(DBM *db);
              `db' specifies a database handle.  The return value is the file descriptor  of  the
              data file.

       Functions  of  Relic are thread-safe as long as a handle is not accessed by threads at the
       same time, on the assumption that `errno', `malloc', and so on are thread-safe.

SEE ALSO

       qdbm(3), depot(3), curia(3), hovel(3), cabin(3), villa(3), odeum(3), ndbm(3), gdbm(3)