1# bufref 2 3This is an internal module for handling buffer references. A referenced 4buffer is associated with its destructor function that is implicitly called 5when the reference is invalidated. Once referenced, a buffer cannot be 6reallocated. 7 8A data length is stored within the reference for binary data handling 9purpose; it is not used by the bufref API. 10 11The `struct bufref` is used to hold data referencing a buffer. The members of 12that structure **MUST NOT** be accessed or modified without using the dedicated 13bufref API. 14 15## init 16 17```c 18void Curl_bufref_init(struct bufref *br); 19``` 20 21Initialises a `bufref` structure. This function **MUST** be called before any 22other operation is performed on the structure. 23 24Upon completion, the referenced buffer is `NULL` and length is zero. 25 26This function may also be called to bypass referenced buffer destruction while 27invalidating the current reference. 28 29## free 30 31```c 32void Curl_bufref_free(struct bufref *br); 33``` 34 35Destroys the previously referenced buffer using its destructor and 36reinitialises the structure for a possible subsequent reuse. 37 38## set 39 40```c 41void Curl_bufref_set(struct bufref *br, const void *buffer, size_t length, 42 void (*destructor)(void *)); 43``` 44 45Releases the previously referenced buffer, then assigns the new `buffer` to 46the structure, associated with its `destructor` function. The later can be 47specified as `NULL`: this will be the case when the referenced buffer is 48static. 49 50if `buffer` is NULL, `length`must be zero. 51 52## memdup 53 54```c 55CURLcode Curl_bufref_memdup(struct bufref *br, const void *data, size_t length); 56``` 57 58Releases the previously referenced buffer, then duplicates the `length`-byte 59`data` into a buffer allocated via `malloc()` and references the latter 60associated with destructor `curl_free()`. 61 62An additional trailing byte is allocated and set to zero as a possible 63string zero-terminator; it is not counted in the stored length. 64 65Returns `CURLE_OK` if successful, else `CURLE_OUT_OF_MEMORY`. 66 67## ptr 68 69```c 70const unsigned char *Curl_bufref_ptr(const struct bufref *br); 71``` 72 73Returns a `const unsigned char *` to the referenced buffer. 74 75## len 76 77```c 78size_t Curl_bufref_len(const struct bufref *br); 79``` 80 81Returns the stored length of the referenced buffer. 82