strm_dict_clone()

Arguments:

dict

An existing dictionary handle.

Library:

Description:

This function clones the dictionary handle in dict. Here, cloning means creating a new handle that points to identical dictionary content.

With this design, each program component can use its own clone of a dictionary handle and destroy the handle when it's done using the dictionary, without impacting other components.

The new handle may represent the same pointer value as the original handle and hence, be considered equal by the comparison operator. But there's an important difference between cloning a handle using strm_dict_clone() versus making copies of it by pointer assignment or memcpy(): Because a dictionary keeps track of how many handles to it have been created, each of those handles must be destroyed in its own strm_dict_destroy() call. Conversely, if you have made multiple copies of a single handle, you can use any one of them to destroy it, and you should not use any of them afterwards.

Returns:

A new handle to the dictionary object on success, or a null pointer on failure.