HSEARCH(3) | Linux Programmer's Manual | HSEARCH(3) |
NAME
hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r, hsearch_r - hash table managementSYNOPSIS
#include<search.h>
int hcreate(size_t nel );
ENTRY *hsearch(ENTRY item , ACTION action );
#define _GNU_SOURCE /* See feature_test_macros(7) */
<search.h>
int hcreate_r(size_t nel , struct hsearch_data * htab );
int hsearch_r(ENTRY item , ACTION action , ENTRY ** retval ,
struct hsearch_data * htab );
void hdestroy_r(struct hsearch_data * htab );
DESCRIPTION
The three functions hcreate(), hsearch(), and hdestroy() allow the caller to create and manage a hash search table containing entries consisting of a key (a string) and associated data. Using these functions, only one hash table can be used at a time.typedef struct entry {
char *key;
void *data;
} ENTRY;
RETURN VALUE
hcreate() and hcreate_r() return nonzero on success. They return 0 on error, with errno set to indicate the cause of the error.ERRORS
hcreate_r() and hdestroy_r() can fail for the following reasons:- EINVAL
- htab is NULL.
hsearch() and hsearch_r() can fail for the following reasons:
- ENOMEM
- action was ENTER, key was not found in the table, and there was no room in the table to add a new entry.
- ESRCH
- action was FIND, and key was not found in the table.
POSIX.1-2001 specifies only the ENOMEM error.
ATTRIBUTES
Multithreading (see pthreads(7))
The hcreate(), hsearch(), and hdestroy() functions use a global space for storing the table, so they are not thread-safe.The hcreate_r(), hsearch_r(), and hdestroy_r() functions are thread-safe.
CONFORMING TO
The functions hcreate(), hsearch(), and hdestroy() are from SVr4, and are described in POSIX.1-2001. The functions hcreate_r(), hsearch_r(), and hdestroy_r() are GNU extensions.NOTES
Hash table implementations are usually more efficient when the table contains enough free space to minimize collisions. Typically, this means that nel should be at least 25% larger than the maximum number of elements that the caller expects to store in the table.BUGS
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. In libc and glibc (before version 2.3), the implementation violates the specification, updating the data for the given key in this case.EXAMPLE
The following program inserts 24 items into a hash table, then prints some of them.
#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;
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);
}
hdestroy();
exit(EXIT_SUCCESS);
}
SEE ALSO
bsearch(3), lsearch(3), malloc(3), tsearch(3)COLOPHON
This page is part of release 3.53 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/.2013-07-22 | GNU |