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: src/share/man/man9/sbuf.9,v 1.12.2.4 2002/09/23 04:51:53 kbyanc Exp $ 27.\" $DragonFly: src/share/man/man9/sbuf.9,v 1.5 2007/01/02 00:25:43 swildner Exp $ 28.\" 29.Dd January 28, 2001 30.Dt SBUF 9 31.Os 32.Sh NAME 33.Nm sbuf_new , 34.Nm sbuf_clear , 35.Nm sbuf_setpos , 36.Nm sbuf_bcat , 37.Nm sbuf_bcopyin , 38.Nm sbuf_bcpy , 39.Nm sbuf_cat , 40.Nm sbuf_copyin , 41.Nm sbuf_cpy , 42.Nm sbuf_printf , 43.Nm sbuf_vprintf , 44.Nm sbuf_putc , 45.Nm sbuf_trim , 46.Nm sbuf_overflowed , 47.Nm sbuf_finish , 48.Nm sbuf_data , 49.Nm sbuf_len , 50.Nm sbuf_delete 51.Nd safe string formatting 52.Sh SYNOPSIS 53.In sys/types.h 54.In sys/sbuf.h 55.Ft struct sbuf * 56.Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags" 57.Ft void 58.Fn sbuf_clear "struct sbuf *s" 59.Ft int 60.Fn sbuf_setpos "struct sbuf *s" "int pos" 61.Ft int 62.Fn sbuf_bcat "struct sbuf *s" "const char *str" "size_t len" 63.Ft int 64.Fn sbuf_bcopyin "struct sbuf *s" "const void *uaddr" "size_t len" 65.Ft int 66.Fn sbuf_bcpy "struct sbuf *s" "const char *str" "size_t len" 67.Ft int 68.Fn sbuf_cat "struct sbuf *s" "const char *str" 69.Ft int 70.Fn sbuf_copyin "struct sbuf *s" "const void *uaddr" "size_t len" 71.Ft int 72.Fn sbuf_cpy "struct sbuf *s" "const char *str" 73.Ft int 74.Fn sbuf_printf "struct sbuf *s" "const char *fmt" "..." 75.Ft int 76.Fn sbuf_vprintf "struct sbuf *s" "const char *fmt" "__va_list ap" 77.Ft int 78.Fn sbuf_putc "struct sbuf *s" "int c" 79.Ft int 80.Fn sbuf_trim "struct sbuf *s" 81.Ft int 82.Fn sbuf_overflowed "struct sbuf *s" 83.Ft void 84.Fn sbuf_finish "struct sbuf *s" 85.Ft char * 86.Fn sbuf_data "struct sbuf *s" 87.Ft int 88.Fn sbuf_len "struct sbuf *s" 89.Ft void 90.Fn sbuf_delete "struct sbuf *s" 91.Sh DESCRIPTION 92The 93.Nm sbuf 94family of functions allows one to safely allocate, construct and 95release bounded null-terminated strings in kernel space. 96Instead of arrays of characters, these functions operate on structures 97called 98.Fa sbufs , 99defined in 100.In sys/sbuf.h . 101.Pp 102The 103.Fn sbuf_new 104function initializes the 105.Fa sbuf 106pointed to by its first argument. 107If that pointer is 108.Dv NULL , 109.Fn sbuf_new 110allocates a 111.Vt struct sbuf 112using 113.Xr kmalloc 9 . 114The 115.Fa buf 116argument is a pointer to a buffer in which to store the actual string; 117if it is 118.Dv NULL , 119.Fn sbuf_new 120will allocate one using 121.Xr kmalloc 9 . 122The 123.Fa length 124is the initial size of the storage buffer. 125The fourth argument, 126.Fa flags , 127may be comprised of the following flags: 128.Bl -tag -width ".Dv SBUF_AUTOEXTEND" 129.It Dv SBUF_FIXEDLEN 130The storage buffer is fixed at its initial size. 131Attempting to extend the sbuf beyond this size results in an overflow condition. 132.It Dv SBUF_AUTOEXTEND 133This indicates that the storage buffer may be extended as necessary, so long 134as resources allow, to hold additional data. 135.El 136.Pp 137Note that if 138.Fa buf 139is not 140.Dv NULL , 141it must point to an array of at least 142.Fa length 143characters. 144The contents of the provided buffer are undefined; to retrieve the sbuf data 145.Fn sbuf_data 146must be called on the finished 147.Fa sbuf . 148.Pp 149The 150.Fn sbuf_clear 151function invalidates the contents of the 152.Fa sbuf 153and resets its position to zero. 154.Pp 155The 156.Fn sbuf_setpos 157function sets the 158.Fa sbuf Ns 's 159end position to 160.Fa pos , 161which is a value between zero and one less than the size of the 162storage buffer. 163This effectively truncates the sbuf at the new position. 164.Pp 165The 166.Fn sbuf_bcat 167function appends the first 168.Fa len 169bytes from the byte string 170.Fa str 171to the 172.Fa sbuf . 173.Pp 174The 175.Fn sbuf_bcopyin 176function copies 177.Fa len 178bytes from the specified userland address into the 179.Fa sbuf . 180.Pp 181The 182.Fn sbuf_bcpy 183function replaces the contents of the 184.Fa sbuf 185with the first 186.Fa len 187bytes from the byte string 188.Fa str . 189.Pp 190The 191.Fn sbuf_cat 192function appends the NUL-terminated string 193.Fa str 194to the 195.Fa sbuf 196at the current position. 197.Pp 198The 199.Fn sbuf_copyin 200function copies a NUL-terminated string from the specified userland 201address into the 202.Fa sbuf . 203If the 204.Fa len 205argument is non-zero, no more than 206.Fa len 207characters (not counting the terminating NUL) are copied; otherwise 208the entire string, or as much of it as can fit in the 209.Fa sbuf , 210is copied. 211.Pp 212The 213.Fn sbuf_cpy 214function replaces the contents of the 215.Fa sbuf 216with those of the NUL-terminated string 217.Fa str . 218This is equivalent to calling 219.Fn sbuf_cat 220with a fresh 221.Fa sbuf 222or one which position has been reset to zero with 223.Fn sbuf_clear 224or 225.Fn sbuf_setpos . 226.Pp 227The 228.Fn sbuf_printf 229function formats its arguments according to the format string pointed 230to by 231.Fa fmt 232and appends the resulting string to the 233.Fa sbuf 234at the current position. 235.Pp 236The 237.Fn sbuf_vprintf 238function behaves the same as 239.Fn sbuf_printf 240except that the arguments are obtained from the variable-length argument list 241.Fa ap . 242.Pp 243The 244.Fn sbuf_putc 245function appends the character 246.Fa c 247to the 248.Fa sbuf 249at the current position. 250.Pp 251The 252.Fn sbuf_trim 253function removes trailing whitespace from the 254.Fa sbuf . 255.Pp 256The 257.Fn sbuf_overflowed 258function returns a non-zero value if the 259.Fa sbuf 260overflowed. 261.Pp 262The 263.Fn sbuf_finish 264function null-terminates the 265.Fa sbuf 266and marks it as finished, which means that it may no longer be 267modified using 268.Fn sbuf_setpos , 269.Fn sbuf_cat , 270.Fn sbuf_cpy , 271.Fn sbuf_printf 272or 273.Fn sbuf_putc . 274.Pp 275The 276.Fn sbuf_data 277and 278.Fn sbuf_len 279functions return the actual string and its length, respectively; 280.Fn sbuf_data 281only works on a finished 282.Fa sbuf . 283.Pp 284Finally, the 285.Fn sbuf_delete 286function clears the 287.Fa sbuf 288and frees its storage buffer if it was allocated by 289.Fn sbuf_new . 290.Sh NOTES 291If an operation caused an 292.Fa sbuf 293to overflow, most subsequent operations on it will fail until the 294.Fa sbuf 295is finished using 296.Fn sbuf_finish 297or reset using 298.Fn sbuf_clear , 299or its position is reset to a value between 0 and one less than the 300size of its storage buffer using 301.Fn sbuf_setpos , 302or it is reinitialized to a sufficiently short string using 303.Fn sbuf_cpy . 304.Sh RETURN VALUES 305.Fn sbuf_new 306returns 307.Dv NULL 308if it failed to allocate a storage buffer, and a pointer to the new 309.Fa sbuf 310otherwise. 311.Pp 312.Fn sbuf_setpos 313returns \-1 if 314.Fa pos 315was invalid, and zero otherwise. 316.Pp 317.Fn sbuf_cat , 318.Fn sbuf_cpy , 319.Fn sbuf_printf , 320.Fn sbuf_putc , 321and 322.Fn sbuf_trim 323all return \-1 if the buffer overflowed, and zero otherwise. 324.Pp 325.Fn sbuf_overflowed 326returns a non-zero value if the buffer overflowed, and zero otherwise. 327.Pp 328.Fn sbuf_data 329and 330.Fn sbuf_len 331return 332.Dv NULL 333and \-1, respectively, if the buffer overflowed. 334.Sh SEE ALSO 335.Xr printf 3 , 336.Xr strcat 3 , 337.Xr strcpy 3 , 338.Xr copyin 9 , 339.Xr copyinstr 9 , 340.Xr kprintf 9 341.Sh HISTORY 342The 343.Nm sbuf 344family of functions first appeared in 345.Fx 4.4 . 346.Sh AUTHORS 347.An -nosplit 348The 349.Nm sbuf 350family of functions was designed by 351.An Poul-Henning Kamp Aq phk@FreeBSD.org 352and implemented by 353.An Dag-Erling Co\(:idan Sm\(/orgrav Aq des@FreeBSD.org . 354Additional improvements were suggested by 355.An Justin T. Gibbs Aq gibbs@FreeBSD.org . 356Auto-extend support added by 357.An Kelly Yancey Aq kbyanc@FreeBSD.org . 358.Pp 359This manual page was written by 360.An Dag-Erling Co\(:idan Sm\(/orgrav . 361