HASH(3)

NAME
hash - hash table support

SYNOPSIS

DESCRIPTION
The hash routines manipulate collections of dynamic, scoped hash tables.

A hash table provides an association between a key and its value. A key is a sequence of elements and a value is a user supplied pointer to the value. Each hash table has a dynamic number of slots, each pointing to the head of a forward linked collision chain.

Hashing occurs as follows: a hash function takes a key as an argument and returns a non-negative index. The index modulo the table size produces a slot that points to a collision chain. The collision chain is sequentially searched until a match is found for key. The hash tables are automatically resized as new entries are added.

Each hash table has one key type. The default key type is a pointer to a null-terminated string. The alternate key type is a pointer to a fixed length byte buffer, declared for a given table by the function described below.

Hash table information is partitioned into two parts for efficient scoping. The root part contains fixed information that is shared among a set of related hash tables. The remaining information is maintained on a per-table basis.

These basic types are defined in the header file hash.h (alternate names are listed in parenthesis):

The per-table information.
    The readonly public elements are:

    The number of table entries.

    The hash table name.

    The root information.
        The public elements are:

        The number of lookups.

        The number of lookup collisions.

    The table that this scope covers,
        if the table is not a scope.

    The current hash table size.

A collision chain hash bucket.
    The public structure elements are:

    Returns a pointer to the hash bucket key given the bucket pointer.

    The value associated with the key.

The hash bucket header that must be the first element in all user defined
    buckets. may not be used with user defined buckets.

Stores the hash table position for
    The public elements are:

    The current hash bucket pointer.

The routines are:

Creates a new hash table and returns a pointer to the table.
    malloc(3) is used to allocate space for the table. is returned if the table cannot be created. is a pointer to a reference hash table that provides default values for unspecified information. The new hash table and share the same root information. If is then new root information is created for the new table. The remaining arguments appear in op-arg pairs, followed by a final argument. The op-arg pairs are:

    is a function that is called to process
        assignments. The single argument is and the processed value is returned.

    are the
        flags to be cleared in the new hash table. See below.

    Specifies an alternate
        key comparison function. The arguments and return value for are the same as for strncmp(3) if is specified and strcmp(3) otherwise. The first argument is the key from the current hash bucket on the collision chain and the second argument is the user supplied key.

    is a function that is called when a hash bucket is freed.
        If was set in then the hash bucket pointer is passed, otherwise the bucket pointer is passed.

    Specifies an alternate
        key hash function. A key argument (and, if is specified, an key size argument) is passed to The return value must be a non-negative

    Specifies the mean collision chain length.
        The hash table is automatically resized when this value is exceeded. The default mean chain length is 2.

    Associates
        with the hash table. Used by

    The fixed size in bytes for
        keys in the table. If is 0 (the default) then the keys are interpreted as null-terminated strings.

    Changes the hash table flags by
        oring in The flags, which may be ored together, are:

        Keys for new hash table entries are to be copied to data areas obtained from
            malloc(3).

        Fixes the hash table size, disabling any automatic table resizing.

        The new hash table is a scope that is to be pushed on top of
            must be

    is a
        variable argument list pointer (see

The hash table
    is freed. The scope covered table pointer is returned, if is not a scope.

Operates on the key
    in the hash table according to and A pointer is returned unless otherwise noted. There are three basic lookup operations:

    is entered into the top level scope if it does not already exist.
        If also appears in a lower scope and is set for the table then the new bucket will share the field value with the lower scope.

    is deleted from the top level scope if it exists.
        is returned.

    The scopes are searched in order from top to bottom for
        The bucket pointer for the first occurrence is returned. is returned if is not found.
The basic operations may be qualified by the following (the qualifiers are restricted to the basic operations in the parenthesized list):

    is a pointer to a bucket that has already been entered into the table.

    is taken to be the size of the hash bucket to be created for
        in the top level scope. The minimum bucket size is silently restricted to

    is a pointer to a bucket that has not been entered into the table.

    The lookup is restricted to the top level scope.

    Sets
        or clears the opaque property for the bucket. An opaque bucket is not visible in lower scopes.

    All scopes are searched for the bucket.
        If the bucket is not found for then a new bucket is created in the lowest scope.

    For the bucket field is set to and the bucket value is returned. For the bucket field is returned, if the bucket is not found.
If then the name from the most recent is used, avoiding recomputation of some internal parameters.

Returns the value
    associated with the key in the hash table If is then the name from the most recent is used, avoiding recomputation of some internal parameters. is returned if is not in the table. All scope covered tables are searched.

Returns a pointer to the most recent hash bucket for
    The value is set by and

Set the value of the key
    to in the top level scope of the hash table is entered into the top level scope if necessary. The (possibly re-allocated) key name pointer is returned (see If is 0 then the most recent lookup to or is used. This eliminates a re-hash and re-lookup of

The function
    is applied to each entry (not covered by a scope starting at in the hash table If is then only the top level hash table is used, otherwise the walk includes all scope covered tables. is called with key as the first argument, value as the second argument, and handle as the third argument. handle may be The walk terminates after the last entry or when returns a negative value. The return value of the last call to is returned. Only one walk may be active within a collection of scoped tables.

Returns a
    pointer for a sequential scan on the hash table If is then only the top level hash table is used, otherwise the scan includes all scope covered tables. Only one scan may be active within a collection of scoped tables. must be called to terminate the scan. is returned on error.

Returnes a pointer to the next bucket in the sequential scan set up by
    on If no elements remain then is returned.

Completes a scan initiated by
    on

Sets the flags for the hash table
    by oring in Only and may be set.

Clears the flags for the hash table
    by masking out Only and may be cleared.

Dumps hash table accounting info to standard error.
    If is then all allocated hash tables are dumped, otherwise only information on is dumped. If is then the hash bucket key-value pairs for each collision chain are also dumped.

Changes the size of the hash table
    to where must be a power of 2. Explicit calls to this routine are not necessary as hash tables are automatically resized.

Hashes the null terminated character string
    using a linear congruent pseudo-random number generator algorithm and returns a non-negative hash value.

Hashes the buffer
    of bytes using a linear congruent pseudo-random number generator algorithm and returns a non-negative hash value.

Returns a running 31-bit checksum of the string
    where is on the first call and the return value from a previous or call otherwise. The checksum value is consistent across all implementations.

Returns a running 31-bit checksum of buffer
    of bytes where is on the first call and the return value from a previous or call otherwise. The checksum value is consistent across all implementations.

SEE ALSO
sum(1)