VSB(3)

NAME
vsb_new, vsb_clear, vsb_setpos, vsb_bcat, vsb_bcpy, vsb_cat, vsb_cpy, vsb_printf, vsb_vprintf, vsb_putc, vsb_trim, vsb_overflowed, vsb_finish, vsb_data, vsb_len, vsb_done, vsb_delete - safe string formatting

LIBRARY
libvarnish

SYNOPSIS
#include <vsb.h>
struct vsb *
vsb_new(struct vsb *s, char *buf, int length, int flags);
void
vsb_clear(struct vsb *s);
int
vsb_setpos(struct vsb *s, int pos);
int
vsb_bcat(struct vsb *s, const void *buf, size_t len);
int
vsb_bcpy(struct vsb *s, const void *buf, size_t len);
int
vsb_cat(struct vsb *s, const char *str);
int
vsb_cpy(struct vsb *s, const char *str);
int
vsb_printf(struct vsb *s, const char *fmt, ...);
int
vsb_vprintf(struct vsb *s, const char *fmt, va_list ap);
int
vsb_putc(struct vsb *s, int c);
int
vsb_trim(struct vsb *s);
int
vsb_overflowed(struct vsb *s);
void
vsb_finish(struct vsb *s);
char *
vsb_data(struct vsb *s);
int
vsb_len(struct vsb *s);
int
vsb_done(struct vsb *s);
void
vsb_delete(struct vsb *s);

DESCRIPTION
The vsb 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 vsbs, defined in <sys/vsb.h>.

The vsb_new() function initializes the vsb pointed to by its first argument. If that pointer is NULL, vsb_new() allocates a struct vsb using malloc(9). The buf argument is a pointer to a buffer in which to store the actual string; if it is NULL, vsb_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:

VSB_FIXEDLEN
    The storage buffer is fixed at its initial size. Attempting to extend the vsb beyond this size results in an overflow condition.

VSB_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 vsb is undefined.

The vsb_delete() function clears the vsb and frees any memory allocated for it. There must be a call to vsb_delete() for every call to vsb_new(). Any attempt to access the vsb after it has been deleted will fail.

The vsb_clear() function invalidates the contents of the vsb and resets its position to zero.

The vsb_setpos() function sets the vsb'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 vsb at the new position.

The vsb_bcat() function appends the first len bytes from the buffer buf to the vsb.

The vsb_bcpy() function replaces the contents of the vsb with the first len bytes from the buffer buf.

The vsb_cat() function appends the NUL-terminated string str to the vsb at the current position.

The vsb_cpy() function replaces the contents of the vsb with those of the NUL-terminated string str. This is equivalent to calling vsb_cat() with a fresh vsb or one which position has been reset to zero with vsb_clear() or vsb_setpos().

The vsb_printf() function formats its arguments according to the format string pointed to by fmt and appends the resulting string to the vsb at the current position.

The vsb_vprintf() function behaves the same as vsb_printf() except that the arguments are obtained from the variable-length argument list ap.

The vsb_putc() function appends the character c to the vsb at the current position.

The vsb_trim() function removes trailing whitespace from the vsb.

The vsb_overflowed() function returns a non-zero value if the vsb overflowed.

The vsb_finish() function null-terminates the vsb and marks it as finished, which means that it may no longer be modified using vsb_setpos(), vsb_cat(), vsb_cpy(), vsb_printf() or vsb_putc().

The vsb_data() and vsb_len() functions return the actual string and its length, respectively; vsb_data() only works on a finished vsb. vsb_done() returns non-zero if the vsb is finished.

NOTES
If an operation caused an vsb to overflow, most subsequent operations on it will fail until the vsb is finished using vsb_finish() or reset using vsb_clear(), or its position is reset to a value between 0 and one less than the size of its storage buffer using vsb_setpos(), or it is reinitialized to a sufficiently short string using vsb_cpy().

RETURN VALUES
vsb_new() returns NULL if it failed to allocate a storage buffer, and a pointer to the new vsb otherwise.

vsb_setpos() returns -1 if pos was invalid, and zero otherwise.

vsb_cat(), vsb_cpy(), vsb_printf(), vsb_putc(), and vsb_trim() all return -1 if the buffer overflowed, and zero otherwise.

vsb_overflowed() returns a non-zero value if the buffer overflowed, and zero otherwise.

vsb_data() and vsb_len() return NULL and -1, respectively, if the buffer overflowed.

SEE ALSO
printf(3), strcat(3), strcpy(3)

HISTORY
The vsb family of functions first appeared in FreeBSD 4.4.

AUTHORS
-nosplit The vsb family of functions was designed by Poul-Henning Kamp <phk@FreeBSD.org> and implemented by Dag-Erling Smørgrav <des@FreeBSD.org>. Additional improvements were suggested by Justin T. Gibbs <gibbs@FreeBSD.org>. Auto-extend support added by Kelly Yancey <kbyanc@FreeBSD.org>.

This manual page was written by Dag-Erling Smørgrav <des@FreeBSD.org>.