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 ,
62 .Nd safe string composition
66 .Ft typedef\ int ( sbuf_drain_func ) ( void\ *arg, const\ char\ *data, int\ len ) ;
105 .Fa "const void *buf"
111 .Fa "const void *buf"
117 .Fa "const char *str"
122 .Fa "const char *str"
127 .Fa "const char *fmt" "..."
132 .Fa "const char *fmt"
143 .Fa "sbuf_drain_func *func"
175 .Fo sbuf_start_section
177 .Fa "ssize_t *old_lenp"
182 .Fa "ssize_t old_len"
188 .Fa "struct sbuf *sb"
191 .Fa "const char *hdr"
204 .Fa "const void *uaddr"
210 .Fa "const void *uaddr"
215 .Fo sbuf_new_for_sysctl
219 .Fa "struct sysctl_req *req"
221 .Fd #endif /* _KERNEL */
225 family of functions allows one to safely allocate, compose and
226 release strings in kernel or user space.
228 Instead of arrays of characters, these functions operate on structures
234 Any errors encountered during the allocation or composition of the
235 string will be latched in the data structure,
236 making a single error test at the end of the composition
237 sufficient to determine success or failure of the entire process.
241 function initializes the
243 pointed to by its first argument.
253 argument is a pointer to a buffer in which to store the actual string;
257 will allocate one using
261 is the initial size of the storage buffer.
264 may be comprised of the following flags:
265 .Bl -tag -width ".Dv SBUF_AUTOEXTEND"
267 The storage buffer is fixed at its initial size.
268 Attempting to extend the sbuf beyond this size results in an overflow condition.
269 .It Dv SBUF_AUTOEXTEND
270 This indicates that the storage buffer may be extended as necessary, so long
271 as resources allow, to hold additional data.
272 .It Dv SBUF_INCLUDENUL
273 This causes the final nulterm byte to be counted in the length of the data.
274 .It Dv SBUF_DRAINTOEOR
275 Treat top-level sections started with
276 .Fn sbuf_start_section
277 as a record boundary marker that will be used during drain operations to avoid
279 If a record grows sufficiently large such that it fills the
281 and therefore cannot be drained without being split, an error of
285 Indicates that attempts to extend the storage buffer should fail in low memory
295 it must point to an array of at least
298 The result of accessing that array directly while it is in use by the
303 function is a shortcut for creating a completely dynamic
305 It is the equivalent of calling
312 .Dv SBUF_AUTOEXTEND .
315 .Fn sbuf_new_for_sysctl
316 function will set up an sbuf with a drain function to use
318 when the internal buffer fills.
319 Note that if the various functions which append to an sbuf are used while
320 a non-sleepable lock is held, the user buffer should be wired using
321 .Fn sysctl_wire_old_buffer .
327 and frees any memory allocated for it.
328 There must be a call to
332 Any attempt to access the sbuf after it has been deleted will fail.
336 function invalidates the contents of the
338 and resets its position to zero.
342 function returns the current user flags.
347 functions set or clear one or more user flags, respectively.
348 The user flags are described under the
358 which is a value between zero and the current position in the buffer.
359 It can only truncate the sbuf to the new position.
363 function appends the first
365 bytes from the buffer
374 bytes from the specified userland address into the
379 function replaces the contents of the
383 bytes from the buffer
388 function appends the NUL-terminated string
392 at the current position.
396 function sets a drain function
400 and records a pointer
402 to be passed to the drain on callback.
403 The drain function cannot be changed while
407 The registered drain function
409 will be called with the argument
415 to a byte string that is the contents of the sbuf, and the length
418 If the drain function exists, it will be called when the sbuf internal
419 buffer is full, or on behalf of
421 The drain function may drain some or all of the data, but must drain
423 The return value from the drain function, if positive, indicates how
424 many bytes were drained.
425 If negative, the return value indicates the negative error code which
426 will be returned from this or a later call to
428 The returned drained length cannot be zero.
429 To do unbuffered draining, initialize the sbuf with a two-byte buffer.
430 The drain will be called for every byte added to the sbuf.
437 functions cannot be used on an sbuf with a drain.
441 function copies a NUL-terminated string from the specified userland
446 argument is non-zero, no more than
448 characters (not counting the terminating NUL) are copied; otherwise
449 the entire string, or as much of it as can fit in the
455 function replaces the contents of the
457 with those of the NUL-terminated string
459 This is equivalent to calling
463 or one which position has been reset to zero with
470 function formats its arguments according to the format string pointed
473 and appends the resulting string to the
475 at the current position.
479 function behaves the same as
481 except that the arguments are obtained from the variable-length argument list
486 function appends the character
490 at the current position.
494 function removes trailing whitespace from the
499 function returns any error value that the
501 may have accumulated, either from the drain function, or ENOMEM if the
504 This function is generally not needed and instead the error code from
506 is the preferred way to discover whether an sbuf had an error.
510 function will call the attached drain function if one exists until all
514 If there is no attached drain,
518 In either case it marks the
520 as finished, which means that it may no longer be modified using
529 is used to reset the sbuf.
533 function returns the actual string;
535 only works on a finished
539 function returns the length of the string.
542 with an attached drain,
544 returns the length of the un-drained data.
546 returns non-zero if the
551 .Fn sbuf_start_section
554 functions may be used for automatic section alignment.
559 specify the padding size and a character used for padding.
564 are to save and restore the current section length when nested sections
566 For the top level section
568 and \-1 can be specified for
576 function prints an array of bytes to the supplied sbuf, along with an ASCII
577 representation of the bytes if possible.
580 man page for more details on the interface.
584 function printfs the sbuf to stdout if in userland, and to the console
585 and log if in the kernel.
586 It does not drain the buffer or update any pointers.
588 If an operation caused an
590 to overflow, most subsequent operations on it will fail until the
596 or its position is reset to a value between 0 and one less than the
597 size of its storage buffer using
599 or it is reinitialized to a sufficiently short string using
602 Drains in user-space will not always function as indicated.
603 While the drain function will be called immediately on overflow from
612 currently have no way to determine whether there will be an overflow
613 until after it occurs, and cannot do a partial expansion of the format
615 Thus when using libsbuf the buffer may be extended to allow completion
616 of a single printf call, even though a drain is attached.
622 if it failed to allocate a storage buffer, and a pointer to the new
628 function returns \-1 if
630 was invalid, and zero otherwise.
641 all return \-1 if the buffer overflowed, and zero otherwise.
645 function returns a non-zero value if the buffer has an overflow or
646 drain error, and zero otherwise.
650 function returns \-1 if the buffer overflowed.
655 returns \-1 if copying string from userland failed, and number of bytes
660 function returns the section length or \-1 if the buffer has an error.
664 function (the kernel version) returns ENOMEM if the sbuf overflowed before
666 or returns the error code from the drain if one is attached.
670 function (the userland version)
671 will return zero for success and \-1 and set errno on error.
673 .Bd -literal -compact
674 #include <sys/types.h>
675 #include <sys/sbuf.h>
679 sb = sbuf_new_auto();
680 sbuf_cat(sb, "Customers found:\en");
681 TAILQ_FOREACH(foo, &foolist, list) {
682 sbuf_printf(sb, " %4d %s\en", foo->index, foo->name);
683 sbuf_printf(sb, " Address: %s\en", foo->address);
684 sbuf_printf(sb, " Zip: %s\en", foo->zipcode);
686 if (sbuf_finish(sb) != 0) /* Check for any and all errors */
687 err(1, "Could not generate message");
688 transmit_msg(sbuf_data(sb), sbuf_len(sb));
702 family of functions first appeared in
708 family of functions was designed by
709 .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org
711 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org .
712 Additional improvements were suggested by
713 .An Justin T. Gibbs Aq Mt gibbs@FreeBSD.org .
714 Auto-extend support added by
715 .An Kelly Yancey Aq Mt kbyanc@FreeBSD.org .
716 Drain functionality added by
717 .An Matthew Fleming Aq Mt mdf@FreeBSD.org .
719 This manual page was written by
720 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org .