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
       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)



Man Page                          2004-04-22                          RELIC(3)
