curl/docs/BUFREF.md

bufref

This is an internal module for handling buffer references. A referenced buffer is associated with its destructor function that is implicitly called when the reference is invalidated. Once referenced, a buffer cannot be reallocated.

A data length is stored within the reference for binary data handling purpose; it is not used by the bufref API.

The struct bufref is used to hold data referencing a buffer. The members of that structure MUST NOT be accessed or modified without using the dedicated bufref API.

init

void Curl_bufref_init(struct bufref *br);

Initialises a bufref structure. This function MUST be called before any other operation is performed on the structure.

Upon completion, the referenced buffer is NULL and length is zero.

This function may also be called to bypass referenced buffer destruction while invalidating the current reference.

free

void Curl_bufref_free(struct bufref *br);

Destroys the previously referenced buffer using its destructor and reinitialises the structure for a possible subsequent reuse.

set

void Curl_bufref_set(struct bufref *br, const void *buffer, size_t length,
                     void (*destructor)(void *));

Releases the previously referenced buffer, then assigns the new buffer to the structure, associated with its destructor function. The later can be specified as NULL: this will be the case when the referenced buffer is static.

if buffer is NULL, lengthmust be zero.

memdup

CURLcode Curl_bufref_memdup(struct bufref *br, const void *data, size_t length);

Releases the previously referenced buffer, then duplicates the length-byte data into a buffer allocated via malloc() and references the later associated with destructor curl_free().

An additional trailing byte is allocated and set to zero as a possible string zero-terminator; it is not counted in the stored length.

Returns CURLE_OK if successful, else CURLE_OUT_OF_MEMORY.

ptr

const unsigned char *Curl_bufref_ptr(const struct bufref *br);

Returns a const unsigned char * to the referenced buffer.

len

size_t Curl_bufref_len(const struct bufref *br);

Returns the stored length of the referenced buffer.