


RELIC(3)              Quick Database Manager             RELIC(3)


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 func-
       tions 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 direc-
       tory 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',



Man Page                    2004-04-22                          1





RELIC(3)              Quick Database Manager             RELIC(3)


       `sys/types.h', `sys/stat.h' and `fcntl.h' in the  source  files.   Usu-
       ally,  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 han-
              dle.

       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  val-
              ues:  `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.





Man Page                    2004-04-22                          2





RELIC(3)              Quick Database Manager             RELIC(3)


       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  struc-
              ture  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 struc-
              ture 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



Man Page                    2004-04-22                          3





RELIC(3)              Quick Database Manager             RELIC(3)


       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)





























Man Page                    2004-04-22                          4


