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