Provided by: manpages-es_1.55-10_all bug

NOMBRE

       hcreate,  hdestroy, hsearch - funciones para manejar una tabla dispersa
       (hash)

SINOPSIS

       #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);

DESCRIPCI'ON

       Las  tres  funciones  hcreate,  hsearch, y hdestroy permiten al usuario
       crear una tabla dispersa (solo una al  mismo  tiempo)  que  asocia  una
       clave  con  cualquier  dato.   Las tres funciones hcreate_r, hsearch_r,
       hdestroy_r son versiones reentrantes que permiten el uso de mas de  una
       tabla.

       En  primer  lugar, se debe crear la tabla con la funcion hcreate().  El
       argumento nel es una estimacion del numero de entradas de la tabla.  La
       funcion   hcreate()  puede  incrementar  este  valor  para  mejorar  el
       rendimiento de la tabla dispersa resultante.

       La funcion correspondiente hdestroy() libera la memoria ocupada por  la
       tabla dispersa de tal forma que se pueda construir una nueva tabla.

       El  argumento item es del tipo ENTRY, que se define mediante typedef en
       <search.h> e incluye estos elementos:

            typedef struct entry {
                char *key;
                void *data;
            } ENTRY;

       El campo key apunta a una cadena terminada en NUL que es  la  clave  de
       busqueda.   El  campo  data apunta a los datos asociados con esa clave.
       La funcion hsearch() busca en la tabla  dispersa  un  elemento  con  la
       misma  clave que item (donde "la misma" se determina usando strcmp(3)),
       y si tiene exito devuelve un puntero al  mismo.   El  argumento  action
       determina  que  debe  hacer  hsearch()  tras una busqueda sin exito. El
       valor ENTER le indica que debe insertar una copia de item, mientras que
       un valor FIND significa que debe devolver NULL.

VALOR DEVUELTO

       hcreate()  y hcreate_r() devuelven 0 cuando falla la reserva de memoria
       para la tabla dispersa, o un valor distinto de cero en otro caso.

       hsearch() devuelve NULL si action es ENTER y  la  tabla  dispersa  esta
       completa,  o  action es FIND e item no puede ser encontrado en la tabla
       dispersa.

       hsearch_r() devuelve 0 si action es ENTER  y  la  tabla  dispersa  esta
       completa, y un valor distinto de cero en otro caso.

ERRORES

       ENOMEM Memoria insuficiente.

CONFORME A

       Las  funciones  hcreate,  hsearch,  y  hdestroy  son  de  SVID, y estan
       descritas en POSIX 1003.1-2001.  Las  funciones  hcreate_r,  hsearch_r,
       hdestroy_r son extensiones de GNU.

FALLOS

       SVID  y  POSIX  1003.1-2001  especifican  que  el  argumento  action es
       significativo solo para busquedas  sin  exito,  por  lo  que  ENTER  no
       deberia  hacer  nada para una busqueda exitosa. Las implementaciones de
       libc y glibc actualizan data para una clave key dada en este caso.

       Se pueden anadir a la tabla dispersa entradas individuales pero  no  se
       pueden eliminar.

EJEMPLO

       El  siguiente  programa  inserta 24 elementos en una tabla dispersa y a
       continuacion imprime algunos de ellos.

           #include <stdio.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;

             /* Comencemos con una pequena tabla y dejemosla que crezca */
             hcreate(30);
             for (i = 0; i < 24; i++) {
                 e.key = data[i];
                 /* Los datos son enteros, en lugar de punteros a alguna cosa */
                 e.data = (char *)i;
                 ep = hsearch(e, ENTER);
                 /* No debe haber fallos */
                 if(ep == NULL) {
                    fprintf(stderr, "Fallo en la entrada\n");
                    exit(1);
              }
             }
             for (i = 22; i < 26; i++) {
               /* Imprime dos entradas de la tabla y demuestra que otras dos no
                  estan en la tabla */

                 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);
             }
             return 0;
           }

V'EASE TAMBI'EN

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