Open System Services Library Calls Reference Manual (G06.29+, H06.08+, J06.03+)

dbm_clearerr(3) OSS Library Calls Reference Manual
If the db parameter does not point to a database structure, the results are undefined and [EIN-
VAL] is returned.
CAUTIONS
The dptr pointer returned by some of these functions may point to static storage that may be
overwritten by future function calls.
The dbm_delete( ) function only makes file space available for future use; it does not physically
reclaim the space.
If, while making a pass through the database with the dbm_firstkey( ) and dbm_nextkey( ) func-
tions, either dbm_store( ) or dbm_delete() is called, dbm_firstkey( ) should be called to reset
the database before again calling dbm_nextkey( ).
Be careful when using the dbm_open( ) function with files in the Guardian (/G) file system. If
the file parameter is longer than five characters, the dbm_open( ) function appends the .pag and
.dir extensions accordingly, but the Guardian file system then removes the . character and trun-
cates the name to the eight character maximum, thereby creating two filenames that are identical.
RETURN VALUES
The dbm_open( ) function returns a pointer to a database structure. If an error occurs, it returns (
"DBM *" )0 and sets errno.
The dbm_close( ) function does not return a value.
The dbm_fetch( ) function returns a datum structure with the contents of the specified record. If
the database does not contain a record with a key that matches the key parameter, or an error
occurs, the dptr field of the datum structure is a null pointer. When an error occurs, errno is set.
The dbm_store( ) function returns 1 if it was called with a flag value of DBM_INSERT and an
existing record was found with the same key. It returns 0 (zero) for other successes, and negative
values for failures. When the failure is due to an error, errno is set.
The dbm_delete( ) function returns 0 (zero) when it succeeds, and a negative value when it fails.
When the failure is due to an error, errno is set.
The dbm_firstkey( ) and dbm_nextkey( ) functions return a key datum that is the key to a
record in the database. When the end of a database is reached, the dptr field of the datum is a
null pointer. If an error is detected, the dptr value is also set to null and the error condition of the
database is set.
The dbm_error() function returns 0 (zero) if the database’s error condition is not set, and a
nonzero value if it is set.
The return value of the dbm_clearerr( ) function is unspecified.
EXAMPLES
The following code can be used to traverse the database:
for (key = dbm.firstkey(db); key.dptr !=NULL; key = dbm_netkey(db))
ERRORS
If the following condition occurs, these functions set errno to the corresponding value:
[EINVAL] An invalid parameter was passed to the function.
[ENOMEM] There was insufficient storage space available.
[ENOPERM] A write operation was attempted on a read-only database.
Other errno values may be returned for I/O operations from a failed internal system call to
open(|), read(), write( ), and lseek().
1−176 Hewlett-Packard Company 527187-017