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

FreeBSD Manual Pages

  
 
  

home | help
SBUF(9)			 BSD Kernel Developer's	Manual		       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 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 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	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
     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 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-
     flowed.

     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.

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

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 buf-
     fer 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				   BSD

NAME | SYNOPSIS | DESCRIPTION | NOTES | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sbuf&sektion=9&manpath=FreeBSD+5.4-RELEASE+and+Ports>

home | help