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: src/share/man/man9/sbuf.9,v 1.12.2.4 2002/09/23 04:51:53 kbyanc Exp $
  27 .\"
  28 .Dd March 16, 2012
  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 char *str" "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 char *str" "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 kmalloc 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 kmalloc 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 contents of the provided buffer are undefined; to retrieve the sbuf data
 147 .Fn sbuf_data
 148 must be called on the finished
 149 .Fa sbuf .
 150 .Pp
 151 The
 152 .Fn sbuf_clear
 153 function invalidates the contents of the
 154 .Fa sbuf
 155 and resets its position to zero.
 156 .Pp
 157 The
 158 .Fn sbuf_setpos
 159 function sets the
 160 .Fa sbuf Ns 's
 161 end position to
 162 .Fa pos ,
 163 which is a value between zero and one less than the size of the
 164 storage buffer.
 165 This effectively truncates the sbuf at the new position.
 166 .Pp
 167 The
 168 .Fn sbuf_bcat
 169 function appends the first
 170 .Fa len
 171 bytes from the byte string
 172 .Fa str
 173 to the
 174 .Fa sbuf .
 175 .Pp
 176 The
 177 .Fn sbuf_bcopyin
 178 function copies
 179 .Fa len
 180 bytes from the specified userland address into the
 181 .Fa sbuf .
 182 .Pp
 183 The
 184 .Fn sbuf_bcpy
 185 function replaces the contents of the
 186 .Fa sbuf
 187 with the first
 188 .Fa len
 189 bytes from the byte string
 190 .Fa str .
 191 .Pp
 192 The
 193 .Fn sbuf_cat
 194 function appends the NUL-terminated string
 195 .Fa str
 196 to the
 197 .Fa sbuf
 198 at the current position.
 199 .Pp
 200 The
 201 .Fn sbuf_copyin
 202 function copies a NUL-terminated string from the specified userland
 203 address into the
 204 .Fa sbuf .
 205 If the
 206 .Fa len
 207 argument is non-zero, no more than
 208 .Fa len
 209 characters (not counting the terminating NUL) are copied; otherwise
 210 the entire string, or as much of it as can fit in the
 211 .Fa sbuf ,
 212 is copied.
 213 .Pp
 214 The
 215 .Fn sbuf_cpy
 216 function replaces the contents of the
 217 .Fa sbuf
 218 with those of the NUL-terminated string
 219 .Fa str .
 220 This is equivalent to calling
 221 .Fn sbuf_cat
 222 with a fresh
 223 .Fa sbuf
 224 or one which position has been reset to zero with
 225 .Fn sbuf_clear
 226 or
 227 .Fn sbuf_setpos .
 228 .Pp
 229 The
 230 .Fn sbuf_printf
 231 function formats its arguments according to the format string pointed
 232 to by
 233 .Fa fmt
 234 and appends the resulting string to the
 235 .Fa sbuf
 236 at the current position.
 237 .Pp
 238 The
 239 .Fn sbuf_vprintf
 240 function behaves the same as
 241 .Fn sbuf_printf
 242 except that the arguments are obtained from the variable-length argument list
 243 .Fa ap .
 244 .Pp
 245 The
 246 .Fn sbuf_putc
 247 function appends the character
 248 .Fa c
 249 to the
 250 .Fa sbuf
 251 at the current position.
 252 .Pp
 253 The
 254 .Fn sbuf_trim
 255 function removes trailing whitespace from the
 256 .Fa sbuf .
 257 .Pp
 258 The
 259 .Fn sbuf_overflowed
 260 function returns a non-zero value if the
 261 .Fa sbuf
 262 overflowed.
 263 .Pp
 264 The
 265 .Fn sbuf_finish
 266 function null-terminates the
 267 .Fa sbuf
 268 and marks it as finished, which means that it may no longer be
 269 modified using
 270 .Fn sbuf_setpos ,
 271 .Fn sbuf_cat ,
 272 .Fn sbuf_cpy ,
 273 .Fn sbuf_printf
 274 or
 275 .Fn sbuf_putc .
 276 .Pp
 277 The
 278 .Fn sbuf_data
 279 and
 280 .Fn sbuf_len
 281 functions return the actual string and its length, respectively;
 282 .Fn sbuf_data
 283 only works on a finished
 284 .Fa sbuf .
 285 .Fn sbuf_done
 286 returns non-zero if the
 287 .Fa sbuf
 288 is finished.
 289 .Pp
 290 Finally, the
 291 .Fn sbuf_delete
 292 function clears the
 293 .Fa sbuf
 294 and frees its storage buffer if it was allocated by
 295 .Fn sbuf_new .
 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 .Sh SEE ALSO
 341 .Xr printf 3 ,
 342 .Xr strcat 3 ,
 343 .Xr strcpy 3 ,
 344 .Xr copyin 9 ,
 345 .Xr copyinstr 9 ,
 346 .Xr kprintf 9
 347 .Sh HISTORY
 348 The
 349 .Nm sbuf
 350 family of functions first appeared in
 351 .Fx 4.4 .
 352 .Sh AUTHORS
 353 .An -nosplit
 354 The
 355 .Nm sbuf
 356 family of functions was designed by
 357 .An Poul-Henning Kamp Aq phk@FreeBSD.org
 358 and implemented by
 359 .An Dag-Erling Co\(:idan Sm\(/orgrav Aq des@FreeBSD.org .
 360 Additional improvements were suggested by
 361 .An Justin T. Gibbs Aq gibbs@FreeBSD.org .
 362 Auto-extend support added by
 363 .An Kelly Yancey Aq kbyanc@FreeBSD.org .
 364 .Pp
 365 This manual page was written by
 366 .An Dag-Erling Co\(:idan Sm\(/orgrav .