HSEARCH

Index

NOM
SYNOPSIS
DESCRIPTION
VALEUR RENVOYÉE
ERREURS
CONFORMITÉ À
BOGUES
EXEMPLE
VOIR AUSSI
TRADUCTION

NOM

hsearch, hcreate, hdestroy - 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() permet 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 simultanément. 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 sinon.
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: Pas assez de mémoire.

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() {
      ENTRY e, *ep;
      int i;
    
      /* On commence avec une petite table, qu'on agrandit ensuite */
      hcreate(30);
      for (i = 0; i < 24; i++) {
          e.key = data[i];
          /* Les données sont de simples entiers, pas des pointeurs */
          e.data = (void *)i;
          ep = hsearch(e, ENTER);
          /* Il ne devrait pas y avoir d'échec */
          if (ep == NULL) {
            fprintf(stderr, "Échec
");
            exit(1);
          }
      }
      for (i = 22; i < 26; i++) {
          /* Afficher 2 entrées, et vérifier que 2
             autres sont absentes */
          e.key = data[i];
          ep = hsearch(e, FIND);
          printf("%9.9s -> %9.9s:%d
", e.key,
                 ep ? ep->key : "NULL",
                 ep ? (int)(ep->data) : 0);
      }
      return 0;
    }

VOIR AUSSI

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

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.
La traduction de cette page de manuel est basée sur les traductions disponibles sur http://manpagesfr.free.fr/, mais est gérée par l'équipe francophone de traduction de Debian au travers de la liste de discussion debian-l10n-french.
Veuillez signaler toute erreur de traduction 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> ».

Création : octobre 2007