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: head/share/man/man9/sbuf.9 249379 2013-04-11 19:51:53Z trociny $
35 .Nm sbuf_new_for_sysctl ,
55 .Nm sbuf_start_section ,
57 .Nd safe string composition
61 .Ft typedef\ int ( sbuf_drain_func ) ( void\ *arg, const\ char\ *data, int\ len ) ;
64 .Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags"
66 .Fn sbuf_new_auto "void"
68 .Fn sbuf_clear "struct sbuf *s"
70 .Fn sbuf_setpos "struct sbuf *s" "ssize_t pos"
72 .Fn sbuf_bcat "struct sbuf *s" "const void *buf" "size_t len"
74 .Fn sbuf_bcopyin "struct sbuf *s" "const void *uaddr" "size_t len"
76 .Fn sbuf_bcpy "struct sbuf *s" "const void *buf" "size_t len"
78 .Fn sbuf_cat "struct sbuf *s" "const char *str"
80 .Fn sbuf_copyin "struct sbuf *s" "const void *uaddr" "size_t len"
82 .Fn sbuf_cpy "struct sbuf *s" "const char *str"
84 .Fn sbuf_printf "struct sbuf *s" "const char *fmt" "..."
86 .Fn sbuf_vprintf "struct sbuf *s" "const char *fmt" "__va_list ap"
88 .Fn sbuf_putc "struct sbuf *s" "int c"
90 .Fn sbuf_set_drain "struct sbuf *s" "sbuf_drain_func *func" "void *arg"
92 .Fn sbuf_trim "struct sbuf *s"
94 .Fn sbuf_error "const struct sbuf *s"
96 .Fn sbuf_finish "struct sbuf *s"
98 .Fn sbuf_data "struct sbuf *s"
100 .Fn sbuf_len "struct sbuf *s"
102 .Fn sbuf_done "const struct sbuf *s"
104 .Fn sbuf_delete "struct sbuf *s"
106 .Fn sbuf_start_section "struct sbuf *s" "ssize_t *old_lenp"
108 .Fn sbuf_end_section "struct sbuf *s" "ssize_t old_len" "size_t pad" "int c"
111 .Fn sbuf_new_for_sysctl "struct sbuf *s" "char *buf" "int length" "struct sysctl_req *req"
115 family of functions allows one to safely allocate, compose and
116 release strings in kernel or user space.
118 Instead of arrays of characters, these functions operate on structures
124 Any errors encountered during the allocation or composition of the
125 string will be latched in the data structure,
126 making a single error test at the end of the composition
127 sufficient to determine success or failure of the entire process.
131 function initializes the
133 pointed to by its first argument.
143 argument is a pointer to a buffer in which to store the actual string;
147 will allocate one using
151 is the initial size of the storage buffer.
154 may be comprised of the following flags:
155 .Bl -tag -width ".Dv SBUF_AUTOEXTEND"
157 The storage buffer is fixed at its initial size.
158 Attempting to extend the sbuf beyond this size results in an overflow condition.
159 .It Dv SBUF_AUTOEXTEND
160 This indicates that the storage buffer may be extended as necessary, so long
161 as resources allow, to hold additional data.
168 it must point to an array of at least
171 The result of accessing that array directly while it is in use by the
176 function is a shortcut for creating a completely dynamic
178 It is the equivalent of calling
185 .Dv SBUF_AUTOEXTEND .
188 .Fn sbuf_new_for_sysctl
189 function will set up an sbuf with a drain function to use
191 when the internal buffer fills.
192 .\"Note that if the various functions which append to an sbuf are used while
193 .\"a non-sleepable lock is held, the user buffer should be wired using
194 .\".Fn sysctl_wire_old_buffer .
200 and frees any memory allocated for it.
201 There must be a call to
205 Any attempt to access the sbuf after it has been deleted will fail.
209 function invalidates the contents of the
211 and resets its position to zero.
219 which is a value between zero and one less than the size of the
221 This effectively truncates the sbuf at the new position.
225 function appends the first
227 bytes from the buffer
236 bytes from the specified userland address into the
241 function replaces the contents of the
245 bytes from the buffer
250 function appends the NUL-terminated string
254 at the current position.
258 function sets a drain function
262 and records a pointer
264 to be passed to the drain on callback.
265 The drain function cannot be changed while
269 The registered drain function
271 will be called with the argument
277 to a byte string that is the contents of the sbuf, and the length
280 If the drain function exists, it will be called when the sbuf internal
281 buffer is full, or on behalf of
283 The drain function may drain some or all of the data, but must drain
285 The return value from the drain function, if positive, indicates how
286 many bytes were drained.
287 If negative, the return value indicates the negative error code which
288 will be returned from this or a later call to
290 The returned drained length cannot be zero.
291 To do unbuffered draining, initialize the sbuf with a two-byte buffer.
292 The drain will be called for every byte added to the sbuf.
299 functions cannot be used on an sbuf with a drain.
303 function copies a NUL-terminated string from the specified userland
308 argument is non-zero, no more than
310 characters (not counting the terminating NUL) are copied; otherwise
311 the entire string, or as much of it as can fit in the
317 function replaces the contents of the
319 with those of the NUL-terminated string
321 This is equivalent to calling
325 or one which position has been reset to zero with
332 function formats its arguments according to the format string pointed
335 and appends the resulting string to the
337 at the current position.
341 function behaves the same as
343 except that the arguments are obtained from the variable-length argument list
348 function appends the character
352 at the current position.
356 function removes trailing whitespace from the
361 function returns any error value that the
363 may have accumulated, either from the drain function, or
368 This function is generally not needed and instead the error code from
370 is the preferred way to discover whether an sbuf had an error.
374 function will call the attached drain function if one exists until all
378 If there is no attached drain,
382 In either case it marks the
384 as finished, which means that it may no longer be modified using
393 is used to reset the sbuf.
397 function returns the actual string;
399 only works on a finished
403 function returns the length of the string.
406 with an attached drain,
408 returns the length of the un-drained data.
410 returns non-zero if the
415 .Fn sbuf_start_section
418 functions may be used for automatic section alignment.
423 specify the padding size and a character used for padding.
428 are to save and restore the current section length when nested sections
430 For the top level section
432 and \-1 can be specified for
438 If an operation caused an
440 to overflow, most subsequent operations on it will fail until the
446 or its position is reset to a value between 0 and one less than the
447 size of its storage buffer using
449 or it is reinitialized to a sufficiently short string using
452 Drains in user-space will not always function as indicated.
453 While the drain function will be called immediately on overflow from
462 currently have no way to determine whether there will be an overflow
463 until after it occurs, and cannot do a partial expansion of the format
465 Thus when using libsbuf the buffer may be extended to allow completion
466 of a single printf call, even though a drain is attached.
472 if it failed to allocate a storage buffer, and a pointer to the new
478 function returns \-1 if
480 was invalid, and zero otherwise.
490 all return \-1 if the buffer overflowed, and zero otherwise.
494 function returns a non-zero value if the buffer has an overflow or
495 drain error, and zero otherwise.
499 function returns \-1 if the buffer overflowed.
504 returns \-1 if copying string from userland failed, and number of bytes
509 function returns the section length or \-1 if the buffer has an error.
513 function (the kernel version) returns
515 if the sbuf overflowed before being finished,
516 or returns the error code from the drain if one is attached.
520 function (the userland version)
521 will return zero for success and \-1 and set errno on error.
523 .Bd -literal -compact
524 #include <sys/sbuf.h>
528 sb = sbuf_new_auto();
529 sbuf_cat(sb, "Customers found:\en");
530 TAILQ_FOREACH(foo, &foolist, list) {
531 sbuf_printf(sb, " %4d %s\en", foo->index, foo->name);
532 sbuf_printf(sb, " Address: %s\en", foo->address);
533 sbuf_printf(sb, " Zip: %s\en", foo->zipcode);
535 if (sbuf_finish(sb) != 0) /* Check for any and all errors */
536 err(1, "Could not generate message");
537 transmit_msg(sbuf_data(sb), sbuf_len(sb));
550 family of functions first appeared in
556 family of functions was designed by
557 .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org
559 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org .
560 Additional improvements were suggested by
561 .An Justin T. Gibbs Aq Mt gibbs@FreeBSD.org .
562 Auto-extend support added by
563 .An Kelly Yancey Aq Mt kbyanc@FreeBSD.org .
564 Drain functionality added by
565 .An Matthew Fleming Aq Mt mdf@FreeBSD.org .
567 This manual page was written by
568 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org .