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

FreeBSD Manual Pages

  
 
  

home | help
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 func-
       tions 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	direc-
       tory 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 en-
       tities of each records.	Relic creates the directory  file  as  a  mere
       dummy  file  and	creates	the data file as a database.  Relic has	no re-
       striction 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.	  Usu-
       ally,  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  ad-
	      ditional	flags  except  for `O_CREAT' and `O_TRUNC' have	no ef-
	      fect.  `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 han-
	      dle.

       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  val-
	      ues:  `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  oc-
	      curs.

       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 re-
	      gion 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	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'.
	      `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	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'.
	      `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)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

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

home | help