int
hcreate(
size_t nel
)
void
hdestroy(
void
)
ENTRY
*
hsearch(
ENTRY item
, ACTION action
)
),
hdestroy(
)
and
hsearch(
)
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
,
a structural type which contains the following members:
char
*key
void
*data
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
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
item
.
)
function returns a non-zero value.
Otherwise, a value of 0 is returned and
errno
is set to indicate the error.
The
hdestroy()
functions
returns 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.
)
and
hsearch(
)
functions will fail if:
ENOMEM
]
),
hdestroy(
)
and
hsearch(
)
functions conform to
X/Open Portability Guide Issue 4, Version 2 (``XPG4.2'') .
),
hdestroy(
)
and
hsearch(
)
functions first appeared in
AT&T
System V UNIX
.