to deal with the fact that the public headers may be used with pre-c99
compilers, __restrict is used in place of restrict, and defined
appropriately for any supported compiler. we also avoid the form
[restrict] since older versions of gcc rejected it due to a bug in the
original c99 standard, and instead use the form *restrict.
null termination is only added when current size grows.
in update modes, null termination is not added if it does not fit
(i.e. it is not allowed to clobber data).
these rules make very little sense, but that's how it goes..
read should not be allowed past "current size".
append mode should write at "current size", not buffer size.
null termination should not be written except when "current size" grows.
