HOVEL(3)                    Quick Database Manager                    HOVEL(3)



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)



Man Page                          2004-04-22                          HOVEL(3)
