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
26 .\" $FreeBSD: src/share/man/man9/sbuf.9,v 1.12.2.4 2002/09/23 04:51:53 kbyanc Exp $
27 .\" $DragonFly: src/share/man/man9/sbuf.9,v 1.5 2007/01/02 00:25:43 swildner Exp $
51 .Nd safe string formatting
56 .Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags"
58 .Fn sbuf_clear "struct sbuf *s"
60 .Fn sbuf_setpos "struct sbuf *s" "int pos"
62 .Fn sbuf_bcat "struct sbuf *s" "const char *str" "size_t len"
64 .Fn sbuf_bcopyin "struct sbuf *s" "const void *uaddr" "size_t len"
66 .Fn sbuf_bcpy "struct sbuf *s" "const char *str" "size_t len"
68 .Fn sbuf_cat "struct sbuf *s" "const char *str"
70 .Fn sbuf_copyin "struct sbuf *s" "const void *uaddr" "size_t len"
72 .Fn sbuf_cpy "struct sbuf *s" "const char *str"
74 .Fn sbuf_printf "struct sbuf *s" "const char *fmt" "..."
76 .Fn sbuf_vprintf "struct sbuf *s" "const char *fmt" "va_list ap"
78 .Fn sbuf_putc "struct sbuf *s" "int c"
80 .Fn sbuf_trim "struct sbuf *s"
82 .Fn sbuf_overflowed "struct sbuf *s"
84 .Fn sbuf_finish "struct sbuf *s"
86 .Fn sbuf_data "struct sbuf *s"
88 .Fn sbuf_len "struct sbuf *s"
90 .Fn sbuf_delete "struct sbuf *s"
94 family of functions allows one to safely allocate, construct and
95 release bounded null-terminated strings in kernel space.
96 Instead of arrays of characters, these functions operate on structures
104 function initializes the
106 pointed to by its first argument.
116 argument is a pointer to a buffer in which to store the actual string;
120 will allocate one using
124 is the initial size of the storage buffer.
127 may be comprised of the following flags:
128 .Bl -tag -width ".Dv SBUF_AUTOEXTEND"
130 The storage buffer is fixed at its initial size.
131 Attempting to extend the sbuf beyond this size results in an overflow condition.
132 .It Dv SBUF_AUTOEXTEND
133 This indicates that the storage buffer may be extended as necessary, so long
134 as resources allow, to hold additional data.
141 it must point to an array of at least
144 The contents of the provided buffer are undefined; to retrieve the sbuf data
146 must be called on the finished
151 function invalidates the contents of the
153 and resets its position to zero.
161 which is a value between zero and one less than the size of the
163 This effectively truncates the sbuf at the new position.
167 function appends the first
169 bytes from the byte string
178 bytes from the specified userland address into the
183 function replaces the contents of the
187 bytes from the byte string
192 function appends the NUL-terminated string
196 at the current position.
200 function copies a NUL-terminated string from the specified userland
205 argument is non-zero, no more than
207 characters (not counting the terminating NUL) are copied; otherwise
208 the entire string, or as much of it as can fit in the
214 function replaces the contents of the
216 with those of the NUL-terminated string
218 This is equivalent to calling
222 or one which position has been reset to zero with
229 function formats its arguments according to the format string pointed
232 and appends the resulting string to the
234 at the current position.
238 function behaves the same as
240 except that the arguments are obtained from the variable-length argument list
245 function appends the character
249 at the current position.
253 function removes trailing whitespace from the
258 function returns a non-zero value if the
264 function null-terminates the
266 and marks it as finished, which means that it may no longer be
279 functions return the actual string and its length, respectively;
281 only works on a finished
288 and frees its storage buffer if it was allocated by
291 If an operation caused an
293 to overflow, most subsequent operations on it will fail until the
299 or its position is reset to a value between 0 and one less than the
300 size of its storage buffer using
302 or it is reinitialized to a sufficiently short string using
308 if it failed to allocate a storage buffer, and a pointer to the new
315 was invalid, and zero otherwise.
323 all return \-1 if the buffer overflowed, and zero otherwise.
326 returns a non-zero value if the buffer overflowed, and zero otherwise.
333 and \-1, respectively, if the buffer overflowed.
344 family of functions first appeared in
350 family of functions was designed by
351 .An Poul-Henning Kamp Aq phk@FreeBSD.org
353 .An Dag-Erling Co\(:idan Sm\(/orgrav Aq des@FreeBSD.org .
354 Additional improvements were suggested by
355 .An Justin T. Gibbs Aq gibbs@FreeBSD.org .
356 Auto-extend support added by
357 .An Kelly Yancey Aq kbyanc@FreeBSD.org .
359 This manual page was written by
360 .An Dag-Erling Co\(:idan Sm\(/orgrav .