HCREATE(3) | Library Functions Manual | HCREATE(3) |
hcreate
, hcreate_r
,
hdestroy
, hdestroy1
,
hdestroy_r
, hdestroy1_r
,
hsearch
, hsearch_r
—
#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);
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:
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
FIND
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
.
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.
hcreate
(), hcreate_r
(),
hsearch
() and hsearch_r
()
functions will fail if:
ENOMEM
]The hsearch
() and
hsearch_r
() functions will also fail if the action
is FIND
and the element is not found:
ESRCH
]hcreate
(), hdestroy
() and
hsearch
() functions conform to X/Open
Portability Guide Issue 4, Version 2
(“XPG4.2”).
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.
February 7, 2017 | NetBSD 9.2 |