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
54 .Nd safe string formatting
58 .Ft typedef\ int ( sbuf_drain_func ) ( void\ *arg, const\ char\ *data, int\ len ) ;
61 .Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags"
65 .Fn sbuf_clear "struct sbuf *s"
67 .Fn sbuf_setpos "struct sbuf *s" "int pos"
69 .Fn sbuf_bcat "struct sbuf *s" "const void *buf" "size_t len"
71 .Fn sbuf_bcopyin "struct sbuf *s" "const void *uaddr" "size_t len"
73 .Fn sbuf_bcpy "struct sbuf *s" "const void *buf" "size_t len"
75 .Fn sbuf_cat "struct sbuf *s" "const char *str"
77 .Fn sbuf_copyin "struct sbuf *s" "const void *uaddr" "size_t len"
79 .Fn sbuf_cpy "struct sbuf *s" "const char *str"
81 .Fn sbuf_printf "struct sbuf *s" "const char *fmt" "..."
83 .Fn sbuf_vprintf "struct sbuf *s" "const char *fmt" "va_list ap"
85 .Fn sbuf_putc "struct sbuf *s" "int c"
87 .Fn sbuf_set_drain "struct sbuf *s" "sbuf_drain_func *func" "void *arg"
89 .Fn sbuf_trim "struct sbuf *s"
91 .Fn sbuf_error "struct sbuf *s"
93 .Fn sbuf_finish "struct sbuf *s"
95 .Fn sbuf_data "struct sbuf *s"
97 .Fn sbuf_len "struct sbuf *s"
99 .Fn sbuf_done "struct sbuf *s"
101 .Fn sbuf_delete "struct sbuf *s"
105 family of functions allows one to safely allocate, construct and
106 release bounded NUL-terminated strings in kernel space.
107 Instead of arrays of characters, these functions operate on structures
115 function initializes the
117 pointed to by its first argument.
127 argument is a pointer to a buffer in which to store the actual string;
131 will allocate one using
135 is the initial size of the storage buffer.
138 may be comprised of the following flags:
139 .Bl -tag -width ".Dv SBUF_AUTOEXTEND"
141 The storage buffer is fixed at its initial size.
142 Attempting to extend the sbuf beyond this size results in an overflow condition.
143 .It Dv SBUF_AUTOEXTEND
144 This indicates that the storage buffer may be extended as necessary, so long
145 as resources allow, to hold additional data.
152 it must point to an array of at least
155 The result of accessing that array directly while it is in use by the
160 function is a shortcut for creating a completely dynamic
162 It is the equivalent of calling
169 .Dv SBUF_AUTOEXTEND .
175 and frees any memory allocated for it.
176 There must be a call to
180 Any attempt to access the sbuf after it has been deleted will fail.
184 function invalidates the contents of the
186 and resets its position to zero.
194 which is a value between zero and one less than the size of the
196 This effectively truncates the sbuf at the new position.
200 function appends the first
202 bytes from the buffer
211 bytes from the specified userland address into the
216 function replaces the contents of the
220 bytes from the buffer
225 function appends the NUL-terminated string
229 at the current position.
233 function sets a drain function
237 and records a pointer
239 to be passed to the drain on callback.
240 The drain function cannot be changed while
244 The registered drain function
246 will be called with the argument
252 to a byte string that is the contents of the sbuf, and the length
255 If the drain function exists, it will be called when the sbuf internal
256 buffer is full, or on behalf of
258 The drain function may drain some or all of the data, but must drain
260 The return value from the drain function, if positive, indicates how
261 many bytes were drained.
262 If negative, the return value indicates the negative error code which
263 will be returned from this or a later call to
265 The returned drained length cannot be zero.
266 To do unbuffered draining, initialize the sbuf with a two-byte buffer.
267 The drain will be called for every byte added to the sbuf.
274 functions cannot be used on an sbuf with a drain.
278 function copies a NUL-terminated string from the specified userland
283 argument is non-zero, no more than
285 characters (not counting the terminating NUL) are copied; otherwise
286 the entire string, or as much of it as can fit in the
292 function replaces the contents of the
294 with those of the NUL-terminated string
296 This is equivalent to calling
300 or one which position has been reset to zero with
307 function formats its arguments according to the format string pointed
310 and appends the resulting string to the
312 at the current position.
316 function behaves the same as
318 except that the arguments are obtained from the variable-length argument list
323 function appends the character
327 at the current position.
331 function removes trailing whitespace from the
336 function returns any error value that the
338 may have accumulated, either from the drain function, or ENOMEM if the
341 This function is generally not needed and instead the error code from
343 is the preferred way to discover whether an sbuf had an error.
347 function will call the attached drain function if one exists until all
351 If there is no attached drain,
355 In either case it marks the
357 as finished, which means that it may no longer be modified using
366 is used to reset the sbuf.
370 function returns the actual string;
372 only works on a finished
375 .Fn sbuf_len function returns the length of the string.
378 with an attached drain,
380 returns the length of the un-drained data.
382 returns non-zero if the
386 returns non-zero if the
390 If an operation caused an
392 to overflow, most subsequent operations on it will fail until the
398 or its position is reset to a value between 0 and one less than the
399 size of its storage buffer using
401 or it is reinitialized to a sufficiently short string using
404 Drains in user-space will not always function as indicated.
405 While the drain function will be called immediately on overflow from
414 currently have no way to determine whether there will be an overflow
415 until after it occurs, and cannot do a partial expansion of the format
417 Thus when using libsbuf the buffer may be extended to allow completion
418 of a single printf call, even though a drain is attached.
424 if it failed to allocate a storage buffer, and a pointer to the new
430 function returns \-1 if
432 was invalid, and zero otherwise.
442 all return \-1 if the buffer overflowed, and zero otherwise.
446 function returns a non-zero value if the buffer has an overflow or
447 drain error, and zero otherwise.
455 and \-1, respectively, if the buffer overflowed.
460 returns \-1 if copying string from userland failed, and number of bytes
464 function returns ENOMEM if the sbuf overflowed before being finished,
465 or returns the error code from the drain if one is attached.
469 will return \-1 and set errno on error instead.
480 family of functions first appeared in
486 family of functions was designed by
487 .An Poul-Henning Kamp Aq phk@FreeBSD.org
489 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
490 Additional improvements were suggested by
491 .An Justin T. Gibbs Aq gibbs@FreeBSD.org .
492 Auto-extend support added by
493 .An Kelly Yancey Aq kbyanc@FreeBSD.org .
494 Drain functionality added by
495 .An Matthew Fleming Aq mdf@FreeBSD.org .
497 This manual page was written by
498 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .