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