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
35 .Nm sbuf_new_for_sysctl ,
55 .Nd safe string formatting
59 .Ft typedef\ int ( sbuf_drain_func ) ( void\ *arg, const\ char\ *data, int\ len ) ;
62 .Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags"
66 .Fn sbuf_clear "struct sbuf *s"
68 .Fn sbuf_setpos "struct sbuf *s" "int pos"
70 .Fn sbuf_bcat "struct sbuf *s" "const void *buf" "size_t len"
72 .Fn sbuf_bcopyin "struct sbuf *s" "const void *uaddr" "size_t len"
74 .Fn sbuf_bcpy "struct sbuf *s" "const void *buf" "size_t len"
76 .Fn sbuf_cat "struct sbuf *s" "const char *str"
78 .Fn sbuf_copyin "struct sbuf *s" "const void *uaddr" "size_t len"
80 .Fn sbuf_cpy "struct sbuf *s" "const char *str"
82 .Fn sbuf_printf "struct sbuf *s" "const char *fmt" "..."
84 .Fn sbuf_vprintf "struct sbuf *s" "const char *fmt" "va_list ap"
86 .Fn sbuf_putc "struct sbuf *s" "int c"
88 .Fn sbuf_set_drain "struct sbuf *s" "sbuf_drain_func *func" "void *arg"
90 .Fn sbuf_trim "struct sbuf *s"
92 .Fn sbuf_error "struct sbuf *s"
94 .Fn sbuf_finish "struct sbuf *s"
96 .Fn sbuf_data "struct sbuf *s"
98 .Fn sbuf_len "struct sbuf *s"
100 .Fn sbuf_done "struct sbuf *s"
102 .Fn sbuf_delete "struct sbuf *s"
105 .Fn sbuf_new_for_sysctl "struct sbuf *s" "char *buf" "int length" "struct sysctl_req *req"
109 family of functions allows one to safely allocate, construct and
110 release bounded NUL-terminated strings in kernel space.
111 Instead of arrays of characters, these functions operate on structures
119 function initializes the
121 pointed to by its first argument.
131 argument is a pointer to a buffer in which to store the actual string;
135 will allocate one using
139 is the initial size of the storage buffer.
142 may be comprised of the following flags:
143 .Bl -tag -width ".Dv SBUF_AUTOEXTEND"
145 The storage buffer is fixed at its initial size.
146 Attempting to extend the sbuf beyond this size results in an overflow condition.
147 .It Dv SBUF_AUTOEXTEND
148 This indicates that the storage buffer may be extended as necessary, so long
149 as resources allow, to hold additional data.
156 it must point to an array of at least
159 The result of accessing that array directly while it is in use by the
164 function is a shortcut for creating a completely dynamic
166 It is the equivalent of calling
173 .Dv SBUF_AUTOEXTEND .
176 .Fn sbuf_new_for_sysctl
177 function will set up an sbuf with a drain function to use
179 when the internal buffer fills.
180 Note that if the various functions which append to an sbuf are used while
181 a non-sleepable lock is held, the user buffer should be wired using
182 .Fn sysctl_wire_old_buffer .
188 and frees any memory allocated for it.
189 There must be a call to
193 Any attempt to access the sbuf after it has been deleted will fail.
197 function invalidates the contents of the
199 and resets its position to zero.
207 which is a value between zero and one less than the size of the
209 This effectively truncates the sbuf at the new position.
213 function appends the first
215 bytes from the buffer
224 bytes from the specified userland address into the
229 function replaces the contents of the
233 bytes from the buffer
238 function appends the NUL-terminated string
242 at the current position.
246 function sets a drain function
250 and records a pointer
252 to be passed to the drain on callback.
253 The drain function cannot be changed while
257 The registered drain function
259 will be called with the argument
265 to a byte string that is the contents of the sbuf, and the length
268 If the drain function exists, it will be called when the sbuf internal
269 buffer is full, or on behalf of
271 The drain function may drain some or all of the data, but must drain
273 The return value from the drain function, if positive, indicates how
274 many bytes were drained.
275 If negative, the return value indicates the negative error code which
276 will be returned from this or a later call to
278 The returned drained length cannot be zero.
279 To do unbuffered draining, initialize the sbuf with a two-byte buffer.
280 The drain will be called for every byte added to the sbuf.
287 functions cannot be used on an sbuf with a drain.
291 function copies a NUL-terminated string from the specified userland
296 argument is non-zero, no more than
298 characters (not counting the terminating NUL) are copied; otherwise
299 the entire string, or as much of it as can fit in the
305 function replaces the contents of the
307 with those of the NUL-terminated string
309 This is equivalent to calling
313 or one which position has been reset to zero with
320 function formats its arguments according to the format string pointed
323 and appends the resulting string to the
325 at the current position.
329 function behaves the same as
331 except that the arguments are obtained from the variable-length argument list
336 function appends the character
340 at the current position.
344 function removes trailing whitespace from the
349 function returns any error value that the
351 may have accumulated, either from the drain function, or ENOMEM if the
354 This function is generally not needed and instead the error code from
356 is the preferred way to discover whether an sbuf had an error.
360 function will call the attached drain function if one exists until all
364 If there is no attached drain,
368 In either case it marks the
370 as finished, which means that it may no longer be modified using
379 is used to reset the sbuf.
383 function returns the actual string;
385 only works on a finished
388 .Fn sbuf_len function returns the length of the string.
391 with an attached drain,
393 returns the length of the un-drained data.
395 returns non-zero if the
399 If an operation caused an
401 to overflow, most subsequent operations on it will fail until the
407 or its position is reset to a value between 0 and one less than the
408 size of its storage buffer using
410 or it is reinitialized to a sufficiently short string using
413 Drains in user-space will not always function as indicated.
414 While the drain function will be called immediately on overflow from
423 currently have no way to determine whether there will be an overflow
424 until after it occurs, and cannot do a partial expansion of the format
426 Thus when using libsbuf the buffer may be extended to allow completion
427 of a single printf call, even though a drain is attached.
433 if it failed to allocate a storage buffer, and a pointer to the new
439 function returns \-1 if
441 was invalid, and zero otherwise.
451 all return \-1 if the buffer overflowed, and zero otherwise.
455 function returns a non-zero value if the buffer has an overflow or
456 drain error, and zero otherwise.
464 and \-1, respectively, if the buffer overflowed.
469 returns \-1 if copying string from userland failed, and number of bytes
473 function returns ENOMEM if the sbuf overflowed before being finished,
474 or returns the error code from the drain if one is attached.
478 will return \-1 and set errno on error instead.
489 family of functions first appeared in
495 family of functions was designed by
496 .An Poul-Henning Kamp Aq phk@FreeBSD.org
498 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
499 Additional improvements were suggested by
500 .An Justin T. Gibbs Aq gibbs@FreeBSD.org .
501 Auto-extend support added by
502 .An Kelly Yancey Aq kbyanc@FreeBSD.org .
503 Drain functionality added by
504 .An Matthew Fleming Aq mdf@FreeBSD.org .
506 This manual page was written by
507 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .