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 August 7, 2019 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_get_flags , 38.Nm sbuf_set_flags , 39.Nm sbuf_clear_flags , 40.Nm sbuf_setpos , 41.Nm sbuf_bcat , 42.Nm sbuf_bcopyin , 43.Nm sbuf_bcpy , 44.Nm sbuf_cat , 45.Nm sbuf_copyin , 46.Nm sbuf_cpy , 47.Nm sbuf_nl_terminate , 48.Nm sbuf_printf , 49.Nm sbuf_vprintf , 50.Nm sbuf_putc , 51.Nm sbuf_set_drain , 52.Nm sbuf_trim , 53.Nm sbuf_error , 54.Nm sbuf_finish , 55.Nm sbuf_data , 56.Nm sbuf_len , 57.Nm sbuf_done , 58.Nm sbuf_delete , 59.Nm sbuf_start_section , 60.Nm sbuf_end_section , 61.Nm sbuf_hexdump , 62.Nm sbuf_printf_drain , 63.Nm sbuf_putbuf 64.Nd safe string composition 65.Sh SYNOPSIS 66.In sys/types.h 67.In sys/sbuf.h 68.Ft typedef int 69.Fo (sbuf_drain_func) 70.Fa "void *arg" 71.Fa "const char *data" 72.Fa "int len" 73.Fc 74.Pp 75.Ft struct sbuf * 76.Fo sbuf_new 77.Fa "struct sbuf *s" 78.Fa "char *buf" 79.Fa "int length" 80.Fa "int flags" 81.Fc 82.Ft struct sbuf * 83.Fo sbuf_new_auto 84.Fa "void" 85.Fc 86.Ft void 87.Fo sbuf_clear 88.Fa "struct sbuf *s" 89.Fc 90.Ft int 91.Fo sbuf_get_flags 92.Fa "struct sbuf *s" 93.Fc 94.Ft void 95.Fo sbuf_set_flags 96.Fa "struct sbuf *s" 97.Fa "int flags" 98.Fc 99.Ft void 100.Fo sbuf_clear_flags 101.Fa "struct sbuf *s" 102.Fa "int flags" 103.Fc 104.Ft int 105.Fo sbuf_setpos 106.Fa "struct sbuf *s" 107.Fa "int pos" 108.Fc 109.Ft int 110.Fo sbuf_bcat 111.Fa "struct sbuf *s" 112.Fa "const void *buf" 113.Fa "size_t len" 114.Fc 115.Ft int 116.Fo sbuf_bcpy 117.Fa "struct sbuf *s" 118.Fa "const void *buf" 119.Fa "size_t len" 120.Fc 121.Ft int 122.Fo sbuf_cat 123.Fa "struct sbuf *s" 124.Fa "const char *str" 125.Fc 126.Ft int 127.Fo sbuf_cpy 128.Fa "struct sbuf *s" 129.Fa "const char *str" 130.Fc 131.Ft int 132.Fn sbuf_nl_terminate "struct sbuf *" 133.Ft int 134.Fo sbuf_printf 135.Fa "struct sbuf *s" 136.Fa "const char *fmt" "..." 137.Fc 138.Ft int 139.Fo sbuf_vprintf 140.Fa "struct sbuf *s" 141.Fa "const char *fmt" 142.Fa "va_list ap" 143.Fc 144.Ft int 145.Fo sbuf_putc 146.Fa "struct sbuf *s" 147.Fa "int c" 148.Fc 149.Ft void 150.Fo sbuf_set_drain 151.Fa "struct sbuf *s" 152.Fa "sbuf_drain_func *func" 153.Fa "void *arg" 154.Fc 155.Ft int 156.Fo sbuf_trim 157.Fa "struct sbuf *s" 158.Fc 159.Ft int 160.Fo sbuf_error 161.Fa "struct sbuf *s" 162.Fc 163.Ft int 164.Fo sbuf_finish 165.Fa "struct sbuf *s" 166.Fc 167.Ft char * 168.Fo sbuf_data 169.Fa "struct sbuf *s" 170.Fc 171.Ft ssize_t 172.Fo sbuf_len 173.Fa "struct sbuf *s" 174.Fc 175.Ft int 176.Fo sbuf_done 177.Fa "struct sbuf *s" 178.Fc 179.Ft void 180.Fo sbuf_delete 181.Fa "struct sbuf *s" 182.Fc 183.Ft void 184.Fo sbuf_start_section 185.Fa "struct sbuf *s" 186.Fa "ssize_t *old_lenp" 187.Fc 188.Ft ssize_t 189.Fo sbuf_end_section 190.Fa "struct sbuf *s" 191.Fa "ssize_t old_len" 192.Fa "size_t pad" 193.Fa "int c" 194.Fc 195.Ft void 196.Fo sbuf_hexdump 197.Fa "struct sbuf *sb" 198.Fa "void *ptr" 199.Fa "int length" 200.Fa "const char *hdr" 201.Fa "int flags" 202.Fc 203.Ft int 204.Fo sbuf_printf_drain 205.Fa "void *arg" 206.Fa "const char *data" 207.Fa "int len" 208.Fc 209.Ft void 210.Fo sbuf_putbuf 211.Fa "struct sbuf *s" 212.Fc 213.Fd #ifdef _KERNEL 214.In sys/types.h 215.In sys/sbuf.h 216.Ft int 217.Fo sbuf_bcopyin 218.Fa "struct sbuf *s" 219.Fa "const void *uaddr" 220.Fa "size_t len" 221.Fc 222.Ft int 223.Fo sbuf_copyin 224.Fa "struct sbuf *s" 225.Fa "const void *uaddr" 226.Fa "size_t len" 227.Fc 228.In sys/sysctl.h 229.Ft struct sbuf * 230.Fo sbuf_new_for_sysctl 231.Fa "struct sbuf *s" 232.Fa "char *buf" 233.Fa "int length" 234.Fa "struct sysctl_req *req" 235.Fc 236.Fd #endif /* _KERNEL */ 237.Sh DESCRIPTION 238The 239.Nm 240family of functions allows one to safely allocate, compose and 241release strings in kernel or user space. 242.Pp 243Instead of arrays of characters, these functions operate on structures 244called 245.Fa sbufs , 246defined in 247.In sys/sbuf.h . 248.Pp 249Any errors encountered during the allocation or composition of the 250string will be latched in the data structure, 251making a single error test at the end of the composition 252sufficient to determine success or failure of the entire process. 253.Pp 254The 255.Fn sbuf_new 256function initializes the 257.Fa sbuf 258pointed to by its first argument. 259If that pointer is 260.Dv NULL , 261.Fn sbuf_new 262allocates a 263.Vt struct sbuf 264using 265.Xr malloc 9 . 266The 267.Fa buf 268argument is a pointer to a buffer in which to store the actual string; 269if it is 270.Dv NULL , 271.Fn sbuf_new 272will allocate one using 273.Xr malloc 9 . 274The 275.Fa length 276is the initial size of the storage buffer. 277The fourth argument, 278.Fa flags , 279may be comprised of the following flags: 280.Bl -tag -width ".Dv SBUF_AUTOEXTEND" 281.It Dv SBUF_FIXEDLEN 282The storage buffer is fixed at its initial size. 283Attempting to extend the sbuf beyond this size results in an overflow condition. 284.It Dv SBUF_AUTOEXTEND 285This indicates that the storage buffer may be extended as necessary, so long 286as resources allow, to hold additional data. 287.It Dv SBUF_INCLUDENUL 288This causes the final nulterm byte to be counted in the length of the data. 289.It Dv SBUF_DRAINTOEOR 290Treat top-level sections started with 291.Fn sbuf_start_section 292as a record boundary marker that will be used during drain operations to avoid 293records being split. 294If a record grows sufficiently large such that it fills the 295.Fa sbuf 296and therefore cannot be drained without being split, an error of 297.Er EDEADLK 298is set. 299.It Dv SBUF_NOWAIT 300Indicates that attempts to extend the storage buffer should fail in low memory 301conditions, like 302.Xr malloc 9 303.Dv M_NOWAIT . 304.El 305.Pp 306Note that if 307.Fa buf 308is not 309.Dv NULL , 310it must point to an array of at least 311.Fa length 312characters. 313The result of accessing that array directly while it is in use by the 314sbuf is undefined. 315.Pp 316The 317.Fn sbuf_new_auto 318function is a shortcut for creating a completely dynamic 319.Nm . 320It is the equivalent of calling 321.Fn sbuf_new 322with values 323.Dv NULL , 324.Dv NULL , 325.Dv 0 , 326and 327.Dv SBUF_AUTOEXTEND . 328.Pp 329The 330.Fn sbuf_new_for_sysctl 331function will set up an sbuf with a drain function to use 332.Fn SYSCTL_OUT 333when the internal buffer fills. 334Note that if the various functions which append to an sbuf are used while 335a non-sleepable lock is held, the user buffer should be wired using 336.Fn sysctl_wire_old_buffer . 337.Pp 338The 339.Fn sbuf_delete 340function clears the 341.Fa sbuf 342and frees any memory allocated for it. 343There must be a call to 344.Fn sbuf_delete 345for every call to 346.Fn sbuf_new . 347Any attempt to access the sbuf after it has been deleted will fail. 348.Pp 349The 350.Fn sbuf_clear 351function invalidates the contents of the 352.Fa sbuf 353and resets its position to zero. 354.Pp 355The 356.Fn sbuf_get_flags 357function returns the current user flags. 358The 359.Fn sbuf_set_flags 360and 361.Fn sbuf_get_flags 362functions set or clear one or more user flags, respectively. 363The user flags are described under the 364.Fn sbuf_new 365function. 366.Pp 367The 368.Fn sbuf_setpos 369function sets the 370.Fa sbuf Ns 's 371end position to 372.Fa pos , 373which is a value between zero and one less than the size of the 374storage buffer. 375This effectively truncates the sbuf at the new position. 376.Pp 377The 378.Fn sbuf_bcat 379function appends the first 380.Fa len 381bytes from the buffer 382.Fa buf 383to the 384.Fa sbuf . 385.Pp 386The 387.Fn sbuf_bcopyin 388function copies 389.Fa len 390bytes from the specified userland address into the 391.Fa sbuf . 392.Pp 393The 394.Fn sbuf_bcpy 395function replaces the contents of the 396.Fa sbuf 397with the first 398.Fa len 399bytes from the buffer 400.Fa buf . 401.Pp 402The 403.Fn sbuf_cat 404function appends the NUL-terminated string 405.Fa str 406to the 407.Fa sbuf 408at the current position. 409.Pp 410The 411.Fn sbuf_set_drain 412function sets a drain function 413.Fa func 414for the 415.Fa sbuf , 416and records a pointer 417.Fa arg 418to be passed to the drain on callback. 419The drain function cannot be changed while 420.Fa sbuf_len 421is non-zero. 422.Pp 423The registered drain function 424.Vt sbuf_drain_func 425will be called with the argument 426.Fa arg 427provided to 428.Fn sbuf_set_drain , 429a pointer 430.Fa data 431to a byte string that is the contents of the sbuf, and the length 432.Fa len 433of the data. 434If the drain function exists, it will be called when the sbuf internal 435buffer is full, or on behalf of 436.Fn sbuf_finish . 437The drain function may drain some or all of the data, but must drain 438at least 1 byte. 439The return value from the drain function, if positive, indicates how 440many bytes were drained. 441If negative, the return value indicates the negative error code which 442will be returned from this or a later call to 443.Fn sbuf_finish . 444If the returned drained length is 0, an error of 445.Er EDEADLK 446is set. 447To do unbuffered draining, initialize the sbuf with a two-byte buffer. 448The drain will be called for every byte added to the sbuf. 449The 450.Fn sbuf_bcopyin , 451.Fn sbuf_bcpy , 452.Fn sbuf_clear , 453.Fn sbuf_copyin , 454.Fn sbuf_cpy , 455.Fn sbuf_trim , 456.Fn sbuf_data , 457and 458.Fn sbuf_len 459functions cannot be used on an sbuf with a drain. 460.Pp 461The 462.Fn sbuf_copyin 463function copies a NUL-terminated string from the specified userland 464address into the 465.Fa sbuf . 466If the 467.Fa len 468argument is non-zero, no more than 469.Fa len 470characters (not counting the terminating NUL) are copied; otherwise 471the entire string, or as much of it as can fit in the 472.Fa sbuf , 473is copied. 474.Pp 475The 476.Fn sbuf_cpy 477function replaces the contents of the 478.Fa sbuf 479with those of the NUL-terminated string 480.Fa str . 481This is equivalent to calling 482.Fn sbuf_cat 483with a fresh 484.Fa sbuf 485or one which position has been reset to zero with 486.Fn sbuf_clear 487or 488.Fn sbuf_setpos . 489.Pp 490The 491.Fn sbuf_nl_terminate 492function appends a trailing newline character, if the current line is non-empty 493and not already terminated by a newline character. 494.Pp 495The 496.Fn sbuf_printf 497function formats its arguments according to the format string pointed 498to by 499.Fa fmt 500and appends the resulting string to the 501.Fa sbuf 502at the current position. 503.Pp 504The 505.Fn sbuf_vprintf 506function behaves the same as 507.Fn sbuf_printf 508except that the arguments are obtained from the variable-length argument list 509.Fa ap . 510.Pp 511The 512.Fn sbuf_putc 513function appends the character 514.Fa c 515to the 516.Fa sbuf 517at the current position. 518.Pp 519The 520.Fn sbuf_trim 521function removes trailing whitespace from the 522.Fa sbuf . 523.Pp 524The 525.Fn sbuf_error 526function returns any error value that the 527.Fa sbuf 528may have accumulated, either from the drain function, or 529.Er ENOMEM 530if the 531.Fa sbuf 532overflowed. 533This function is generally not needed and instead the error code from 534.Fn sbuf_finish 535is the preferred way to discover whether an sbuf had an error. 536.Pp 537The 538.Fn sbuf_finish 539function will call the attached drain function if one exists until all 540the data in the 541.Fa sbuf 542is flushed. 543If there is no attached drain, 544.Fn sbuf_finish 545NUL-terminates the 546.Fa sbuf . 547In either case it marks the 548.Fa sbuf 549as finished, which means that it may no longer be modified using 550.Fn sbuf_setpos , 551.Fn sbuf_cat , 552.Fn sbuf_cpy , 553.Fn sbuf_printf 554or 555.Fn sbuf_putc , 556until 557.Fn sbuf_clear 558is used to reset the sbuf. 559.Pp 560The 561.Fn sbuf_data 562function returns the actual string; 563.Fn sbuf_data 564only works on a finished 565.Fa sbuf . 566The 567.Fn sbuf_len 568function returns the length of the string. 569For an 570.Fa sbuf 571with an attached drain, 572.Fn sbuf_len 573returns the length of the un-drained data. 574.Fn sbuf_done 575returns non-zero if the 576.Fa sbuf 577is finished. 578.Pp 579The 580.Fn sbuf_start_section 581and 582.Fn sbuf_end_section 583functions may be used for automatic section alignment. 584The arguments 585.Fa pad 586and 587.Fa c 588specify the padding size and a character used for padding. 589The arguments 590.Fa old_lenp 591and 592.Fa old_len 593are to save and restore the current section length when nested sections 594are used. 595For the top level section 596.Dv NULL 597and \-1 can be specified for 598.Fa old_lenp 599and 600.Fa old_len 601respectively. 602.Pp 603The 604.Fn sbuf_hexdump 605function prints an array of bytes to the supplied sbuf, along with an ASCII 606representation of the bytes if possible. 607See the 608.Xr hexdump 3 609man page for more details on the interface. 610.Pp 611The 612.Fn sbuf_printf_drain 613function is a drain function that will call printf, or log to the console. 614The argument 615.Fa arg 616must be either 617.Dv NULL , 618or a valid pointer to a 619.Vt size_t . 620If 621.Fa arg 622is not 623.Dv NULL , 624the total bytes drained will be added to the value pointed to by 625.Fa arg . 626.Pp 627The 628.Fn sbuf_putbuf 629function printfs the sbuf to stdout if in userland, and to the console 630and log if in the kernel. 631The 632.Fa sbuf 633must be finished before calling 634.Fn sbuf_putbuf . 635It does not drain the buffer or update any pointers. 636.Sh NOTES 637If an operation caused an 638.Fa sbuf 639to overflow, most subsequent operations on it will fail until the 640.Fa sbuf 641is finished using 642.Fn sbuf_finish 643or reset using 644.Fn sbuf_clear , 645or its position is reset to a value between 0 and one less than the 646size of its storage buffer using 647.Fn sbuf_setpos , 648or it is reinitialized to a sufficiently short string using 649.Fn sbuf_cpy . 650.Pp 651Drains in user-space will not always function as indicated. 652While the drain function will be called immediately on overflow from 653the 654.Fa sbuf_putc , 655.Fa sbuf_bcat , 656.Fa sbuf_cat 657functions, 658.Fa sbuf_printf 659and 660.Fa sbuf_vprintf 661currently have no way to determine whether there will be an overflow 662until after it occurs, and cannot do a partial expansion of the format 663string. 664Thus when using libsbuf the buffer may be extended to allow completion 665of a single printf call, even though a drain is attached. 666.Sh RETURN VALUES 667The 668.Fn sbuf_new 669function returns 670.Dv NULL 671if it failed to allocate a storage buffer, and a pointer to the new 672.Fa sbuf 673otherwise. 674.Pp 675The 676.Fn sbuf_setpos 677function returns \-1 if 678.Fa pos 679was invalid, and zero otherwise. 680.Pp 681The 682.Fn sbuf_bcat , 683.Fn sbuf_cat , 684.Fn sbuf_cpy , 685.Fn sbuf_printf , 686.Fn sbuf_putc , 687and 688.Fn sbuf_trim 689functions 690all return \-1 if the buffer overflowed, and zero otherwise. 691.Pp 692The 693.Fn sbuf_error 694function returns a non-zero value if the buffer has an overflow or 695drain error, and zero otherwise. 696.Pp 697The 698.Fn sbuf_len 699function returns \-1 if the buffer overflowed. 700.Pp 701The 702.Fn sbuf_copyin 703function 704returns \-1 if copying string from userland failed, and number of bytes 705copied otherwise. 706.Pp 707The 708.Fn sbuf_end_section 709function returns the section length or \-1 if the buffer has an error. 710.Pp 711The 712.Fn sbuf_finish 9 713function (the kernel version) returns 714.Er ENOMEM 715if the sbuf overflowed before being finished, 716or returns the error code from the drain if one is attached. 717.Pp 718The 719.Fn sbuf_finish 3 720function (the userland version) 721will return zero for success and \-1 and set errno on error. 722.Sh EXAMPLES 723.Bd -literal -compact 724#include <sys/types.h> 725#include <sys/sbuf.h> 726 727struct sbuf *sb; 728 729sb = sbuf_new_auto(); 730sbuf_cat(sb, "Customers found:\en"); 731TAILQ_FOREACH(foo, &foolist, list) { 732 sbuf_printf(sb, " %4d %s\en", foo->index, foo->name); 733 sbuf_printf(sb, " Address: %s\en", foo->address); 734 sbuf_printf(sb, " Zip: %s\en", foo->zipcode); 735} 736if (sbuf_finish(sb) != 0) /* Check for any and all errors */ 737 err(1, "Could not generate message"); 738transmit_msg(sbuf_data(sb), sbuf_len(sb)); 739sbuf_delete(sb); 740.Ed 741.Sh SEE ALSO 742.Xr hexdump 3 , 743.Xr printf 3 , 744.Xr strcat 3 , 745.Xr strcpy 3 , 746.Xr copyin 9 , 747.Xr copyinstr 9 , 748.Xr printf 9 749.Sh HISTORY 750The 751.Nm 752family of functions first appeared in 753.Fx 4.4 . 754.Sh AUTHORS 755.An -nosplit 756The 757.Nm 758family of functions was designed by 759.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org 760and implemented by 761.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . 762Additional improvements were suggested by 763.An Justin T. Gibbs Aq Mt gibbs@FreeBSD.org . 764Auto-extend support added by 765.An Kelly Yancey Aq Mt kbyanc@FreeBSD.org . 766Drain functionality added by 767.An Matthew Fleming Aq Mt mdf@FreeBSD.org . 768.Pp 769This manual page was written by 770.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . 771