Man Page
Manual Section... (3) - page: hdestroy_r
NAMEhcreate, hdestroy, hsearch, hcreate_r, hdestroy_r, hsearch_r - 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 *htab); int hsearch_r(ENTRY item, ACTION action, ENTRY **retval, struct hsearch_data *htab); void hdestroy_r(struct hsearch_data *htab);
DESCRIPTIONThe 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.
The three functions hcreate_r(), hsearch_r(), hdestroy_r() are reentrant versions that allow a program to use more than one hash search table at the same time. The last argument, htab, points to a structure that describes the table on which the function is to operate. The programmer performs unsuccessful table described by *htab. The hsearch_r() function differs from hsearch() in that a pointer to the found item is returned in *retval, rather than as the function result.
RETURN VALUEhcreate() and hcreate_r() return nonzero on success. They return 0.
ERRORS
hcreate() and hcreate_r() can fail for the following reasons:
- EINVAL
- (hcreate_r()) htab is NULL.
- ENOMEM
- Table full with action set to ENTER.
- ESRCH
- The action argument is FIND and no corresponding element is found in the table. only specifies the ENOMEM error.
CONFORMING TOThe 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.
NOTESHash allocated dynamically.) If these buffers need to be freed (perhaps because the program is repeatedly creating and destroying hash tables, rather than creating a single table whose lifetime matches that of the program), then the program must maintain bookkeeping data structures that allow it to free them.
BUGSSVr4 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 implementationbsearch(3), lsearch(3), malloc(3), tsearch