---
name: "sbuf_trim"
section: "9"
platform: "linux"
package: "freebsd-manpages"
version: "6.0-5"
release: "Debian 4.0 (Etch)"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/sbuf_trim"
---

# sbuf\_trim(9)

safe string formatting

## 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 ⟨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)](/malloc/9.md). 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)](/malloc/9.md). 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\_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

**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\_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)](/printf/3.md), [strcat(3)](/strcat/3.md), [strcpy(3)](/strcpy/3.md), [copyin(9)](/copyin/9.md), [copyinstr(9)](/copyinstr/9.md), [printf(9)](/printf/9.md)

## 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⟩.