Provided by:
manpages-fr-dev_2.80.1-1_all 
NOM
hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r, hsearch_r - Gestion
de table de hachage.
SYNOPSIS
#include <search.h>
int hcreate(size_t nel);
ENTRY *hsearch(ENTRY item, ACTION action);
void hdestroy(void);
#define _GNU_SOURCE
#include <search.h>
int hcreate_r(size_t nel, struct hsearch_data *tab);
int hsearch_r(ENTRY item, ACTION action, ENTRY **ret,
struct hsearch_data *tab);
void hdestroy_r(struct hsearch_data *tab);
DESCRIPTION
Les trois fonctions hcreate(), hsearch() et hdestroy() permettent à
l’utilisateur de créer une table (une seule à la fois) de hachage qui
associe une clé avec des données quelconques.
La table doit d’abord être créée avec la fonction hcreate(). L’argument
nel est une estimation du nombre maximum d’éléments de la table. La
fonction hcreate() peut décider d’augmenter cette valeur, afin
d’améliorer les performances de la table de hachage.
La fonction hdestroy() libère la mémoire occupée par la table, afin de
pouvoir en construire une nouvelle.
L’argument item est du type ENTRY, qui est définie dans <search.h>
ainsi :
typedef struct entry {
char *key;
void *data;
} ENTRY;
Le champ key pointe sur une chaîne de caractères ASCII terminée par un
caractère nul. Cette chaîne est la clé de recherche. Le champ data
pointe sur les données associées à cette clé. La fonction hsearch()
recherche dans la table un élément associé à la même clé que item
(comparées avec strcmp(3)), et si elle réussit, elle renvoie un
pointeur sur cet élément. L’argument action détermine ce que fera
hsearch() si la recherche est infructueuse. Si action vaut ENTER,
hsearch() insérera une copie de item. Si action vaut FIND, elle
renverra NULL.
Les fonctions hcreate_r(), hsearch_r() et hdestroy_r() sont des
versions ré-entrantes qui permettent d’utiliser plusieurs tables. Le
dernier argument utilisé identifie la table. La structure sur laquelle
il pointe doit être mise à zéro avant le premier appel à hcreate_r().
VALEUR RENVOYÉE
hcreate() et hcreate_r() renvoient zéro si la table ne peut pas être
allouée et une valeur non nulle dans le cas contraire.
hsearch() renvoie NULL si l’action est ENTER et si la table est pleine
ou si l’action est FIND et si l’item n’est pas trouvé dans la table.
hsearch_r() renvoie zéro si action est ENTER et si la table de hachage
est pleine, et une valeur non nulle sinon.
ERREURS
POSIX documente l’erreur :
ENOMEM Plus de mémoire disponible.
L’implémentation glibc renvoie les deux erreurs suivantes :
ENOMEM La table est pleine et action vaut ENTER.
ESRCH Le paramètre action vaut FIND et aucun élément n’a été trouvé
dans la table.
CONFORMITÉ
Les fonctions hcreate(), hsearch() et hdestroy() viennent de SVr4, et
sont décrites dans POSIX.1-2001. Les fonctions hcreate_r(), hsearch_r()
et hdestroy_r() sont des extensions GNU.
BOGUES
SVr4 et POSIX.1-2001 précisent que action n’est significative que pour
les recherches infructueuses ; ainsi ENTER ne devrait avoir aucune
influence pour une recherche réussie. Les implémentations libc et glibc
mettent à jour data de la clé key fournie dans ce cas.
Les entrées ne peuvent être qu’ajoutées dans la table, on ne peut pas
les supprimer individuellement.
EXEMPLE
Le programme suivant insère 24 éléments dans une table de hachage, puis
affiche quelques uns d’entre-eux.
#include <stdio.h>
#include <stdlib.h>
#include <search.h>
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, *ep;
int i;
/* starting with small table, and letting it grow does not work */
hcreate(30);
for (i = 0; i < 24; i++) {
e.key = data[i];
/* data is just an integer, instead of a
pointer to something */
e.data = (void *) i;
ep = hsearch(e, ENTER);
/* there should be no failures */
if (ep == NULL) {
fprintf(stderr, "entry failed\n");
exit(EXIT_FAILURE);
}
}
for (i = 22; i < 26; i++) {
/* print two entries from the table, and
show that two are not in the table */
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);
}
exit(EXIT_SUCCESS);
}
VOIR AUSSI
bsearch(3), lsearch(3), malloc(3), tsearch(3), feature_test_macros(7)
COLOPHON
Cette page fait partie de la publication 2.80 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent être trouvées à l’adresse
http://www.kernel.org/doc/man-pages/.
TRADUCTION
Cette page de manuel a été traduite et mise à jour par Christophe
Blaess <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis par
Alain Portal <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et mise à
disposition sur http://manpagesfr.free.fr/.
Les mises à jour et corrections de la version présente dans Debian sont
directement gérées par Florentin Duneau <fduneau@gmail.com> et l’équipe
francophone de traduction de Debian.
Veuillez signaler toute erreur de traduction en écrivant à
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir accès à la version anglaise de ce document
en utilisant la commande « man -L C <section> <page_de_man> ».