sbuf(9)

NAME

sbuf_new, 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);
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
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 al
locate one
using malloc(9). The length is the initial size of the
storage buffer.
The fourth argument, flags, may be comprised of the follow
ing flags:
SBUF_FIXEDLEN The storage buffer is fixed at its ini
tial 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 re
sources 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 di
rectly while it
is in use by the sbuf is undefined.
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 stor
age 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 speci
fied 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 call
ing 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 be
tween 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

sbuf_new() returns NULL if it failed to allocate a storage
buffer, and a
pointer to the new sbuf otherwise.
sbuf_setpos() returns -1 if pos was invalid, and zero other
wise.
sbuf_cat(), sbuf_cpy(), sbuf_printf(), sbuf_putc(), and
sbuf_trim() all
return -1 if the buffer overflowed, and zero otherwise.
sbuf_overflowed() returns a non-zero value if the buffer
overflowed, and
zero otherwise.
sbuf_data() and sbuf_len() return NULL and -1, respectively,
if the
buffer overflowed.

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 Smorgrav
<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 Smorgrav
<des@FreeBSD.org>.
BSD July 9, 2004
Copyright © 2010-2024 Platon Technologies, s.r.o.           Home | Man pages | tLDP | Documents | Utilities | About
Design by styleshout