To create a buffer, you must invoke
sbuf_init
first. After all the necessary operations, the
sbuf *
structure must be disposed with
sbuf_free.

After the buffer is created, you might want to add a data to the buffer.
It can be done using
sbuf_add sbuf *sb const char *string
and
sbuf_add2 sbuf *sb const void *data size_t nbytes
functions. The second function does not rely on ASCIIZ idea and places the
nbytes
of the
data
into the smart buffer. Both functions automatically extend buffer to fit
all the characters provided. In case of error, the functions will return -1
and the buffer will be left intact.
Upon success,
sbuf_add
returns with the number of written bytes and
sbuf_add2
returns with the adjusted
len
field of the passed
sbuf *
structure. Otherwise a -1 is returned by both functions.

sbuf_trim
trims given number of characters off the buffer from the left or right side,
returning a number of bytes actually trimmed (which may be less than requested
in case the actual buffer length is smaller). This is a zero-cost operation,
as it just shifts pointers.

sbuf_detach
used to detach the buffer from the smart buffer descriptor, and return
a pointer to that detached memory. If
the optional
optLength
or
optSize
are given,
sbuf_detach
will fill them with the actual values of the buffer length (number of
meaningful bytes) and buffer size (allocated memory) appropriately.
Upon detach, the smart buffer descriptor will be re-initialized
to contain new, empty buffer. After detaching, the buffer descriptor
( sbuf)
will be reinitialized (read "empty").

To pre-extend the buffer up to the specified size, use
sbuf_extend.
This function will also clear the buffer from the current position
( sb->len)
to the end of the allocated memory.

sbuf_sprintf
and
sbuf_vsprintf
functions used to add the formatted string to the end of the buffer.
These functions returns the number of bytes actually writen. Buffer
will be automatically extended to fit the string. In case of error,
-1 will be returned and buffer will be left intact. See the
manual pages on
sprintf(3)
and
vsprintf(3)
to learn more.

sbuf_fetch
used to fetch the substring or token from the start of the buffer.
If
optLen
argument is zero
optDdelimiter
must contain the set of delimiting characters, overwise ignored.
The
flags
argument controls the behavior of splitting routinge most like
in
splitf(3)
function, with exception that the buffer cant be split by regular expression.
optRetLen
will contain the length of returned string.

sbuf_fgets
is analogous to plain
fgets(3),
but has the significant feature. It adds the whole line from the given
stream to the buffer and returns the pointer. The buffer is reallocated
to suffice the memory requirements by this line.