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 ,
47 .Nm sbuf_nl_terminate ,
59 .Nm sbuf_start_section ,
60 .Nm sbuf_end_section ,
62 .Nm sbuf_printf_drain ,
64 .Nd safe string composition
71 .Fa "const char *data"
112 .Fa "const void *buf"
118 .Fa "const void *buf"
124 .Fa "const char *str"
129 .Fa "const char *str"
132 .Fn sbuf_nl_terminate "struct sbuf *"
136 .Fa "const char *fmt" "..."
141 .Fa "const char *fmt"
152 .Fa "sbuf_drain_func *func"
184 .Fo sbuf_start_section
186 .Fa "ssize_t *old_lenp"
191 .Fa "ssize_t old_len"
197 .Fa "struct sbuf *sb"
200 .Fa "const char *hdr"
204 .Fo sbuf_printf_drain
206 .Fa "const char *data"
219 .Fa "const void *uaddr"
225 .Fa "const void *uaddr"
230 .Fo sbuf_new_for_sysctl
234 .Fa "struct sysctl_req *req"
236 .Fd #endif /* _KERNEL */
240 family of functions allows one to safely allocate, compose and
241 release strings in kernel or user space.
243 Instead of arrays of characters, these functions operate on structures
249 Any errors encountered during the allocation or composition of the
250 string will be latched in the data structure,
251 making a single error test at the end of the composition
252 sufficient to determine success or failure of the entire process.
256 function initializes the
258 pointed to by its first argument.
268 argument is a pointer to a buffer in which to store the actual string;
272 will allocate one using
276 is the initial size of the storage buffer.
279 may be comprised of the following flags:
280 .Bl -tag -width ".Dv SBUF_AUTOEXTEND"
282 The storage buffer is fixed at its initial size.
283 Attempting to extend the sbuf beyond this size results in an overflow condition.
284 .It Dv SBUF_AUTOEXTEND
285 This indicates that the storage buffer may be extended as necessary, so long
286 as resources allow, to hold additional data.
287 .It Dv SBUF_INCLUDENUL
288 This causes the final nulterm byte to be counted in the length of the data.
289 .It Dv SBUF_DRAINTOEOR
290 Treat top-level sections started with
291 .Fn sbuf_start_section
292 as a record boundary marker that will be used during drain operations to avoid
294 If a record grows sufficiently large such that it fills the
296 and therefore cannot be drained without being split, an error of
300 Indicates that attempts to extend the storage buffer should fail in low memory
310 it must point to an array of at least
313 The result of accessing that array directly while it is in use by the
318 function is a shortcut for creating a completely dynamic
320 It is the equivalent of calling
327 .Dv SBUF_AUTOEXTEND .
330 .Fn sbuf_new_for_sysctl
331 function will set up an sbuf with a drain function to use
333 when the internal buffer fills.
334 Note that if the various functions which append to an sbuf are used while
335 a non-sleepable lock is held, the user buffer should be wired using
336 .Fn sysctl_wire_old_buffer .
342 and frees any memory allocated for it.
343 There must be a call to
347 Any attempt to access the sbuf after it has been deleted will fail.
351 function invalidates the contents of the
353 and resets its position to zero.
357 function returns the current user flags.
362 functions set or clear one or more user flags, respectively.
363 The user flags are described under the
373 which is a value between zero and the current position in the buffer.
374 It can only truncate the sbuf to the new position.
378 function appends the first
380 bytes from the buffer
389 bytes from the specified userland address into the
394 function replaces the contents of the
398 bytes from the buffer
403 function appends the NUL-terminated string
407 at the current position.
411 function sets a drain function
415 and records a pointer
417 to be passed to the drain on callback.
418 The drain function cannot be changed while
422 The registered drain function
424 will be called with the argument
430 to a byte string that is the contents of the sbuf, and the length
433 If the drain function exists, it will be called when the sbuf internal
434 buffer is full, or on behalf of
436 The drain function may drain some or all of the data, but must drain
438 The return value from the drain function, if positive, indicates how
439 many bytes were drained.
440 If negative, the return value indicates the negative error code which
441 will be returned from this or a later call to
443 If the returned drained length is 0, an error of
446 To do unbuffered draining, initialize the sbuf with a two-byte buffer.
447 The drain will be called for every byte added to the sbuf.
458 functions cannot be used on an sbuf with a drain.
462 function copies a NUL-terminated string from the specified userland
467 argument is non-zero, no more than
469 characters (not counting the terminating NUL) are copied; otherwise
470 the entire string, or as much of it as can fit in the
476 function replaces the contents of the
478 with those of the NUL-terminated string
480 This is equivalent to calling
484 or one which position has been reset to zero with
490 .Fn sbuf_nl_terminate
491 function appends a trailing newline character, if the current line is non-empty
492 and not already terminated by a newline character.
496 function formats its arguments according to the format string pointed
499 and appends the resulting string to the
501 at the current position.
505 function behaves the same as
507 except that the arguments are obtained from the variable-length argument list
512 function appends the character
516 at the current position.
520 function removes trailing whitespace from the
525 function returns any error value that the
527 may have accumulated, either from the drain function, or
532 This function is generally not needed and instead the error code from
534 is the preferred way to discover whether an sbuf had an error.
538 function will call the attached drain function if one exists until all
542 If there is no attached drain,
546 In either case it marks the
548 as finished, which means that it may no longer be modified using
557 is used to reset the sbuf.
561 function returns the actual string;
563 only works on a finished
567 function returns the length of the string.
570 with an attached drain,
572 returns the length of the un-drained data.
574 returns non-zero if the
579 .Fn sbuf_start_section
582 functions may be used for automatic section alignment.
587 specify the padding size and a character used for padding.
592 are to save and restore the current section length when nested sections
594 For the top level section
596 and \-1 can be specified for
604 function prints an array of bytes to the supplied sbuf, along with an ASCII
605 representation of the bytes if possible.
608 man page for more details on the interface.
611 .Fn sbuf_printf_drain
612 function is a drain function that will call printf, or log to the console.
617 or a valid pointer to a
623 the total bytes drained will be added to the value pointed to by
628 function printfs the sbuf to stdout if in userland, and to the console
629 and log if in the kernel.
632 must be finished before calling
634 It does not drain the buffer or update any pointers.
636 If an operation caused an
638 to overflow, most subsequent operations on it will fail until the
644 or its position is reset to a value between 0 and one less than the
645 size of its storage buffer using
647 or it is reinitialized to a sufficiently short string using
650 Drains in user-space will not always function as indicated.
651 While the drain function will be called immediately on overflow from
660 currently have no way to determine whether there will be an overflow
661 until after it occurs, and cannot do a partial expansion of the format
663 Thus when using libsbuf the buffer may be extended to allow completion
664 of a single printf call, even though a drain is attached.
670 if it failed to allocate a storage buffer, and a pointer to the new
676 function returns \-1 if
678 was invalid, and zero otherwise.
689 all return \-1 if the buffer overflowed, and zero otherwise.
693 function returns a non-zero value if the buffer has an overflow or
694 drain error, and zero otherwise.
698 function returns \-1 if the buffer overflowed.
703 returns \-1 if copying string from userland failed, and number of bytes
708 function returns the section length or \-1 if the buffer has an error.
712 function (the kernel version) returns
714 if the sbuf overflowed before being finished,
715 or returns the error code from the drain if one is attached.
719 function (the userland version)
720 will return zero for success and \-1 and set errno on error.
722 .Bd -literal -compact
723 #include <sys/types.h>
724 #include <sys/sbuf.h>
728 sb = sbuf_new_auto();
729 sbuf_cat(sb, "Customers found:\en");
730 TAILQ_FOREACH(foo, &foolist, list) {
731 sbuf_printf(sb, " %4d %s\en", foo->index, foo->name);
732 sbuf_printf(sb, " Address: %s\en", foo->address);
733 sbuf_printf(sb, " Zip: %s\en", foo->zipcode);
735 if (sbuf_finish(sb) != 0) /* Check for any and all errors */
736 err(1, "Could not generate message");
737 transmit_msg(sbuf_data(sb), sbuf_len(sb));
751 family of functions first appeared in
757 family of functions was designed by
758 .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org
760 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org .
761 Additional improvements were suggested by
762 .An Justin T. Gibbs Aq Mt gibbs@FreeBSD.org .
763 Auto-extend support added by
764 .An Kelly Yancey Aq Mt kbyanc@FreeBSD.org .
765 Drain functionality added by
766 .An Matthew Fleming Aq Mt mdf@FreeBSD.org .
768 This manual page was written by
769 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org .