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 January 28, 2001 29.Dt SBUF 9 30.Os FreeBSD 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_putc , 43.Nm sbuf_overflowed , 44.Nm sbuf_finish , 45.Nm sbuf_data , 46.Nm sbuf_len , 47.Nm sbuf_delete 48.Nd safe string formatting 49.Sh SYNOPSIS 50.Fd #include <sys/types.h> 51.Fd #include <sys/sbuf.h> 52.Ft struct sbuf *s 53.Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags" 54.Ft void 55.Fn sbuf_clear "struct sbuf *s" 56.Ft int 57.Fn sbuf_setpos "struct sbuf *s" "int pos" 58.Ft int 59.Fn sbuf_bcat "struct sbuf *s" "const char *str" "size_t len" 60.Ft int 61.Fn sbuf_bcopyin "struct sbuf *s" "const void *uaddr" "size_t len" 62.Ft int 63.Fn sbuf_bcpy "struct sbuf *s" "const char *str" "size_t len" 64.Ft int 65.Fn sbuf_cat "struct sbuf *s" "const char *str" 66.Ft int 67.Fn sbuf_copyin "struct sbuf *s" "const void *uaddr" "size_t len" 68.Ft int 69.Fn sbuf_cpy "struct sbuf *s" "const char *str" 70.Ft int 71.Fn sbuf_printf "struct sbuf *s" "char *fmt" "..." 72.Ft int 73.Fn sbuf_putc "struct sbuf *s" "int c" 74.Ft int 75.Fn sbuf_overflowed "struct sbuf *s" 76.Ft void 77.Fn sbuf_finish "struct sbuf *s" 78.Ft char * 79.Fn sbuf_data "struct sbuf *s" 80.Ft int 81.Fn sbuf_len "struct sbuf *s" 82.Ft void 83.Fn sbuf_delete "struct sbuf *s" 84.Sh DESCRIPTION 85The 86.Nm sbuf 87family of functions allows one to safely allocate, construct and 88release bounded null-terminated strings in kernel space. 89Instead of arrays of characters, these functions operate on structures 90called 91.Fa sbufs , 92defined in 93.Aq Pa sys/sbuf.h . 94.Pp 95The 96.Fn sbuf_new 97function initializes the 98.Fa sbuf 99pointed to by its first argument. 100If that pointer is 101.Dv NULL , 102.Fn sbuf_new 103allocates a 104.Fa struct sbuf 105using 106.Xr malloc 9 . 107The 108.Fa buf 109argument is a pointer to a buffer in which to store the actual string; 110if it is 111.Dv NULL , 112.Fn sbuf_new 113will allocate one using 114.Xr malloc 9 . 115The 116.Fa length 117is the intended size of the storage buffer. 118The fourth argument, 119.Fa flags , 120is currently unused and should always be set to zero. 121.Pp 122Note that if 123.Fa buf 124is not 125.Dv NULL , 126it must point to an array of at least 127.Fa length 128characters. 129.Pp 130The 131.Fn sbuf_clear 132function invalidates the contents of the 133.Fa sbuf 134and resets its position to zero. 135.Pp 136The 137.Fn sbuf_setpos 138function sets the 139.Fa sbuf Ns 's 140current position to 141.Fa pos , 142which is a value between zero and one less than the size of the 143storage buffer. 144.Pp 145The 146.Fn sbuf_bcat 147function appends the first 148.Fa len 149bytes from the byte string 150.Fa str 151to the 152.Fa sbuf . 153.Pp 154The 155.Fn sbuf_bcopyin 156function copies 157.Fa len 158bytes from the specified userland address into the 159.Fa sbuf . 160.Pp 161The 162.Fn sbuf_bcpy 163function replaces the contents of the 164.Fa sbuf 165with the first 166.Fa len 167bytes from the byte string 168.Fa str . 169.Pp 170The 171.Fn sbuf_cat 172function appends the NUL-terminated string 173.Fa str 174to the 175.Fa sbuf 176at the current position. 177.Pp 178The 179.Fn sbuf_copyin 180function copies a NUL-terminated string from the specified userland 181address into the 182.Fa sbuf . 183If the 184.Fa len 185argument is non-zero, no more than 186.Fa len 187characters (not counting the terminating NUL) are copied; otherwise 188the entire string, or as much of it as can fit in the 189.Fa sbuf , 190is copied. 191.Pp 192The 193.Fn sbuf_cpy 194function replaces the contents of the 195.Fa sbuf 196with those of the NUL-terminated string 197.Fa str . 198This is equivalent to calling 199.Fn sbuf_cat 200with a fresh 201.Fa sbuf 202or one which position has been reset to zero with 203.Fn sbuf_clear 204or 205.Fn sbuf_setpos . 206.Pp 207The 208.Fn sbuf_printf 209function formats its arguments according to the format string pointed 210to by 211.Fa fmt 212and appends the resulting string to the 213.Fa sbuf 214at the current position. 215.Pp 216The 217.Fn sbuf_putc 218function appends the character 219.Fa c 220to the 221.Fa sbuf 222at the current position. 223.Pp 224The 225.Fn sbuf_overflowed 226function returns a non-zero value if the 227.Fa sbuf 228overflowed. 229.Pp 230The 231.Fn sbuf_finish 232function null-terminates the 233.Fa sbuf 234and marks it as finished, which means that it may no longer be 235modified using 236.Fn sbuf_setpos , 237.Fn sbuf_cat , 238.Fn sbuf_cpy , 239.Fn sbuf_printf 240or 241.Fn sbuf_putc . 242.Pp 243The 244.Fn sbuf_data 245and 246.Fn sbuf_len 247functions return the actual string and its length, respectively; 248.Fn sbuf_data 249only works on a finished 250.Fa sbuf . 251.Pp 252Finally, the 253.Fn sbuf_delete 254function clears the 255.Fa sbuf 256and frees its storage buffer if it was allocated by 257.Fn sbuf_new . 258.Sh NOTES 259If an operation caused an 260.Fa sbuf 261to overflow, most subsequent operations on it will fail until the 262.Fa sbuf 263is finished using 264.Fn sbuf_finish 265or reset using 266.Fn sbuf_clear , 267or its position is reset to a value between 0 and one less than the 268size of its storage buffer using 269.Fn sbuf_setpos , 270or it is reinitialized to a sufficiently short string using 271.Fn sbuf_cpy . 272.Sh RETURN VALUES 273.Fn sbuf_new 274returns 275.Dv NULL 276if it failed to allocate a storage buffer, and a pointer to the new 277.Fa sbuf 278otherwise. 279.Pp 280.Fn sbuf_setpos 281returns \-1 if 282.Fa pos 283was invalid, and zero otherwise. 284.Pp 285.Fn sbuf_cat , 286.Fn sbuf_cpy , 287.Fn sbuf_printf , 288and 289.Fn sbuf_putc 290all return \-1 if the buffer overflowed, and zero otherwise. 291.Pp 292.Fn sbuf_overflowed 293returns a non-zero value if the buffer overflowed, and zero otherwise. 294.Pp 295.Fn sbuf_data 296and 297.Fn sbuf_len 298return 299.Dv NULL 300and \-1, respectively, if the buffer overflowed. 301.Sh SEE ALSO 302.Xr copyin 9 , 303.Xr copyinstr 9 , 304.Xr printf 3 , 305.Xr strcat 3 , 306.Xr strcpy 3 307.Sh HISTORY 308The 309.Nm sbuf 310family of functions first appeared in 311.Fx 5.0 . 312.Sh AUTHORS 313.An -nosplit 314The 315.Nm sbuf 316family of functions was designed by 317.An Poul-Henning Kamp Aq phk@FreeBSD.org 318and implemented by 319.An Dag-Erling Co\(:idan Sm\(/orgrav Aq des@FreeBSD.org . 320Additional improvements were suggested by 321.An Justin T. Gibbs Aq gibbs@FreeBSD.org . 322.Pp 323This manual page was written by 324.An Dag-Erling Co\(:idan Sm\(/orgrav . 325