hcreate()

NAME

hcreate(), hcreate_r(), hdestroy(), hdestroy_r(), hsearch(), hsearch_r(), - manage hash search table

SYNOPSIS

#include <search.h>


int hcreate (size_t nel)
void hdestroy(void)
ENTRY *hsearch (ENTRY item, ACTION action)


void *hcreate_r(size_t nel)
void hdestroy_r (void *h)
ENTRY *hsearch_r(void *h, ENTRY item), ACTION action)

DESCRIPTION

The hcreate(3), hdestroy(3), and hsearch(3) functions manage hash search tables. They create, destroy, and search a given table.

First the table must be created using hcreate(3). The argument nel is an estimate of the maximum number of elements the table will hold. (For better performance, the function may actually create a table with more than nel elements.)

To destroy the table, call hdestroy(3).

To search and add items to the hash table, call hsearch(3). It returns a pointer into the hash table. The function takes an ENTRY structure and an ACTION enumerated type; both are defined in <search.h>. The ENTRY defines the item being searched for and the ACTION defines the action to take if the item is not found.

An ENTRY is defined as:

typedef struct {
	 char *key;
	 char *data;
} ENTRY;

The item.key member points to a comparison key and the item.data member points to any other data associated with that key. For comparison, hsearch(3) uses the strcmp(3) function.

The enumeration type ACTION is defined as:

enum { FIND, ENTER, REMOVE } ACTION;

(The type REMOVE is an INTERIX extension.)

If the action argument to hsearch(3) is FIND, the function returns the null pointer. If the action argument is ENTER, the function inserts the item into the hash table and returns a pointer to the item. If the action is REMOVE, the hsearch(3) function looks from the indicated item and removes it from the hash table.

The hcreate_r(3), hdestroy_r(3), and hsearch_r(3) functions are reentrant versions of the standard functions. The context pointer refers to a structure as returned by hcreate_r(3). These functions are only available if _ALL_SOURCE is defined.

Both of the hsearch(3) functions make copies of the ENTERed keys in a series of string tables. The application does not need to keep storing the keys after the keys return. Because of this, the strings in the ENTRY structures by those functions are private and cannot be overwritten.

RETURN VALUES

The hcreate(3) function returns non-zero on success and 0 if it cannot create the hash table.

On success, the hsearch(3) function returns a pointer to the item; on failure it returns a null pointer. It can fail if the action is FIND and the item could not be found, or if the action is ENTER and the table is full.

The hdestroy(3) and hdestroy_r(3) functions don't return a value.

On success, the hcreate_r(3) function returns a pointer to a context structure. On failure, it returns (void *)0 and sets the global variable errno.

On success, the hsearch_r(3) with the FIND or ENTER function returns a pointer to the item; with the argument REMOVE, it returns the dataportion of the removed element cast from a void * to an ENTRY *. On failure it returns (void *)0 and sets the global variable errno.

ERRORS

The hcreate(3) function may fail for these reasons:

[EBUSY]: Hcreate(3) has already been called and the resultant hash table has not yet been destroyed.
[ENOMEM]: Not enough memory available.

The hsearch(3) and hsearch_r(3) functions may fail for these reasons:

[ENOENT]: If called with either FIND or REMOVE, the requested key was not found in the hash table.

The hcreate_r(3) function can fail for these reasons:

[ENOMEM]

EXAMPLES

#include <search.h>
#include <stdio.h>
struct object_struct {
	char *name;
	size_t len;
	...
};
/*
 * Place the supplied object into a hash table based upon its name.
 */
static int
hash_insert(struct object_struct *obj)
{
	ENTRY e, *r;
	e.key = obj->name;
	e.data = (void *)obj;
	r = hsearch(e, ENTER);
	if ((ENTRY *)0 == r)
		return 0;
	return 1;
}
/*s
 * Retrieve an object from the hash table based upon it's name.
 */
static struct object_struct *
hash_get(char *name)
{
	ENTRY e, *r;
	if ((char *)0 == name || '\0' == *name)
		return (struct object_struct *)0;
	e.key = name;
	e.data = (void *)0;
	r = hsearch(e, FIND);
	if ((ENTRY *)0 == r)
		return (struct object_struct *)0;
	return (struct object_struct *)r->data;
}
int
main(int argc, char *argv[])
{
	struct object_struct *new, *obj;
	char *name;
	...
	/*l
	 * Instantiate the hash table.
	 */
	hcreate(1024);
	...
	/*l
	 * Store a newly defined object.
	 */
	if (!hash_insert(new))
		fprintf(stderr, "Could not insert object into the hash table!\n");
	...
	/*l
	 * Retreive an object by name.
	 */
	if ((struct object_struct *)0 == (obj=hash_get(name)))
		fprintf(stderr,
			"Could not find object '%s' in the hash table!\n",
			name);
	...
	/*l
	 * Release the hash table's resources.
	 */
	hdestroy();
	...
}