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