hsearch, hcreate, hdestroy

Purpose

     Manages hash tables.

Library

     Standard C Library (libc.a)

Syntax

     #include <search.h>

     ENTRY *hsearch (item, action)             int hcreate (nel)
     ENTRY item;                               unsigned int nel;
     ACTION action;
                                               void hdestroy ( )
     Description

     The hsearch  subroutine is  a hash table  search routine.
     It returns a pointer into a hash table that indicates the
     location  of a  given  entry.  The  item  parameter is  a
     structure of  the type ENTRY  as defined in  the search.h
     header file.  It contains two pointers:

     item.key  Points to the comparison key.
     item.data Points  to any  other data  be associated  with
               that key.

     Pointers  to types  other  than char  should  be cast  to
     pointer-to-character.  The action parameter is a value of
     the ACTION enumeration type that  indicates what is to be
     done with an entry if it cannot be found in the table:

     ENTER     Enters the  item into  the table at  the appro-
               priate  point.  If  the table  is full,  a NULL
               pointer is returned.

     FIND      Does  not enter  the item  into the  table, but
               returns a  NULL pointer  if the item  cannot be
               found.

     The hsearch subroutine uses open addressing with a multi-
     plicative hash function.

     The hcreate subroutine allocates sufficient space for the
     table.   You must  call hcreate  before calling  hsearch.
     The nel parameter is an estimate of the maximum number of
     entries  that the  table  contains.   Under some  circum-
     stances, hcreate may actually  make the table larger than
     specified.  Upon  successful completion,  hcreate returns
     1.  hcreate  returns 0  if it cannot  allocate sufficient
     space for the table.

     The  hdestroy subroutine  deletes the  hash table.   This
     allows you to start a new hash table since only one table
     can be active at a time.

     Related Information

     In this book:  "bsearch," "lsearch, lfind," "string," and
     "tsearch, tdelete, twalk."