SBUF(9)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

💖 SBUF(9) — safe string composition 💖

okay bestie, welcome to the safe-string-composition page, straight from the Kernel Developer’s Manual. this is the sbuf glow-up: build strings without the chaos, and yes we’re keeping every function name exactly as-is. no cap.

🎀 NAME 🎀

Meet the whole sbuf fam: sbuf, sbuf_new, sbuf_new_auto, sbuf_new_for_sysctl, sbuf_clear, sbuf_get_flags, sbuf_set_flags, sbuf_clear_flags, sbuf_setpos, sbuf_bcat, sbuf_bcopyin, sbuf_bcpy, sbuf_cat, sbuf_copyin, sbuf_cpy, sbuf_nl_terminate, 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, sbuf_hexdump, sbuf_printf_drain, sbuf_putbuf. iconic lineup, honestly.

📚 LIBRARY 📚

library “libsbuf” — yup, that’s the one, bestie. slay.

✨ SYNOPSIS ✨

okay so here’s the C spellbook, copy it exactly — no autocorrect energy:

#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);

void
sbuf_clear(struct sbuf *s);

int
sbuf_get_flags(struct sbuf *s);

void
sbuf_set_flags(struct sbuf *s, int flags);

void
sbuf_clear_flags(struct sbuf *s, int flags);

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

int
sbuf_bcat(struct sbuf *s, const void *buf, 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_cpy(struct sbuf *s, const char *str);

int
sbuf_nl_terminate(struct sbuf *);

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);

void
sbuf_hexdump(struct sbuf *sb, void *ptr, int length, const char *hdr,
    int flags);

int
sbuf_printf_drain(void *arg, const char *data, int len);

void
sbuf_putbuf(struct sbuf *s);

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

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

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

#include <sys/sysctl.h>

struct sbuf *
sbuf_new_for_sysctl(struct sbuf *s, char *buf, int length,
    struct sysctl_req *req);

#endif    /* _KERNEL */

💖 DESCRIPTION 💖

okay so bestie, the whole sbuf family is basically your little string-building bestie that lets you safely allocate, compose and release strings — and it works in kernel space or user space, no cap. 🦋

instead of dealing with raw arrays of characters (ugh, so much manual work 😭), these functions operate on structs called sbufs, and they're defined in <sys/sbuf.h>. cute, right?

and here's the iconic part: any errors that happen while you're allocating or composing the string get latched right into the data structure itself. so you literally just do one error check at the very end and you instantly know if the whole process worked or flopped. main character error handling fr fr. ✨

🌸 sbuf_new() — the beginning of everything

The sbuf_new() function initializes the sbuf that its first argument points to. and if that pointer is NULL, sbuf_new() allocates a struct sbuf for you using malloc(9). generous queen. 💅

the buf argument is a pointer to a buffer where the actual string goes — and if that's NULL too, sbuf_new() will allocate one for you using malloc(9). the length argument is the initial size of the storage buffer.

the fourth argument, flags, can be made up of these beauties:

  • SBUF_FIXEDLEN — the storage buffer is locked at its initial size. trying to extend the sbuf past that size gets you an overflow condition, bestie. it's giving "you shall not pass". 💀
  • SBUF_AUTOEXTEND — this one says the storage buffer can be extended as necessary, as long as resources allow, to hold extra data. grow bestie grow 🌱
  • SBUF_INCLUDENUL — this makes the final nulterm byte count in the length of the data. so it's included, hence the name, iykyk 👑
  • SBUF_DRAINTOEOR — treats top-level sections started with sbuf_start_section() as a record boundary marker that gets used during drain operations to avoid records being split. but listen — if a record grows so big that it fills the sbuf and therefore can't be drained without being split, an error of EDEADLK is set. 😭
  • SBUF_NOWAIT — says that attempts to extend the storage buffer should fail under low memory conditions, exactly like malloc(9) with M_NOWAIT. no waiting around ✋
⚠️ huge warning bestie: if buf is not NULL, it must point to an array of at least length characters. and the result of accessing that array directly while it's in use by the sbuf is undefined. so like… don't. 🙈

🧚 the shortcuts

  • sbuf_new_auto() — a shortcut for creating a completely dynamic sbuf. it's the equivalent of calling sbuf_new() with the values NULL, NULL, 0, and SBUF_AUTOEXTEND. literally the lazy girl's (affectionate) way in 💅
  • sbuf_new_for_sysctl() — sets up an sbuf with a drain function so it uses SYSCTL_OUT() when the internal buffer fills up. but heads up: if the various functions that append to an sbuf are used while a non-sleepable lock is held, the user buffer should be wired using sysctl_wire_old_buffer(). safety first, always 🫶

🎀 the lifecycle functions

  • sbuf_delete() — clears the sbuf and frees any memory allocated for it. and this is a strict rule: there must be a call to sbuf_delete() for every call to sbuf_new(). any attempt to access the sbuf after it's been deleted will fail. periodt. 💀
  • sbuf_clear() — invalidates the contents of the sbuf and resets its position to zero. fresh start energy ✨

🦋 the flags functions

  • sbuf_get_flags() — returns the current user flags.
  • sbuf_set_flags() and sbuf_clear_flags() — set or clear one or more user flags, respectively.

the user flags are the ones described up in the sbuf_new() section, so scroll up if you forgot 👀

💜 the position function

  • sbuf_setpos() — sets the sbuf's end position to pos, which is a value between zero and the current position in the buffer. important: it can only truncate the sbuf to the new position. it does not let you grow, bestie, it only lets you snip. ✂️

🌈 the appending + copying girlies

  • sbuf_bcat() — appends the first len bytes from the buffer buf to the sbuf.
  • sbuf_bcopyin() — copies len bytes from the specified userland address into the sbuf.
  • sbuf_bcpy() — replaces the contents of the sbuf with the first len bytes from the buffer buf.
  • sbuf_cat() — appends the NUL-terminated string str to the sbuf at the current position.
  • sbuf_copyin() — 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 are copied (not counting the terminating NUL); otherwise the entire string — or as much of it as can fit in the sbuf — is copied. 🍓
  • sbuf_cpy() — 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 whose position has been reset to zero with sbuf_clear() or sbuf_setpos().

🧚 the drain stuff (pay attention bestie)

sbuf_set_drain() 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. nope, not allowed 💅

the registered drain function sbuf_drain_func gets called with:

  • the argument arg that you 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 it must drain at least 1 byte. no excuses.

the return value rules:

  • if positive, it indicates how many bytes were drained.
  • if negative, the return value indicates the negative error code which will be returned from this call or a later call to sbuf_finish().
  • if the returned drained length is 0, an error of EDEADLK is set. 😭

want unbuffered draining? initialize the sbuf with a two-byte buffer, and the drain will be called for every single byte added to the sbuf. iconic dedication honestly.

🚨 big one: the sbuf_bcopyin(), sbuf_bcpy(), sbuf_clear(), sbuf_copyin(), sbuf_cpy(), sbuf_trim(), sbuf_data(), and sbuf_len() functions cannot be used on an sbuf that has a drain. like, just don't even try it. 🙅‍♀️

🌸 the formatting + writing functions

  • sbuf_nl_terminate() — appends a trailing newline character, if the current line is non-empty and not already terminated by a newline character. polite little touch ✨
  • sbuf_printf() — formats its arguments according to the format string pointed to by fmt and appends the resulting string to the sbuf at the current position.
  • sbuf_vprintf() — behaves the same as sbuf_printf() except the arguments are obtained from the variable-length argument list ap.
  • sbuf_putc() — appends the character c to the sbuf at the current position.
  • sbuf_trim() — removes trailing whitespace from the sbuf. bye bye extra spaces 👋

💖 errors, finishing, and reading back

  • sbuf_error() — returns any error value the sbuf may have accumulated, either from the drain function, or ENOMEM if the sbuf overflowed. but real talk: this function is generally not needed, and the error code from sbuf_finish() is the preferred way to discover whether an sbuf had an error. iykyk 💅
  • sbuf_finish() — will call the attached drain function if one exists, until all the data in the sbuf is flushed. if there's no attached drain, sbuf_finish() NUL-terminates the sbuf. in either case it marks the sbuf as finished, which means 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 is officially retired, show's over. 🎬
  • sbuf_data() — returns the actual string. but it only works on a finished sbuf.
  • sbuf_len() — 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.

🎀 sections + hexdumps + special drains

sbuf_start_section() and sbuf_end_section() can 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 there 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. nesting slays 🌈

sbuf_hexdump() prints an array of bytes to the supplied sbuf, along with an ASCII representation of the bytes if possible. see the hexdump(3) man page for more details on the interface. 🔥

sbuf_printf_drain() is a drain function that will call printf, or log to the console. the argument arg must be either NULL, or a valid pointer to a size_t. if arg is not NULL, the total bytes drained will be added to the value pointed to by arg. cute little counter 🫶

sbuf_putbuf() printfs the sbuf to stdout if in userland, and to the console and log if in the kernel. the sbuf must be finished before calling sbuf_putbuf(). and heads up: it does not drain the buffer or update any pointers. 👑

⭐ NOTES ⭐

okay so if an operation caused an sbuf to overflow, most subsequent operations on it will fail — until one of these happens:

  • the sbuf is finished using sbuf_finish(), or
  • it's 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's reinitialized to a sufficiently short string using sbuf_cpy().

and here's a user-space caveat that lowkey matters: drains in user-space will not always function as indicated. while the drain function will be called immediately on overflow from 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 they cannot do a partial expansion of the format string. so when you're using libsbuf, the buffer may be extended to allow completion of a single printf call, even though a drain is attached. so like… it's giving "close enough". 😭

💀 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 otherwise.
  • sbuf_bcat(), sbuf_cat(), sbuf_cpy(), sbuf_printf(), sbuf_putc(), and sbuf_trim() all return -1 if the buffer overflowed, and zero otherwise.
  • sbuf_error() returns a non-zero value if the buffer has an overflow or drain error, and zero otherwise.
  • sbuf_len() returns -1 if the buffer overflowed.
  • sbuf_copyin() returns -1 if copying a string from userland failed, and the number of bytes copied otherwise.
  • sbuf_end_section() returns the section length or -1 if the buffer has an error.
  • sbuf_finish(9) (the kernel version) returns ENOMEM if the sbuf overflowed before being finished, or returns the error code from the drain if one is attached.
  • sbuf_finish(3) (the userland version) will return zero for success and -1 and set errno on error.

🦋 EXAMPLES 🦋

#include <sys/types.h>
#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 🌈

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

📜 HISTORY

okay so storytime bestie 💖 — the sbuf family of functions first appeared in FreeBSD 4.4. that's the origin story, that's the lore, no cap. ✨

👑 AUTHORS

these are the actual main characters, fr fr 🫶 — give them their flowers:

  • the sbuf family of functions was designed by Poul-Henning Kamp <phk@FreeBSD.org> 😭 iconic
  • and implemented by Dag-Erling Smørgrav <des@FreeBSD.org> — the way that duo just ate 💅
  • Additional improvements were suggested by Justin T. Gibbs <gibbs@FreeBSD.org> 🌟
  • Auto-extend support was added by Kelly Yancey <kbyanc@FreeBSD.org> 🔥
  • Drain functionality was added by Matthew Fleming <mdf@FreeBSD.org> 💜
  • and this very manual page was written by Dag-Erling Smørgrav <des@FreeBSD.org> 🎀

so yeah, a whole squad of legends built this thing. respect on every single name. 👑

and that's a wrap on SBUF(9), bestie 🦋💖 this one's from the Debian edition, dated October 3, 2023 — take care of it, and go forth and sbuf responsibly 🌸✨

📦 where this page comes from