.\" -*- coding: UTF-8 -*- '\" t .\" Copyright 1993 Ulrich Drepper (drepper@karlsruhe.gmd.de) .\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk .\" .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" 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 "2. Mai 2024" "Linux man\-pages 6.8" .SH BEZEICHNUNG hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r, hsearch_r \- Verwaltung von Hash\-Tabellen .SH BIBLIOTHEK Standard\-C\-Bibliothek (\fIlibc\fP, \fI\-lc\fP) .SH ÜBERSICHT .nf \fB#include \fP .P \fBint hcreate(size_t \fP\fInel\fP\fB);\fP \fBvoid hdestroy(void);\fP .P \fBENTRY *hsearch(ENTRY \fP\fIeintrag\fP\fB, ACTION \fP\fIaktion\fP\fB);\fP .P \fB#define _GNU_SOURCE\fP /* siehe feature_test_macros(7) */ \fB#include \fP .P \fBint hcreate_r(size_t \fP\fInel\fP\fB, struct hsearch_data *\fP\fIhtab\fP\fB);\fP \fBvoid hdestroy_r(struct hsearch_data *\fP\fIhtab\fP\fB);\fP .P \fBint hsearch_r(ENTRY \fP\fIeintrag\fP\fB, ACTION \fP\fIaktion\fP\fB, ENTRY **\fP\fIrückwert\fP\fB,\fP \fB 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. .P 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). .P .\" 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. .P 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. .P 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. .P Die Funktion \fBhsearch\fP() durchsucht die Hash\-Tabelle nach einem Eintrag mit dem gleichen Schlüssel wie \fIeintrag\fP (wobei »der gleiche« mittels \fBstrcmp\fP(3) bestimmt wird) und gibt bei Erfolg einen Zeiger auf diesen Eintrag zurück. .P Das Argument \fIeintrag\fP ist vom Typ \fIENTRY\fP, der in \fI\fP wie folgt definiert wird: .P .in +4n .EX typedef struct entry { char *key; void *data; } ENTRY; .EE .in .P 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. .P Das Argument \fIaktion\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 \fIeintrag\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 \fIaktion\fP gleich \fBFIND\fP ist, wird \fIdata\fP ignoriert.) .P 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*rückwert\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 gesetzt wird, um den Fehler anzuzeigen. .P 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 \fIaktion\fP \fBENTER\fP und die Hash\-Tabelle voll ist oder wenn die \fIaktion\fP \fBFIND\fP ist und \fIeintrag\fP nicht in der Hash\-Tabelle gefunden werden kann. Im Fehlerfall setzen diese zwei Funktionen \fIerrno\fP, um den Fehler 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. .P \fBhsearch\fP() und \fBhsearch_r\fP() können aus den folgenden Gründen fehlschlagen: .TP \fBENOMEM\fP Die \fIaktion\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 \fIaktion\fP war \fBFIND\fP und \fIkey\fP wurde nicht in der Tabelle gefunden. .P .\" 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; lbx lb lb l l l. Schnittstelle Attribut Wert T{ .na .nh \fBhcreate\fP(), \fBhsearch\fP(), \fBhdestroy\fP() T} Multithread\-Fähigkeit MT\-Unsicher race:hsearch T{ .na .nh \fBhcreate_r\fP(), \fBhsearch_r\fP(), \fBhdestroy_r\fP() T} Multithread\-Fähigkeit MT\-Sicher race:htab .TE .SH STANDARDS .TP \fBhcreate\fP() .TQ \fBhsearch\fP() .TQ \fBhdestroy\fP() POSIX.1\-2008. .TP \fBhcreate_r\fP() .TQ \fBhsearch_r\fP() .TQ \fBhdestroy_r\fP() GNU. .SH GESCHICHTE .TP \fBhcreate\fP() .TQ \fBhsearch\fP() .TQ \fBhdestroy\fP() SVr4, POSIX.1\-2001. .TP \fBhcreate_r\fP() .TQ \fBhsearch_r\fP() .TQ \fBhdestroy_r\fP() GNU. .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. .P 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 \fIaktion\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. .P 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. .P .\" SRC BEGIN (hsearch.c) .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 (size_t 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 auftreten */ if (ep == NULL) { fprintf(stderr, "entry failed\en"); exit(EXIT_FAILURE); } } \& for (size_t 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 .\" SRC END .SH "SIEHE AUCH" \fBbsearch\fP(3), \fBlsearch\fP(3), \fBmalloc\fP(3), \fBtsearch\fP(3) .PP .SH ÜBERSETZUNG Die deutsche Übersetzung dieser Handbuchseite wurde von Martin Eberhard Schauer und Mario Blättermann erstellt. .PP 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. .PP 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 .