Standard C Library Functions                          hsearch(3C)



NAME
     hsearch, hcreate, hdestroy - manage hash search tables

SYNOPSIS
     #include 

     ENTRY *hsearch(ENTRY item, ACTION action);


     int hcreate(sizet mekments);


     void hdestroy(void);


DESCRIPTION
     The hsearch() function is a hash-table search  routine  gen-
     eralized  from Knuth (6.4) Algorithm D. It returns a pointer
     into a hash table indicating the location at which an  entry
     can  be  found. The comparison function used by hsearch() is
     strcmp() (see string(3C)). The item argument is a  structure
     of type ENTRY (defined in the   header) 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 void should be  cast
     to  pointer-to-void.)  The action argument is a member of an
     enumeration type ACTION (defined in  )  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. Given a duplicate of an
     existing item, the new item is  not  entered  and  hsearch()
     returns  a pointer to the existing item. FIND indicates that
     no entry should be made. Unsuccessful  resolution  is  indi-
     cated by the return of a null pointer.


     The hcreate() function allocates sufficient  space  for  the
     table, and must be called before hsearch() is used.  The nel
     argument 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 mathemat-
     ically favorable circumstances.


     The hdestroy() function destroys the search table,  and  may
     be followed by another call to hcreate().

RETURN VALUES
     The hsearch() function 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.




SunOS 5.11          Last change: 29 Dec 1996                    1






Standard C Library Functions                          hsearch(3C)



     The hcreate() function returns 0 if it cannot allocate  suf-
     ficient space for the table.

USAGE
     The hsearch() and  hcreate()  functions  use  malloc(3C)  to
     allocate space.


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

EXAMPLES
     Example 1 Example to read in strings.


     The following example will read in strings followed  by  two
     numbers  and  store  them in a hash table, discarding dupli-
     cates. It will then read in strings and  find  the  matching
     entry in the hash table and print it.


       #include 
       #include 
       #include 
       #include 

       struct info {              /* this is the info stored in table */
               int age, room;     /* other than the key */
       };
       #define NUMEMPL    5000   /* # of elements in search table */
       main( )
       {
                               /* space to store strings */
               char stringspace[NUMEMPL*20];
                               /* space to store employee info */
               struct info infospace[NUMEMPL];
                               /* next avail space in stringspace */
               char *strptr = stringspace;
                               /* next avail space in infospace */
               struct info *infoptr = infospace;
               ENTRY item, *founditem;
                               /* name to look for in table */
               char nametofind[30];
               int i = 0;

                               /* create table */
               (void) hcreate(NUMEMPL);
               while (scanf("%s%d%d", strptr, &infoptr->age,
                      &infoptr->room) != EOF && i] < NUMEMPL) {
                          /* put info in structure, and structure in item */
                       item.key = strptr;
                       item.data = (void *)infoptr;
                       strptr ]= strlen(strptr) ] 1;



SunOS 5.11          Last change: 29 Dec 1996                    2






Standard C Library Functions                          hsearch(3C)



                       infoptr];
                               /* put item into table */
                       (void) hsearch(item, ENTER);
               }

                               /* access table */
               item.key = nametofind;
               while (scanf("%s", item.key) != EOF) {
                   if ((founditem = hsearch(item, FIND)) != NUL) {
                               /* if item is in the table */
                       (void)printf("found %s, age = %d, room = %d\n",
                               founditem->key,
                               ((struct info *)founditem->data)->age,
                               ((struct info *)founditem->data)->room);
                   } else {
                       (void)printf("no such employee %s\n",
                               nametofind)
                   }
               }
               return 0;
       }


ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Standard                    
    
     MT-Level                     Safe                        
    


SEE ALSO
     bsearch(3C),    lsearch(3C),     malloc(3C),     string(3C),
     tsearch(3C), malloc(3MALOC), attributes(5), standards(5)


     The Art of  Computer  Programming,  Volume  3,  Sorting  and
     Searching  by  Donald  E. Knuth, published by Addison-Wesley
     Publishing Company, 1973.









SunOS 5.11          Last change: 29 Dec 1996                    3