the vsb.3 man page living in lib/libvarnish is now retired

lib/libvarnish/vsb.3

-.\"-
-.\" Copyright (c) 2000 Poul Henning Kamp and Dag-Erling 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: src/share/man/man9/vsb.9,v 1.25 2005/12/23 11:49:52 phk Exp $
-.\"
-.\" XXX
-.ds str-Lb-libvarnish Varnish Library (libvarnish, \-lvarnish)
-.\" XXX
-.Dd March 14, 2006
-.Dt VSB 3
-.Os
-.Sh NAME
-.Nm vsb_new ,
-.Nm vsb_clear ,
-.Nm vsb_bcat ,
-.Nm vsb_cat ,
-.Nm vsb_printf ,
-.Nm vsb_vprintf ,
-.Nm vsb_putc ,
-.Nm vsb_finish ,
-.Nm vsb_data ,
-.Nm vsb_len ,
-.Nm vsb_delete
-.Nd safe string formatting
-.Sh LIBRARY
-.Lb libvarnish
-.Sh SYNOPSIS
-.In vsb.h
-.Ft struct vsb *
-.Fn vsb_new "struct vsb *s" "char *buf" "int length" "int flags"
-.Ft void
-.Fn vsb_clear "struct vsb *s"
-.Ft int
-.Fn vsb_bcat "struct vsb *s" "const void *buf" "size_t len"
-.Ft int
-.Fn vsb_cat "struct vsb *s" "const char *str"
-.Ft int
-.Fn vsb_printf "struct vsb *s" "const char *fmt" "..."
-.Ft int
-.Fn vsb_vprintf "struct vsb *s" "const char *fmt" "va_list ap"
-.Ft int
-.Fn vsb_putc "struct vsb *s" "int c"
-.Ft void
-.Fn vsb_finish "struct vsb *s"
-.Ft char *
-.Fn vsb_data "struct vsb *s"
-.Ft int
-.Fn vsb_len "struct vsb *s"
-.Ft void
-.Fn vsb_delete "struct vsb *s"
-.Sh DESCRIPTION
-The
-.Nm vsb
-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 vsbs ,
-defined in
-.In sys/vsb.h .
-.Pp
-The
-.Fn vsb_new
-function initializes the
-.Fa vsb
-pointed to by its first argument.
-If that pointer is
-.Dv NULL ,
-.Fn vsb_new
-allocates a
-.Vt struct vsb
-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 vsb_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 VSB_AUTOEXTEND"
-.It Dv VSB_FIXEDLEN
-The storage buffer is fixed at its initial size.
-Attempting to extend the vsb beyond this size results in an overflow condition.
-.It Dv VSB_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
-vsb is undefined.
-.Pp
-The
-.Fn vsb_delete
-function clears the
-.Fa vsb
-and frees any memory allocated for it.
-There must be a call to
-.Fn vsb_delete
-for every call to
-.Fn vsb_new .
-Any attempt to access the vsb after it has been deleted will fail.
-.Pp
-The
-.Fn vsb_clear
-function invalidates the contents of the
-.Fa vsb
-and resets its position to zero.
-.Pp
-The
-.Fn vsb_bcat
-function appends the first
-.Fa len
-bytes from the buffer
-.Fa buf
-to the
-.Fa vsb .
-.Pp
-The
-.Fn vsb_cat
-function appends the NUL-terminated string
-.Fa str
-to the
-.Fa vsb
-at the current position.
-.Pp
-The
-.Fn vsb_printf
-function formats its arguments according to the format string pointed
-to by
-.Fa fmt
-and appends the resulting string to the
-.Fa vsb
-at the current position.
-.Pp
-The
-.Fn vsb_vprintf
-function behaves the same as
-.Fn vsb_printf
-except that the arguments are obtained from the variable-length argument list
-.Fa ap .
-.Pp
-The
-.Fn vsb_putc
-function appends the character
-.Fa c
-to the
-.Fa vsb
-at the current position.
-.Pp
-The
-.Fn vsb_finish
-function null-terminates the
-.Fa vsb
-and marks it as finished, which means that it may no longer be
-modified using
-.Fn vsb_cat ,
-.Fn vsb_printf
-or
-.Fn vsb_putc .
-.Pp
-The
-.Fn vsb_data
-and
-.Fn vsb_len
-functions return the actual string and its length, respectively;
-.Fn vsb_data
-only works on a finished
-.Fa vsb .
-.Sh NOTES
-If an operation caused an
-.Fa vsb
-to overflow, most subsequent operations on it will fail until the
-.Fa vsb
-is finished using
-.Fn vsb_finish
-or reset using
-.Fn vsb_clear .
-.Sh RETURN VALUES
-.Fn vsb_new
-returns
-.Dv NULL
-if it failed to allocate a storage buffer, and a pointer to the new
-.Fa vsb
-otherwise.
-.Pp
-.Fn vsb_cat ,
-.Fn vsb_printf ,
-and
-.Fn vsb_putc
-all return \-1 if the buffer overflowed, and zero otherwise.
-.Pp
-.Fn vsb_data
-and
-.Fn vsb_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 vsb
-family of functions first appeared in
-.Fx 4.4 .
-.Sh AUTHORS
-.An -nosplit
-The
-.Nm vsb
-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 .