hcreate(3)                                                   hcreate(3)

  hcreate()

  NAME

    hcreate(), hcreate_r(), hdestroy(), hdestroy_r(), hsearch(), hsearch_r(),
    - manage hash search table

  SYNOPSIS

    #include 

    int hcreate (size_t nel)
    void hdestroy(void)
    ENTRY *hsearch (ENTRY item, ACTION action)

    void *hcreate_r(size_t nel)
    void hdestroy_r (void *h)
    ENTRY *hsearch_r(void *h, ENTRY item), ACTION action)

  DESCRIPTION

    The hcreate(3), hdestroy(3), and hsearch(3) functions manage hash search
    tables. They create, destroy, and search a given table.

    First the table must be created using hcreate(3). The argument nel is an
    estimate of the maximum number of elements the table will hold. (For
    better performance, the function may actually create a table with more
    than nel elements.)

    To destroy the table, call hdestroy(3).

    To search and add items to the hash table, call hsearch(3). It returns a
    pointer into the hash table. The function takes an ENTRY structure and an
    ACTION enumerated type; both are defined in . The ENTRY defines
    the item being searched for and the ACTION defines the action to take if
    the item is not found.

    An ENTRY is defined as:

    typedef struct {
         char *key;
         char *data;
    } ENTRY;

    The item.key member points to a comparison key and the item.data member
    points to any other data associated with that key. For comparison,
    hsearch(3) uses the strcmp(3) function.

    The enumeration type ACTION is defined as:

    enum { FIND, ENTER, REMOVE } ACTION;

    (The type REMOVE is an INTERIX extension.)

    If the action argument to hsearch(3) is FIND, the function returns the
    null pointer. If the action argument is ENTER, the function inserts the
    item into the hash table and returns a pointer to the item. If the action
    is REMOVE, the hsearch(3) function looks from the indicated item and
    removes it from the hash table.

    The hcreate_r(3), hdestroy_r(3), and hsearch_r(3) functions are reentrant
    versions of the standard functions. The context pointer refers to a
    structure as returned by hcreate_r(3). These functions are only available
    if _ALL_SOURCE is defined.

    Both of the hsearch(3) functions make copies of the ENTERed keys in a
    series of string tables. The application does not need to keep storing the
    keys after the keys return. Because of this, the strings in the ENTRY
    structures by those functions are private and cannot be overwritten.

  RETURN VALUES

    The hcreate(3) function returns non-zero on success and 0 if it cannot
    create the hash table.

    On success, the hsearch(3) function returns a pointer to the item; on
    failure it returns a null pointer. It can fail if the action is FIND and
    the item could not be found, or if the action is ENTER and the table is
    full.

    The hdestroy(3) and hdestroy_r(3) functions don't return a value.

    On success, the hcreate_r(3) function returns a pointer to a context
    structure. On failure, it returns (void *)0 and sets the global variable
    errno.

    On success, the hsearch_r(3) with the FIND or ENTER function returns a
    pointer to the item; with the argument REMOVE, it returns the dataportion
    of the removed element cast from a void * to an ENTRY *. On failure it
    returns (void *)0 and sets the global variable errno.

  ERRORS

    The hcreate(3) function may fail for these reasons:

    [EBUSY]
        Hcreate(3) has already been called and the resultant hash table has
        not yet been destroyed.

    [ENOMEM]
        Not enough memory available.

    The hsearch(3) and hsearch_r(3) functions may fail for these reasons:

    [ENOENT]
        If called with either FIND or REMOVE, the requested key was not found
        in the hash table.

    The hcreate_r(3) function can fail for these reasons:

    [ENOMEM]

  EXAMPLES

    #include 
    #include 
    struct object_struct {
        char *name;
        size_t len;
        ...
    };
    /*
     * Place the supplied object into a hash table based upon its name.
     */
    static int
    hash_insert(struct object_struct *obj)
    {
        ENTRY e, *r;
        e.key = obj->name;
        e.data = (void *)obj;
        r = hsearch(e, ENTER);
        if ((ENTRY *)0 == r)
            return 0;
        return 1;
    }
    /*s
     * Retrieve an object from the hash table based upon it's name.
     */
    static struct object_struct *
    hash_get(char *name)
    {
        ENTRY e, *r;
        if ((char *)0 == name || '\0' == *name)
            return (struct object_struct *)0;
        e.key = name;
        e.data = (void *)0;
        r = hsearch(e, FIND);
        if ((ENTRY *)0 == r)
            return (struct object_struct *)0;
        return (struct object_struct *)r->data;
    }
    int
    main(int argc, char *argv[])
    {
        struct object_struct *new, *obj;
        char *name;
        ...
        /*l
         * Instantiate the hash table.
         */
        hcreate(1024);
        ...
        /*l
         * Store a newly defined object.
         */
        if (!hash_insert(new))
            fprintf(stderr, "Could not insert object into the hash table!\n");
        ...
        /*l
         * Retreive an object by name.
         */
        if ((struct object_struct *)0 == (obj=hash_get(name)))
            fprintf(stderr,
                  "Could not find object '%s' in the hash table!\n",
                  name);
        ...
        /*l
         * Release the hash table's resources.
         */
        hdestroy();
        ...
    }

  SEE ALSO

    bsearch(3)

    lsearch(3)

    tsearch(3)

  USAGE NOTES

    The following functions are thread safe: hcreate_r, hdestroy_r, hsearch_r.
    The following functions are not thread safe: hcreate, hdestroy, hsearch.

    None of these functions are async-signal safe.