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 ) ;
69 .Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags"
73 .Fn sbuf_clear "struct sbuf *s"
75 .Fn sbuf_get_flags "struct sbuf *s"
77 .Fn sbuf_set_flags "struct sbuf *s" "int flags"
79 .Fn sbuf_clear_flags "struct sbuf *s" "int flags"
81 .Fn sbuf_setpos "struct sbuf *s" "int pos"
83 .Fn sbuf_bcat "struct sbuf *s" "const void *buf" "size_t len"
85 .Fn sbuf_bcopyin "struct sbuf *s" "const void *uaddr" "size_t len"
87 .Fn sbuf_bcpy "struct sbuf *s" "const void *buf" "size_t len"
89 .Fn sbuf_cat "struct sbuf *s" "const char *str"
91 .Fn sbuf_copyin "struct sbuf *s" "const void *uaddr" "size_t len"
93 .Fn sbuf_cpy "struct sbuf *s" "const char *str"
95 .Fn sbuf_printf "struct sbuf *s" "const char *fmt" "..."
97 .Fn sbuf_vprintf "struct sbuf *s" "const char *fmt" "va_list ap"
99 .Fn sbuf_putc "struct sbuf *s" "int c"
101 .Fn sbuf_set_drain "struct sbuf *s" "sbuf_drain_func *func" "void *arg"
103 .Fn sbuf_trim "struct sbuf *s"
105 .Fn sbuf_error "struct sbuf *s"
107 .Fn sbuf_finish "struct sbuf *s"
109 .Fn sbuf_data "struct sbuf *s"
111 .Fn sbuf_len "struct sbuf *s"
113 .Fn sbuf_done "struct sbuf *s"
115 .Fn sbuf_delete "struct sbuf *s"
117 .Fn sbuf_start_section "struct sbuf *s" "ssize_t *old_lenp"
119 .Fn sbuf_end_section "struct sbuf *s" "ssize_t old_len" "size_t pad" "int c"
122 .Fa "struct sbuf *sb"
125 .Fa "const char *hdr"
129 .Fn sbuf_putbuf "struct sbuf *s"
132 .Fn sbuf_new_for_sysctl "struct sbuf *s" "char *buf" "int length" "struct sysctl_req *req"
136 family of functions allows one to safely allocate, compose and
137 release strings in kernel or user space.
139 Instead of arrays of characters, these functions operate on structures
145 Any errors encountered during the allocation or composition of the
146 string will be latched in the data structure,
147 making a single error test at the end of the composition
148 sufficient to determine success or failure of the entire process.
152 function initializes the
154 pointed to by its first argument.
164 argument is a pointer to a buffer in which to store the actual string;
168 will allocate one using
172 is the initial size of the storage buffer.
175 may be comprised of the following flags:
176 .Bl -tag -width ".Dv SBUF_AUTOEXTEND"
178 The storage buffer is fixed at its initial size.
179 Attempting to extend the sbuf beyond this size results in an overflow condition.
180 .It Dv SBUF_AUTOEXTEND
181 This indicates that the storage buffer may be extended as necessary, so long
182 as resources allow, to hold additional data.
183 .It Dv SBUF_INCLUDENUL
184 This causes the final nulterm byte to be counted in the length of the data.
191 it must point to an array of at least
194 The result of accessing that array directly while it is in use by the
199 function is a shortcut for creating a completely dynamic
201 It is the equivalent of calling
208 .Dv SBUF_AUTOEXTEND .
211 .Fn sbuf_new_for_sysctl
212 function will set up an sbuf with a drain function to use
214 when the internal buffer fills.
215 Note that if the various functions which append to an sbuf are used while
216 a non-sleepable lock is held, the user buffer should be wired using
217 .Fn sysctl_wire_old_buffer .
223 and frees any memory allocated for it.
224 There must be a call to
228 Any attempt to access the sbuf after it has been deleted will fail.
232 function invalidates the contents of the
234 and resets its position to zero.
238 function returns the current user flags.
243 functions set or clear one or more user flags, respectively.
244 The user flags are described under the
254 which is a value between zero and one less than the size of the
256 This effectively truncates the sbuf at the new position.
260 function appends the first
262 bytes from the buffer
271 bytes from the specified userland address into the
276 function replaces the contents of the
280 bytes from the buffer
285 function appends the NUL-terminated string
289 at the current position.
293 function sets a drain function
297 and records a pointer
299 to be passed to the drain on callback.
300 The drain function cannot be changed while
304 The registered drain function
306 will be called with the argument
312 to a byte string that is the contents of the sbuf, and the length
315 If the drain function exists, it will be called when the sbuf internal
316 buffer is full, or on behalf of
318 The drain function may drain some or all of the data, but must drain
320 The return value from the drain function, if positive, indicates how
321 many bytes were drained.
322 If negative, the return value indicates the negative error code which
323 will be returned from this or a later call to
325 The returned drained length cannot be zero.
326 To do unbuffered draining, initialize the sbuf with a two-byte buffer.
327 The drain will be called for every byte added to the sbuf.
334 functions cannot be used on an sbuf with a drain.
338 function copies a NUL-terminated string from the specified userland
343 argument is non-zero, no more than
345 characters (not counting the terminating NUL) are copied; otherwise
346 the entire string, or as much of it as can fit in the
352 function replaces the contents of the
354 with those of the NUL-terminated string
356 This is equivalent to calling
360 or one which position has been reset to zero with
367 function formats its arguments according to the format string pointed
370 and appends the resulting string to the
372 at the current position.
376 function behaves the same as
378 except that the arguments are obtained from the variable-length argument list
383 function appends the character
387 at the current position.
391 function removes trailing whitespace from the
396 function returns any error value that the
398 may have accumulated, either from the drain function, or ENOMEM if the
401 This function is generally not needed and instead the error code from
403 is the preferred way to discover whether an sbuf had an error.
407 function will call the attached drain function if one exists until all
411 If there is no attached drain,
415 In either case it marks the
417 as finished, which means that it may no longer be modified using
426 is used to reset the sbuf.
430 function returns the actual string;
432 only works on a finished
436 function returns the length of the string.
439 with an attached drain,
441 returns the length of the un-drained data.
443 returns non-zero if the
448 .Fn sbuf_start_section
451 functions may be used for automatic section alignment.
456 specify the padding size and a character used for padding.
461 are to save and restore the current section length when nested sections
463 For the top level section
465 and \-1 can be specified for
473 function prints an array of bytes to the supplied sbuf, along with an ASCII
474 representation of the bytes if possible.
477 man page for more details on the interface.
481 function printfs the sbuf to stdout if in userland, and to the console
482 and log if in the kernel.
483 It does not drain the buffer or update any pointers.
485 If an operation caused an
487 to overflow, most subsequent operations on it will fail until the
493 or its position is reset to a value between 0 and one less than the
494 size of its storage buffer using
496 or it is reinitialized to a sufficiently short string using
499 Drains in user-space will not always function as indicated.
500 While the drain function will be called immediately on overflow from
509 currently have no way to determine whether there will be an overflow
510 until after it occurs, and cannot do a partial expansion of the format
512 Thus when using libsbuf the buffer may be extended to allow completion
513 of a single printf call, even though a drain is attached.
519 if it failed to allocate a storage buffer, and a pointer to the new
525 function returns \-1 if
527 was invalid, and zero otherwise.
537 all return \-1 if the buffer overflowed, and zero otherwise.
541 function returns a non-zero value if the buffer has an overflow or
542 drain error, and zero otherwise.
546 function returns \-1 if the buffer overflowed.
551 returns \-1 if copying string from userland failed, and number of bytes
556 function returns the section length or \-1 if the buffer has an error.
560 function (the kernel version) returns ENOMEM if the sbuf overflowed before
562 or returns the error code from the drain if one is attached.
566 function (the userland version)
567 will return zero for success and \-1 and set errno on error.
569 .Bd -literal -compact
570 #include <sys/sbuf.h>
574 sb = sbuf_new_auto();
575 sbuf_cat(sb, "Customers found:\en");
576 TAILQ_FOREACH(foo, &foolist, list) {
577 sbuf_printf(sb, " %4d %s\en", foo->index, foo->name);
578 sbuf_printf(sb, " Address: %s\en", foo->address);
579 sbuf_printf(sb, " Zip: %s\en", foo->zipcode);
581 if (sbuf_finish(sb) != 0) /* Check for any and all errors */
582 err(1, "Could not generate message");
583 transmit_msg(sbuf_data(sb), sbuf_len(sb));
597 family of functions first appeared in
603 family of functions was designed by
604 .An Poul-Henning Kamp Aq phk@FreeBSD.org
606 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
607 Additional improvements were suggested by
608 .An Justin T. Gibbs Aq gibbs@FreeBSD.org .
609 Auto-extend support added by
610 .An Kelly Yancey Aq kbyanc@FreeBSD.org .
611 Drain functionality added by
612 .An Matthew Fleming Aq mdf@FreeBSD.org .
614 This manual page was written by
615 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .