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

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