table of contents
other versions
- wheezy 3.44-1
- jessie 3.74-1
- jessie-backports 4.10-2~bpo8+1
- testing 4.10-2
- unstable 4.10-2
other languages
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);void hdestroy(void);#define _GNU_SOURCE /* See feature_test_macros(7) */#include <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.ERRORS¶
hcreate_r() and hdestroy_r() can fail for the following reasons:- EINVAL
- htab is NULL.
- 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.
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.44 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/.2011-09-10 | GNU |