Add sbuf(9) man page with links to API function names.

Reviewed by:	ru

2 files changed, 245 insertions, 0 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 494b8e8..1023dbe 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -48,6 +48,7 @@ MAN9+=	device.9 device_add_child.9 device_delete_child.9 device_enable.9 \
 	bus_alloc_resource.9 bus_release_resource.9 \
 	VOP_ACLCHECK.9 VOP_GETACL.9 VOP_GETEXTATTR.9 VOP_SETACL.9 \
 	VOP_SETEXTATTR.9 acl.9 extattr.9 kobj.9 taskqueue.9 accept_filter.9 \
+	sbuf.9 \
 	sysctl_add_oid.9 sysctl_ctx_init.9
 
 MLINKS+=MD5.9 MD5Init.9 MD5.9 MD5Transform.9
@@ -180,4 +181,15 @@ MLINKS+=sysctl_ctx_init.9 sysctl_ctx_entry_add.9
 MLINKS+=sysctl_ctx_init.9 sysctl_ctx_entry_del.9
 MLINKS+=sysctl_ctx_init.9 sysctl_ctx_entry_find.9
 
+MLINKS+=sbuf.9 sbuf_new.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_putc.9
+MLINKS+=sbuf.9 sbuf_finish.9
+MLINKS+=sbuf.9 sbuf_data.9
+MLINKS+=sbuf.9 sbuf_len.9
+MLINKS+=sbuf.9 sbuf_delete.9
+
 .include <bsd.prog.mk>
diff --git a/share/man/man9/sbuf.9 b/share/man/man9/sbuf.9
new file mode 100644
index 0000000..bf74332
--- /dev/null
+++ b/share/man/man9/sbuf.9
@@ -0,0 +1,233 @@
+.\"-
+.\" Copyright (c) 2000 Poul Henning Kamp and Dag-Erling Coïdan Smørgrav
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd December 10, 2000
+.Dt sbuf 9
+.Os FreeBSD
+.Sh NAME
+.Nm sbuf_new ,
+.Nm sbuf_setpos ,
+.Nm sbuf_cat ,
+.Nm sbuf_cpy ,
+.Nm sbuf_printf ,
+.Nm sbuf_putc ,
+.Nm sbuf_finish ,
+.Nm sbuf_data ,
+.Nm sbuf_len ,
+.Nm sbuf_delete
+.Nd safe string formatting
+.Sh SYNOPSIS
+.Fd #include <sys/sbuf.h>
+.Ft int
+.Fn sbuf_new "struct sbuf *s" "char *buf" "size_t length" "int flags"
+.Ft int
+.Fn sbuf_setpos "struct sbuf *s" "size_t pos"
+.Ft int
+.Fn sbuf_cat "struct sbuf *s" "char *str"
+.Ft int
+.Fn sbuf_cpy "struct sbuf *s" "char *str"
+.Ft int
+.Fn sbuf_printf "struct sbuf *s" "char *fmt" "..."
+.Ft int
+.Fn sbuf_putc "struct sbuf *s" "int c"
+.Ft int
+.Fn sbuf_finish "struct sbuf *s"
+.Ft char *
+.Fn sbuf_data "struct sbuf *s"
+.Ft size_t
+.Fn sbuf_len "struct sbuf *s"
+.Ft void
+.Fn sbuf_delete "struct sbuf *s"
+.Sh DESCRIPTION
+The
+.Nm sbuf
+family of functions allow 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
+.Fa sbufs ,
+defined in
+.Aq Pa sys/sbuf.h .
+.Pp
+The
+.Fn sbuf_new
+function initializes the
+.Fa sbuf
+pointed to by its first argument.
+The
+.Fa buf
+argument is a pointer to a buffer in which to store the actual string;
+if it is
+.Dv NULL ,
+.Fn sbuf_new
+will allocate one using
+.Xr malloc 9 .
+The
+.Fa length
+is the intended size of the storage buffer.
+The fourth argument,
+.Fa flags ,
+is currently unused and should always be set to zero.
+.Pp
+Note that if
+.Fa buf
+is not
+.Dv NULL ,
+it must point to an array of at least
+.Fa length
+characters.
+.Pp
+The
+.Fn sbuf_setpos
+function sets the
+.Fa sbuf Ns 's
+current position to
+.Fa pos ,
+which is a value between zero and one less than the size of the
+storage buffer.
+.Pp
+The
+.Fn sbuf_cat
+function appends the string
+.Fa str
+to the
+.Fa sbuf
+at the current position.
+.Pp
+The
+.Fn sbuf_cpy
+function replaces the contents of the
+.Fa sbuf
+with those of the string
+.Fa str .
+This is equivalent to calling
+.Fn sbuf_cat
+with a fresh
+.Fa sbuf
+or one which position has been reset to zero with
+.Fn sbuf_setpos .
+.Pp
+The
+.Fn sbuf_printf
+function formats its arguments according to the format string pointed
+to by
+.Fa fmt
+and appends the resulting string to the
+.Fa sbuf
+at the current position.
+.Pp
+The
+.Fn sbuf_putc
+function appends the character
+.Fa c
+to the
+.Fa sbuf
+at the current position.
+.Pp
+The
+.Fn sbuf_finish
+function null-terminates the
+.Fa sbuf
+and marks it as finished, which means that it may no longer be
+modified using
+.Fn sbuf_setpos ,
+.Fn sbuf_cat ,
+.Fn sbuf_cpu ,
+.Fn sbuf_printf
+or
+.Fn sbuf_putc .
+.Pp
+The
+.Fn sbuf_data
+and
+.Fn sbuf_len
+functions return the actual string and its length, respectively, and
+only work on a finished and non-overflowed
+.Fa sbuf .
+.Pp
+Finally, the
+.Fn sbuf_delete
+function clears the
+.Fa sbuf
+and frees its storage buffer if it was allocated by
+.Fn sbuf_new .
+.Sh NOTES
+If an operation caused an
+.Fa sbuf
+to overflow, most subsequent operations (including
+.Fn sbuf_finish )
+on it will fail until the
+.Fa sbuf Ns 's
+position is reset to a value between 0 and one less than the size of
+its storage buffer using
+.Fn sbuf_setpos ,
+or it is reinitialized to a sufficiently short string using
+.Fn sbuf_cpy .
+.Sh RETURN VALUES
+.Fn sbuf_new
+returns \-1 if it failed to allocate a storage buffer, and zero
+otherwise.
+.Pp
+.Fn sbuf_setpos
+returns \-1 if
+.Fa pos
+was invalid, and zero otherwise.
+.Pp
+.Fn sbuf_cat ,
+.Fn sbuf_cpy ,
+.Fn sbuf_printf ,
+.Fn sbuf_putc ,
+and
+.Fn sbuf_finish
+all return \-1 if the buffer overflowed, and zero otherwise.
+.Pp
+.Fn sbuf_data
+and
+.Fn sbuf_len
+return
+.Dv NULL
+and 0, respectively, if the buffer overflowed.
+.Sh SEE ALSO
+.Xr printf 3 ,
+.Xr strcat 3 ,
+.Xr strcpy 3
+.Sh HISTORY
+The
+.Nm sbuf
+family of functions first appeared in
+.Fx 4.3 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm sbuf
+family of functions was designed by
+.An Poul-Henning Kamp Aq phk@FreeBSD.org
+and implemented by
+.An Dag-Erling Co\(:idan Sm\(/orgrav Aq des@FreeBSD.org .
+.Pp
+This manual page was written by
+.An Dag-Erling Co\(:idan Sm\(/orgrav .