From 1575d4ecd73853fc50aaf5fa415028d4ec039917 Mon Sep 17 00:00:00 2001 From: des Date: Wed, 13 Dec 2000 19:53:37 +0000 Subject: Add sbuf(9) man page with links to API function names. Reviewed by: ru --- share/man/man9/Makefile | 12 +++ share/man/man9/sbuf.9 | 233 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 245 insertions(+) create mode 100644 share/man/man9/sbuf.9 (limited to 'share') 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 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 +.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 . -- cgit v1.1