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