Buffers
=======

'lib/buffers.h' describes Dovecot's buffer API. Unless your code happens to be
VERY performance critical, you shouldn't handle writing to buffers/arrays
manually, but instead use the buffer API's safe functions to guarantee that
your code can't write past the buffer and cause a security hole.

Dovecot's buffers are the basic building block for <arrays> [Design.Arrays.txt]
and <strings> [Design.Strings.txt]. Use them instead if they make more sense
than buffers.

There are a two different ways to create buffers: statically and dynamically
allocated.

Static buffers
--------------

You can create statically allocated buffers with 'buffer_create_data()'. Trying
to write past the given buffer size will panic. The code to initialize this
looks like:

---%<-------------------------------------------------------------------------
unsigned char buf_data[1024];
buffer_t buf;

buffer_create_data(&buf, buf_data, sizeof(buf_data));
---%<-------------------------------------------------------------------------

Trying to write more than 1024 bytes to the buffer will cause an assert-crash,
so these buffers shouldn't be used unless you know exactly what the maximum
buffer size is.

To avoid accidental buffer overflows, don't use any more complex calculations
in the size parameter of 'buffer_create_data()'. It should always be
'sizeof(data_buffer)'.

You can also create non-writable buffers with 'buffer_create_const_data()'.
Static buffers don't need to be freed.

Dynamic buffers
---------------

Dynamically growing buffers can be created with 'buffer_create_dynamic(pool,
init_size)'. Memory for buffer is allocated from the given pool. When memory
needs to be grown, it's grown exponentially (2^n), with some exceptions to
avoid growing the given memory pool unless necessary. The initial buffer size
is always a guess - try to make it large enough that buffer wouldn't be grown
most of the time, but not so large that it wastes memory.

You should be careful with memory returned by 'buffer_get_space_unsafe()' and
'buffer_append_space_unsafe()'. This returned memory should be accessed
immediately afterwards and it must not be accessed anymore after other
'buffer_*()' calls, because they may reallocate the buffer and move it
elsewhere in memory.

Buffers always look like they're filled with NUL bytes. If you write past the
end of buffer, all the inserted bytes are filled with NULs. If you shrink the
buffer with 'buffer_set_used_size()' and again write past the end of used size,
all the old data is again gone and filled with NULs. If you for some reason
want to just temporarily shrink the buffer size and then change it back, you
can use 'buffer_set_used_size()' to grow it back to its original size (but no
larger).

(This file was created from the wiki on 2017-10-10 04:42)