1.\"- 2.\" Copyright (c) 2000 Poul-Henning Kamp and Dag-Erling Coïdan Smørgrav 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 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. 13.\" 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 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd April 11, 2013 29.Dt SBUF 9 30.Os 31.Sh NAME 32.Nm sbuf , 33.Nm sbuf_new , 34.Nm sbuf_new_auto , 35.Nm sbuf_new_for_sysctl , 36.Nm sbuf_clear , 37.Nm sbuf_setpos , 38.Nm sbuf_bcat , 39.Nm sbuf_bcopyin , 40.Nm sbuf_bcpy , 41.Nm sbuf_cat , 42.Nm sbuf_copyin , 43.Nm sbuf_cpy , 44.Nm sbuf_printf , 45.Nm sbuf_vprintf , 46.Nm sbuf_putc , 47.Nm sbuf_set_drain , 48.Nm sbuf_trim , 49.Nm sbuf_error , 50.Nm sbuf_finish , 51.Nm sbuf_data , 52.Nm sbuf_len , 53.Nm sbuf_done , 54.Nm sbuf_delete , 55.Nm sbuf_start_section , 56.Nm sbuf_end_section 57.Nd safe string composition 58.Sh SYNOPSIS 59.In sys/types.h 60.In sys/sbuf.h 61.Ft typedef\ int ( sbuf_drain_func ) ( void\ *arg, const\ char\ *data, int\ len ) ; 62.Pp 63.Ft struct sbuf * 64.Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags" 65.Ft struct sbuf * 66.Fn sbuf_new_auto 67.Ft void 68.Fn sbuf_clear "struct sbuf *s" 69.Ft int 70.Fn sbuf_setpos "struct sbuf *s" "int pos" 71.Ft int 72.Fn sbuf_bcat "struct sbuf *s" "const void *buf" "size_t len" 73.Ft int 74.Fn sbuf_bcopyin "struct sbuf *s" "const void *uaddr" "size_t len" 75.Ft int 76.Fn sbuf_bcpy "struct sbuf *s" "const void *buf" "size_t len" 77.Ft int 78.Fn sbuf_cat "struct sbuf *s" "const char *str" 79.Ft int 80.Fn sbuf_copyin "struct sbuf *s" "const void *uaddr" "size_t len" 81.Ft int 82.Fn sbuf_cpy "struct sbuf *s" "const char *str" 83.Ft int 84.Fn sbuf_printf "struct sbuf *s" "const char *fmt" "..." 85.Ft int 86.Fn sbuf_vprintf "struct sbuf *s" "const char *fmt" "va_list ap" 87.Ft int 88.Fn sbuf_putc "struct sbuf *s" "int c" 89.Ft void 90.Fn sbuf_set_drain "struct sbuf *s" "sbuf_drain_func *func" "void *arg" 91.Ft int 92.Fn sbuf_trim "struct sbuf *s" 93.Ft int 94.Fn sbuf_error "struct sbuf *s" 95.Ft int 96.Fn sbuf_finish "struct sbuf *s" 97.Ft char * 98.Fn sbuf_data "struct sbuf *s" 99.Ft ssize_t 100.Fn sbuf_len "struct sbuf *s" 101.Ft int 102.Fn sbuf_done "struct sbuf *s" 103.Ft void 104.Fn sbuf_delete "struct sbuf *s" 105.Ft void 106.Fn sbuf_start_section "struct sbuf *s" "ssize_t *old_lenp" 107.Ft ssize_t 108.Fn sbuf_end_section "struct sbuf *s" "ssize_t old_len" "size_t pad" "int c" 109.In sys/sysctl.h 110.Ft struct sbuf * 111.Fn sbuf_new_for_sysctl "struct sbuf *s" "char *buf" "int length" "struct sysctl_req *req" 112.Sh DESCRIPTION 113The 114.Nm 115family of functions allows one to safely allocate, compose and 116release strings in kernel or user space. 117.Pp 118Instead of arrays of characters, these functions operate on structures 119called 120.Fa sbufs , 121defined in 122.In sys/sbuf.h . 123.Pp 124Any errors encountered during the allocation or composition of the 125string will be latched in the data structure, 126making a single error test at the end of the composition 127sufficient to determine success or failure of the entire process. 128.Pp 129The 130.Fn sbuf_new 131function initializes the 132.Fa sbuf 133pointed to by its first argument. 134If that pointer is 135.Dv NULL , 136.Fn sbuf_new 137allocates a 138.Vt struct sbuf 139using 140.Xr malloc 9 . 141The 142.Fa buf 143argument is a pointer to a buffer in which to store the actual string; 144if it is 145.Dv NULL , 146.Fn sbuf_new 147will allocate one using 148.Xr malloc 9 . 149The 150.Fa length 151is the initial size of the storage buffer. 152The fourth argument, 153.Fa flags , 154may be comprised of the following flags: 155.Bl -tag -width ".Dv SBUF_AUTOEXTEND" 156.It Dv SBUF_FIXEDLEN 157The storage buffer is fixed at its initial size. 158Attempting to extend the sbuf beyond this size results in an overflow condition. 159.It Dv SBUF_AUTOEXTEND 160This indicates that the storage buffer may be extended as necessary, so long 161as resources allow, to hold additional data. 162.El 163.Pp 164Note that if 165.Fa buf 166is not 167.Dv NULL , 168it must point to an array of at least 169.Fa length 170characters. 171The result of accessing that array directly while it is in use by the 172sbuf is undefined. 173.Pp 174The 175.Fn sbuf_new_auto 176function is a shortcut for creating a completely dynamic 177.Nm . 178It is the equivalent of calling 179.Fn sbuf_new 180with values 181.Dv NULL , 182.Dv NULL , 183.Dv 0 , 184and 185.Dv SBUF_AUTOEXTEND . 186.Pp 187The 188.Fn sbuf_new_for_sysctl 189function will set up an sbuf with a drain function to use 190.Fn SYSCTL_OUT 191when the internal buffer fills. 192Note that if the various functions which append to an sbuf are used while 193a non-sleepable lock is held, the user buffer should be wired using 194.Fn sysctl_wire_old_buffer . 195.Pp 196The 197.Fn sbuf_delete 198function clears the 199.Fa sbuf 200and frees any memory allocated for it. 201There must be a call to 202.Fn sbuf_delete 203for every call to 204.Fn sbuf_new . 205Any attempt to access the sbuf after it has been deleted will fail. 206.Pp 207The 208.Fn sbuf_clear 209function invalidates the contents of the 210.Fa sbuf 211and resets its position to zero. 212.Pp 213The 214.Fn sbuf_setpos 215function sets the 216.Fa sbuf Ns 's 217end position to 218.Fa pos , 219which is a value between zero and one less than the size of the 220storage buffer. 221This effectively truncates the sbuf at the new position. 222.Pp 223The 224.Fn sbuf_bcat 225function appends the first 226.Fa len 227bytes from the buffer 228.Fa buf 229to the 230.Fa sbuf . 231.Pp 232The 233.Fn sbuf_bcopyin 234function copies 235.Fa len 236bytes from the specified userland address into the 237.Fa sbuf . 238.Pp 239The 240.Fn sbuf_bcpy 241function replaces the contents of the 242.Fa sbuf 243with the first 244.Fa len 245bytes from the buffer 246.Fa buf . 247.Pp 248The 249.Fn sbuf_cat 250function appends the NUL-terminated string 251.Fa str 252to the 253.Fa sbuf 254at the current position. 255.Pp 256The 257.Fn sbuf_set_drain 258function sets a drain function 259.Fa func 260for the 261.Fa sbuf , 262and records a pointer 263.Fa arg 264to be passed to the drain on callback. 265The drain function cannot be changed while 266.Fa sbuf_len 267is non-zero. 268.Pp 269The registered drain function 270.Vt sbuf_drain_func 271will be called with the argument 272.Fa arg 273provided to 274.Fn sbuf_set_drain , 275a pointer 276.Fa data 277to a byte string that is the contents of the sbuf, and the length 278.Fa len 279of the data. 280If the drain function exists, it will be called when the sbuf internal 281buffer is full, or on behalf of 282.Fn sbuf_finish . 283The drain function may drain some or all of the data, but must drain 284at least 1 byte. 285The return value from the drain function, if positive, indicates how 286many bytes were drained. 287If negative, the return value indicates the negative error code which 288will be returned from this or a later call to 289.Fn sbuf_finish . 290The returned drained length cannot be zero. 291To do unbuffered draining, initialize the sbuf with a two-byte buffer. 292The drain will be called for every byte added to the sbuf. 293The 294.Fn sbuf_bcopyin , 295.Fn sbuf_copyin , 296.Fn sbuf_trim , 297and 298.Fn sbuf_data 299functions cannot be used on an sbuf with a drain. 300.Pp 301The 302.Fn sbuf_copyin 303function copies a NUL-terminated string from the specified userland 304address into the 305.Fa sbuf . 306If the 307.Fa len 308argument is non-zero, no more than 309.Fa len 310characters (not counting the terminating NUL) are copied; otherwise 311the entire string, or as much of it as can fit in the 312.Fa sbuf , 313is copied. 314.Pp 315The 316.Fn sbuf_cpy 317function replaces the contents of the 318.Fa sbuf 319with those of the NUL-terminated string 320.Fa str . 321This is equivalent to calling 322.Fn sbuf_cat 323with a fresh 324.Fa sbuf 325or one which position has been reset to zero with 326.Fn sbuf_clear 327or 328.Fn sbuf_setpos . 329.Pp 330The 331.Fn sbuf_printf 332function formats its arguments according to the format string pointed 333to by 334.Fa fmt 335and appends the resulting string to the 336.Fa sbuf 337at the current position. 338.Pp 339The 340.Fn sbuf_vprintf 341function behaves the same as 342.Fn sbuf_printf 343except that the arguments are obtained from the variable-length argument list 344.Fa ap . 345.Pp 346The 347.Fn sbuf_putc 348function appends the character 349.Fa c 350to the 351.Fa sbuf 352at the current position. 353.Pp 354The 355.Fn sbuf_trim 356function removes trailing whitespace from the 357.Fa sbuf . 358.Pp 359The 360.Fn sbuf_error 361function returns any error value that the 362.Fa sbuf 363may have accumulated, either from the drain function, or ENOMEM if the 364.Fa sbuf 365overflowed. 366This function is generally not needed and instead the error code from 367.Fn sbuf_finish 368is the preferred way to discover whether an sbuf had an error. 369.Pp 370The 371.Fn sbuf_finish 372function will call the attached drain function if one exists until all 373the data in the 374.Fa sbuf 375is flushed. 376If there is no attached drain, 377.Fn sbuf_finish 378NUL-terminates the 379.Fa sbuf . 380In either case it marks the 381.Fa sbuf 382as finished, which means that it may no longer be modified using 383.Fn sbuf_setpos , 384.Fn sbuf_cat , 385.Fn sbuf_cpy , 386.Fn sbuf_printf 387or 388.Fn sbuf_putc , 389until 390.Fn sbuf_clear 391is used to reset the sbuf. 392.Pp 393The 394.Fn sbuf_data 395function returns the actual string; 396.Fn sbuf_data 397only works on a finished 398.Fa sbuf . 399The 400.Fn sbuf_len 401function returns the length of the string. 402For an 403.Fa sbuf 404with an attached drain, 405.Fn sbuf_len 406returns the length of the un-drained data. 407.Fn sbuf_done 408returns non-zero if the 409.Fa sbuf 410is finished. 411.Pp 412The 413.Fn sbuf_start_section 414and 415.Fn sbuf_end_section 416functions may be used for automatic section alignment. 417The arguments 418.Fa pad 419and 420.Fa c 421specify the padding size and a character used for padding. 422The arguments 423.Fa old_lenp 424and 425.Fa old_len 426are to save and restore the current section length when nested sections 427are used. 428For the top level section 429.Dv NULL 430and \-1 can be specified for 431.Fa old_lenp 432and 433.Fa old_len 434respectively. 435.Sh NOTES 436If an operation caused an 437.Fa sbuf 438to overflow, most subsequent operations on it will fail until the 439.Fa sbuf 440is finished using 441.Fn sbuf_finish 442or reset using 443.Fn sbuf_clear , 444or its position is reset to a value between 0 and one less than the 445size of its storage buffer using 446.Fn sbuf_setpos , 447or it is reinitialized to a sufficiently short string using 448.Fn sbuf_cpy . 449.Pp 450Drains in user-space will not always function as indicated. 451While the drain function will be called immediately on overflow from 452the 453.Fa sbuf_putc , 454.Fa sbuf_bcat , 455.Fa sbuf_cat 456functions, 457.Fa sbuf_printf 458and 459.Fa sbuf_vprintf 460currently have no way to determine whether there will be an overflow 461until after it occurs, and cannot do a partial expansion of the format 462string. 463Thus when using libsbuf the buffer may be extended to allow completion 464of a single printf call, even though a drain is attached. 465.Sh RETURN VALUES 466The 467.Fn sbuf_new 468function returns 469.Dv NULL 470if it failed to allocate a storage buffer, and a pointer to the new 471.Fa sbuf 472otherwise. 473.Pp 474The 475.Fn sbuf_setpos 476function returns \-1 if 477.Fa pos 478was invalid, and zero otherwise. 479.Pp 480The 481.Fn sbuf_cat , 482.Fn sbuf_cpy , 483.Fn sbuf_printf , 484.Fn sbuf_putc , 485and 486.Fn sbuf_trim 487functions 488all return \-1 if the buffer overflowed, and zero otherwise. 489.Pp 490The 491.Fn sbuf_error 492function returns a non-zero value if the buffer has an overflow or 493drain error, and zero otherwise. 494.Pp 495The 496.Fn sbuf_len 497function returns \-1 if the buffer overflowed. 498.Pp 499The 500.Fn sbuf_copyin 501function 502returns \-1 if copying string from userland failed, and number of bytes 503copied otherwise. 504.Pp 505The 506.Fn sbuf_end_section 507function returns the section length or \-1 if the buffer has an error. 508.Pp 509The 510.Fn sbuf_finish 9 511function (the kernel version) returns ENOMEM if the sbuf overflowed before 512being finished, 513or returns the error code from the drain if one is attached. 514.Pp 515The 516.Fn sbuf_finish 3 517function (the userland version) 518will return zero for success and \-1 and set errno on error. 519.Sh EXAMPLES 520.Bd -literal -compact 521#include <sys/sbuf.h> 522 523struct sbuf *sb; 524 525sb = sbuf_new_auto(); 526sbuf_cat(sb, "Customers found:\en"); 527TAILQ_FOREACH(foo, &foolist, list) { 528 sbuf_printf(sb, " %4d %s\en", foo->index, foo->name); 529 sbuf_printf(sb, " Address: %s\en", foo->address); 530 sbuf_printf(sb, " Zip: %s\en", foo->zipcode); 531} 532if (sbuf_finish(sb) != 0) /* Check for any and all errors */ 533 err(1, "Could not generate message"); 534transmit_msg(sbuf_data(sb), sbuf_len(sb)); 535sbuf_delete(sb); 536.Ed 537.Sh SEE ALSO 538.Xr printf 3 , 539.Xr strcat 3 , 540.Xr strcpy 3 , 541.Xr copyin 9 , 542.Xr copyinstr 9 , 543.Xr printf 9 544.Sh HISTORY 545The 546.Nm 547family of functions first appeared in 548.Fx 4.4 . 549.Sh AUTHORS 550.An -nosplit 551The 552.Nm 553family of functions was designed by 554.An Poul-Henning Kamp Aq phk@FreeBSD.org 555and implemented by 556.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org . 557Additional improvements were suggested by 558.An Justin T. Gibbs Aq gibbs@FreeBSD.org . 559Auto-extend support added by 560.An Kelly Yancey Aq kbyanc@FreeBSD.org . 561Drain functionality added by 562.An Matthew Fleming Aq mdf@FreeBSD.org . 563.Pp 564This manual page was written by 565.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org . 566