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 appli-
       cation 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 follow-
       ing 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' speci-
	      fies 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 suc-
	      cessful, -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  com-
	      patibility.

       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)