share/man/man9/sbuf.9

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