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 ,
39 .Nm sbuf_clear_flags ,
58 .Nm sbuf_start_section ,
60 .Nd safe string composition
64 .Ft typedef\ int ( sbuf_drain_func ) ( void\ *arg, const\ char\ *data, int\ len ) ;
67 .Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags"
71 .Fn sbuf_clear "struct sbuf *s"
73 .Fn sbuf_get_flags "struct sbuf *s"
75 .Fn sbuf_set_flags "struct sbuf *s" "int flags"
77 .Fn sbuf_clear_flags "struct sbuf *s" "int flags"
79 .Fn sbuf_setpos "struct sbuf *s" "int pos"
81 .Fn sbuf_bcat "struct sbuf *s" "const void *buf" "size_t len"
83 .Fn sbuf_bcopyin "struct sbuf *s" "const void *uaddr" "size_t len"
85 .Fn sbuf_bcpy "struct sbuf *s" "const void *buf" "size_t len"
87 .Fn sbuf_cat "struct sbuf *s" "const char *str"
89 .Fn sbuf_copyin "struct sbuf *s" "const void *uaddr" "size_t len"
91 .Fn sbuf_cpy "struct sbuf *s" "const char *str"
93 .Fn sbuf_printf "struct sbuf *s" "const char *fmt" "..."
95 .Fn sbuf_vprintf "struct sbuf *s" "const char *fmt" "va_list ap"
97 .Fn sbuf_putc "struct sbuf *s" "int c"
99 .Fn sbuf_set_drain "struct sbuf *s" "sbuf_drain_func *func" "void *arg"
101 .Fn sbuf_trim "struct sbuf *s"
103 .Fn sbuf_error "struct sbuf *s"
105 .Fn sbuf_finish "struct sbuf *s"
107 .Fn sbuf_data "struct sbuf *s"
109 .Fn sbuf_len "struct sbuf *s"
111 .Fn sbuf_done "struct sbuf *s"
113 .Fn sbuf_delete "struct sbuf *s"
115 .Fn sbuf_start_section "struct sbuf *s" "ssize_t *old_lenp"
117 .Fn sbuf_end_section "struct sbuf *s" "ssize_t old_len" "size_t pad" "int c"
120 .Fn sbuf_new_for_sysctl "struct sbuf *s" "char *buf" "int length" "struct sysctl_req *req"
124 family of functions allows one to safely allocate, compose and
125 release strings in kernel or user space.
127 Instead of arrays of characters, these functions operate on structures
133 Any errors encountered during the allocation or composition of the
134 string will be latched in the data structure,
135 making a single error test at the end of the composition
136 sufficient to determine success or failure of the entire process.
140 function initializes the
142 pointed to by its first argument.
152 argument is a pointer to a buffer in which to store the actual string;
156 will allocate one using
160 is the initial size of the storage buffer.
163 may be comprised of the following flags:
164 .Bl -tag -width ".Dv SBUF_AUTOEXTEND"
166 The storage buffer is fixed at its initial size.
167 Attempting to extend the sbuf beyond this size results in an overflow condition.
168 .It Dv SBUF_AUTOEXTEND
169 This indicates that the storage buffer may be extended as necessary, so long
170 as resources allow, to hold additional data.
171 .It Dv SBUF_INCLUDENUL
172 This causes the final nulterm byte to be counted in the length of the data.
179 it must point to an array of at least
182 The result of accessing that array directly while it is in use by the
187 function is a shortcut for creating a completely dynamic
189 It is the equivalent of calling
196 .Dv SBUF_AUTOEXTEND .
199 .Fn sbuf_new_for_sysctl
200 function will set up an sbuf with a drain function to use
202 when the internal buffer fills.
203 Note that if the various functions which append to an sbuf are used while
204 a non-sleepable lock is held, the user buffer should be wired using
205 .Fn sysctl_wire_old_buffer .
211 and frees any memory allocated for it.
212 There must be a call to
216 Any attempt to access the sbuf after it has been deleted will fail.
220 function invalidates the contents of the
222 and resets its position to zero.
226 function returns the current user flags.
231 functions set or clear one or more user flags, respectively.
232 The user flags are described under the
242 which is a value between zero and one less than the size of the
244 This effectively truncates the sbuf at the new position.
248 function appends the first
250 bytes from the buffer
259 bytes from the specified userland address into the
264 function replaces the contents of the
268 bytes from the buffer
273 function appends the NUL-terminated string
277 at the current position.
281 function sets a drain function
285 and records a pointer
287 to be passed to the drain on callback.
288 The drain function cannot be changed while
292 The registered drain function
294 will be called with the argument
300 to a byte string that is the contents of the sbuf, and the length
303 If the drain function exists, it will be called when the sbuf internal
304 buffer is full, or on behalf of
306 The drain function may drain some or all of the data, but must drain
308 The return value from the drain function, if positive, indicates how
309 many bytes were drained.
310 If negative, the return value indicates the negative error code which
311 will be returned from this or a later call to
313 The returned drained length cannot be zero.
314 To do unbuffered draining, initialize the sbuf with a two-byte buffer.
315 The drain will be called for every byte added to the sbuf.
322 functions cannot be used on an sbuf with a drain.
326 function copies a NUL-terminated string from the specified userland
331 argument is non-zero, no more than
333 characters (not counting the terminating NUL) are copied; otherwise
334 the entire string, or as much of it as can fit in the
340 function replaces the contents of the
342 with those of the NUL-terminated string
344 This is equivalent to calling
348 or one which position has been reset to zero with
355 function formats its arguments according to the format string pointed
358 and appends the resulting string to the
360 at the current position.
364 function behaves the same as
366 except that the arguments are obtained from the variable-length argument list
371 function appends the character
375 at the current position.
379 function removes trailing whitespace from the
384 function returns any error value that the
386 may have accumulated, either from the drain function, or ENOMEM if the
389 This function is generally not needed and instead the error code from
391 is the preferred way to discover whether an sbuf had an error.
395 function will call the attached drain function if one exists until all
399 If there is no attached drain,
403 In either case it marks the
405 as finished, which means that it may no longer be modified using
414 is used to reset the sbuf.
418 function returns the actual string;
420 only works on a finished
424 function returns the length of the string.
427 with an attached drain,
429 returns the length of the un-drained data.
431 returns non-zero if the
436 .Fn sbuf_start_section
439 functions may be used for automatic section alignment.
444 specify the padding size and a character used for padding.
449 are to save and restore the current section length when nested sections
451 For the top level section
453 and \-1 can be specified for
459 If an operation caused an
461 to overflow, most subsequent operations on it will fail until the
467 or its position is reset to a value between 0 and one less than the
468 size of its storage buffer using
470 or it is reinitialized to a sufficiently short string using
473 Drains in user-space will not always function as indicated.
474 While the drain function will be called immediately on overflow from
483 currently have no way to determine whether there will be an overflow
484 until after it occurs, and cannot do a partial expansion of the format
486 Thus when using libsbuf the buffer may be extended to allow completion
487 of a single printf call, even though a drain is attached.
493 if it failed to allocate a storage buffer, and a pointer to the new
499 function returns \-1 if
501 was invalid, and zero otherwise.
511 all return \-1 if the buffer overflowed, and zero otherwise.
515 function returns a non-zero value if the buffer has an overflow or
516 drain error, and zero otherwise.
520 function returns \-1 if the buffer overflowed.
525 returns \-1 if copying string from userland failed, and number of bytes
530 function returns the section length or \-1 if the buffer has an error.
534 function (the kernel version) returns ENOMEM if the sbuf overflowed before
536 or returns the error code from the drain if one is attached.
540 function (the userland version)
541 will return zero for success and \-1 and set errno on error.
543 .Bd -literal -compact
544 #include <sys/sbuf.h>
548 sb = sbuf_new_auto();
549 sbuf_cat(sb, "Customers found:\en");
550 TAILQ_FOREACH(foo, &foolist, list) {
551 sbuf_printf(sb, " %4d %s\en", foo->index, foo->name);
552 sbuf_printf(sb, " Address: %s\en", foo->address);
553 sbuf_printf(sb, " Zip: %s\en", foo->zipcode);
555 if (sbuf_finish(sb) != 0) /* Check for any and all errors */
556 err(1, "Could not generate message");
557 transmit_msg(sbuf_data(sb), sbuf_len(sb));
570 family of functions first appeared in
576 family of functions was designed by
577 .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org
579 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org .
580 Additional improvements were suggested by
581 .An Justin T. Gibbs Aq Mt gibbs@FreeBSD.org .
582 Auto-extend support added by
583 .An Kelly Yancey Aq Mt kbyanc@FreeBSD.org .
584 Drain functionality added by
585 .An Matthew Fleming Aq Mt mdf@FreeBSD.org .
587 This manual page was written by
588 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org .