.\" -*- coding: UTF-8 -*- .\" Copyright 1993 Ulrich Drepper (drepper@karlsruhe.gmd.de) .\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk .\" .\" .\" %%%LICENSE_START(GPLv2+_DOC_FULL) .\" This is free documentation; you can redistribute it and/or .\" modify it under the terms of the GNU General Public License as .\" published by the Free Software Foundation; either version 2 of .\" the License, or (at your option) any later version. .\" .\" The GNU General Public License's references to "object code" .\" and "executables" are to be interpreted as the output of any .\" document formatting or typesetting system, including .\" intermediate and printed output. .\" .\" This manual is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. .\" .\" You should have received a copy of the GNU General Public .\" License along with this manual; if not, see .\" . .\" %%%LICENSE_END .\" .\" References consulted: .\" SunOS 4.1.1 man pages .\" Modified Sat Sep 30 21:52:01 1995 by Jim Van Zandt .\" Remarks from dhw@gamgee.acad.emich.edu Fri Jun 19 06:46:31 1998 .\" Modified 2001-12-26, 2003-11-28, 2004-05-20, aeb .\" 2008-09-02, mtk: various additions and rewrites .\" 2008-09-03, mtk, restructured somewhat, in part after suggestions from .\" Timothy S. Nelson .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH HSEARCH 3 "1. November 2020" GNU Linux\-Programmierhandbuch .SH BEZEICHNUNG hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r, hsearch_r \- Verwaltung von Hash\-Tabellen .SH ÜBERSICHT .nf \fB#include \fP .PP \fBint hcreate(size_t \fP\fInel\fP\fB);\fP .PP \fBENTRY *hsearch(ENTRY \fP\fIitem\fP\fB, ACTION \fP\fIaction\fP\fB);\fP .PP \fBvoid hdestroy(void);\fP .PP \fB#define _GNU_SOURCE\fP /* siehe feature_test_macros(7) */ \fB#include \fP .PP \fBint hcreate_r(size_t \fP\fInel\fP\fB, struct hsearch_data *\fP\fIhtab\fP\fB);\fP .PP \fBint hsearch_r(ENTRY \fP\fIitem\fP\fB, ACTION \fP\fIaction\fP\fB, ENTRY **\fP\fIretval\fP\fB,\fP \fB struct hsearch_data *\fP\fIhtab\fP\fB);\fP .PP \fBvoid hdestroy_r(struct hsearch_data *\fP\fIhtab\fP\fB);\fP .fi .SH BESCHREIBUNG Die drei Funktionen \fBhcreate\fP(), \fBhsearch\fP() und \fBhdestroy\fP() ermöglichen dem Aufrufer die Erstellung und Verwaltung einer Hash\-Suchtabelle. Deren Einträge sind Paare aus einem Schlüssel (eine Zeichenkette) und zugeordneten Daten. Mit diesen Funktionen kann immer nur eine Hash\-Tabelle genutzt werden. .PP Die drei Funktionen \fBhcreate_r\fP(), \fBhsearch_r\fP(), \fBhdestroy_r\fP() sind ablaufinvariante Funktionen, die überdies Programmen ermöglichen, mit mehreren Hash\-Tabellen gleichzeitig zu arbeiten. Das letzte Argument, \fIhtab\fP, zeigt auf eine Struktur mit der Beschreibung der Hash\-Tabelle, die die Funktion verwenden soll. Der Programmierer sollte diese Struktur als »undurchsichtig« behandeln (d.h. er sollte nicht versuchen, direkt auf Felder der Struktur zuzugreifen oder zu verändern). .PP .\" e.g., in glibc it is raised to the next higher prime number Zuerst muss mittels \fBhcreate\fP() eine Hash\-Tabelle erzeugt werden. Das Argument \fInel\fP gibt die Maximalzahl der Einträge in der Tabelle an. (Dieses Maximum kann in der Folge nicht geändert werden, wählen Sie es also mit Bedacht.) Es ist möglich, dass die Implementierung diesen Wert nach oben anpasst, um die Leistungsfähigkeit der resultierenden Hash\-Tabelle zu verbessern. .PP Die Funktion \fBhcreate_r\fP() erledigt die gleiche Aufgabe wie \fBhcreate\fP(), tut das aber für die Tabelle, die durch die Struktur \fI*htab\fP beschrieben wird. Vor dem ersten Aufruf von \fBhcreate_r\fP() muss die Struktur \fIhtab\fP mit Nullen initialisiert werden. .PP Die Funktion \fBhdestroy\fP() gibt den Speicher frei, den die von \fBhcreate\fP() erzeugte Hash\-Tabelle beansprucht. Nach dem Aufruf von \fBhdestroy\fP() kann mittels \fBhcreate\fP() eine neue Hash\-Tabelle erzeugt werden. Die Funktion \fBhdestroy_r\fP() erledigt die analoge Aufgabe für die durch \fI*htab\fP beschriebene Hash\-Tabelle, die zuvor mittels \fBhcreate_r\fP() erzeugt wurde. .PP Die Funktion \fBhsearch\fP() durchsucht die Hash\-Tabelle nach einem Eintrag mit dem gleichen Schlüssel wie \fIitem\fP (wobei »der gleiche« mittels \fBstrcmp\fP(3) bestimmt wird) und gibt bei Erfolg einen Zeiger auf diesen Eintrag zurück. .PP Das Argument \fIitem\fP ist vom Typ \fIENTRY\fP, der in \fI\fP wie folgt definiert wird: .PP .in +4n .EX typedef struct entry { char *key; void *data; } ENTRY; .EE .in .PP Das Feld \fIkey\fP zeigt auf eine null\-terminierte Zeichenkette, die als Suchschlüssel dient. Das Feld \fIdata\fP zeigt auf dem Schlüssel zugeordnete Daten. .PP Das Argument \fIaction\fP bestimmt, was \fBhsearch\fP() nach einer erfolglosen Suche unternimmt. Dieses Argument muss einen von zwei Werten annehmen: für den Wert \fBENTER\fP soll eine Kopie von \fIitem\fP in die Tabelle eingefügt werden (und ein Zeiger auf den neuen Eintrag in der Hash\-Tabelle als Ergebnis der Funktion zurückgegeben werden); \fBFIND\fP bedeutet, dass NULL zurückgegeben werden sollte. (Falls \fIaction\fP gleich \fBFIND\fP ist, wird \fIdata\fP ignoriert.) .PP Die Funktion \fBhsearch_r\fP() arbeitet wie \fBhsearch\fP(), aber mit der durch \fI*htab\fP beschriebenen Hash\-Tabelle. Der Unterschied zwischen \fBhsearch_r\fP() und \fBhsearch\fP() ist, das der Zeiger auf den gefundenen Eintrag in \fI*retval\fP zurückgegeben wird und nicht als Funktionsergebnis. .SH RÜCKGABEWERT \fBhcreate\fP() und \fBhcreate_r\fP() geben bei Erfolg einen Wert ungleich null zurück; im Fehlerfall 0, wobei \fIerrno\fP auf die Ursache des Fehlers gesetzt wird. .PP Bei Erfolg gibt \fBhsearch\fP() einen Zeiger auf einen Eintrag in der Hash\-Tabelle zurück. Bei einem Fehler gibt \fBhsearch\fP() NULL zurück. Fehler treten auf, wenn die gewünschte \fIaction\fP \fBENTER\fP und die Hash\-Tabelle voll ist oder wenn die \fIaction\fP \fBFIND\fP ist und \fIitem\fP nicht in der Hash\-Tabelle gefunden werden kann. Im Fehlerfall setzen diese zwei Funktionen \fIerrno\fP, um die Ursache des Fehlers anzuzeigen. .SH FEHLER \fBhcreate_r\fP() und \fBhdestroy_r\fP() können aus den folgenden Gründen fehlschlagen: .TP \fBEINVAL\fP \fIhtab\fP ist NULL. .PP \fBhsearch\fP() und \fBhsearch_r\fP() können aus den folgenden Gründen fehlschlagen: .TP \fBENOMEM\fP Die \fIaction\fP war \fBENTER\fP, \fIkey\fP wurde nicht in der Tabelle gefunden und es war nicht ausreichend Platz für einen neuen Eintrag vorhanden. .TP \fBESRCH\fP Die \fIaction\fP war \fBFIND\fP und \fIkey\fP wurde nicht in der Tabelle gefunden. .PP .\" PROX.1-2001, POSIX.1-2008 POSIX.1 beschreibt nur den Fehler \fBENOMEM\fP. .SH ATTRIBUTE Siehe \fBattributes\fP(7) für eine Erläuterung der in diesem Abschnitt verwandten Ausdrücke. .TS allbox; lbw25 lb lb l l l. Schnittstelle Attribut Wert T{ \fBhcreate\fP(), \fBhsearch\fP(), .br \fBhdestroy\fP() T} Multithread\-Fähigkeit MT\-Unsafe race:hsearch T{ \fBhcreate_r\fP(), \fBhsearch_r\fP(), .br \fBhdestroy_r\fP() T} Multithread\-Fähigkeit MT\-Safe race:htab .TE .SH "KONFORM ZU" Die Funktionen \fBhcreate\fP(), \fBhsearch\fP() und \fBhdestroy\fP() stammen aus SVr4 und werden in POSIX.1\-2001 und POSIX.1\-2008 beschrieben. .PP Die Funktionen \fBhcreate_r\fP(), \fBhsearch_r\fP() und \fBhdestroy_r\fP() sind GNU\-Erweiterungen. .SH ANMERKUNGEN Implementierungen von Hash\-Tabellen sind in der Regel effizienter, wenn die Tabelle ausreichend freien Raum bereitstellt, um Kollisionen zu reduzieren. Typischerweise bedeutet das, dass \fInel\fP mindestens 25% größer als sein sollte als die maximale Anzahl von Elementen, die der Aufrufende in der Tabelle zu speichern erwartet. .PP Die Funktionen \fBhdestroy\fP() und \fBhdestroy_r\fP() geben die Puffer nicht frei, auf die die Elemente \fIkey\fP und \fIdata\fP der Einträge in der Hash\-Tabelle weisen. (Das können sie nicht tun, weil sie nicht wissen, ob diese Puffer dynamisch zugewiesen wurden.) Falls diese Puffer freigegeben werden müssen (vielleicht, weil das Programm wiederholt Hash\-Tabellen erzeugt und wieder freigibt, anstatt eine einzelne Tabelle über die Programmlaufzeit hinweg zu pflegen), dann muss das Programm Datenstrukturen zur Speicherverwaltung pflegen, um die Elemente der Tabelleneinträge freigeben zu können. .SH FEHLER SVr4 und POSIX.1\-2001 geben an, dass \fIaction\fP nur für erfolglose Suchen von Bedeutung ist, so dass ein \fBENTER\fP nichts für eine erfolgreiche Suche tun sollte. In Libc und Glibc (vor Version 2.3) verstößt die Implementierung gegen die Spezifikation und aktualisiert in diesem Fall \fIdata\fP für den gegebenen \fIkey\fP. .PP Einzelne Einträge können der Hash\-Tabelle hinzugefügt, jedoch nicht gelöscht werden. .SH BEISPIELE Das folgende Programm fügt 24 Einträge in eine Hashtabelle ein und zeigt dann einige davon an. .PP .EX #include #include #include static char *data[] = { "alpha", "bravo", "charlie", "delta", "echo", "foxtrot", "golf", "hotel", "india", "juliet", "kilo", "lima", "mike", "november", "oscar", "papa", "quebec", "romeo", "sierra", "tango", "uniform", "victor", "whisky", "x\-ray", "yankee", "zulu" }; int main(void) { ENTRY e; ENTRY *ep; hcreate(30); for (int i = 0; i < 24; i++) { e.key = data[i]; /* Datum ist nur eine Ganzzahl, anstatt eines Zeigers auf irgendwas */ e.data = (void *) i; ep = hsearch(e, ENTER); /* Es sollten keine Fehler eintreten */ if (ep == NULL) { fprintf(stderr, "Eintrag fehlgeschlagen\en"); exit(EXIT_FAILURE); } } for (int i = 22; i < 26; i++) { /* Zwei Einträge aus der Tabelle ausgeben und zeigen, dass zwei nicht in der Tabelle sind */ e.key = data[i]; ep = hsearch(e, FIND); printf("%9.9s \-> %9.9s:%d\en", e.key, ep ? ep\->key : "NULL", ep ? (int)(ep\->data) : 0); } hdestroy(); exit(EXIT_SUCCESS); } .EE .SH "SIEHE AUCH" \fBbsearch\fP(3), \fBlsearch\fP(3), \fBmalloc\fP(3), \fBtsearch\fP(3) .SH KOLOPHON Diese Seite ist Teil der Veröffentlichung 5.10 des Projekts Linux\-\fIman\-pages\fP. Eine Beschreibung des Projekts, Informationen, wie Fehler gemeldet werden können sowie die aktuelle Version dieser Seite finden sich unter \%https://www.kernel.org/doc/man\-pages/. .SH ÜBERSETZUNG Die deutsche Übersetzung dieser Handbuchseite wurde von Martin Eberhard Schauer und Mario Blättermann erstellt. Diese Übersetzung ist Freie Dokumentation; lesen Sie die .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License Version 3 .UE oder neuer bezüglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG übernommen. Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an die .MT debian-l10n-german@\:lists.\:debian.\:org Mailingliste der Übersetzer .ME .