db_hsearch3db

Usage

#define DB_DBM_HSEARCH    1
#include <db2/db.h>
typedef enum {
        FIND, ENTER
} ACTION;
typedef struct entry {
        char *key;
        void *data;
} ENTRY;
ENTRY *
hsearch(ENTRY item, ACTION action);
int
hcreate(size_t nelem);
void
hdestroy(void);

Overview

The hsearch interface to the DB library is intended to provide source code compatibility for historic applications. It is not recommended for any other purpose.

To compile hsearch applications, replace the application's #include of the hsearch include file (e.g., ``#include <search.h>'') with the following two lines:

and recompile.

The hcreate function creates an in-memory database. The nelem argument is an estimation of the maximum number of key/data pairs that will be stored in the database.

The hdestroy function discards the database.

Database elements are structures of type ENTRY, which contain at least two fields: key and data. The field key is declared to be of type ``char *'' and is the key used for storage and retrieval. The field data is declared to be of type ``void *'' and is its associated data.

The hsearch function retrieves key/data pairs from, and stores key/data pairs into, the database.

The action argument must be set to one of two values:

ENTER

If the key does not already appear in the database, insert the key/data pair into the database. If the key already appears in the database, return a reference to an ENTRY structure referencing the existing key and its associated data element.

FIND

Retrieve the specified key/data pair from the database.

Compatibility notes

Historically, hsearch required applications to maintain the keys and data in the application's memory for as long as the hsearch database existed. As DB handles key and data management internally, there is no requirement that applications maintain local copies of key and data items, although the only effect of doing so should be the allocation of additional memory.

Diagnostics

The hcreate function returns 0 on failure, setting errno, and non-zero on success.

The hsearch function returns a pointer to an ENTRY structure on success, and NULL, setting errno, if the action specified was FIND and the item did not appear in the database.

Errors

The hcreate function may fail and return errno for any of the errors specified for the following DB and library functions: db_open(3), and memset(3).

The hsearch function may fail and return errno for any of the errors specified for the following DB and library functions: DB->get(3), DB->put(3), memset(3), and strlen(3).

In addition, the hsearch function will fail, setting errno to 0, if the action specified was FIND and the item did not appear in the database.