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