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 ,
59 .Nm sbuf_end_section ,
61 .Nm sbuf_printf_drain ,
63 .Nd safe string composition
67 .Ft typedef\ int ( sbuf_drain_func ) ( void\ *arg, const\ char\ *data, int\ len ) ;
106 .Fa "const void *buf"
112 .Fa "const void *buf"
118 .Fa "const char *str"
123 .Fa "const char *str"
128 .Fa "const char *fmt" "..."
133 .Fa "const char *fmt"
144 .Fa "sbuf_drain_func *func"
176 .Fo sbuf_start_section
178 .Fa "ssize_t *old_lenp"
183 .Fa "ssize_t old_len"
189 .Fa "struct sbuf *sb"
192 .Fa "const char *hdr"
196 .Fo sbuf_printf_drain
198 .Fa "const char *data"
211 .Fa "const void *uaddr"
217 .Fa "const void *uaddr"
222 .Fo sbuf_new_for_sysctl
226 .Fa "struct sysctl_req *req"
228 .Fd #endif /* _KERNEL */
232 family of functions allows one to safely allocate, compose and
233 release strings in kernel or user space.
235 Instead of arrays of characters, these functions operate on structures
241 Any errors encountered during the allocation or composition of the
242 string will be latched in the data structure,
243 making a single error test at the end of the composition
244 sufficient to determine success or failure of the entire process.
248 function initializes the
250 pointed to by its first argument.
260 argument is a pointer to a buffer in which to store the actual string;
264 will allocate one using
268 is the initial size of the storage buffer.
271 may be comprised of the following flags:
272 .Bl -tag -width ".Dv SBUF_AUTOEXTEND"
274 The storage buffer is fixed at its initial size.
275 Attempting to extend the sbuf beyond this size results in an overflow condition.
276 .It Dv SBUF_AUTOEXTEND
277 This indicates that the storage buffer may be extended as necessary, so long
278 as resources allow, to hold additional data.
279 .It Dv SBUF_INCLUDENUL
280 This causes the final nulterm byte to be counted in the length of the data.
281 .It Dv SBUF_DRAINTOEOR
282 Treat top-level sections started with
283 .Fn sbuf_start_section
284 as a record boundary marker that will be used during drain operations to avoid
286 If a record grows sufficiently large such that it fills the
288 and therefore cannot be drained without being split, an error of
297 it must point to an array of at least
300 The result of accessing that array directly while it is in use by the
305 function is a shortcut for creating a completely dynamic
307 It is the equivalent of calling
314 .Dv SBUF_AUTOEXTEND .
317 .Fn sbuf_new_for_sysctl
318 function will set up an sbuf with a drain function to use
320 when the internal buffer fills.
321 Note that if the various functions which append to an sbuf are used while
322 a non-sleepable lock is held, the user buffer should be wired using
323 .Fn sysctl_wire_old_buffer .
329 and frees any memory allocated for it.
330 There must be a call to
334 Any attempt to access the sbuf after it has been deleted will fail.
338 function invalidates the contents of the
340 and resets its position to zero.
344 function returns the current user flags.
349 functions set or clear one or more user flags, respectively.
350 The user flags are described under the
360 which is a value between zero and one less than the size of the
362 This effectively truncates the sbuf at the new position.
366 function appends the first
368 bytes from the buffer
377 bytes from the specified userland address into the
382 function replaces the contents of the
386 bytes from the buffer
391 function appends the NUL-terminated string
395 at the current position.
399 function sets a drain function
403 and records a pointer
405 to be passed to the drain on callback.
406 The drain function cannot be changed while
410 The registered drain function
412 will be called with the argument
418 to a byte string that is the contents of the sbuf, and the length
421 If the drain function exists, it will be called when the sbuf internal
422 buffer is full, or on behalf of
424 The drain function may drain some or all of the data, but must drain
426 The return value from the drain function, if positive, indicates how
427 many bytes were drained.
428 If negative, the return value indicates the negative error code which
429 will be returned from this or a later call to
431 If the returned drained length is 0, an error of
434 To do unbuffered draining, initialize the sbuf with a two-byte buffer.
435 The drain will be called for every byte added to the sbuf.
442 functions cannot be used on an sbuf with a drain.
446 function copies a NUL-terminated string from the specified userland
451 argument is non-zero, no more than
453 characters (not counting the terminating NUL) are copied; otherwise
454 the entire string, or as much of it as can fit in the
460 function replaces the contents of the
462 with those of the NUL-terminated string
464 This is equivalent to calling
468 or one which position has been reset to zero with
475 function formats its arguments according to the format string pointed
478 and appends the resulting string to the
480 at the current position.
484 function behaves the same as
486 except that the arguments are obtained from the variable-length argument list
491 function appends the character
495 at the current position.
499 function removes trailing whitespace from the
504 function returns any error value that the
506 may have accumulated, either from the drain function, or
511 This function is generally not needed and instead the error code from
513 is the preferred way to discover whether an sbuf had an error.
517 function will call the attached drain function if one exists until all
521 If there is no attached drain,
525 In either case it marks the
527 as finished, which means that it may no longer be modified using
536 is used to reset the sbuf.
540 function returns the actual string;
542 only works on a finished
546 function returns the length of the string.
549 with an attached drain,
551 returns the length of the un-drained data.
553 returns non-zero if the
558 .Fn sbuf_start_section
561 functions may be used for automatic section alignment.
566 specify the padding size and a character used for padding.
571 are to save and restore the current section length when nested sections
573 For the top level section
575 and \-1 can be specified for
583 function prints an array of bytes to the supplied sbuf, along with an ASCII
584 representation of the bytes if possible.
587 man page for more details on the interface.
590 .Fn sbuf_printf_drain
591 function is a drain function that will call printf, or log to the console.
596 or a valid pointer to a
602 the total bytes drained will be added to the value pointed to by
607 function printfs the sbuf to stdout if in userland, and to the console
608 and log if in the kernel.
611 must be finished before calling
613 It does not drain the buffer or update any pointers.
615 If an operation caused an
617 to overflow, most subsequent operations on it will fail until the
623 or its position is reset to a value between 0 and one less than the
624 size of its storage buffer using
626 or it is reinitialized to a sufficiently short string using
629 Drains in user-space will not always function as indicated.
630 While the drain function will be called immediately on overflow from
639 currently have no way to determine whether there will be an overflow
640 until after it occurs, and cannot do a partial expansion of the format
642 Thus when using libsbuf the buffer may be extended to allow completion
643 of a single printf call, even though a drain is attached.
649 if it failed to allocate a storage buffer, and a pointer to the new
655 function returns \-1 if
657 was invalid, and zero otherwise.
668 all return \-1 if the buffer overflowed, and zero otherwise.
672 function returns a non-zero value if the buffer has an overflow or
673 drain error, and zero otherwise.
677 function returns \-1 if the buffer overflowed.
682 returns \-1 if copying string from userland failed, and number of bytes
687 function returns the section length or \-1 if the buffer has an error.
691 function (the kernel version) returns
693 if the sbuf overflowed before being finished,
694 or returns the error code from the drain if one is attached.
698 function (the userland version)
699 will return zero for success and \-1 and set errno on error.
701 .Bd -literal -compact
702 #include <sys/types.h>
703 #include <sys/sbuf.h>
707 sb = sbuf_new_auto();
708 sbuf_cat(sb, "Customers found:\en");
709 TAILQ_FOREACH(foo, &foolist, list) {
710 sbuf_printf(sb, " %4d %s\en", foo->index, foo->name);
711 sbuf_printf(sb, " Address: %s\en", foo->address);
712 sbuf_printf(sb, " Zip: %s\en", foo->zipcode);
714 if (sbuf_finish(sb) != 0) /* Check for any and all errors */
715 err(1, "Could not generate message");
716 transmit_msg(sbuf_data(sb), sbuf_len(sb));
730 family of functions first appeared in
736 family of functions was designed by
737 .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org
739 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org .
740 Additional improvements were suggested by
741 .An Justin T. Gibbs Aq Mt gibbs@FreeBSD.org .
742 Auto-extend support added by
743 .An Kelly Yancey Aq Mt kbyanc@FreeBSD.org .
744 Drain functionality added by
745 .An Matthew Fleming Aq Mt mdf@FreeBSD.org .
747 This manual page was written by
748 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org .