Provided by: freebsd-manpages_8.2-1_all bug

NAME

     sbuf, sbuf_new, sbuf_new_auto, sbuf_clear, sbuf_setpos, sbuf_bcat, sbuf_bcopyin, sbuf_bcpy,
     sbuf_cat, sbuf_copyin, sbuf_cpy, sbuf_printf, sbuf_vprintf, sbuf_putc, sbuf_trim,
     sbuf_overflowed, sbuf_finish, sbuf_data, sbuf_len, sbuf_done, sbuf_delete — safe string
     formatting

SYNOPSIS

     #include <sys/types.h>
     #include <sys/sbuf.h>

     struct sbuf *
     sbuf_new(struct sbuf *s, char *buf, int length, int flags);

     struct sbuf *
     sbuf_new_auto();

     void
     sbuf_clear(struct sbuf *s);

     int
     sbuf_setpos(struct sbuf *s, int pos);

     int
     sbuf_bcat(struct sbuf *s, const void *buf, size_t len);

     int
     sbuf_bcopyin(struct sbuf *s, const void *uaddr, size_t len);

     int
     sbuf_bcpy(struct sbuf *s, const void *buf, size_t len);

     int
     sbuf_cat(struct sbuf *s, const char *str);

     int
     sbuf_copyin(struct sbuf *s, const void *uaddr, size_t len);

     int
     sbuf_cpy(struct sbuf *s, const char *str);

     int
     sbuf_printf(struct sbuf *s, const char *fmt, ...);

     int
     sbuf_vprintf(struct sbuf *s, const char *fmt, va_list ap);

     int
     sbuf_putc(struct sbuf *s, int c);

     int
     sbuf_trim(struct sbuf *s);

     int
     sbuf_overflowed(struct sbuf *s);

     void
     sbuf_finish(struct sbuf *s);

     char *
     sbuf_data(struct sbuf *s);

     int
     sbuf_len(struct sbuf *s);

     int
     sbuf_done(struct sbuf *s);

     void
     sbuf_delete(struct sbuf *s);

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 <sys/sbuf.h>.

     The sbuf_new() function initializes the sbuf pointed to by its first argument.  If that
     pointer is NULL, sbuf_new() allocates a struct sbuf 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().

RETURN VALUES

     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.

SEE ALSO

     printf(3), strcat(3), strcpy(3), copyin(9), copyinstr(9), printf(9)

HISTORY

     The sbuf family of functions first appeared in FreeBSD 4.4.

AUTHORS

     The sbuf 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>.