Provided by: manpages-de-dev_0.5-2ubuntu1_all bug

BEZEICHNUNG

       hcreate, hdestroy, hsearch - hash table management

ÜBERSICHT

       #include <search.h>

       ENTRY *hsearch(ENTRY item, ACTION action);

       int     hcreate (unsigned nel);

       void    hdestroy (void);

BESCHREIBUNG

       Diese    drei    Funktionen  erlauben  dem  Anwender  eine  Hashtabelle
       anzulegen, die einen Schlüssel  mit  irgendwelchen  Daten verbindet.

       Zuerst muss die Tabelle mit hcreate()  erzeugt  werden.   nel  ist  die
       geschätzte  Größe  der  Tabelle.   hcreate() kann diesen Wert nach oben
       korrigieren, um die Performance des  Algorithmus  zu  verbessern.   Die
       GNU-Implementierung   von   hsearch()   wird   die   Tabelle  ebenfalls
       verlängern, wenn sie fast  voll  ist.   malloc(3)  wird  verwendet,  um
       Speicherplatz zu alloziieren.

       Die  entsprechende  Funktion  hdestroy() gibt den Speicher wieder frei,
       der von der Hashtabelle belegt wurde, um so Platz für eine neue Tabelle
       zu schaffen.

       item  ist vom Typ ENTRY, der in <search.h> definiert wurde und folgende
       Elemente enthlt:

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

       key  zeigt  auf  eine  null-terminierte  ASCII-Zeichenkette,  die   den
       Suchschlüssel  repräsentiert.   data  zeigt  auf das Datum, das mit dem
       Schlüssel verbunden ist.  (Ein Zeiger auf einen anderen  Typ  als  char
       sollte auf einen char * gecastet werden.)  hsearch() sucht nach item in
       der Hashtabelle  und  gibt  bei  Erfolg  einen  Zeiger  darauf  zurück,
       ansonsten  NULL.   action bestimmt, wie sich hsearch() nach erfolgloser
       Suche verhält.  Der Wert  ENTER  bewirkt,  dass  item  in  die  Tabelle
       eingefügt   wird,   während   der  Wert  FIND  hsearch()  anweist  NULL
       zurückzugeben.

RÜCKGABEWERT

       hcreate() gibt NULL zurück,  wenn  die  Hashtabelle  nicht  erfolgreich
       angelegt werden konnte.

       hsearch() gibt NULL zurück, wenn action ENTER ist und nicht ausreichend
       Speicher zur Verfügung steht, um die  Hashtabelle  zu  erweitern,  oder
       wenn  action  FIND  ist  und  item nicht in der Tabelle gefunden werden
       konnte.

KONFORM ZU

       SVID, außer, dass die Tabelle bei SysV nicht wachsen kann.

FEHLER

       Diese Implementierung kann  nur  eine  Hashtabelle  zur  gleichen  Zeit
       verwalten.  Einzelne Einträge können hinzugefügt, jedoch nicht gelöscht
       werden.

BEISPIEL

       Das folgende Programm fügt 24 Einträge in die Hashtabelle ein und zeigt
       dann einige.

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

           char *data[]={ "alpha", "bravo", "charley", "delta",
                "echo", "foxtrot", "golf", "hotel", "india", "juliette",
                "kilo", "lima", "mike", "november", "oscar", "papa",
                "quebec", "romeo", "sierra", "tango", "uniform",
                "victor", "whiskey", "x-ray", "yankee", "zulu"
            };

           int main()
           {
             ENTRY e, *ep;
             int i;

             /* Fang mit einer kleinen Tabelle an und laß sie wachsen */
             hcreate(3);
             for (i = 0; i < 24; i++)
               {
                 e.key = data[i];
                 /* Datum ist nur eine Ganzzahl anstelle eines Zeigers auf
                    irgendetwas */
                 e.data = (char *)i;
                 ep = hsearch(e, ENTER);
                 /* Es sollte keine Fehler geben */
                 if(ep == NULL) {fprintf(stderr, "entry failed\n"); exit(1);}
               }
             for (i = 22; i < 26; i++)
               /* Gib zwei Einträge der Tabelle aus und zeige, dass zwei nicht
                  in der Tabelle enthalten sind */
               {
                 e.key = data[i];
                 ep = hsearch(e, FIND);
                 printf("%9.9s -> %9.9s:%d\n", e.key, ep?ep->key:"NULL",
                        ep?(int)(ep->data):0);
               }
             return 0;
           }

SIEHE AUCH

       bsearch(3), lsearch(3), tsearch(3), malloc(3).