Standards
| Standards / Extensions |
C or C++ |
Dependencies |
|---|
XPG4.2
Single UNIX Specification, Version 3
|
both |
|
Format
#define _XOPEN_SOURCE_EXTENDED 1
#include <ndbm.h>
DBM *dbm_open(const char *file, int open_flags, mode_t file_mode);
General description
The dbm_open() function
opens a database. The file argument is
the path name of the database, not including the filename suffix (the
part after the .). The database is stored in two files. One file
is a directory containing a bit map of blocks in use and has .dir
as its suffix. The second file contains all the data and has .pag
as its suffix. The open_flags argument
has the same meaning as the flags argument
of open() except that a database opened for write-only access opens
the files for read and write access. The file_mode argument
has the same meaning as the third argument of open().
The number
of records that can be stored in the database is limited by the file
space available for the .dir and .pag files, and by the underlying
key hashing. If multiple keys hash to the same 32 bit hash value,
the number of keys for that hash value is limited to the amount of
data (key sizes plus content sizes plus overhead) that can be stored
in a single logical block of 1024 bytes.
Special behavior
for z/OS® UNIX Services: In
a multithreaded environment, the dbm_ functions have both POSIX process
wide and thread-specific characteristics. z/OS UNIX services
provide the following multithreaded behavior:
- A database handle returned by the dbm_open() function is a process
wide resource. This means that multiple threads within the process
can access the database using the same database handle.
- Each thread using a given database handle has its own positioning
information for dbm_firstkey() and dbm_nextkey() operations. This
means that multiple threads can each be executing a dbm_nextkey()
loop.
- Each thread using a given database handle has its own buffering
for dbm_fetch() operations. This means that a pointer to a keys content
(as returned by dbm_fetch()) remains valid, even if other threads
modify the database.
- Database modifications are automatically reflected to all of the
threads using the same database handle. For example, if a thread
adds a key/data pair using dbm_store(), a dbm_fetch() of that key
by another thread will be successful.
- Operations which modify the database, such as dbm_store() and
dbm_delete(), can cause unpredictable results to threads executing
dbm_nextkey(). If a database modification is done, all threads should
reset positioning using a dbm_firstkey() call before executing dbm_nextkey().
- A dbm_close() operation removes access to the database for all
threads that use the database handle.
- Multiple dbm_open() operations, whether by a single thread, multiple
threads within a process, or by multiple processes are permitted,
but for read access only. No protection is provided for database modification,
and modification can result in unpredictable results, including database
destruction.
Returned value
If successful, dbm_open()
returns a pointer to the database descriptor.
If unsuccessful,
dbm_open() returns a NULL pointer and stores the error value in errno.