hsearch, hcreate, or hdestroy Subroutine

Purpose

Manages hash tables.

Library

Standard C Library (libc.a)

Syntax

#include <search.h>

ENTRY *hsearch ( Item,  Action)
ENTRY Item;
Action Action;

int hcreate ( NumberOfElements)
size_t NumberOfElements;
void hdestroy ( )

Description

Attention: Do not use the hsearch, hcreate, or hdestroy subroutine in a multithreaded environment.

The hsearch subroutine searches a hash table. It returns a pointer into a hash table that indicates the location of the given item. The hsearch subroutine uses open addressing with a multiplicative hash function.

The hcreate subroutine allocates sufficient space for the table. You must call the hcreate subroutine before calling the hsearch subroutine. The NumberOfElements parameter is an estimate of the maximum number of entries that the table will contain. This number may be adjusted upward by the algorithm in order to obtain certain mathematically favorable circumstances.

The hdestroy subroutine deletes the hash table. This action allows you to start a new hash table since only one table can be active at a time. After the call to the hdestroy subroutine, the data can no longer be considered accessible.

Parameters

Item Description
Item Identifies a structure of the type ENTRY as defined in the search.h file. It contains two pointers:
Item.key
Points to the comparison key. The key field is of the char type.
Item.data
Points to any other data associated with that key. The data field is of the void type.

Pointers to data types other than the char type should be declared to pointer-to-character.
Action Specifies the value of the Action enumeration parameter that indicates what is to be done with an entry if it cannot be found in the table. Values are:
ENTER
Enters the value of the Item parameter into the table at the appropriate point. If the table is full, the hsearch subroutine returns a null pointer.
FIND
Does not enter the value of the Item parameter into the table. If the value of the Item parameter cannot be found, the hsearch subroutine returns a null pointer. If the value of the Item parameter is found, the subroutine returns the address of the item in the hash table.
NumberOfElements Provides an estimate of the maximum number of entries that the table contains. Under some circumstances, the hcreate subroutine may actually make the table larger than specified.

Return Values

The hcreate subroutine returns a value of 0 if it cannot allocate sufficient space for the table.