Updated: May 06, 2022

Dictionary object


#include <sys/strm.h>
typedef struct strm_dict strm_dict_t;




The strm_dict_t structure is a private data type representing a dictionary object. Pointers to this data type are used as dictionary handles in API functions.

To create a new dictionary handle, call strm_dict_new(). The handle lets you access the dictionary content by reading, adding, modifying, or removing entries.

For functions that update dictionary entries, the original dictionary handle is destroyed and a new dictionary is created and a handle to it returned. The contents of the new dictionary are identical to the previous one except for the entry that was updated. This design means that any program components with handles to the previous dictionary will still see the older set of entries.

You can clone handles with strm_dict_clone(); this is more efficient than copying all of the dictionary content. You must call strm_dict_destroy() separately for each cloned handle to properly dispose of any resources associated with it.

Only when the last handle to a dictionary gets destroyed does the library free the object's memory (because it's now safe to do so).