NDBM(3B)							      NDBM(3B)

NAME    [Toc]    [Back]

     ndbm: dbm_open, dbm_open64, dbm_close, dbm_close64, dbm_fetch,
     dbm_fetch64, dbm_store, dbm_store64, dbm_delete, dbm_delete64,
     dbm_firstkey, dbm_firstkey64, dbm_nextkey,	dbm_nextkey64, dbm_error,
     dbm_error64, dbm_clearerr , dbm_clearerr64	- data base subroutines

SYNOPSIS    [Toc]    [Back]

     #include <ndbm.h>

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

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

     DBM64 *dbm_open64(const char *file, int flags, mode_t mode);

     void dbm_close(DBM	*db);

     void dbm_close64(DBM64 *db);

     datum dbm_fetch(DBM *db, datum key);

     datum dbm_fetch64(DBM64 *db, datum	key);

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

     int dbm_store64(DBM64 *db,	datum key, datum content, int flags);

     int dbm_delete(DBM	*db, datum key);

     int dbm_delete64(DBM64 *db, datum key);

     datum dbm_firstkey(DBM *db);

     datum dbm_firstkey64(DBM64	*db);

     datum dbm_nextkey(DBM *db);

     datum dbm_nextkey64(DBM64 *db);

     int dbm_error(DBM *db);

     int dbm_error64(DBM64 *db);

     int dbm_clearerr(DBM *db);

     int dbm_clearerr64(DBM64 *db);






									Page 1






NDBM(3B)							      NDBM(3B)

DESCRIPTION    [Toc]    [Back]

     These functions maintain key/content pairs	in a data base.	 The ndbm
     functions will handle very	large (a billion blocks) databases and will
     access a keyed item in one	or two file system accesses.  The ndbm64
     functions are identical to	the ndbm routines except that they can be used
     to	operate	on databases larger than 2 Gigabytes.  This package replaces
     the earlier dbm(3B) library, which	managed	only a single database.

     Keys and contents are described by	the datum typedef.  A datum specifies
     a string of dsize bytes pointed to	by dptr. Arbitrary binary data,	as
     well as normal ASCII strings, are allowed.	 The data base is stored in
     two files.	 One file is a directory containing a bit map and has `.dir'
     as	its suffix.  The second	file contains all data and has `.pag' as its
     suffix.

     Before a database can be accessed,	it must	be opened by dbm_open.	This
     will open and/or create the files file.dir	and file.pag depending on the
     flags parameter (see open(2)).

     Once open,	the data stored	under a	key is accessed	by dbm_fetch and data
     is	placed under a key by dbm_store.  The flags field can be either
     DBM_INSERT	or DBM_REPLACE.	DBM_INSERT will	only insert new	entries	into
     the database and will not change an existing entry	with the same key.
     DBM_REPLACE will replace an existing entry	if it has the same key.	 A key
     (and its associated contents) is deleted by dbm_delete.  A	linear pass
     through all keys in a database may	be made, in an (apparently) random
     order, by use of dbm_firstkey and dbm_nextkey.  Dbm_firstkey will return
     the first key in the database.  Dbm_nextkey will return the next key in
     the database.  The	following code will traverse the data base:

	  for (key = dbm_firstkey(db);
	       key.dptr	!= NULL;
	       key = dbm_nextkey(db))


     Dbm_error returns non-zero	when an	error has occurred reading or writing
     the database.  Dbm_clearerr resets	the error condition on the named
     database.

DIAGNOSTICS    [Toc]    [Back]

     All functions that	return an int indicate errors with negative values.  A
     zero return indicates ok.	Routines that return a datum indicate errors
     with a null (0) dptr. If dbm_store	called with a flags value of
     DBM_INSERT	finds an existing entry	with the same key it returns 1.

     Some error	conditions will	set errno. These are:  ENOMEM: runtime memory
     allocation	failed;	EPERM: file permissions	don't match the	process
     euid/egid permissions; EINVAL: key+data sizes for dbm_store exceed	the
     internal block size; EFBIG: hash table overflow would cause the maximum
     dbm file size to be exceeded.





									Page 2






NDBM(3B)							      NDBM(3B)

SEE ALSO    [Toc]    [Back]

     dbm(3B) and Berkeley db: dbopen(3)

BUGS    [Toc]    [Back]

     The `.pag'	file is	designed to contain holes in files.  The EFS file
     system does not implement holes, so the file will frequently be
     significantly larger than the actual content.

     Dptr pointers returned by these subroutines point into static storage
     that is changed by	subsequent calls.

     dbm databases may not be portable across machines with different
     alignment restrictions or different byte sexes.

     Dptr pointers returned by these subroutines point into possibly non word
     aligned storage. You cannot assume	that you can cast the Dptr pointer
     into an arbitrary data type and dereference it.  This is a	general	rule
     in	ANSI-C rather than dbm specific, but users often hit it	while using
     dbm.

     The sum of	the sizes of a key/content pair	must not exceed	the internal
     block size	minus the dbm small book-keeping overhead (currently: _PBLKSIZ
     - 6 = 1018	bytes).	 Moreover all key/content pairs	that hash together
     must fit on a single block.  For a	dbm-like implementation	with much less
     size limitations, check out dbopen(3) (Berkeley DB).

     Dbm_store will return an error in the event that a	disk block fills with
     inseparable data.

     Dbm_delete	does not physically reclaim file space,	although it does make
     it	available for reuse.

     The order of keys presented by dbm_firstkey and dbm_nextkey depends on a
     hashing function, not on anything interesting.


									PPPPaaaaggggeeee 3333