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