Quick ?s
Cheat Sheets
Man Pages
The Lynx
HSEARCH(3)		   Linux Programmers Manual		   HSEARCH(3)

       hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r, hsearch_r - hash ta
       ble management


       int hcreate(size_t nel);

       ENTRY *hsearch(ENTRY item, ACTION action);

       void hdestroy(void);

       #define _GNU_SOURCE

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

       The three functions hcreate(), hsearch(), and hdestroy() allow the user
       to create a hash table (only one at a time) which associates a key with
       any data.

       First the table must be created with the function hcreate().  The argu
       ment  nel is an estimate of the maximum number of entries in the table.
       The function hcreate() may adjust this value upward to improve the per
       formance of the resulting hash table.

       The  corresponding function hdestroy() frees the memory occupied by the
       hash table so that a new table can be constructed.

       The argument item is of type ENTRY,  which  is  a  typedef  defined  in
        and includes these elements:

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

       The  field key points to the null-terminated string which is the search
       key.  The field data points to the data associated with that key.   The
       function  hsearch()  searches  the hash table for an item with the same
       key as item (where "the same" is determined using  strcmp(3)),  and  if
       successful  returns  a  pointer	to it.	The argument action determines
       what hsearch() does after an unsuccessful search.   A  value  of  ENTER
       instructs  it  to insert a copy of item, while a value of FIND means to
       return NULL.

       The three functions hcreate_r(), hsearch_r(),  hdestroy_r()  are  reen
       trant  versions	that  allow  the use of more than one table.  The last
       argument used identifies the table.  The struct it points  to  must  be
       zeroed before the first call to hcreate_r().

       hcreate()  and  hcreate_r()  return 0 when allocation of the memory for
       the hash table fails, non-zero otherwise.

       hsearch() returns NULL if action is ENTER and the hash table  is  full,
       or action is FIND and item cannot be found in the hash table.

       hsearch_r()  returns  0	if action is ENTER and the hash table is full,
       and non-zero otherwise.

       POSIX documents

       ENOMEM Out of memory.

       The glibc implementation will return the following two errors.

       ENOMEM Table full with action set to ENTER.

       ESRCH  The action argument is FIND  and	no  corresponding  element  is
	      found in the table.

       The  functions  hcreate(), hsearch(), and hdestroy() are from SVr4, and
       are described in POSIX.1-2001.  The functions hcreate_r(), hsearch_r(),
       hdestroy_r() are GNU extensions.

       SVr4  and  POSIX.1-2001	specify  that  action  is significant only for
       unsuccessful searches, so that an ENTER should not do  anything	for  a
       successful  search.  The libc and glibc implementations update the data
       for the given key in this case.

       Individual hash table entries can be added, but not deleted.

       The following program inserts 24 items in to a hash table, then	prints
       some of them.


       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"

	   ENTRY e, *ep;
	   int i;

	   /* starting with small table, and letting it grow does not work */
	   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");
	   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);

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

       This  page  is  part of release 3.05 of the Linux man-pages project.  A
       description of the project, and information about reporting  bugs,  can
       be found at http://www.kernel.org/doc/man-pages/.

GNU				  2004-05-20			    HSEARCH(3)

Yals.net is © 1999-2009 Crescendo Communications
Sharing tech info on the web for more than a decade!
This page was generated Thu Apr 30 17:05:26 2009