NAME
hcreate,
hcreate_r,
hdestroy,
hdestroy1,
hdestroy_r,
hdestroy1_r,
hsearch,
hsearch_r —
manage hash search table
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <search.h>
int
hcreate(
size_t
nel);
int
hcreate_r(
size_t
nel,
struct hsearch_data
*table);
void
hdestroy(
void);
void
hdestroy1(
void
(*freekey)(void *),
void
(*freedata)(void *));
void
hdestroy_r(
struct
hsearch_data *table);
void
hdestroy1_r(
struct
hsearch_data *table,
void
(*freekey)(void *),
void
(*freedata)(void *));
ENTRY *
hsearch(
ENTRY
item,
ACTION action);
int
hsearch_r(
ENTRY
item,
ACTION action,
ENTRY ** itemp,
struct hsearch_data
*table);
DESCRIPTION
The
hcreate(),
hcreate_r(),
hdestroy(),
hdestroy_r()
hdestroy1(),
hdestroy1_r()
hsearch(), and
hsearch_r() functions
manage hash search tables.
The
hcreate() function allocates and initializes the table.
The
nel argument specifies an estimate of the maximum
number of entries to be held by the table. Unless further memory allocation
fails, supplying an insufficient
nel value will not
result in functional harm, although a performance degradation may occur.
Initialization using the
hcreate() function is mandatory
prior to any access operations using
hsearch().
The
hdestroy() function destroys a table previously created
using
hcreate(). After a call to
hdestroy(), the data can no longer be accessed.
The
hsearch() function is used to search to the hash table. It
returns a pointer into the hash table indicating the address of an item. The
item argument is of type
ENTRY,
defined in the
<search.h> header.
This is a structure type that contains two pointers:
- char
*key
- comparison key
- void
*data
- pointer to data associated with
key
The key comparison function used by
hsearch() is
strcmp(3).
The
action argument is of type
ACTION, an enumeration type which defines the following
values:
-
-
ENTER
- Insert item into the hash table. If
an existing item with the same key is found, it is not replaced. Note that
the key and data elements of
item are used directly by the new table entry. The
storage for the key must not be modified during the lifetime of the hash
table.
-
-
FIND
- Search the hash table without inserting
item.
The traditional
hdestroy() and
hdestroy_r()
functions don't
free(3) the data
associated with the
key and
value
of each entry, because they did not allocate them. Since there is no
“iterator” function provided, the
hdestroy1()
and
hdestroy1_r() allow controlling how the
key or
value will be freed using
the provided functions in the
freekey and
freedata arguments. If they are
NULL
, then
key and
value are not freed.
The
hcreate_r(),
hdestroy_r(),
hdestroy1_r(), and
hsearch_r() functions
are re-entrant versions of the above functions that can operate on a table
supplied by the user. The
hsearch_r() function returns
0
if the action is
ENTER
and
the element cannot be created,
1
otherwise. If the
element exists or can be created, it will be placed in
itemp, otherwise
itemp will be set
to
NULL
.
RETURN VALUES
If successful, the
hcreate() and
hcreate_r()
functions return a non-zero value. Otherwise, a value of
0
is returned and
errno is set
to indicate the error.
The
hdestroy() and
hdestroy_r() functions
return no value.
If successful, the
hsearch() function returns a pointer to
hash table entry matching the provided key. If the action is
FIND
and the item was not found, or if the action is
ENTER
and the insertion failed,
NULL
is returned and
errno is
set to indicate the error. If the action is
ENTER
and
an entry already existed in the table matching the given key, the existing
entry is returned and is not replaced.
The
hsearch_r() function returns
1
unless the table is full, when it returns
0
. If
hsearch() returns
0
or the element
is not found,
errno is set to indicate the error.
ERRORS
The
hcreate(),
hcreate_r(),
hsearch() and
hsearch_r() functions will
fail if:
-
-
- [
ENOMEM
]
- Insufficient memory is available.
The
hsearch() and
hsearch_r() functions will
also fail if the action is
FIND
and the element is not
found:
-
-
- [
ESRCH
]
- The item given is not found.
SEE ALSO
bsearch(3),
free(3),
lsearch(3),
malloc(3),
strcmp(3)
STANDARDS
The
hcreate(),
hdestroy() and
hsearch() functions conform to
X/Open
Portability Guide Issue 4, Version 2 (“XPG4.2”).
HISTORY
The
hcreate(),
hdestroy() and
hsearch() functions first appeared in
AT&T System V UNIX. The
hcreate_r(),
hdestroy_r(), and
hsearch_r() functions are GNU extensions. The
hdestroy1() and
hdestroy1_r() are
NetBSD extensions.
CAVEATS
At least the following limitations can be mentioned:
- The original, non-GNU interface permits the use of only
one hash table at a time.
- Individual hash table entries can be added, but not
deleted.
- There is no iterator to scan for all entries in the
table.