hsearch(3C)                                                     hsearch(3C)

NAME
     hsearch, hcreate, hdestroy - Hash-Suchtabellen verwalten

SYNTAX
     #include <search.h>

     ENTRY *hsearch(ENTRY item, ACTION action);

     int hcreate(sizet nel);

     void hdestroy(void);

BESCHREIBUNG
     hsearch() ist eine auf der Grundlage des Algorithmus D (6.4) von Knuth
     verallgemeinerte Suchfunktion für Hash-Tabellen. Sie gibt einen Zeiger
     in eine Hash-Tabelle zurück, der die Stelle anzeigt, an der ein Ein-
     trag gefunden wurde. Die von hsearch() benutzte Vergleichsfunktion ist
     strcmp() [siehe string(3C)]. item ist eine Struktur des in der
     Include-Datei search.h definierten Typs ENTRY, die zwei Zeiger ent-
     hält: item.key weist auf den Vergleichsschlüssel (vom Typ char*), und
     item.data (void*) weist auf alle anderen Daten in Zusammenhang mit
     diesem Schlüssel. Zeiger auf Typen, die nicht void sind, sind zu Zei-
     gern auf void umzuwandeln. action ist ein Element des Aufzählungstyps
     ACTION (definiert in search.h), das die Behandlung des Eintrags
     angibt, wenn dieser nicht in der Tabelle gefunden werden kann. ENTER
     zeigt an, daß item an einem geeigneten Punkt in die Tabelle eingetra-
     gen werden soll. Ist ein Duplikat eines existierenden Eintrags vorhan-
     den, so wird der neue Eintrag nicht eingetragen, und hsearch() gibt
     den Zeiger zu dem existierenden Eintrag zurück. FIND zeigt an, daß
     kein Eintrag vorgenommen werden soll. Eine erfolglose Suche wird durch
     die Rückgabe eines Nullzeigers gemeldet.

     hcreate() weist ausreichend Speicher für die Tabelle zu und muß vor
     hsearch() aufgerufen werden. nel schätzt die größtmögliche Anzahl von
     Einträgen, die eine Tabelle enthalten wird. Diese Zahl kann durch den
     Algorithmus nach oben justiert werden, damit bestimmte, mathematisch
     günstige Umstände erreicht werden.

     hdestroy() zerstört die Suchtabelle. Ein weiterer Aufruf von hcreate()
     kann folgen.

     Die Funktionen schlagen fehl, wenn:

     ENOMEM    Es ist nicht genügend Speicherplatz vorhanden.

BEISPIELE
     Im folgenden Beispiel werden Zeichenketten, gefolgt von zwei Zahlen,
     eingelesen und in einer Hash-Tabelle gespeichert, wobei Duplikate
     gelöscht werden. Anschließend werden Zeichenketten eingelesen und der
     übereinstimmende Eintrag in der Hash-Tabelle gesucht und ausgedruckt.





Seite 1                      Reliant UNIX 5.44               Gedruckt 11/98

hsearch(3C)                                                     hsearch(3C)

     #include <stdio.h>
     #include <search.h>
     #include <string.h>

     struct info { /* dies sind die in der Tabelle gespeicherten */
           int age, room;  /* Daten außer dem Schlüssel. */
     };

     #define NUMEMPL   5000    /* # der Elemente in Suchtabelle */

     int main(void)
     {
           /* Platz zum Speichern von Zeichenketten */
           char stringspace[NUMEMPL*20];
           /* Platz zum Speichern von Mitarbeiterdaten */
           struct info infospace[NUMEMPL];
           /* nächster verfügbarer Platz im stringspace */
           char *strptr = stringspace;
           /* nächster verfügbarer Platz im infospace */
           struct info *infoptr = infospace;
           ENTRY item, *founditem;
           /* zu suchender Name in Tabelle */
           char nametofind[30];
           int i = 0;

           /* Tabelle erstellen */
           (void) hcreate(NUMEMPL);
           while (scanf("%s%d%d", strptr, &infoptr->age,
                   &infoptr->room) != EOF && i++ <NUMEMPL) {
                   /* Daten in Struktur und Struktur in item setzen */
                   item.key = strptr;
                   item.data = infoptr;
                   strptr += strlen(strptr) + 1;
                   infoptr++;
                   /* item in Tabelle setzen */
                   (void) hsearch(item, ENTER);
           }

           /* auf Tabelle zugreifen */
                   item.key = nametofind;
                   while (scanf("%s", item.key) != EOF) {
                      if ((founditem = hsearch(item, FIND)) != NULL) {
                          /* wenn item in Tabelle ist */
                          (void)printf("found %s, age = %d, room = %d\n"
                              founditem->key,
                               ((struct info *)founditem->data)->age,
                               ((struct info *)founditem->data)->room);
                      } else
                          (void)printf("diesen Mitarbeiter gibt es nicht:
                                %s\n", nametofind)
                   }
           return 0;


Seite 2                      Reliant UNIX 5.44               Gedruckt 11/98

hsearch(3C)                                                     hsearch(3C)

     }

ERGEBNIS
     hsearch() gibt einen Nullzeiger zurück, wenn die Aktion FIND (suchen)
     ist und der Eintrag nicht gefunden werden konnte oder wenn die Aktion
     ENTER (eintragen) ist und die Tabelle voll ist.

     hcreate() gibt Null zurück, wenn es nicht genug Speicherplatz für die
     Tabelle zuweisen kann.

HINWEISE
     hsearch() und hcreate() verwenden malloc(3C) um Speicherplatz zuzuwei-
     sen.

     Es kann jeweils nur eine Hash-Suchtabelle aktiv sein.

SIEHE AUCH
     bsearch(3C), lsearch(3C), malloc(3C), string(3C), tsearch(3C),
     malloc(3X).



































Seite 3                      Reliant UNIX 5.44               Gedruckt 11/98