Document sbuf_trim() and sbuf_vprintf(); add MLINKs.

Clarify that the contents of a caller-supplied buffer are undefined and
should not be examined directly.

Reviewed by:	des

2 files changed, 41 insertions, 5 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 04d1f85..1ca0633 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -350,7 +350,9 @@ MLINKS+=sbuf.9 sbuf_setpos.9
 MLINKS+=sbuf.9 sbuf_cat.9
 MLINKS+=sbuf.9 sbuf_cpy.9
 MLINKS+=sbuf.9 sbuf_printf.9
+MLINKS+=sbuf.9 sbuf_vprintf.9
 MLINKS+=sbuf.9 sbuf_putc.9
+MLINKS+=sbuf.9 sbuf_trim.9
 MLINKS+=sbuf.9 sbuf_overflowed.9
 MLINKS+=sbuf.9 sbuf_finish.9
 MLINKS+=sbuf.9 sbuf_data.9
diff --git a/share/man/man9/sbuf.9 b/share/man/man9/sbuf.9
index 09edb77..35b288c 100644
--- a/share/man/man9/sbuf.9
+++ b/share/man/man9/sbuf.9
@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd January 28, 2001
+.Dd January 3, 2002
 .Dt SBUF 9
 .Os
 .Sh NAME
@@ -39,7 +39,9 @@
 .Nm sbuf_copyin ,
 .Nm sbuf_cpy ,
 .Nm sbuf_printf ,
+.Nm sbuf_vprintf ,
 .Nm sbuf_putc ,
+.Nm sbuf_trim ,
 .Nm sbuf_overflowed ,
 .Nm sbuf_finish ,
 .Nm sbuf_data ,
@@ -70,8 +72,12 @@
 .Ft int
 .Fn sbuf_printf "struct sbuf *s" "const char *fmt" "..."
 .Ft int
+.Fn sbuf_vprintf "struct sbuf *s" "const char *fmt" "va_list ap"
+.Ft int
 .Fn sbuf_putc "struct sbuf *s" "int c"
 .Ft int
+.Fn sbuf_trim "struct sbuf *s"
+.Ft int
 .Fn sbuf_overflowed "struct sbuf *s"
 .Ft void
 .Fn sbuf_finish "struct sbuf *s"
@@ -114,10 +120,18 @@ will allocate one using
 .Xr malloc 9 .
 The
 .Fa length
-is the intended size of the storage buffer.
+is the initial size of the storage buffer.
 The fourth argument,
 .Fa flags ,
-is currently unused and should always be set to zero.
+may be comprised of the following flags:
+.Bl -tag -width SBUF_AUTOEXTEND
+.It Dv SBUF_FIXEDLEN
+The storage buffer is fixed at it's initial size.
+Attempting to extend the sbuf beyond this size results in an overflow condition.
+.It Dv SBUF_AUTOEXTEND
+This indicates that the storage buffer may be extended as necessary, so long
+as resources allow, to hold additional data.
+.El
 .Pp
 Note that if
 .Fa buf
@@ -126,6 +140,10 @@ is not
 it must point to an array of at least
 .Fa length
 characters.
+The contents of the provided buffer are undefined; to retrieve the sbuf data
+.Fn sbuf_data
+must be called on the finished
+.Fa sbuf .
 .Pp
 The
 .Fn sbuf_clear
@@ -137,10 +155,11 @@ The
 .Fn sbuf_setpos
 function sets the
 .Fa sbuf Ns 's
-current position to
+end position to
 .Fa 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.
 .Pp
 The
 .Fn sbuf_bcat
@@ -214,6 +233,13 @@ and appends the resulting string to the
 at the current position.
 .Pp
 The
+.Fn sbuf_vprintf
+function behaves the same as
+.Fn sbuf_printf
+except that the arguments are obtained from the variable-length argument list
+.Fa ap .
+.Pp
+The
 .Fn sbuf_putc
 function appends the character
 .Fa c
@@ -222,6 +248,11 @@ to the
 at the current position.
 .Pp
 The
+.Fn sbuf_trim
+function removes trailing whitespace from the
+.Fa sbuf .
+.Pp
+The
 .Fn sbuf_overflowed
 function returns a non-zero value if the
 .Fa sbuf
@@ -285,8 +316,9 @@ was invalid, and zero otherwise.
 .Fn sbuf_cat ,
 .Fn sbuf_cpy ,
 .Fn sbuf_printf ,
+.Fn sbuf_putc ,
 and
-.Fn sbuf_putc
+.Fn sbuf_trim
 all return \-1 if the buffer overflowed, and zero otherwise.
 .Pp
 .Fn sbuf_overflowed
@@ -320,6 +352,8 @@ and implemented by
 .An Dag-Erling Co\(:idan Sm\(/orgrav Aq des@FreeBSD.org .
 Additional improvements were suggested by
 .An Justin T. Gibbs Aq gibbs@FreeBSD.org .
+Auto-extend support added by
+.An Kelly Yancey Aq kbyanc@FreeBSD.org .
 .Pp
 This manual page was written by
 .An Dag-Erling Co\(:idan Sm\(/orgrav .