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