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.\" 28.Dd March 16, 2012 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 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 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 kmalloc 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 kmalloc 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 contents of the provided buffer are undefined; to retrieve the sbuf data 147.Fn sbuf_data 148must be called on the finished 149.Fa sbuf . 150.Pp 151The 152.Fn sbuf_clear 153function invalidates the contents of the 154.Fa sbuf 155and resets its position to zero. 156.Pp 157The 158.Fn sbuf_setpos 159function sets the 160.Fa sbuf Ns 's 161end position to 162.Fa pos , 163which is a value between zero and one less than the size of the 164storage buffer. 165This effectively truncates the sbuf at the new position. 166.Pp 167The 168.Fn sbuf_bcat 169function appends the first 170.Fa len 171bytes from the byte string 172.Fa str 173to the 174.Fa sbuf . 175.Pp 176The 177.Fn sbuf_bcopyin 178function copies 179.Fa len 180bytes from the specified userland address into the 181.Fa sbuf . 182.Pp 183The 184.Fn sbuf_bcpy 185function replaces the contents of the 186.Fa sbuf 187with the first 188.Fa len 189bytes from the byte string 190.Fa str . 191.Pp 192The 193.Fn sbuf_cat 194function appends the NUL-terminated string 195.Fa str 196to the 197.Fa sbuf 198at the current position. 199.Pp 200The 201.Fn sbuf_copyin 202function copies a NUL-terminated string from the specified userland 203address into the 204.Fa sbuf . 205If the 206.Fa len 207argument is non-zero, no more than 208.Fa len 209characters (not counting the terminating NUL) are copied; otherwise 210the entire string, or as much of it as can fit in the 211.Fa sbuf , 212is copied. 213.Pp 214The 215.Fn sbuf_cpy 216function replaces the contents of the 217.Fa sbuf 218with those of the NUL-terminated string 219.Fa str . 220This is equivalent to calling 221.Fn sbuf_cat 222with a fresh 223.Fa sbuf 224or one which position has been reset to zero with 225.Fn sbuf_clear 226or 227.Fn sbuf_setpos . 228.Pp 229The 230.Fn sbuf_printf 231function formats its arguments according to the format string pointed 232to by 233.Fa fmt 234and appends the resulting string to the 235.Fa sbuf 236at the current position. 237.Pp 238The 239.Fn sbuf_vprintf 240function behaves the same as 241.Fn sbuf_printf 242except that the arguments are obtained from the variable-length argument list 243.Fa ap . 244.Pp 245The 246.Fn sbuf_putc 247function appends the character 248.Fa c 249to the 250.Fa sbuf 251at the current position. 252.Pp 253The 254.Fn sbuf_trim 255function removes trailing whitespace from the 256.Fa sbuf . 257.Pp 258The 259.Fn sbuf_overflowed 260function returns a non-zero value if the 261.Fa sbuf 262overflowed. 263.Pp 264The 265.Fn sbuf_finish 266function null-terminates the 267.Fa sbuf 268and marks it as finished, which means that it may no longer be 269modified using 270.Fn sbuf_setpos , 271.Fn sbuf_cat , 272.Fn sbuf_cpy , 273.Fn sbuf_printf 274or 275.Fn sbuf_putc . 276.Pp 277The 278.Fn sbuf_data 279and 280.Fn sbuf_len 281functions return the actual string and its length, respectively; 282.Fn sbuf_data 283only works on a finished 284.Fa sbuf . 285.Fn sbuf_done 286returns non-zero if the 287.Fa sbuf 288is finished. 289.Pp 290Finally, the 291.Fn sbuf_delete 292function clears the 293.Fa sbuf 294and frees its storage buffer if it was allocated by 295.Fn sbuf_new . 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 kprintf 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 Mt phk@FreeBSD.org 358and implemented by 359.An Dag-Erling Co\(:idan Sm\(/orgrav Aq Mt des@FreeBSD.org . 360Additional improvements were suggested by 361.An Justin T. Gibbs Aq Mt gibbs@FreeBSD.org . 362Auto-extend support added by 363.An Kelly Yancey Aq Mt kbyanc@FreeBSD.org . 364.Pp 365This manual page was written by 366.An Dag-Erling Co\(:idan Sm\(/orgrav . 367