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