ndbm.h(0p) [posix man page]

<ndbm.h>(P)						     POSIX Programmer's Manual						       <ndbm.h>(P)

NAME

       ndbm.h - definitions for ndbm database operations

SYNOPSIS

       #include <ndbm.h>

DESCRIPTION

       The <ndbm.h> header shall define the datum type as a structure that includes at least the following members:

	      void   *dptr  A pointer to the application's data.
	      size_t  dsize The size of the object pointed to by dptr.

       The size_t type shall be defined as described in <stddef.h> .

       The <ndbm.h> header shall define the DBM type.

       The following constants shall be defined as possible values for the store_mode argument to dbm_store():

       DBM_INSERT
	      Insertion of new entries only.

       DBM_REPLACE
	      Allow replacing existing entries.

       The following shall be declared as functions and may also be defined as macros. Function prototypes shall be provided.

	      int     dbm_clearerr(DBM *);
	      void    dbm_close(DBM *);
	      int     dbm_delete(DBM *, datum);
	      int     dbm_error(DBM *);
	      datum   dbm_fetch(DBM *, datum);
	      datum   dbm_firstkey(DBM *);
	      datum   dbm_nextkey(DBM *);
	      DBM    *dbm_open(const char *, int, mode_t);
	      int     dbm_store(DBM *, datum, datum, int);

       The mode_t type shall be defined through typedef as described in <sys/types.h> .

       The following sections are informative.

APPLICATION USAGE

       None.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       <stddef.h> , <sys/types.h> , the System Interfaces volume of IEEE Std 1003.1-2001, dbm_clearerr()

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Standard for Information Technol-
       ogy -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
       Electrical  and	Electronics  Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE
       and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can  be  obtained
       online at http://www.opengroup.org/unix/online.html .

IEEE
/The Open Group						       2003							       <ndbm.h>(P)

DBM(3)							   BSD 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
     functions

SYNOPSIS

     #include <ndbm.h>

     int
     dbm_clearerr(DBM *db);

     void
     dbm_close(DBM *db);

     int
     dbm_delete(DBM *db, datum key);

     int
     dbm_dirfno(DBM *db);

     int
     dbm_error(DBM *db);

     datum
     dbm_fetch(DBM *db, datum key);

     datum
     dbm_firstkey(DBM *db);

     datum
     dbm_nextkey(DBM *db);

     DBM *
     dbm_open(const char *file, int open_flags, mode_t file_mode);

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

DESCRIPTION

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

     datum is declared in <ndbm.h>:

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

     The dbm_open(file, open_flags, file_mode) function opens or creates a database file.  The file argument is the basename of the file contain-
     ing the database; the actual database has a .db suffix.  I.e., if file is "/home/me/mystuff" then the actual database is in the file
     /home/me/mystuff.db.  The open_flags and file_mode arguments are passed to open(2).  (O_RDWR | O_CREAT) is a typical value for open_flags;
     0660 is a typical value for file_mode.  O_WRONLY is not allowed in open_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, content, store_mode) function inserts or replaces an entry in the database.  The store_mode argument is either
     DBM_INSERT or DBM_REPLACE.  If store_mode is DBM_INSERT and the database already contains an entry for key, that entry is not replaced.  Oth-
     erwise the entry is replaced or inserted.	The dbm_store() function normally returns zero but returns 1 if the entry could not be inserted
     (because store_mode 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 content corresponding to key.

     The dbm_delete(db, key) function deletes the entry for key.  The dbm_delete() function normally returns zero but returns 1 if there was no
     entry with key in the database 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
     returns 0.

     The dbm_dirfno(db) function returns the file descriptor to the database.

LEGACY SYNOPSIS

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

     The include file <ndbm.h> is necessary for all functions.

     DBM *
     dbm_open(const char *file, int open_flags, int file_mode);

     file_mode has type int.

SEE ALSO

     open(2), dbopen(3), hash(3), compat(5)

STANDARDS

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

BSD
								  April 16, 2006							       BSD