Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

RedHat 9 (Linux i386) - man page for hcreate (redhat section 3)

HSEARCH(3)			    Linux Programmer's Manual			       HSEARCH(3)

NAME
       hcreate, hdestroy, hsearch - hash table management

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
       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.  The three functions hcreate_r,
       hsearch_r, hdestroy_r are reentrant versions that allow the use of more than one table.

       First the table must be created with the function hcreate().  The argument nel is an esti-
       mate of the maximum number of entries in the table.  The  function  hcreate()  may  adjust
       this value upward to improve the performance 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 <search.h> and  includes
       these elements:

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

       The field key points to the NUL-terminated string which is the search key.  The field data
       points to the data associated with that key.  The function hsearch() searches the hash ta-
       ble  for  an  item  with  the  same key as item (where "the same" is determined using str-
       cmp(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.

RETURN VALUE
       hcreate() and hcreate_r() return 0 when allocation of the memory for the hash table fails,
       nonzero 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  nonzero  other-
       wise.

ERRORS
       ENOMEM Out of memory.

CONFORMS TO
       The  functions  hcreate,  hsearch,  and hdestroy are from SVID, and are described in POSIX
       1003.1-2001.  The functions hcreate_r, hsearch_r, hdestroy_r are GNU extensions.

BUGS
       SVID and POSIX 1003.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.

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

	     /* 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 = (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",
			ep ? (int)(ep->data) : 0);
	     }
	     return 0;
	   }

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

GNU					    2001-12-26				       HSEARCH(3)


All times are GMT -4. The time now is 02:24 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password