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 January 25, 2011
  29 .Dt SBUF 9
  30 .Os
  31 .Sh NAME
  32 .Nm sbuf ,
  33 .Nm sbuf_new ,
  34 .Nm sbuf_new_auto ,
  35 .Nm sbuf_new_for_sysctl ,
  36 .Nm sbuf_clear ,
  37 .Nm sbuf_setpos ,
  38 .Nm sbuf_bcat ,
  39 .Nm sbuf_bcopyin ,
  40 .Nm sbuf_bcpy ,
  41 .Nm sbuf_cat ,
  42 .Nm sbuf_copyin ,
  43 .Nm sbuf_cpy ,
  44 .Nm sbuf_printf ,
  45 .Nm sbuf_vprintf ,
  46 .Nm sbuf_putc ,
  47 .Nm sbuf_set_drain ,
  48 .Nm sbuf_trim ,
  49 .Nm sbuf_error ,
  50 .Nm sbuf_finish ,
  51 .Nm sbuf_data ,
  52 .Nm sbuf_len ,
  53 .Nm sbuf_done ,
  54 .Nm sbuf_delete
  55 .Nd safe string composition
  56 .Sh SYNOPSIS
  57 .In sys/types.h
  58 .In sys/sbuf.h
  59 .Ft typedef\ int ( sbuf_drain_func ) ( void\ *arg, const\ char\ *data, int\ len ) ;
  60 .Pp
  61 .Ft struct sbuf *
  62 .Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags"
  63 .Ft struct sbuf *
  64 .Fn sbuf_new_auto
  65 .Ft void
  66 .Fn sbuf_clear "struct sbuf *s"
  67 .Ft int
  68 .Fn sbuf_setpos "struct sbuf *s" "int pos"
  69 .Ft int
  70 .Fn sbuf_bcat "struct sbuf *s" "const void *buf" "size_t len"
  71 .Ft int
  72 .Fn sbuf_bcopyin "struct sbuf *s" "const void *uaddr" "size_t len"
  73 .Ft int
  74 .Fn sbuf_bcpy "struct sbuf *s" "const void *buf" "size_t len"
  75 .Ft int
  76 .Fn sbuf_cat "struct sbuf *s" "const char *str"
  77 .Ft int
  78 .Fn sbuf_copyin "struct sbuf *s" "const void *uaddr" "size_t len"
  79 .Ft int
  80 .Fn sbuf_cpy "struct sbuf *s" "const char *str"
  81 .Ft int
  82 .Fn sbuf_printf "struct sbuf *s" "const char *fmt" "..."
  83 .Ft int
  84 .Fn sbuf_vprintf "struct sbuf *s" "const char *fmt" "va_list ap"
  85 .Ft int
  86 .Fn sbuf_putc "struct sbuf *s" "int c"
  87 .Ft void
  88 .Fn sbuf_set_drain "struct sbuf *s" "sbuf_drain_func *func" "void *arg"
  89 .Ft int
  90 .Fn sbuf_trim "struct sbuf *s"
  91 .Ft int
  92 .Fn sbuf_error "struct sbuf *s"
  93 .Ft int
  94 .Fn sbuf_finish "struct sbuf *s"
  95 .Ft char *
  96 .Fn sbuf_data "struct sbuf *s"
  97 .Ft int
  98 .Fn sbuf_len "struct sbuf *s"
  99 .Ft int
 100 .Fn sbuf_done "struct sbuf *s"
 101 .Ft void
 102 .Fn sbuf_delete "struct sbuf *s"
 103 .In sys/sysctl.h
 104 .Ft struct sbuf *
 105 .Fn sbuf_new_for_sysctl "struct sbuf *s" "char *buf" "int length" "struct sysctl_req *req"
 106 .Sh DESCRIPTION
 107 The
 108 .Nm
 109 family of functions allows one to safely allocate, compose and
 110 release strings in kernel or user space.
 111 .Pp
 112 Instead of arrays of characters, these functions operate on structures
 113 called
 114 .Fa sbufs ,
 115 defined in
 116 .In sys/sbuf.h .
 117 .Pp
 118 Any errors encountered during the allocation or composition of the
 119 string will be latched in the data structure,
 120 making a single error test at the end of the composition
 121 sufficient to determine success or failure of the entire process.
 122 .Pp
 123 The
 124 .Fn sbuf_new
 125 function initializes the
 126 .Fa sbuf
 127 pointed to by its first argument.
 128 If that pointer is
 129 .Dv NULL ,
 130 .Fn sbuf_new
 131 allocates a
 132 .Vt struct sbuf
 133 using
 134 .Xr malloc 9 .
 135 The
 136 .Fa buf
 137 argument is a pointer to a buffer in which to store the actual string;
 138 if it is
 139 .Dv NULL ,
 140 .Fn sbuf_new
 141 will allocate one using
 142 .Xr malloc 9 .
 143 The
 144 .Fa length
 145 is the initial size of the storage buffer.
 146 The fourth argument,
 147 .Fa flags ,
 148 may be comprised of the following flags:
 149 .Bl -tag -width ".Dv SBUF_AUTOEXTEND"
 150 .It Dv SBUF_FIXEDLEN
 151 The storage buffer is fixed at its initial size.
 152 Attempting to extend the sbuf beyond this size results in an overflow condition.
 153 .It Dv SBUF_AUTOEXTEND
 154 This indicates that the storage buffer may be extended as necessary, so long
 155 as resources allow, to hold additional data.
 156 .El
 157 .Pp
 158 Note that if
 159 .Fa buf
 160 is not
 161 .Dv NULL ,
 162 it must point to an array of at least
 163 .Fa length
 164 characters.
 165 The result of accessing that array directly while it is in use by the
 166 sbuf is undefined.
 167 .Pp
 168 The
 169 .Fn sbuf_new_auto
 170 function is a shortcut for creating a completely dynamic
 171 .Nm .
 172 It is the equivalent of calling
 173 .Fn sbuf_new
 174 with values
 175 .Dv NULL ,
 176 .Dv NULL ,
 177 .Dv 0 ,
 178 and
 179 .Dv SBUF_AUTOEXTEND .
 180 .Pp
 181 The
 182 .Fn sbuf_new_for_sysctl
 183 function will set up an sbuf with a drain function to use
 184 .Fn SYSCTL_OUT
 185 when the internal buffer fills.
 186 Note that if the various functions which append to an sbuf are used while
 187 a non-sleepable lock is held, the user buffer should be wired using
 188 .Fn sysctl_wire_old_buffer .
 189 .Pp
 190 The
 191 .Fn sbuf_delete
 192 function clears the
 193 .Fa sbuf
 194 and frees any memory allocated for it.
 195 There must be a call to
 196 .Fn sbuf_delete
 197 for every call to
 198 .Fn sbuf_new .
 199 Any attempt to access the sbuf after it has been deleted will fail.
 200 .Pp
 201 The
 202 .Fn sbuf_clear
 203 function invalidates the contents of the
 204 .Fa sbuf
 205 and resets its position to zero.
 206 .Pp
 207 The
 208 .Fn sbuf_setpos
 209 function sets the
 210 .Fa sbuf Ns 's
 211 end position to
 212 .Fa pos ,
 213 which is a value between zero and one less than the size of the
 214 storage buffer.
 215 This effectively truncates the sbuf at the new position.
 216 .Pp
 217 The
 218 .Fn sbuf_bcat
 219 function appends the first
 220 .Fa len
 221 bytes from the buffer
 222 .Fa buf
 223 to the
 224 .Fa sbuf .
 225 .Pp
 226 The
 227 .Fn sbuf_bcopyin
 228 function copies
 229 .Fa len
 230 bytes from the specified userland address into the
 231 .Fa sbuf .
 232 .Pp
 233 The
 234 .Fn sbuf_bcpy
 235 function replaces the contents of the
 236 .Fa sbuf
 237 with the first
 238 .Fa len
 239 bytes from the buffer
 240 .Fa buf .
 241 .Pp
 242 The
 243 .Fn sbuf_cat
 244 function appends the NUL-terminated string
 245 .Fa str
 246 to the
 247 .Fa sbuf
 248 at the current position.
 249 .Pp
 250 The
 251 .Fn sbuf_set_drain
 252 function sets a drain function
 253 .Fa func
 254 for the
 255 .Fa sbuf ,
 256 and records a pointer
 257 .Fa arg
 258 to be passed to the drain on callback.
 259 The drain function cannot be changed while
 260 .Fa sbuf_len
 261 is non-zero.
 262 .Pp
 263 The registered drain function
 264 .Vt sbuf_drain_func
 265 will be called with the argument
 266 .Fa arg
 267 provided to
 268 .Fn sbuf_set_drain ,
 269 a pointer
 270 .Fa data
 271 to a byte string that is the contents of the sbuf, and the length
 272 .Fa len
 273 of the data.
 274 If the drain function exists, it will be called when the sbuf internal
 275 buffer is full, or on behalf of
 276 .Fn sbuf_finish .
 277 The drain function may drain some or all of the data, but must drain
 278 at least 1 byte.
 279 The return value from the drain function, if positive, indicates how
 280 many bytes were drained.
 281 If negative, the return value indicates the negative error code which
 282 will be returned from this or a later call to
 283 .Fn sbuf_finish .
 284 The returned drained length cannot be zero.
 285 To do unbuffered draining, initialize the sbuf with a two-byte buffer.
 286 The drain will be called for every byte added to the sbuf.
 287 The
 288 .Fn sbuf_bcopyin ,
 289 .Fn sbuf_copyin ,
 290 .Fn sbuf_trim ,
 291 and
 292 .Fn sbuf_data
 293 functions cannot be used on an sbuf with a drain.
 294 .Pp
 295 The
 296 .Fn sbuf_copyin
 297 function copies a NUL-terminated string from the specified userland
 298 address into the
 299 .Fa sbuf .
 300 If the
 301 .Fa len
 302 argument is non-zero, no more than
 303 .Fa len
 304 characters (not counting the terminating NUL) are copied; otherwise
 305 the entire string, or as much of it as can fit in the
 306 .Fa sbuf ,
 307 is copied.
 308 .Pp
 309 The
 310 .Fn sbuf_cpy
 311 function replaces the contents of the
 312 .Fa sbuf
 313 with those of the NUL-terminated string
 314 .Fa str .
 315 This is equivalent to calling
 316 .Fn sbuf_cat
 317 with a fresh
 318 .Fa sbuf
 319 or one which position has been reset to zero with
 320 .Fn sbuf_clear
 321 or
 322 .Fn sbuf_setpos .
 323 .Pp
 324 The
 325 .Fn sbuf_printf
 326 function formats its arguments according to the format string pointed
 327 to by
 328 .Fa fmt
 329 and appends the resulting string to the
 330 .Fa sbuf
 331 at the current position.
 332 .Pp
 333 The
 334 .Fn sbuf_vprintf
 335 function behaves the same as
 336 .Fn sbuf_printf
 337 except that the arguments are obtained from the variable-length argument list
 338 .Fa ap .
 339 .Pp
 340 The
 341 .Fn sbuf_putc
 342 function appends the character
 343 .Fa c
 344 to the
 345 .Fa sbuf
 346 at the current position.
 347 .Pp
 348 The
 349 .Fn sbuf_trim
 350 function removes trailing whitespace from the
 351 .Fa sbuf .
 352 .Pp
 353 The
 354 .Fn sbuf_error
 355 function returns any error value that the
 356 .Fa sbuf
 357 may have accumulated, either from the drain function, or ENOMEM if the
 358 .Fa sbuf
 359 overflowed.
 360 This function is generally not needed and instead the error code from
 361 .Fn sbuf_finish
 362 is the preferred way to discover whether an sbuf had an error.
 363 .Pp
 364 The
 365 .Fn sbuf_finish
 366 function will call the attached drain function if one exists until all
 367 the data in the
 368 .Fa sbuf
 369 is flushed.
 370 If there is no attached drain,
 371 .Fn sbuf_finish
 372 NUL-terminates the
 373 .Fa sbuf .
 374 In either case it marks the
 375 .Fa sbuf
 376 as finished, which means that it may no longer be modified using
 377 .Fn sbuf_setpos ,
 378 .Fn sbuf_cat ,
 379 .Fn sbuf_cpy ,
 380 .Fn sbuf_printf
 381 or
 382 .Fn sbuf_putc ,
 383 until
 384 .Fn sbuf_clear
 385 is used to reset the sbuf.
 386 .Pp
 387 The
 388 .Fn sbuf_data
 389 function returns the actual string;
 390 .Fn sbuf_data
 391 only works on a finished
 392 .Fa sbuf .
 393 The
 394 .Fn sbuf_len function returns the length of the string.
 395 For an
 396 .Fa sbuf
 397 with an attached drain,
 398 .Fn sbuf_len
 399 returns the length of the un-drained data.
 400 .Fn sbuf_done
 401 returns non-zero if the
 402 .Fa sbuf
 403 is finished.
 404 .Sh NOTES
 405 If an operation caused an
 406 .Fa sbuf
 407 to overflow, most subsequent operations on it will fail until the
 408 .Fa sbuf
 409 is finished using
 410 .Fn sbuf_finish
 411 or reset using
 412 .Fn sbuf_clear ,
 413 or its position is reset to a value between 0 and one less than the
 414 size of its storage buffer using
 415 .Fn sbuf_setpos ,
 416 or it is reinitialized to a sufficiently short string using
 417 .Fn sbuf_cpy .
 418 .Pp
 419 Drains in user-space will not always function as indicated.
 420 While the drain function will be called immediately on overflow from
 421 the
 422 .Fa sbuf_putc ,
 423 .Fa sbuf_bcat ,
 424 .Fa sbuf_cat
 425 functions,
 426 .Fa sbuf_printf
 427 and
 428 .Fa sbuf_vprintf
 429 currently have no way to determine whether there will be an overflow
 430 until after it occurs, and cannot do a partial expansion of the format
 431 string.
 432 Thus when using libsbuf the buffer may be extended to allow completion
 433 of a single printf call, even though a drain is attached.
 434 .Sh RETURN VALUES
 435 The
 436 .Fn sbuf_new
 437 function returns
 438 .Dv NULL
 439 if it failed to allocate a storage buffer, and a pointer to the new
 440 .Fa sbuf
 441 otherwise.
 442 .Pp
 443 The
 444 .Fn sbuf_setpos
 445 function returns \-1 if
 446 .Fa pos
 447 was invalid, and zero otherwise.
 448 .Pp
 449 The
 450 .Fn sbuf_cat ,
 451 .Fn sbuf_cpy ,
 452 .Fn sbuf_printf ,
 453 .Fn sbuf_putc ,
 454 and
 455 .Fn sbuf_trim
 456 functions
 457 all return \-1 if the buffer overflowed, and zero otherwise.
 458 .Pp
 459 The
 460 .Fn sbuf_error
 461 function returns a non-zero value if the buffer has an overflow or
 462 drain error, and zero otherwise.
 463 .Pp
 464 The
 465 .Fn sbuf_data
 466 and
 467 .Fn sbuf_len
 468 functions return
 469 .Dv NULL
 470 and \-1, respectively, if the buffer overflowed.
 471 .Pp
 472 The
 473 .Fn sbuf_copyin
 474 function
 475 returns \-1 if copying string from userland failed, and number of bytes
 476 copied otherwise.
 477 .Pp
 478 The
 479 .Fn sbuf_finish 9
 480 function (the kernel version) returns ENOMEM if the sbuf overflowed before
 481 being finished,
 482 or returns the error code from the drain if one is attached.
 483 .Pp
 484 The
 485 .Fn sbuf_finish 3
 486 function (the userland version)
 487 will return zero for success and \-1 and set errno on error.
 488 .Sh EXAMPLES
 489 .Bd -literal -compact
 490 #include <sys/sbuf.h>
 491
 492 struct sbuf *sb;
 493
 494 sb = sbuf_new_auto();
 495 sbuf_cat(sb, "Customers found:\en");
 496 TAILQ_FOREACH(foo, &foolist, list) {
 497         sbuf_printf(sb, "   %4d %s\en", foo->index, foo->name);
 498         sbuf_printf(sb, "      Address: %s\en", foo->address);
 499         sbuf_printf(sb, "      Zip: %s\en", foo->zipcode);
 500 }
 501 if (sbuf_finish(sb)) /* Check for any and all errors */
 502         err(1,"Could not generate message");
 503 transmit_msg(sbuf_data(sb), sbuf_len(sb));
 504 sbuf_delete(sb);
 505 .Ed
 506 .Sh SEE ALSO
 507 .Xr printf 3 ,
 508 .Xr strcat 3 ,
 509 .Xr strcpy 3 ,
 510 .Xr copyin 9 ,
 511 .Xr copyinstr 9 ,
 512 .Xr printf 9
 513 .Sh HISTORY
 514 The
 515 .Nm
 516 family of functions first appeared in
 517 .Fx 4.4 .
 518 .Sh AUTHORS
 519 .An -nosplit
 520 The
 521 .Nm
 522 family of functions was designed by
 523 .An Poul-Henning Kamp Aq phk@FreeBSD.org
 524 and implemented by
 525 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
 526 Additional improvements were suggested by
 527 .An Justin T. Gibbs Aq gibbs@FreeBSD.org .
 528 Auto-extend support added by
 529 .An Kelly Yancey Aq kbyanc@FreeBSD.org .
 530 Drain functionality added by
 531 .An Matthew Fleming Aq mdf@FreeBSD.org .
 532 .Pp
 533 This manual page was written by
 534 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .