[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
19.1 NDBM interface functions.
The functions below implement the POSIX ‘ndbm’ interface:
- ndbm: DBM * dbm_open (char *file, int flags, int mode)
Opens a database. The file argument is the full name of the database file to be opened. The function opens two files: ‘file.pag’ and ‘file.dir’. The flags and mode arguments have the same meaning as the second and third arguments of open(2), except that a database opened for write-only access opens the files for read and write access and the behavior of the
O_APPEND
flag is unspecified.The function returns a pointer to the
DBM
structure describing the database. This pointer is used to refer to this database in all operations described below.Any error detected will cause a return value of ‘NULL’ and an appropriate value will be stored in
gdbm_errno
(see section Useful global variables.).
- ndbm: void dbm_close (DBM *dbf)
Closes the database. The dbf argument must be a pointer returned by an earlier call to
dbm_open
.
- ndbm: datum dbm_fetch (DBM *dbf, datum key)
Reads a record from the database with the matching key. The key argument supplies the key that is being looked for.
If no matching record is found, the
dptr
member of the returned datum is ‘NULL’. Otherwise, thedptr
member of the returned datum points to the memory managed by the compatibility library. The application should never free it.
- ndbm: int dbm_store (DBM *dbf, datum key, datum content, int mode)
Writes a key/value pair to the database. The argument dbf is a pointer to the
DBM
structure returned from a call todbm_open
. The key and content provide the values for the record key and content. The mode argument controls the behavior ofdbm_store
in case a matching record already exists in the database. It can have one of the following two values:DBM_REPLACE
Replace existing record with the new one.
DBM_INSERT
The existing record is left unchanged, and the function returns ‘1’.
If no matching record exists in the database, new record will be inserted no matter what the value of the mode is.
- ndbm: int dbm_delete (DBM *dbf, datum key)
Deletes the record with the matching key from the database. If the function succeeds, ‘0’ is returned. Otherwise, if no matching record is found or if an error occurs, ‘-1’ is returned.
- ndbm: datum dbm_firstkey (DBM *dbf)
Initializes iteration over the keys from the database and returns the first key. Note, that the word ‘first’ does not imply any specific ordering of the keys.
If there are no records in the database, the
dptr
member of the returned datum is ‘NULL’. Otherwise, thedptr
member of the returned datum points to the memory managed by the compatibility library. The application should never free it.
- ndbm: datum dbm_nextkey (DBM *dbf)
Continues the iteration started by
dbm_firstkey
. Returns the next key in the database. If the iteration covered all keys in the database, thedptr
member of the returned datum is ‘NULL’. Otherwise, thedptr
member of the returned datum points to the memory managed by the compatibility library. The application should never free it.The usual way of iterating over all the records in the database is:
for (key = dbm_firstkey (dbf); key.ptr; key = dbm_nextkey (dbf)) { /* do something with the key */ }
The loop above should not try to delete any records from the database, otherwise the iteration is not guaranteed to cover all the keys. See section Sequential access to records., for a detailed discussion of this.
- ndbm: int dbm_error (DBM *dbf)
Returns the error condition of the database: ‘0’ if no errors occurred so far while manipulating the database, and a non-zero value otherwise.
- ndbm: int dbm_dirfno (DBM *dbf)
Returns the file descriptor of the ‘dir’ file of the database. It is guaranteed to be different from the descriptor returned by the
dbm_pagfno
function (see below).The application can lock this descriptor to serialize accesses to the database.
- ndbm: int dbm_pagfno (DBM *dbf)
Returns the file descriptor of the ‘pag’ file of the database. See also
dbm_dirfno
.
- ndbm: int dbm_rdonly (DBM *dbf)
Returns ‘1’ if the database dbf is open in a read-only mode and ‘0’ otherwise.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated on January 24, 2014 using texi2html 5.0.