Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SBUF(9)			 BSD Kernel Developer's	Manual		       SBUF(9)

     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

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

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

     sbuf_clear(struct sbuf *s);

     sbuf_setpos(struct	sbuf *s, int pos);

     sbuf_bcat(struct sbuf *s, const char *str,	size_t len);

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

     sbuf_bcpy(struct sbuf *s, const char *str,	size_t len);

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

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

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

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

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

     sbuf_putc(struct sbuf *s, int c);

     sbuf_trim(struct sbuf *s);

     sbuf_overflowed(struct sbuf *s);

     sbuf_finish(struct	sbuf *s);

     char *
     sbuf_data(struct sbuf *s);

     sbuf_len(struct sbuf *s);

     sbuf_done(struct sbuf *s);

     sbuf_delete(struct	sbuf *s);

     The sbuf family of	functions allows one to	safely allocate, construct and
     release bounded null-terminated strings in	kernel space.  Instead of ar-
     rays 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 ar-
     gument.  If that pointer is NULL, sbuf_new() allocates a struct sbuf us-
     ing 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 us-
     ing 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.	At-
		      tempting 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	addi-
		      tional data.

     Note that if buf is not NULL, it must point to an array of	at least
     length characters.	 The contents of the provided buffer are undefined; to
     retrieve the sbuf data sbuf_data()	must be	called on the finished sbuf.

     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 byte	string
     str 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	byte string str.

     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	speci-
     fied 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

     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 cur-
     rent position.

     The sbuf_trim() function removes trailing whitespace from the sbuf.

     The sbuf_overflowed() function returns a non-zero value if	the sbuf over-

     The sbuf_finish() function	null-terminates	the sbuf and marks it as fin-
     ished, 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.

     Finally, the sbuf_delete()	function clears	the sbuf and frees its storage
     buffer if it was allocated	by sbuf_new().

     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 us-
     ing 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().

     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 buf-
     fer overflowed.

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

     The sbuf family of	functions first	appeared in FreeBSD 4.4.

     The sbuf family of	functions was designed by Poul-Henning Kamp
     <> and implemented by Dag-Erling Coidan Smorgrav
     <>.	 Additional improvements were suggested	by Justin T.
     Gibbs <>.	 Auto-extend support added by Kelly Yancey

     This manual page was written by Dag-Erling	Coidan Smorgrav.

BSD				January	3, 2002				   BSD


Want to link to this manual page? Use this URL:

home | help