2097a095c9
avoid "will", detect "will" as a bad word in the CI Also line wrapped a bunch of paragraphs Closes #13001
2.2 KiB
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 purposes; 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);
Initializes 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 reinitializes 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 latter can be
specified as NULL: this is the case when the referenced buffer is static.
if buffer is NULL, length must 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 latter
associated with destructor curl_free().
An additional trailing byte is allocated and set to zero as a possible string null-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.