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

FreeBSD Manual Pages

  
 
  

home | help 
DBM(3)			    Library Functions Manual			DBM(3)

NAME
       dbm_clearerr,  dbm_close, dbm_delete, dbm_dirfno, dbm_error, dbm_fetch,
       dbm_firstkey, dbm_nextkey, dbm_open, dbm_store -- database access func-
       tions

SYNOPSIS
       #include	<fcntl.h>
       #include	<ndbm.h>

       DBM *
       dbm_open(const char *base, int flags, mode_t mode);

       void
       dbm_close(DBM *db);

       int
       dbm_store(DBM *db, datum	key, datum data, int flags);

       datum
       dbm_fetch(DBM *db, datum	key);

       int
       dbm_delete(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_dirfno(DBM *db);

DESCRIPTION
       Database	access	functions.   These  functions  are  implemented	 using
       dbopen(3) with a	hash(3)	database.

       datum is	declared in <ndbm.h>:

       typedef struct {
	       void *dptr;
	       int dsize;
       } datum;

       The  dbm_open(base,  flags, mode) function opens	or creates a database.
       The base	argument is the	basename of the	file containing	the  database;
       the   actual   database	 has   a   .db	 suffix.   I.e.,  if  base  is
       "/home/me/mystuff"  then	 the  actual   database	  is   in   the	  file
       /home/me/mystuff.db.   The  flags  and  mode  arguments	are  passed to
       open(2).	 (O_RDWR | O_CREAT) is a typical value for flags;  0660	 is  a
       typical value for mode.	O_WRONLY is not	allowed	in flags.  The pointer
       returned	 by  dbm_open()	identifies the database	and is the db argument
       to the other functions.	The dbm_open() function	returns	NULL and  sets
       errno if	there were any errors.

       The dbm_close(db) function closes the database.

       The dbm_store(db, key, data, flags) function inserts or replaces	an en-
       try  in	the  database.	 The  flags  argument  is either DBM_INSERT or
       DBM_REPLACE.  If	flags is DBM_INSERT and	the database already  contains
       an  entry  for key, that	entry is not replaced.	Otherwise the entry is
       replaced	or inserted.  The dbm_store() function normally	 returns  zero
       but  returns  1	if  the	 entry could not be inserted (because flags is
       DBM_INSERT, and an entry	with key already exists)  or  returns  -1  and
       sets errno if there were	any errors.

       The  dbm_fetch(db, key) function	returns	NULL or	the data corresponding
       to key.

       The dbm_delete(db, key)	function  deletes  the	entry  for  key.   The
       dbm_delete()  function  normally	 returns  zero	or returns -1 and sets
       errno if	there were any errors.

       The dbm_firstkey(db) function returns the first key  in	the  database.
       The    dbm_nextkey(db)	function   returns   subsequent	  keys.	   The
       db_firstkey() function must be called before dbm_nextkey().  The	 order
       in  which  keys are returned is unspecified and may appear random.  The
       dbm_nextkey() function returns NULL after all keys have been returned.

       The dbm_error(db) function returns the errno value of the  most	recent
       error.	The  dbm_clearerr(db)  function	resets this value to 0 and re-
       turns 0.

       The dbm_dirfno(db) function returns the file descriptor	to  the	 data-
       base.

SEE ALSO
       open(2),	dbopen(3), hash(3)

STANDARDS
       These  functions	(except	dbm_dirfno()) are included in the Version 2 of
       the Single UNIX Specification ("SUSv2").

HISTORY
       The functions dbminit(),	fetch(), store(),  delete(),  firstkey(),  and
       nextkey() first appeared	in Version 7 AT&T UNIX.

FreeBSD	14.3			 April 2, 2022				DBM(3)

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

home | help