1# dynbuf 2 3This is the internal module for creating and handling "dynamic buffers". This 4means buffers that can be appended to, dynamically and grow in size to adapt. 5 6There will always be a terminating zero put at the end of the dynamic buffer. 7 8The `struct dynbuf` is used to hold data for each instance of a dynamic 9buffer. The members of that struct **MUST NOT** be accessed or modified 10without using the dedicated dynbuf API. 11 12## init 13 14 void Curl_dyn_init(struct dynbuf *s, size_t toobig); 15 16This inits a struct to use for dynbuf and it can't fail. The `toobig` value 17**must** be set to the maximum size we allow this buffer instance to grow to. 18The functions below will return `CURLE_OUT_OF_MEMORY` when hitting this limit. 19 20## free 21 22 void Curl_dyn_free(struct dynbuf *s); 23 24Free the associated memory and clean up. After a free, the `dynbuf` struct can 25be re-used to start appending new data to. 26 27## addn 28 29 CURLcode Curl_dyn_addn(struct dynbuf *s, const void *mem, size_t len); 30 31Append arbitrary data of a given length to the end of the buffer. 32 33## add 34 35 CURLcode Curl_dyn_add(struct dynbuf *s, const char *str); 36 37Append a C string to the end of the buffer. 38 39## addf 40 41 CURLcode Curl_dyn_addf(struct dynbuf *s, const char *fmt, ...); 42 43Append a `printf()`-style string to the end of the buffer. 44 45## vaddf 46 47 CURLcode Curl_dyn_vaddf(struct dynbuf *s, const char *fmt, va_list ap); 48 49Append a `vprintf()`-style string to the end of the buffer. 50 51## reset 52 53 void Curl_dyn_reset(struct dynbuf *s); 54 55Reset the buffer length, but leave the allocation. 56 57## tail 58 59 CURLcode Curl_dyn_tail(struct dynbuf *s, size_t length) 60 61Keep `length` bytes of the buffer tail (the last `length` bytes of the 62buffer). The rest of the buffer is dropped. The specified `length` must not be 63larger than the buffer length. 64 65## ptr 66 67 char *Curl_dyn_ptr(const struct dynbuf *s); 68 69Returns a `char *` to the buffer if it has a length, otherwise a NULL. Since 70the buffer may be reallocated, this pointer should not be trusted or used 71anymore after the next buffer manipulation call. 72 73## uptr 74 75 unsigned char *Curl_dyn_uptr(const struct dynbuf *s); 76 77Returns an `unsigned char *` to the buffer if it has a length, otherwise a 78NULL. Since the buffer may be reallocated, this pointer should not be trusted 79or used anymore after the next buffer manipulation call. 80 81## len 82 83 size_t Curl_dyn_len(const struct dynbuf *s); 84 85Returns the length of the buffer in bytes. Does not include the terminating 86zero byte. 87