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