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
68 .Ft typedef\ int ( sbuf_drain_func ) ( void\ *arg, const\ char\ *data, int\ len ) ;
107 .Fa "const void *buf"
113 .Fa "const void *buf"
119 .Fa "const char *str"
124 .Fa "const char *str"
127 .Fn sbuf_nl_terminate "struct sbuf *"
131 .Fa "const char *fmt" "..."
136 .Fa "const char *fmt"
147 .Fa "sbuf_drain_func *func"
179 .Fo sbuf_start_section
181 .Fa "ssize_t *old_lenp"
186 .Fa "ssize_t old_len"
192 .Fa "struct sbuf *sb"
195 .Fa "const char *hdr"
199 .Fo sbuf_printf_drain
201 .Fa "const char *data"
214 .Fa "const void *uaddr"
220 .Fa "const void *uaddr"
225 .Fo sbuf_new_for_sysctl
229 .Fa "struct sysctl_req *req"
231 .Fd #endif /* _KERNEL */
235 family of functions allows one to safely allocate, compose and
236 release strings in kernel or user space.
238 Instead of arrays of characters, these functions operate on structures
244 Any errors encountered during the allocation or composition of the
245 string will be latched in the data structure,
246 making a single error test at the end of the composition
247 sufficient to determine success or failure of the entire process.
251 function initializes the
253 pointed to by its first argument.
263 argument is a pointer to a buffer in which to store the actual string;
267 will allocate one using
271 is the initial size of the storage buffer.
274 may be comprised of the following flags:
275 .Bl -tag -width ".Dv SBUF_AUTOEXTEND"
277 The storage buffer is fixed at its initial size.
278 Attempting to extend the sbuf beyond this size results in an overflow condition.
279 .It Dv SBUF_AUTOEXTEND
280 This indicates that the storage buffer may be extended as necessary, so long
281 as resources allow, to hold additional data.
282 .It Dv SBUF_INCLUDENUL
283 This causes the final nulterm byte to be counted in the length of the data.
284 .It Dv SBUF_DRAINTOEOR
285 Treat top-level sections started with
286 .Fn sbuf_start_section
287 as a record boundary marker that will be used during drain operations to avoid
289 If a record grows sufficiently large such that it fills the
291 and therefore cannot be drained without being split, an error of
295 Indicates that attempts to extend the storage buffer should fail in low memory
305 it must point to an array of at least
308 The result of accessing that array directly while it is in use by the
313 function is a shortcut for creating a completely dynamic
315 It is the equivalent of calling
322 .Dv SBUF_AUTOEXTEND .
325 .Fn sbuf_new_for_sysctl
326 function will set up an sbuf with a drain function to use
328 when the internal buffer fills.
329 Note that if the various functions which append to an sbuf are used while
330 a non-sleepable lock is held, the user buffer should be wired using
331 .Fn sysctl_wire_old_buffer .
337 and frees any memory allocated for it.
338 There must be a call to
342 Any attempt to access the sbuf after it has been deleted will fail.
346 function invalidates the contents of the
348 and resets its position to zero.
352 function returns the current user flags.
357 functions set or clear one or more user flags, respectively.
358 The user flags are described under the
368 which is a value between zero and one less than the size of the
370 This effectively truncates the sbuf at the new position.
374 function appends the first
376 bytes from the buffer
385 bytes from the specified userland address into the
390 function replaces the contents of the
394 bytes from the buffer
399 function appends the NUL-terminated string
403 at the current position.
407 function sets a drain function
411 and records a pointer
413 to be passed to the drain on callback.
414 The drain function cannot be changed while
418 The registered drain function
420 will be called with the argument
426 to a byte string that is the contents of the sbuf, and the length
429 If the drain function exists, it will be called when the sbuf internal
430 buffer is full, or on behalf of
432 The drain function may drain some or all of the data, but must drain
434 The return value from the drain function, if positive, indicates how
435 many bytes were drained.
436 If negative, the return value indicates the negative error code which
437 will be returned from this or a later call to
439 If the returned drained length is 0, an error of
442 To do unbuffered draining, initialize the sbuf with a two-byte buffer.
443 The drain will be called for every byte added to the sbuf.
454 functions cannot be used on an sbuf with a drain.
458 function copies a NUL-terminated string from the specified userland
463 argument is non-zero, no more than
465 characters (not counting the terminating NUL) are copied; otherwise
466 the entire string, or as much of it as can fit in the
472 function replaces the contents of the
474 with those of the NUL-terminated string
476 This is equivalent to calling
480 or one which position has been reset to zero with
486 .Fn sbuf_nl_terminate
487 function appends a trailing newline character, if the current line is non-empty
488 and not already terminated by a newline character.
492 function formats its arguments according to the format string pointed
495 and appends the resulting string to the
497 at the current position.
501 function behaves the same as
503 except that the arguments are obtained from the variable-length argument list
508 function appends the character
512 at the current position.
516 function removes trailing whitespace from the
521 function returns any error value that the
523 may have accumulated, either from the drain function, or
528 This function is generally not needed and instead the error code from
530 is the preferred way to discover whether an sbuf had an error.
534 function will call the attached drain function if one exists until all
538 If there is no attached drain,
542 In either case it marks the
544 as finished, which means that it may no longer be modified using
553 is used to reset the sbuf.
557 function returns the actual string;
559 only works on a finished
563 function returns the length of the string.
566 with an attached drain,
568 returns the length of the un-drained data.
570 returns non-zero if the
575 .Fn sbuf_start_section
578 functions may be used for automatic section alignment.
583 specify the padding size and a character used for padding.
588 are to save and restore the current section length when nested sections
590 For the top level section
592 and \-1 can be specified for
600 function prints an array of bytes to the supplied sbuf, along with an ASCII
601 representation of the bytes if possible.
604 man page for more details on the interface.
607 .Fn sbuf_printf_drain
608 function is a drain function that will call printf, or log to the console.
613 or a valid pointer to a
619 the total bytes drained will be added to the value pointed to by
624 function printfs the sbuf to stdout if in userland, and to the console
625 and log if in the kernel.
628 must be finished before calling
630 It does not drain the buffer or update any pointers.
632 If an operation caused an
634 to overflow, most subsequent operations on it will fail until the
640 or its position is reset to a value between 0 and one less than the
641 size of its storage buffer using
643 or it is reinitialized to a sufficiently short string using
646 Drains in user-space will not always function as indicated.
647 While the drain function will be called immediately on overflow from
656 currently have no way to determine whether there will be an overflow
657 until after it occurs, and cannot do a partial expansion of the format
659 Thus when using libsbuf the buffer may be extended to allow completion
660 of a single printf call, even though a drain is attached.
666 if it failed to allocate a storage buffer, and a pointer to the new
672 function returns \-1 if
674 was invalid, and zero otherwise.
685 all return \-1 if the buffer overflowed, and zero otherwise.
689 function returns a non-zero value if the buffer has an overflow or
690 drain error, and zero otherwise.
694 function returns \-1 if the buffer overflowed.
699 returns \-1 if copying string from userland failed, and number of bytes
704 function returns the section length or \-1 if the buffer has an error.
708 function (the kernel version) returns
710 if the sbuf overflowed before being finished,
711 or returns the error code from the drain if one is attached.
715 function (the userland version)
716 will return zero for success and \-1 and set errno on error.
718 .Bd -literal -compact
719 #include <sys/types.h>
720 #include <sys/sbuf.h>
724 sb = sbuf_new_auto();
725 sbuf_cat(sb, "Customers found:\en");
726 TAILQ_FOREACH(foo, &foolist, list) {
727 sbuf_printf(sb, " %4d %s\en", foo->index, foo->name);
728 sbuf_printf(sb, " Address: %s\en", foo->address);
729 sbuf_printf(sb, " Zip: %s\en", foo->zipcode);
731 if (sbuf_finish(sb) != 0) /* Check for any and all errors */
732 err(1, "Could not generate message");
733 transmit_msg(sbuf_data(sb), sbuf_len(sb));
747 family of functions first appeared in
753 family of functions was designed by
754 .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org
756 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org .
757 Additional improvements were suggested by
758 .An Justin T. Gibbs Aq Mt gibbs@FreeBSD.org .
759 Auto-extend support added by
760 .An Kelly Yancey Aq Mt kbyanc@FreeBSD.org .
761 Drain functionality added by
762 .An Matthew Fleming Aq Mt mdf@FreeBSD.org .
764 This manual page was written by
765 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org .