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 cannot 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