From: des Date: Tue, 14 Mar 2006 11:57:28 +0000 (+0000) Subject: Add a man page, and set the correct property (svn:keywords, not svn:keyword) X-Git-Url: https://err.no/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b716746f0eb763c3a5d3d300c6a592d1e7005213;p=varnish Add a man page, and set the correct property (svn:keywords, not svn:keyword) git-svn-id: svn+ssh://projects.linpro.no/svn/varnish/trunk@49 d4fa192b-c00b-0410-8231-f00ffab90ce4 --- diff --git a/varnish-cache/lib/libsbuf/Makefile.am b/varnish-cache/lib/libsbuf/Makefile.am index 8cb80ede..6f43a6df 100644 --- a/varnish-cache/lib/libsbuf/Makefile.am +++ b/varnish-cache/lib/libsbuf/Makefile.am @@ -6,3 +6,6 @@ lib_LTLIBRARIES = libsbuf.la libsbuf_la_SOURCES = \ sbuf.c + +man_MANS = \ + sbuf.3 diff --git a/varnish-cache/lib/libsbuf/sbuf.3 b/varnish-cache/lib/libsbuf/sbuf.3 new file mode 100644 index 00000000..f0ceb680 --- /dev/null +++ b/varnish-cache/lib/libsbuf/sbuf.3 @@ -0,0 +1,338 @@ +.\"- +.\" 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. +.\" +.\" $Id$ +.\" $FreeBSD: src/share/man/man9/sbuf.9,v 1.25 2005/12/23 11:49:52 phk Exp $ +.\" +.Dd March 14, 2006 +.Dt SBUF 3 +.Os +.Sh NAME +.Nm sbuf_new , +.Nm sbuf_clear , +.Nm sbuf_setpos , +.Nm sbuf_bcat , +.Nm sbuf_bcpy , +.Nm sbuf_cat , +.Nm sbuf_cpy , +.Nm sbuf_printf , +.Nm sbuf_vprintf , +.Nm sbuf_putc , +.Nm sbuf_trim , +.Nm sbuf_overflowed , +.Nm sbuf_finish , +.Nm sbuf_data , +.Nm sbuf_len , +.Nm sbuf_done , +.Nm sbuf_delete +.Nd safe string formatting +.Sh LIBRARY +.Lb libsbuf +.Sh SYNOPSIS +.In sbuf.h +.Ft struct sbuf * +.Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags" +.Ft void +.Fn sbuf_clear "struct sbuf *s" +.Ft int +.Fn sbuf_setpos "struct sbuf *s" "int pos" +.Ft int +.Fn sbuf_bcat "struct sbuf *s" "const void *buf" "size_t len" +.Ft int +.Fn sbuf_bcpy "struct sbuf *s" "const void *buf" "size_t len" +.Ft int +.Fn sbuf_cat "struct sbuf *s" "const char *str" +.Ft int +.Fn sbuf_cpy "struct sbuf *s" "const char *str" +.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" +.Ft char * +.Fn sbuf_data "struct sbuf *s" +.Ft int +.Fn sbuf_len "struct sbuf *s" +.Ft int +.Fn sbuf_done "struct sbuf *s" +.Ft void +.Fn sbuf_delete "struct sbuf *s" +.Sh DESCRIPTION +The +.Nm sbuf +family of functions allows 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 +.In sys/sbuf.h . +.Pp +The +.Fn sbuf_new +function initializes the +.Fa sbuf +pointed to by its first argument. +If that pointer is +.Dv NULL , +.Fn sbuf_new +allocates a +.Vt struct sbuf +using +.Xr malloc 9 . +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 initial size of the storage buffer. +The fourth argument, +.Fa flags , +may be comprised of the following flags: +.Bl -tag -width ".Dv SBUF_AUTOEXTEND" +.It Dv SBUF_FIXEDLEN +The storage buffer is fixed at its 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 +is not +.Dv NULL , +it must point to an array of at least +.Fa length +characters. +The result of accessing that array directly while it is in use by the +sbuf is undefined. +.Pp +The +.Fn sbuf_delete +function clears the +.Fa sbuf +and frees any memory allocated for it. +There must be a call to +.Fn sbuf_delete +for every call to +.Fn sbuf_new . +Any attempt to access the sbuf after it has been deleted will fail. +.Pp +The +.Fn sbuf_clear +function invalidates the contents of the +.Fa sbuf +and resets its position to zero. +.Pp +The +.Fn sbuf_setpos +function sets the +.Fa sbuf Ns 's +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 +function appends the first +.Fa len +bytes from the buffer +.Fa buf +to the +.Fa sbuf . +.Pp +The +.Fn sbuf_bcpy +function replaces the contents of the +.Fa sbuf +with the first +.Fa len +bytes from the buffer +.Fa buf . +.Pp +The +.Fn sbuf_cat +function appends the NUL-terminated 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 NUL-terminated 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_clear +or +.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_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 +to the +.Fa sbuf +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 +overflowed. +.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_cpy , +.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; +.Fn sbuf_data +only works on a finished +.Fa sbuf . +.Fn sbuf_done +returns non-zero if the sbuf is finished. +.Sh NOTES +If an operation caused an +.Fa sbuf +to overflow, most subsequent operations on it will fail until the +.Fa sbuf +is finished using +.Fn sbuf_finish +or reset using +.Fn sbuf_clear , +or its 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 +.Dv NULL +if it failed to allocate a storage buffer, and a pointer to the new +.Fa sbuf +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_trim +all return \-1 if the buffer overflowed, and zero otherwise. +.Pp +.Fn sbuf_overflowed +returns a non-zero value if the buffer overflowed, and zero otherwise. +.Pp +.Fn sbuf_data +and +.Fn sbuf_len +return +.Dv NULL +and \-1, 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.4 . +.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 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 Sm\(/orgrav Aq des@FreeBSD.org .