2 .\" Copyright (c) 2000 Poul-Henning Kamp and Dag-Erling Coïdan 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
53 .Nd safe string formatting
58 .Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags"
62 .Fn sbuf_clear "struct sbuf *s"
64 .Fn sbuf_setpos "struct sbuf *s" "int pos"
66 .Fn sbuf_bcat "struct sbuf *s" "const void *buf" "size_t len"
68 .Fn sbuf_bcopyin "struct sbuf *s" "const void *uaddr" "size_t len"
70 .Fn sbuf_bcpy "struct sbuf *s" "const void *buf" "size_t len"
72 .Fn sbuf_cat "struct sbuf *s" "const char *str"
74 .Fn sbuf_copyin "struct sbuf *s" "const void *uaddr" "size_t len"
76 .Fn sbuf_cpy "struct sbuf *s" "const char *str"
78 .Fn sbuf_printf "struct sbuf *s" "const char *fmt" "..."
80 .Fn sbuf_vprintf "struct sbuf *s" "const char *fmt" "va_list ap"
82 .Fn sbuf_putc "struct sbuf *s" "int c"
84 .Fn sbuf_trim "struct sbuf *s"
86 .Fn sbuf_overflowed "struct sbuf *s"
88 .Fn sbuf_finish "struct sbuf *s"
90 .Fn sbuf_data "struct sbuf *s"
92 .Fn sbuf_len "struct sbuf *s"
94 .Fn sbuf_done "struct sbuf *s"
96 .Fn sbuf_delete "struct sbuf *s"
100 family of functions allows one to safely allocate, construct and
101 release bounded null-terminated strings in kernel space.
102 Instead of arrays of characters, these functions operate on structures
110 function initializes the
112 pointed to by its first argument.
122 argument is a pointer to a buffer in which to store the actual string;
126 will allocate one using
130 is the initial size of the storage buffer.
133 may be comprised of the following flags:
134 .Bl -tag -width ".Dv SBUF_AUTOEXTEND"
136 The storage buffer is fixed at its initial size.
137 Attempting to extend the sbuf beyond this size results in an overflow condition.
138 .It Dv SBUF_AUTOEXTEND
139 This indicates that the storage buffer may be extended as necessary, so long
140 as resources allow, to hold additional data.
147 it must point to an array of at least
150 The result of accessing that array directly while it is in use by the
155 function is a shortcut for creating a completely dynamic
157 It is the equivalent of calling
164 .Dv SBUF_AUTOEXTEND .
170 and frees any memory allocated for it.
171 There must be a call to
175 Any attempt to access the sbuf after it has been deleted will fail.
179 function invalidates the contents of the
181 and resets its position to zero.
189 which is a value between zero and one less than the size of the
191 This effectively truncates the sbuf at the new position.
195 function appends the first
197 bytes from the buffer
206 bytes from the specified userland address into the
211 function replaces the contents of the
215 bytes from the buffer
220 function appends the NUL-terminated string
224 at the current position.
228 function copies a NUL-terminated string from the specified userland
233 argument is non-zero, no more than
235 characters (not counting the terminating NUL) are copied; otherwise
236 the entire string, or as much of it as can fit in the
242 function replaces the contents of the
244 with those of the NUL-terminated string
246 This is equivalent to calling
250 or one which position has been reset to zero with
257 function formats its arguments according to the format string pointed
260 and appends the resulting string to the
262 at the current position.
266 function behaves the same as
268 except that the arguments are obtained from the variable-length argument list
273 function appends the character
277 at the current position.
281 function removes trailing whitespace from the
286 function returns a non-zero value if the
292 function null-terminates the
294 and marks it as finished, which means that it may no longer be
307 functions return the actual string and its length, respectively;
309 only works on a finished
312 returns non-zero if the sbuf is finished.
314 If an operation caused an
316 to overflow, most subsequent operations on it will fail until the
322 or its position is reset to a value between 0 and one less than the
323 size of its storage buffer using
325 or it is reinitialized to a sufficiently short string using
332 if it failed to allocate a storage buffer, and a pointer to the new
338 function returns \-1 if
340 was invalid, and zero otherwise.
350 all return \-1 if the buffer overflowed, and zero otherwise.
355 returns a non-zero value if the buffer overflowed, and zero otherwise.
363 and \-1, respectively, if the buffer overflowed.
368 returns \-1 if copying string from userland failed, and number of bytes
380 family of functions first appeared in
386 family of functions was designed by
387 .An Poul-Henning Kamp Aq phk@FreeBSD.org
389 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
390 Additional improvements were suggested by
391 .An Justin T. Gibbs Aq gibbs@FreeBSD.org .
392 Auto-extend support added by
393 .An Kelly Yancey Aq kbyanc@FreeBSD.org .
395 This manual page was written by
396 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .