Add a man page, and set the correct property (svn:keywords, not svn:keyword)

git-svn-id: http://www.varnish-cache.org/svn/trunk/varnish-cache@49 d4fa192b-c00b-0410-8231-f00ffab90ce4

lib/libsbuf/Makefile.am

@@ -6,3 +6,6 @@ lib_LTLIBRARIES = libsbuf.la
 
 libsbuf_la_SOURCES = \
 	sbuf.c
+
+man_MANS = \
+	sbuf.3

lib/libsbuf/sbuf.3

+.\"-
+.\" 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 .