Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 func-
       tions 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 fol-
       lowing 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 han-
       dle   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  ver-
       sion 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_CAN-
	      NOT_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 af-
       ter 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 ig-
	      nored.	`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 ig-
	      nored.  `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 af-
       ter 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	updat-
	      ing 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  re-
	      turning  handle is created as a wrapper of Depot,	else, it is as
	      a	wrapper	of Curia.  `align' specifies the basic size of	align-
	      ment.   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 han-
	      dle.

       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 suc-
	      cessful,	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	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'.
	      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	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'.
	      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 con-
       tents 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	 data-
       base.

       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)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=hovel&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help