DESCRIPTION

The sbuf family of functions allows one to safely allocate, construct and
release bounded null-terminated strings in kernel space. Instead of
arrays of characters, these functions operate on structures called sbufs,
defined in
The sbuf_new() function initializes the sbuf pointed to by its first
argument. If that pointer is NULL, sbuf_new() allocates a structsbuf
using malloc(9). The buf argument is a pointer to a buffer in which to
store the actual string; if it is NULL, sbuf_new() will allocate one
using malloc(9). The length is the initial size of the storage buffer.
The fourth argument, flags, may be comprised of the following flags:
SBUF_FIXEDLEN The storage buffer is fixed at its initial size.
Attempting to extend the sbuf beyond this size results
in an overflow condition.
SBUF_AUTOEXTEND This indicates that the storage buffer may be extended
as necessary, so long as resources allow, to hold
additional data.
Note that if buf is not NULL, it must point to an array of at least
length characters. The result of accessing that array directly while it
is in use by the sbuf is undefined.
The sbuf_new_auto() function is a shortcut for creating a completely
dynamic sbuf. It is the equivalent of calling sbuf_new() with values
NULL, NULL, 0, and SBUF_AUTOEXTEND.
The sbuf_delete() function clears the sbuf and frees any memory allocated
for it. There must be a call to sbuf_delete() for every call to
sbuf_new(). Any attempt to access the sbuf after it has been deleted
will fail.
The sbuf_clear() function invalidates the contents of the sbuf and resets
its position to zero.
The sbuf_setpos() function sets the sbuf’s end position to pos, which is
a value between zero and one less than the size of the storage buffer.
This effectively truncates the sbuf at the new position.
The sbuf_bcat() function appends the first len bytes from the buffer buf
to the sbuf.
The sbuf_bcopyin() function copies len bytes from the specified userland
address into the sbuf.
The sbuf_bcpy() function replaces the contents of the sbuf with the first
len bytes from the buffer buf.
The sbuf_cat() function appends the NUL-terminated string str to the sbuf
at the current position.
The sbuf_copyin() function copies a NUL-terminated string from the
specified userland address into the sbuf. If the len argument is non-
zero, no more than len characters (not counting the terminating NUL) are
copied; otherwise the entire string, or as much of it as can fit in the
sbuf, is copied.
The sbuf_cpy() function replaces the contents of the sbuf with those of
the NUL-terminated string str. This is equivalent to calling sbuf_cat()
with a fresh sbuf or one which position has been reset to zero with
sbuf_clear() or sbuf_setpos().
The sbuf_printf() function formats its arguments according to the format
string pointed to by fmt and appends the resulting string to the sbuf at
the current position.
The sbuf_vprintf() function behaves the same as sbuf_printf() except that
the arguments are obtained from the variable-length argument list ap.
The sbuf_putc() function appends the character c to the sbuf at the
current position.
The sbuf_trim() function removes trailing whitespace from the sbuf.
The sbuf_overflowed() function returns a non-zero value if the sbuf
overflowed.
The sbuf_finish() function null-terminates the sbuf and marks it as
finished, which means that it may no longer be modified using
sbuf_setpos(), sbuf_cat(), sbuf_cpy(), sbuf_printf() or sbuf_putc().
The sbuf_data() and sbuf_len() functions return the actual string and its
length, respectively; sbuf_data() only works on a finished sbuf.
sbuf_done() returns non-zero if the sbuf is finished.

NOTES

If an operation caused an sbuf to overflow, most subsequent operations on
it will fail until the sbuf is finished using sbuf_finish() or reset
using sbuf_clear(), or its position is reset to a value between 0 and one
less than the size of its storage buffer using sbuf_setpos(), or it is
reinitialized to a sufficiently short string using sbuf_cpy().

RETURNVALUES

The sbuf_new() function returns NULL if it failed to allocate a storage
buffer, and a pointer to the new sbuf otherwise.
The sbuf_setpos() function returns -1 if pos was invalid, and zero
otherwise.
The sbuf_cat(), sbuf_cpy(), sbuf_printf(), sbuf_putc(), and sbuf_trim()
functions all return -1 if the buffer overflowed, and zero otherwise.
The sbuf_overflowed() function returns a non-zero value if the buffer
overflowed, and zero otherwise.
The sbuf_data() and sbuf_len() functions return NULL and -1,
respectively, if the buffer overflowed.
The sbuf_copyin() function returns -1 if copying string from userland
failed, and number of bytes copied otherwise.