| 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:
ENTERFINDThe 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.4 |