


      HSEARCH(3C)                 (UNIX 5.0)                HSEARCH(3C)



      NAME
           hsearch, hcreate, hdestroy - manage hash search tables

      SYNTAX
           #include <search.h>

           ENTRY *hsearch (item, action)
           ENTRY item;
           ACTION action;

           int hcreate (nel)
           unsigned nel;

           void hdestroy ( )

      DESCRIPTION
           Hsearch is a hash-table search routine generalized from
           Knuth (6.4) Algorithm D.  It returns a pointer into a hash
           table indicating the location at which an entry can be
           found.  Item is a structure of type ENTRY (defined in the
           <search.h> header file) containing two pointers:  item.key
           points to the comparison key, and item.data points to any
           other data to be associated with that key.  (Pointers to
           types other than character should be cast to pointer-to-
           character.) Action is a member of an enumeration type ACTION
           indicating the disposition of the entry if it cannot be
           found in the table.  ENTER indicates that the item should be
           inserted in the table at an appropriate point.  FIND
           indicates that no entry should be made.  Unsuccessful
           resolution is indicated by the return of a NULL pointer.

           Hcreate allocates sufficient space for the table, and must
           be called before hsearch is used.  nel 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.

           Hdestroy destroys the search table, and may be followed by
           another call to hcreate.

      NOTES
           Hsearch uses open addressing with a multiplicative hash
           function.  However, its source code has many other options
           available which the user may select by compiling the hsearch
           source with the following symbols defined to the
           preprocessor:

                DIV      Use the remainder modulo table size as the
                         hash function instead of the multiplicative
                         algorithm.

                USCR     Use a User Supplied Comparison Routine for



      Page 1                                         (73 A2 02MTA REV1)






      HSEARCH(3C)                 (UNIX 5.0)                HSEARCH(3C)



                         ascertaining table membership.  The routine
                         should be named hcompar and should behave in a
                         mannner similar to strcmp (see string(3C)).

                CHAINED  Use a linked list to resolve collisions.  If
                         this option is selected, the following other
                         options become available.

                         START     Place new entries at the beginning
                                   of the linked list (default is at
                                   the end).

                         SORTUP    Keep the linked list sorted by key
                                   in ascending order.

                         SORTDOWN  Keep the linked list sorted by key
                                   in descending order.

           Additionally, there are preprocessor flags for obtaining
           debugging printout (-DDEBUG) and for including a test driver
           in the calling routine (-DDRIVER).  The source code should
           be consulted for further details.

      SEE ALSO
           bsearch(3C), lsearch(3C), string(3C), tsearch(3C).

      DIAGNOSTICS
           Hsearch returns a NULL pointer if either the action is FIND
           and the item could not be found or the action is ENTER and
           the table is full.

           Hcreate returns zero if it cannot allocate sufficient space
           for the table.

      BUGS
           Only one hash search table may be active at any given time.



















      Page 2                                         (73 A2 02MTA REV1)



