Provided by: libqdbm-dev_1.8.78-12.1build2_amd64 bug

NAME

       Hovel - the GDBM-compatible API of QDBM

SYNOPSIS

       #include <hovel.h>
       #include <stdlib.h>
       #include <sys/types.h>
       #include <sys/stat.h>

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

       extern char *gdbm_version;

       extern gdbm_error gdbm_errno;

       char *gdbm_strerror(gdbm_error gdbmerrno);

       GDBM_FILE   gdbm_open(char   *name,   int  block_size,  int  read_write,  int  mode,  void
       (*fatal_func)(void));

       GDBM_FILE gdbm_open2(char *name, int read_write, int mode, int bnum, int dnum, int align);

       void gdbm_close(GDBM_FILE dbf);

       int gdbm_store(GDBM_FILE dbf, datum key, datum content, int flag);

       int gdbm_delete(GDBM_FILE dbf, datum key);

       datum gdbm_fetch(GDBM_FILE dbf, datum key);

       int gdbm_exists(GDBM_FILE dbf, datum key);

       datum gdbm_firstkey(GDBM_FILE dbf);

       datum gdbm_nextkey(GDBM_FILE dbf, datum key);

       void gdbm_sync(GDBM_FILE dbf);

       int gdbm_reorganize(GDBM_FILE dbf);

       int gdbm_fdesc(GDBM_FILE dbf);

       int gdbm_setopt(GDBM_FILE dbf, int option, int *value, int size);

DESCRIPTION

       Hovel is the API which is compatible with GDBM.  So, Hovel wraps functions  of  Depot  and
       Curia  as  API  of  GDBM.   It  is easy to port an application from GDBM to QDBM.  In most
       cases, you should only replace the includings of `gdbm.h' with `hovel.h' and  replace  the
       linking  option  `-lgdbm'  with  `-lqdbm'.  Hovel cannot handle database files made by the
       original GDBM.

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

              #include <hovel.h>
              #include <stdlib.h>
              #include <sys/types.h>
              #include <sys/stat.h>

       An object of `GDBM_FILE' is used as a database handle.  A database handle is  opened  with
       the  function  `gdbm_open' and closed with `gdbm_close'.  You should not refer directly to
       any member of a handle.  Although Hovel works as a wrapper of Depot and handles a database
       file  usually,  if you use the function `gdbm_open2' to open the handle, it is possible to
       make behavior of a handle as a wrapper of Curia and treat a database directory.

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

       typedef struct { char *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 external variable `gdbm_version' is the string containing the version information.

       extern char *gdbm_version;

       The external variable `gdbm_errno' is assigned with the last happened error  code.   Refer
       to `hovel.h' for details of the error codes.

       extern gdbm_error gdbm_errno;
              The  initial  value  of  this  variable  is  `GDBM_NO_ERROR'.  The other values are
              `GDBM_MALLOC_ERROR',        `GDBM_BLOCK_SIZE_ERROR',        `GDBM_FILE_OPEN_ERROR',
              `GDBM_FILE_WRITE_ERROR',       `GDBM_FILE_SEEK_ERROR',      `GDBM_FILE_READ_ERROR',
              `GDBM_BAD_MAGIC_NUMBER',       `GDBM_EMPTY_DATABASE',        `GDBM_CANT_BE_READER',
              `GDBM_CANT_BE_WRITER',     `GDBM_READER_CANT_DELETE',     `GDBM_READER_CANT_STORE',
              `GDBM_READER_CANT_REORGANIZE',    `GDBM_UNKNOWN_UPDATE',     `GDBM_ITEM_NOT_FOUND',
              `GDBM_REORGANIZE_FAILED',        `GDBM_CANNOT_REPLACE',        `GDBM_ILLEGAL_DATA',
              `GDBM_OPT_ALREADY_SET', and `GDBM_OPT_ILLEGAL'.

       The function `gdbm_strerror' is used in order to get a message string corresponding to  an
       error code.

       char *gdbm_strerror(gdbm_error gdbmerrno);
              `gdbmerrno' specifies an error code.  The return value is the message string of the
              error code.  The region of the return value is not writable.

       The function `gdbm_open' is used in order to get a database handle after  the  fashion  of
       GDBM.

       GDBM_FILE   gdbm_open(char   *name,   int  block_size,  int  read_write,  int  mode,  void
       (*fatal_func)(void));
              `name' specifies the name of a database.  `block_size'  is  ignored.   `read_write'
              specifies   the   connection   mode:  `GDBM_READER'  as  a  reader,  `GDBM_WRITER',
              `GDBM_WRCREAT' and `GDBM_NEWDB' as a writer.  `GDBM_WRCREAT' makes a database  file
              or  directory  if  it does not exist.  `GDBM_NEWDB' makes a new database even if it
              exists.  You can add the following to writer  modes  by  bitwise  or:  `GDBM_SYNC',
              `GDBM_NOLOCK',  `GDBM_LOCKNB', `GDBM_FAST', and `GDBM_SPARSE'.  `GDBM_SYNC' means a
              database is synchronized  after  every  updating  method.   `GDBM_NOLOCK'  means  a
              database  is  opened  without  file  locking.   `GDBM_LOCKNB' means file locking is
              performed without blocking.  `GDBM_FAST' is ignored.  `GDBM_SPARSE' is an  original
              mode of QDBM and makes database a sparse file.  `mode' specifies mode of a database
              file as the one of `open' call does.  `fatal_func' is ignored.  The return value is
              the database handle or `NULL' if it is not successful.

       The  function  `gdbm_open2' is used in order to get a database handle after the fashion of
       QDBM.

       GDBM_FILE gdbm_open2(char *name, int read_write, int mode, int bnum, int dnum, int align);
              `name' specifies the name of a database.   `read_write'  specifies  the  connection
              mode:  `GDBM_READER' as a reader, `GDBM_WRITER', `GDBM_WRCREAT' and `GDBM_NEWDB' as
              a writer.  `GDBM_WRCREAT' makes a database file or directory if it does not  exist.
              `GDBM_NEWDB'  makes a new database even if it exists.  You can add the following to
              writer modes by bitwise or: `GDBM_SYNC', `GDBM_NOLOCK', `GDBM_LOCKNB', `GDBM_FAST',
              and  `GDBM_SPARSE'.   `GDBM_SYNC'  means  a  database  is  synchronized after every
              updating method.  `GDBM_NOLOCK' means a database is opened  without  file  locking.
              `GDBM_LOCKNB'  means  file  locking  is performed without blocking.  `GDBM_FAST' is
              ignored.  `GDBM_SPARSE' is an original mode  of  QDBM  and  makes  database  sparse
              files.   `mode'  specifies a mode of a database file or a database directory as the
              one of `open' or `mkdir' call does.  `bnum' specifies the  number  of  elements  of
              each  bucket  array.   If  it  is  not more than 0, the default value is specified.
              `dnum' specifies the number of division of the database.  If it is not more than 0,
              the  returning handle is created as a wrapper of Depot, else, it is as a wrapper of
              Curia.  `align' specifies the basic size of alignment.  The  return  value  is  the
              database handle or `NULL' if it is not successful.  If the database already exists,
              whether it is one of Depot or Curia is measured automatically.

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

       void gdbm_close(GDBM_FILE dbf);
              `dbf' specifies a database handle.  Because the region  of  the  closed  handle  is
              released, it becomes impossible to use the handle.

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

       int gdbm_store(GDBM_FILE dbf, datum key, datum content, int flag);
              `dbf'  specifies  a  database  handle  connected  as  a  writer.  `key' specifies a
              structure of a key.  `content' specifies a structure of a value.  `flag'  specifies
              behavior  when  the  key  overlaps,  by the following values: `GDBM_REPLACE', which
              means the specified value overwrites the existing one, `GDBM_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 `gdbm_delete' is used in order to delete a record.

       int gdbm_delete(GDBM_FILE dbf, datum key);
              `dbf' specifies a database  handle  connected  as  a  writer.   `key'  specifies  a
              structure  of  a key.  The return value is 0 if it is successful, -1 if some errors
              occur.

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

       datum gdbm_fetch(GDBM_FILE dbf, datum key);
              `dbf' 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'.  Because the region pointed to
              by `dptr' is allocated with the `malloc' call,  it  should  be  released  with  the
              `free' call if it is no longer in use.

       The function `gdbm_exists' is used in order to check whether a record exists or not.

       int gdbm_exists(GDBM_FILE dbf, datum key);
              `dbf'  specifies  a  database  handle.   `key' specifies a structure of a key.  The
              return value is true if a record corresponds and no error occurs, or  false,  else,
              it is false.

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

       datum gdbm_firstkey(GDBM_FILE dbf);
              `dbf'  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'.  Because the region pointed to by `dptr' is  allocated  with  the  `malloc'
              call, it should be released with the `free' call if it is no longer in use.

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

       datum gdbm_nextkey(GDBM_FILE dbf, datum key);
              `dbf'  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'.  Because the region pointed to by `dptr' is  allocated  with  the  `malloc'
              call, it should be released with the `free' call if it is no longer in use.

       The  function  `gdbm_sync' is used in order to synchronize updating contents with the file
       and the device.

       void gdbm_sync(GDBM_FILE dbf);
              `dbf' specifies a database handle connected as a writer.

       The function `gdbm_reorganize' is used in order to reorganize a database.

       int gdbm_reorganize(GDBM_FILE dbf);
              `dbf' specifies a database handle connected as a writer.  If successful, the return
              value is 0, else -1.

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

       int gdbm_fdesc(GDBM_FILE dbf);
              `dbf'  specifies  a database handle connected as a writer.  The return value is the
              file descriptor of the database file.  If the database is a  directory  the  return
              value is -1.

       The function `gdbm_setopt' has no effect.

       int gdbm_setopt(GDBM_FILE dbf, int option, int *value, int size);
              `dbf'  specifies  a database handle.  `option' is ignored.  `size' is ignored.  The
              return value is 0.  The function is only for compatibility.

       If QDBM was built with POSIX thread enabled, the global variable `gdbm_errno'  is  treated
       as  thread  specific  data,  and functions of Hovel are reentrant.  In that case, they 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), relic(3), cabin(3), villa(3), odeum(3), ndbm(3), gdbm(3)