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```c 15void Curl_dyn_init(struct dynbuf *s, size_t toobig); 16``` 17 18This inits a struct to use for dynbuf and it can't fail. The `toobig` value 19**must** be set to the maximum size we allow this buffer instance to grow to. 20The functions below will return `CURLE_OUT_OF_MEMORY` when hitting this limit. 21 22## free 23 24```c 25void Curl_dyn_free(struct dynbuf *s); 26``` 27 28Free the associated memory and clean up. After a free, the `dynbuf` struct can 29be re-used to start appending new data to. 30 31## addn 32 33```c 34CURLcode Curl_dyn_addn(struct dynbuf *s, const void *mem, size_t len); 35``` 36 37Append arbitrary data of a given length to the end of the buffer. 38 39## add 40 41```c 42CURLcode Curl_dyn_add(struct dynbuf *s, const char *str); 43``` 44 45Append a C string to the end of the buffer. 46 47## addf 48 49```c 50CURLcode Curl_dyn_addf(struct dynbuf *s, const char *fmt, ...); 51``` 52 53Append a `printf()`-style string to the end of the buffer. 54 55## vaddf 56 57```c 58CURLcode Curl_dyn_vaddf(struct dynbuf *s, const char *fmt, va_list ap); 59``` 60 61Append a `vprintf()`-style string to the end of the buffer. 62 63## reset 64 65```c 66void Curl_dyn_reset(struct dynbuf *s); 67``` 68 69Reset the buffer length, but leave the allocation. 70 71## tail 72 73```c 74CURLcode Curl_dyn_tail(struct dynbuf *s, size_t length); 75``` 76 77Keep `length` bytes of the buffer tail (the last `length` bytes of the 78buffer). The rest of the buffer is dropped. The specified `length` must not be 79larger than the buffer length. 80 81## ptr 82 83```c 84char *Curl_dyn_ptr(const struct dynbuf *s); 85``` 86 87Returns a `char *` to the buffer if it has a length, otherwise a NULL. Since 88the buffer may be reallocated, this pointer should not be trusted or used 89anymore after the next buffer manipulation call. 90 91## uptr 92 93```c 94unsigned char *Curl_dyn_uptr(const struct dynbuf *s); 95``` 96 97Returns an `unsigned char *` to the buffer if it has a length, otherwise a 98NULL. Since the buffer may be reallocated, this pointer should not be trusted 99or used anymore after the next buffer manipulation call. 100 101## len 102 103```c 104size_t Curl_dyn_len(const struct dynbuf *s); 105``` 106 107Returns the length of the buffer in bytes. Does not include the terminating 108zero byte. 109