table of contents
SBUF(9) | Kernel Developer's Manual | SBUF(9) |
NAME¶
sbuf
,
sbuf_new
,
sbuf_new_auto
,
sbuf_new_for_sysctl
,
sbuf_clear
,
sbuf_setpos
,
sbuf_bcat
,
sbuf_bcopyin
,
sbuf_bcpy
,
sbuf_cat
,
sbuf_copyin
,
sbuf_cpy
,
sbuf_printf
,
sbuf_vprintf
,
sbuf_putc
,
sbuf_set_drain
,
sbuf_trim
,
sbuf_error
,
sbuf_finish
,
sbuf_data
,
sbuf_len
,
sbuf_done
,
sbuf_delete
,
sbuf_start_section
,
sbuf_end_section
—
safe string composition
SYNOPSIS¶
#include
<sys/types.h>
#include
<sys/sbuf.h>
typedef int (
sbuf_drain_func) (
void *arg, const char *data, int len);
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);
void
sbuf_set_drain
(struct
sbuf *s,
sbuf_drain_func
*func, void
*arg);
int
sbuf_trim
(struct
sbuf *s);
int
sbuf_error
(struct
sbuf *s);
int
sbuf_finish
(struct
sbuf *s);
char *
sbuf_data
(struct
sbuf *s);
ssize_t
sbuf_len
(struct
sbuf *s);
int
sbuf_done
(struct
sbuf *s);
void
sbuf_delete
(struct
sbuf *s);
void
sbuf_start_section
(struct
sbuf *s, ssize_t
*old_lenp);
ssize_t
sbuf_end_section
(struct
sbuf *s, ssize_t
old_len, size_t
pad, int
c);
#include
<sys/sysctl.h>
struct sbuf *
sbuf_new_for_sysctl
(struct
sbuf *s, char
*buf, int
length, struct
sysctl_req *req);
DESCRIPTION¶
Thesbuf
family of functions allows one to
safely allocate, compose and release strings in kernel or user space.
Instead of arrays of characters, these functions operate on structures called
sbufs, defined in
<sys/sbuf.h>
.
Any errors encountered during the allocation or composition of the string will
be latched in the data structure, making a single error test at the end of the
composition sufficient to determine success or failure of the entire process.
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.
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_new_for_sysctl
() function will set
up an sbuf with a drain function to use
SYSCTL_OUT
() when the internal buffer
fills. Note that if the various functions which append to an sbuf are used
while a non-sleepable lock is held, the user buffer should be wired using
sysctl_wire_old_buffer
().
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_set_drain
() function sets a drain
function func for the
sbuf, and records a pointer
arg to be passed to the drain on callback.
The drain function cannot be changed while
sbuf_len is non-zero.
The registered drain function sbuf_drain_func
will be called with the argument arg provided
to sbuf_set_drain
(), a pointer
data to a byte string that is the contents of
the sbuf, and the length len of the data. If
the drain function exists, it will be called when the sbuf internal buffer is
full, or on behalf of sbuf_finish
(). The
drain function may drain some or all of the data, but must drain at least 1
byte. The return value from the drain function, if positive, indicates how
many bytes were drained. If negative, the return value indicates the negative
error code which will be returned from this or a later call to
sbuf_finish
(). The returned drained length
cannot be zero. To do unbuffered draining, initialize the sbuf with a two-byte
buffer. The drain will be called for every byte added to the sbuf. The
sbuf_bcopyin
(),
sbuf_copyin
(),
sbuf_trim
(), and
sbuf_data
() functions cannot be used on an
sbuf with a drain.
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_error
() function returns any error
value that the sbuf may have accumulated,
either from the drain function, or ENOMEM if the
sbuf overflowed. This function is generally
not needed and instead the error code from
sbuf_finish
() is the preferred way to
discover whether an sbuf had an error.
The sbuf_finish
() function will call the
attached drain function if one exists until all the data in the
sbuf is flushed. If there is no attached
drain, sbuf_finish
() NUL-terminates the
sbuf. In either case it marks the
sbuf as finished, which means that it may no
longer be modified using sbuf_setpos
(),
sbuf_cat
(),
sbuf_cpy
(),
sbuf_printf
() or
sbuf_putc
(), until
sbuf_clear
() is used to reset the sbuf.
The sbuf_data
() function returns the actual
string; sbuf_data
() only works on a
finished sbuf. The
sbuf_len
() function returns the length of
the string. For an sbuf with an attached
drain, sbuf_len
() returns the length of the
un-drained data. sbuf_done
() returns
non-zero if the sbuf is finished.
The sbuf_start_section
() and
sbuf_end_section
() functions may be used
for automatic section alignment. The arguments
pad and c
specify the padding size and a character used for padding. The arguments
old_lenp and
old_len are to save and restore the current
section length when nested sections are used. For the top level section
NULL
and -1 can be specified for
old_lenp and
old_len respectively.
NOTES¶
If an operation caused an sbuf to overflow, most subsequent operations on it will fail until the sbuf is finished usingsbuf_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
().
Drains in user-space will not always function as indicated. While the drain
function will be called immediately on overflow from the
sbuf_putc,
sbuf_bcat,
sbuf_cat functions,
sbuf_printf and
sbuf_vprintf currently have no way to
determine whether there will be an overflow until after it occurs, and cannot
do a partial expansion of the format string. Thus when using libsbuf the
buffer may be extended to allow completion of a single printf call, even
though a drain is attached.
RETURN VALUES¶
Thesbuf_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_error
() function returns a non-zero
value if the buffer has an overflow or drain error, and zero otherwise.
The sbuf_len
() function returns -1 if the
buffer overflowed.
The sbuf_copyin
() function returns -1 if
copying string from userland failed, and number of bytes copied otherwise.
The sbuf_end_section
() function returns the
section length or -1 if the buffer has an error.
The
sbuf_finish
(9)
function (the kernel version) returns ENOMEM if the sbuf overflowed before
being finished, or returns the error code from the drain if one is attached.
The
sbuf_finish
(3)
function (the userland version) will return zero for success and -1 and set
errno on error.
EXAMPLES¶
#include <sys/sbuf.h> struct sbuf *sb; sb = sbuf_new_auto(); sbuf_cat(sb, "Customers found:\n"); TAILQ_FOREACH(foo, &foolist, list) { sbuf_printf(sb, " %4d %s\n", foo->index, foo->name); sbuf_printf(sb, " Address: %s\n", foo->address); sbuf_printf(sb, " Zip: %s\n", foo->zipcode); } if (sbuf_finish(sb) != 0) /* Check for any and all errors */ err(1, "Could not generate message"); transmit_msg(sbuf_data(sb), sbuf_len(sb)); sbuf_delete(sb);
SEE ALSO¶
printf(3), strcat(3), strcpy(3), copyin(9), copyinstr(9), printf(9)HISTORY¶
Thesbuf
family of functions first appeared
in FreeBSD 4.4.
AUTHORS¶
Thesbuf
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⟩. Drain functionality added by
Matthew Fleming
⟨mdf@FreeBSD.org⟩.
This manual page was written by Dag-Erling
Smørgrav ⟨des@FreeBSD.org⟩.April 11, 2013 | Debian |