cp_hashtable

Section: libcprops - cp_hashtable (3)
Updated: OCTOBER 2005
Index Return to Main Contents

NAME

cp_hashtable_get, cp_hashtable_get_by_option - lookup a hashtable entry by key

SYNOPSIS

void *cp_hashtable_get(cp_hashtable *table, void *key);
void *cp_hashtable_get_by_option(cp_hashtable *table, void *key,
int mode);

DESCRIPTION

cp_hashtable_get looks up the value stored under key. cp_hashtable_get_by_option allows specifying the retrieval mode as well. If COLLECTION_MODE_MULTIPLE_VALUES is set the hashtable is searched for multiple matches for key and the result, even if it is a single item, is returned in a newly created cp_list. The result list is created with the same mode, value copy function and value destructor as the hashtable. Hence the result list contains copies of values if COLLECTION_MODE_COPY was set on the table, and calling the list destructor triggers calls to the value finalization function if COLLECTION_MODE_DEEP is set. Also note that like cp_list_iterator and cp_hashlist_iterator the table and the result list share the same synchronization mechanism. These features add up to a consistent api behavior but also introduce certain subtleties. Potential complications are avoided by refraining from using the COLLECTION_MODE_DEEP bit with hashtables.

RETURN VALUE

get functions return the value the key maps to, or if COLLECTION_MODE_MULTIPLE_VALUES is set, a pointer to a newly created cp_list containing all matches; or NULL on error or if there is no mapping for the specified key. NULL may also be returned if a locking error occurs.

ERRORS

EINVAL: - the table or key parameter are NULL.
ENOMEM: - COLLECTION_MODE_MULTIPLE_VALUES is set and the result list creation failed.
EDEADLK: - a locking error occured. This should not normally come up unless accessing the collection lock directly rather than using api calls.

This document was created by man2html, using the manual pages.
Time: 12:01:45 GMT, May 23, 2006