UTHASH(3)

# UTHASH(3) Manual Page

## NAME

uthash - C macros to add, find and delete items from a hash

## SYNOPSIS

    HASH_ADD        (hh_name, head, keyfield_name, key_len, item_ptr)
    HASH_ADD_KEYPTR (hh_name, head, key_ptr, key_len, item_ptr)
    HASH_FIND       (hh_name, head, key_ptr, key_len, item_ptr)
    HASH_DELETE     (hh_name, head, item_ptr)
    HASH_SORT       (head, cmp)

    HASH_ADD_INT    (head, keyfield_name, item_ptr)
    HASH_FIND_INT   (head, key_ptr, item_ptr)
    HASH_ADD_STR    (head, keyfield_name, item_ptr)
    HASH_FIND_STR   (head, key_ptr, item_ptr)
    HASH_DEL        (head, item_ptr)

## DESCRIPTION

These macros add, find, delete and sort items in a hash.

The first five generalized macros work with keys of any data type and fields of any name. The latter five convenience macros do the same thing, but take fewer arguments. (In order to use the convenience macros, the structure's `UT_hash_handle` field must be named `hh`, and the key field must be of type `int` or `char[]`).

The arguments are summarized below. Refer to the User Guide for a full explanation of the usage of these macros.

## ARGUMENTS

hh_name

  name of the `UT_hash_handle` field in the structure. Conventionally called `hh`.

head

  the structure pointer variable which acts as the "head" of the hash. So named because it points to the first item which is added to the hash.

keyfield_name

  the name of the key field in the structure. (In the case of a multi-field key, this is the first field of the key). If you're new to macros, it might seem strange to pass the name of a structure field as a parameter. Rest assured the macros expand to valid C code.

key_len

  the length of the key field in bytes. E.g. for an integer key, this is `sizeof(int)`, while for a string key it's `strlen(key)`. (For a multi-field key, see the notes in the User Guide on calculating key length).

key_ptr

  for `HASH_FIND`, this is a pointer to the key to look up in the hash (since it's a pointer, you can't directly pass a literal value here). For `HASH_ADD_KEYPTR`, this is the address of the key of the item being added.

item_ptr

  pointer to the structure being added, deleted or looked up. This is an input parameter for HASH_ADD and HASH_DELETE macros, and an output parameter for HASH_FIND.

cmp

  pointer to comparison function which accepts two arguments (pointers to items to compare) and returns an int specifying whether the first item should sort before, equal to, or after the second item (like `strcmp()`).

## NOTES

`HASH_ADD_KEYPTR` is used when the structure contains a pointer to the key, rather than the key itself.

## AUTHOR

Written by Troy D. Hanson, <thanson@users.sourceforge.net>

## RESOURCES

See the uthash web site for the complete User Guide.