strm_string_clone()

Arguments:

sstr

An existing shareable string handle.

Library:

Description:

This function clones the shareable string handle in sstr. Here, cloning means creating a new handle that points to identical string content.

With this design, each program component can use its own clone of a shareable string handle and destroy the handle when it's done using the string, 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_string_clone() versus making copies of it by pointer assignment or memcpy(): Because a shareable string keeps track of how many handles to it have been created, each of those handles must be destroyed in its own strm_string_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 shareable string on success, or a null pointer on failure (errno is set).