---
name: "db_hsearch"
section: "3db"
platform: "linux"
package: "libdb2-dev"
version: "2.4.14-1"
release: "Debian 2.1 (Slink)"
platforms: ["linux"]
url: "https://new.carta.tech/db_hsearch"
---

# db\_hsearch(3db)

hsearch, hcreate, hdestroy

## NAME

hsearch - hsearch, hcreate, hdestroy

## SYNOPSIS

```
#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);
```

## DESCRIPTION

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:

\#define DB\_DBM\_HSEARCH    1\
 \#include \<db2/db.h\>

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)](/memset/3.md).

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)](/memset/3.md),  and [strlen(3)](/strlen/3.md).

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.

## SEE ALSO

The DB library is a family of groups of functions that provides a modular programming interface to transactions and record-oriented file access. The library includes support for transactions, locking, logging and file page caching, as well as various indexed access methods. Many of the functional groups (e.g., the file page caching functions) are useful independent of the other DB functions, although some functional groups are explicitly based on other functional groups (e.g., transactions and logging). For a general description of the DB package, see *db\_intro*(3).

[*db\_archive*(1)](/db_archive/1.md), [*db\_checkpoint*(1)](/db_checkpoint/1.md), [*db\_deadlock*(1)](/db_deadlock/1.md), [*db\_dump*(1)](/db_dump/1.md), [*db\_load*(1)](/db_load/1.md), [*db\_recover*(1)](/db_recover/1.md), [*db\_stat*(1)](/db_stat/1.md), *db\_intro*(3), *db\_appinit*(3), *db\_cursor*(3), *db\_dbm*(3), *db\_internal*(3), *db\_lock*(3), *db\_log*(3), *db\_mpool*(3), *db\_open*(3), *db\_thread*(3), *db\_txn*(3)