*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Linux man pages -> hsearch (3)              



NAME    [Toc]    [Back]

       hcreate, hdestroy, hsearch - hash table management

SYNOPSIS    [Toc]    [Back]

       #include <search.h>

       ENTRY *hsearch(ENTRY item, ACTION action);

       int hcreate(unsigned nel);

       void hdestroy(void);

DESCRIPTION    [Toc]    [Back]

       These three functions allow the user to create a hash table which associates
 a key with any data.

       First the table must be created with the function hcreate().  nel is an
       estimate  of  the number of entries in the table.  hcreate() may adjust
       this value upward to improve the performance of the resulting hash  table.
   The  GNU implementation of hsearch() will also enlarge the table
       if it gets nearly full.	malloc(3) is used to allocate  space  for  the

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

       item is of type ENTRY, which is a typedef  defined  in  <search.h>  and
       includes these elements:

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

       key points to the zero-terminated ASCII string which is the search key.
       data points to the data associated with that key.  (A pointer to a type
       other   than   character   should  be  cast  to	pointer-to-character.)
       hsearch() searches the hash table for an item  with  the  same  key  as
       item,  and  if  successful  returns a pointer to it.  action determines
       what hsearch() does after an unsuccessful search.   A  value  of  ENTER
       instructs  it  to  insert  the new item, while a value of FIND means to
       return NULL.

RETURN VALUE    [Toc]    [Back]

       hcreate() returns  NULL	if  the  hash  table  cannot  be  successfully

       hsearch()  returns  NULL  if  action is ENTER and there is insufficient
       memory to expand the hash table, or action is FIND and item  cannot  be
       found in the hash table.

CONFORMS TO    [Toc]    [Back]

       SVID, except that in SysV, the hash table cannot grow.

BUGS    [Toc]    [Back]

       The  implementation can manage only one hash table at a time.  Individual
 hash table entries can be added, but not deleted.

EXAMPLE    [Toc]    [Back]

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

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

	     /* start with small table, and let it grow */
	     for (i = 0; i < 24; i++)
		 e.key = data[i];
		 /* data is just an integer, instead of a pointer
		    to something */
		 e.data = (char *)i;
		 ep = hsearch(e, ENTER);
		 /* there should be no failures */
		 if(ep == NULL) {fprintf(stderr, "entry failed\n"); exit(1);}
	     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",
	     return 0;

SEE ALSO    [Toc]    [Back]

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

GNU				  1995-09-30			    HSEARCH(3)
[ Back ]
 Similar pages
Name OS Title
lh_free Tru64 Dynamic hash table
openssl_lhash NetBSD dynamic hash table
lh_retrieve Tru64 Dynamic hash table
lh_new Tru64 Dynamic hash table
lh_insert Tru64 Dynamic hash table
lh_error Tru64 Dynamic hash table
lh_delete OpenBSD dynamic hash table
lh_doall_arg Tru64 Dynamic hash table
lh_doall Tru64 Dynamic hash table
lhash Tru64 Dynamic hash table
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service