2
.\" Copyright (c) 2000 Poul Henning Kamp and Dag-Erling Smørgrav
3
.\" All rights reserved.
5
.\" Redistribution and use in source and binary forms, with or without
6
.\" modification, are permitted provided that the following conditions
8
.\" 1. Redistributions of source code must retain the above copyright
9
.\" notice, this list of conditions and the following disclaimer.
10
.\" 2. Redistributions in binary form must reproduce the above copyright
11
.\" notice, this list of conditions and the following disclaimer in the
12
.\" documentation and/or other materials provided with the distribution.
14
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27
.\" $FreeBSD: src/share/man/man9/vsb.9,v 1.25 2005/12/23 11:49:52 phk Exp $
30
.ds str-Lb-libvarnish Varnish Library (libvarnish, \-lvarnish)
53
.Nd safe string formatting
59
.Fn vsb_new "struct vsb *s" "char *buf" "int length" "int flags"
61
.Fn vsb_clear "struct vsb *s"
63
.Fn vsb_setpos "struct vsb *s" "int pos"
65
.Fn vsb_bcat "struct vsb *s" "const void *buf" "size_t len"
67
.Fn vsb_bcpy "struct vsb *s" "const void *buf" "size_t len"
69
.Fn vsb_cat "struct vsb *s" "const char *str"
71
.Fn vsb_cpy "struct vsb *s" "const char *str"
73
.Fn vsb_printf "struct vsb *s" "const char *fmt" "..."
75
.Fn vsb_vprintf "struct vsb *s" "const char *fmt" "va_list ap"
77
.Fn vsb_putc "struct vsb *s" "int c"
79
.Fn vsb_trim "struct vsb *s"
81
.Fn vsb_overflowed "struct vsb *s"
83
.Fn vsb_finish "struct vsb *s"
85
.Fn vsb_data "struct vsb *s"
87
.Fn vsb_len "struct vsb *s"
89
.Fn vsb_done "struct vsb *s"
91
.Fn vsb_delete "struct vsb *s"
95
family of functions allows one to safely allocate, construct and
96
release bounded null-terminated strings in kernel space.
97
Instead of arrays of characters, these functions operate on structures
105
function initializes the
107
pointed to by its first argument.
117
argument is a pointer to a buffer in which to store the actual string;
121
will allocate one using
125
is the initial size of the storage buffer.
128
may be comprised of the following flags:
129
.Bl -tag -width ".Dv VSB_AUTOEXTEND"
131
The storage buffer is fixed at its initial size.
132
Attempting to extend the vsb beyond this size results in an overflow condition.
133
.It Dv VSB_AUTOEXTEND
134
This indicates that the storage buffer may be extended as necessary, so long
135
as resources allow, to hold additional data.
142
it must point to an array of at least
145
The result of accessing that array directly while it is in use by the
152
and frees any memory allocated for it.
153
There must be a call to
157
Any attempt to access the vsb after it has been deleted will fail.
161
function invalidates the contents of the
163
and resets its position to zero.
171
which is a value between zero and one less than the size of the
173
This effectively truncates the vsb at the new position.
177
function appends the first
179
bytes from the buffer
186
function replaces the contents of the
190
bytes from the buffer
195
function appends the NUL-terminated string
199
at the current position.
203
function replaces the contents of the
205
with those of the NUL-terminated string
207
This is equivalent to calling
211
or one which position has been reset to zero with
218
function formats its arguments according to the format string pointed
221
and appends the resulting string to the
223
at the current position.
227
function behaves the same as
229
except that the arguments are obtained from the variable-length argument list
234
function appends the character
238
at the current position.
242
function removes trailing whitespace from the
247
function returns a non-zero value if the
253
function null-terminates the
255
and marks it as finished, which means that it may no longer be
268
functions return the actual string and its length, respectively;
270
only works on a finished
273
returns non-zero if the vsb is finished.
275
If an operation caused an
277
to overflow, most subsequent operations on it will fail until the
283
or its position is reset to a value between 0 and one less than the
284
size of its storage buffer using
286
or it is reinitialized to a sufficiently short string using
292
if it failed to allocate a storage buffer, and a pointer to the new
299
was invalid, and zero otherwise.
307
all return \-1 if the buffer overflowed, and zero otherwise.
310
returns a non-zero value if the buffer overflowed, and zero otherwise.
317
and \-1, respectively, if the buffer overflowed.
325
family of functions first appeared in
331
family of functions was designed by
332
.An Poul-Henning Kamp Aq phk@FreeBSD.org
334
.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
335
Additional improvements were suggested by
336
.An Justin T. Gibbs Aq gibbs@FreeBSD.org .
337
Auto-extend support added by
338
.An Kelly Yancey Aq kbyanc@FreeBSD.org .
340
This manual page was written by
341
.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
added
removed
lib/libvarnish/vsb.3
