Content-type: text/html Man page of ndbm

ndbm

Section: C Library Functions (3)
Index Return to Main Contents
 

NAME

dbm_clearerr, dbm_close, dbm_delete, dbm_error, dbm_fetch, dbm_firstkey, dbm_forder, dbm_nextkey, dbm_open, dbm_setpblksiz, dbm_store - Database subroutines  

SYNOPSIS

#include <ndbm.h>

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

int dbm_clearerr(
        DBM *db);

void dbm_close(
        DBM *db);

int dbm_delete(
        DBM *db,        datum key);

int dbm_error(
        DBM *db);

datum dbm_fetch(
        DBM *db,
        datum key);

datum dbm_firstkey(
        DBM *db);

long dbm_forder(
        DBM *db,
        datum key);

datum dbm_nextkey(
        DBM *db);

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

int dbm_setpblksiz(
        DBM *db,
        int size);

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

The following declarations do not conform to current standards and are supported only for backward compatibility:

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

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

STANDARDS

Interfaces documented by this reference page conform to industry standards as follows:

XPG4-UNIX: dbm_clearerr, dbm_close, dbm_delete, dbm_error, dbm_fetch, dbm_firstkey, dbm_nextkey, dbm_open, dbm_store

Refer to the standards(5) reference page for more information about industry standards and associated tags.  

PARAMETERS

Specifies a value associated with key. Points to a database structure that has been returned from a call to the dbm_open() function. Specifies the file to be opened. If the file parameter refers to a symbolic link, the dbm_open() function opens the file pointed to by the symbolic link. See the open(2) reference page for further details. Specifies the type of access, special open processing, the type of update, and the initial state of the open file. The parameter value is constructed by logically ORing special processing flags described in the fcntl.h header file. See the open(2) reference page for further details. A datum that has been initialized by the application program to the value of the key that identifies the record that the program is handling. Specifies the read, write, and execute permissions of the file to be created (requested by the O_CREAT flag). If the file already exists, this parameter is ignored. This parameter is constructed by logically ORing values described in the sys/mode.h header file. See the open(2) reference page for further details. The new page file block size set by dbm_setpblksiz(). This function forces values to a minimum setting of 1024 bytes and a maximum setting of 32,768 bytes. It also rounds values up to a multiple of 1024. Specifies one of the following flags to dbm_store(): Only insert new entries into the database. Do not change an existing entry with the same key. Replace an existing entry if it has the same key.  

DESCRIPTION

The dbm_open(), dbm_close(), dbm_fetch(), dbm_store(), dbm_delete(), dbm_firstkey(), dbm_nextkey(), dbm_forder(), dbm_setpblksiz(), dbm_error(), and dbm_clearerr() functions maintain key/content pairs in a database. The functions handle very large databases (a billion blocks) and access a keyed item in one or two file system accesses. Arbitrary binary data, as well as normal ASCII strings, are allowed.

The database 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 the dbm_open() function. The dbm_open() function opens (and if necessary, creates) the file.dir and file.pag files, depending on the flags parameter. The flags parameter has the same meaning as the oflag parameter of open() except that a database opened for write-only access opens the files for read and write access.

Once open, the data stored under a key is accessed by the dbm_fetch() function and data is placed under a key by the dbm_store() function. The store_mode parameter controls whether dbm_store() replaces any preexisting record whose key matches the key specified by the key parameter.

The dbm_delete() function deletes a record and its key from the database.

The dbm_firstkey() and dbm_nextkey() functions can be used to make a linear pass through all keys in a database, in an (apparently) random order. The dbm_firstkey() function returns the first key in the database. The dbm_nextkey() function returns the next key in the database. The order of keys presented by the dbm_firstkey() and dbm_nextkey() functions depends on a hashing function.

The following code traverses the database: for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))

The dbm_setpblksiz() function sets the page file block size, which is 1024 bytes by default. This function should only be called immediately after a call to dbm_open() and prior to calls to other ndbm functions. For an existing database, dbm_open() automatically sets the page file block size to the size set at the time of its creation.

The dbm_error() function returns the error condition of the database.

The dbm_clearerr() function clears the error condition of the database.

[Digital]  The dbm_forder() function returns the block number in the .pag file to which the specified key maps.  

NOTES

[Digital]  When compiled in the X/Open UNIX environment, calls to the dbm_delete(), dbm_fetch(), dbm_firstkey(), dbm_forder(), dbm_nextkey(), and dbm_store() functions are internally renamed by prepending _E to the function name. When you are debugging a module that includes any of these functions and for which _XOPEN_SOURCE_EXTENDED has been defined, use _Ename to refer to the name() call. For example, use _Edbm_delete to refer to the dbm_delete call. See standards(5) for further information.

When using key structures containing gaps, make sure that the whole structure, including gaps, is initialized to a known value; otherwise, the keys may not match.  

RETURN VALUES

Upon successful completion, all functions that return an int return a value of 0 (zero). Otherwise, a negative value is returned.

Functions that return a datum indicate errors with a null (0) dptr.

The dbm_store() function returns 1 if it is called with a flags value of DBM_INSERT and the function finds an existing entry with the same key.  

ERRORS

If any of the following conditions occurs, the dbm_open(), dbm_delete(), and dbm_store() functions set errno to the value that corresponds to the condition: [Digital]  Insufficient space to allocate a buffer. [Digital]  An attempt was made to store or delete a key (and its associated contents) in a database that was opened read-only. [Digital]  An attempt was made to store a key whose size exceeds the page block size limit as defined by PBLKSIZ in /usr/include/ndbm.h or a key whose size plus the size of its associated contents exceeds the page block size limit set by dbm_setpblksiz().  

RELATED INFORMATION

Functions: dbm(3), open(2)

Standards: standards(5) delim off


 

Index

NAME
SYNOPSIS
STANDARDS
PARAMETERS
DESCRIPTION
NOTES
RETURN VALUES
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:42:28 GMT, October 02, 2010