Provided by: manpages-fr-dev_2.64.1-1_all bug

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()   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 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(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)

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> ».