hsearch(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
HCREATE(3)              NetBSD Library Functions Manual             HCREATE(3)


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 argu-
     ments.  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 ta-
     ble 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 exten-
     sions.


CAVEATS

     At least the following limitations can be mentioned:

     ·   The original, non-GNU interface permits the use of only one hash ta-
         ble 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.

NetBSD 8.0                     February 7, 2017                     NetBSD 8.0