/share/man/man9/sbuf.9

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 531 lines · 529 code · 2 blank · 0 comment · 0 complexity · e7c55a70f0560698290f14a9a28367f5 MD5 · raw file

  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 December 21, 2011
  29. .Dt SBUF 9
  30. .Os
  31. .Sh NAME
  32. .Nm sbuf ,
  33. .Nm sbuf_new ,
  34. .Nm sbuf_new_auto ,
  35. .Nm sbuf_new_for_sysctl ,
  36. .Nm sbuf_clear ,
  37. .Nm sbuf_setpos ,
  38. .Nm sbuf_bcat ,
  39. .Nm sbuf_bcopyin ,
  40. .Nm sbuf_bcpy ,
  41. .Nm sbuf_cat ,
  42. .Nm sbuf_copyin ,
  43. .Nm sbuf_cpy ,
  44. .Nm sbuf_printf ,
  45. .Nm sbuf_vprintf ,
  46. .Nm sbuf_putc ,
  47. .Nm sbuf_set_drain ,
  48. .Nm sbuf_trim ,
  49. .Nm sbuf_error ,
  50. .Nm sbuf_finish ,
  51. .Nm sbuf_data ,
  52. .Nm sbuf_len ,
  53. .Nm sbuf_done ,
  54. .Nm sbuf_delete
  55. .Nd safe string composition
  56. .Sh SYNOPSIS
  57. .In sys/types.h
  58. .In sys/sbuf.h
  59. .Ft typedef\ int ( sbuf_drain_func ) ( void\ *arg, const\ char\ *data, int\ len ) ;
  60. .Pp
  61. .Ft struct sbuf *
  62. .Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags"
  63. .Ft struct sbuf *
  64. .Fn sbuf_new_auto
  65. .Ft void
  66. .Fn sbuf_clear "struct sbuf *s"
  67. .Ft int
  68. .Fn sbuf_setpos "struct sbuf *s" "int pos"
  69. .Ft int
  70. .Fn sbuf_bcat "struct sbuf *s" "const void *buf" "size_t len"
  71. .Ft int
  72. .Fn sbuf_bcopyin "struct sbuf *s" "const void *uaddr" "size_t len"
  73. .Ft int
  74. .Fn sbuf_bcpy "struct sbuf *s" "const void *buf" "size_t len"
  75. .Ft int
  76. .Fn sbuf_cat "struct sbuf *s" "const char *str"
  77. .Ft int
  78. .Fn sbuf_copyin "struct sbuf *s" "const void *uaddr" "size_t len"
  79. .Ft int
  80. .Fn sbuf_cpy "struct sbuf *s" "const char *str"
  81. .Ft int
  82. .Fn sbuf_printf "struct sbuf *s" "const char *fmt" "..."
  83. .Ft int
  84. .Fn sbuf_vprintf "struct sbuf *s" "const char *fmt" "va_list ap"
  85. .Ft int
  86. .Fn sbuf_putc "struct sbuf *s" "int c"
  87. .Ft void
  88. .Fn sbuf_set_drain "struct sbuf *s" "sbuf_drain_func *func" "void *arg"
  89. .Ft int
  90. .Fn sbuf_trim "struct sbuf *s"
  91. .Ft int
  92. .Fn sbuf_error "struct sbuf *s"
  93. .Ft int
  94. .Fn sbuf_finish "struct sbuf *s"
  95. .Ft char *
  96. .Fn sbuf_data "struct sbuf *s"
  97. .Ft int
  98. .Fn sbuf_len "struct sbuf *s"
  99. .Ft int
  100. .Fn sbuf_done "struct sbuf *s"
  101. .Ft void
  102. .Fn sbuf_delete "struct sbuf *s"
  103. .In sys/sysctl.h
  104. .Ft struct sbuf *
  105. .Fn sbuf_new_for_sysctl "struct sbuf *s" "char *buf" "int length" "struct sysctl_req *req"
  106. .Sh DESCRIPTION
  107. The
  108. .Nm
  109. family of functions allows one to safely allocate, compose and
  110. release strings in kernel or user space.
  111. .Pp
  112. Instead of arrays of characters, these functions operate on structures
  113. called
  114. .Fa sbufs ,
  115. defined in
  116. .In sys/sbuf.h .
  117. .Pp
  118. Any errors encountered during the allocation or composition of the
  119. string will be latched in the data structure,
  120. making a single error test at the end of the composition
  121. sufficient to determine success or failure of the entire process.
  122. .Pp
  123. The
  124. .Fn sbuf_new
  125. function initializes the
  126. .Fa sbuf
  127. pointed to by its first argument.
  128. If that pointer is
  129. .Dv NULL ,
  130. .Fn sbuf_new
  131. allocates a
  132. .Vt struct sbuf
  133. using
  134. .Xr malloc 9 .
  135. The
  136. .Fa buf
  137. argument is a pointer to a buffer in which to store the actual string;
  138. if it is
  139. .Dv NULL ,
  140. .Fn sbuf_new
  141. will allocate one using
  142. .Xr malloc 9 .
  143. The
  144. .Fa length
  145. is the initial size of the storage buffer.
  146. The fourth argument,
  147. .Fa flags ,
  148. may be comprised of the following flags:
  149. .Bl -tag -width ".Dv SBUF_AUTOEXTEND"
  150. .It Dv SBUF_FIXEDLEN
  151. The storage buffer is fixed at its initial size.
  152. Attempting to extend the sbuf beyond this size results in an overflow condition.
  153. .It Dv SBUF_AUTOEXTEND
  154. This indicates that the storage buffer may be extended as necessary, so long
  155. as resources allow, to hold additional data.
  156. .El
  157. .Pp
  158. Note that if
  159. .Fa buf
  160. is not
  161. .Dv NULL ,
  162. it must point to an array of at least
  163. .Fa length
  164. characters.
  165. The result of accessing that array directly while it is in use by the
  166. sbuf is undefined.
  167. .Pp
  168. The
  169. .Fn sbuf_new_auto
  170. function is a shortcut for creating a completely dynamic
  171. .Nm .
  172. It is the equivalent of calling
  173. .Fn sbuf_new
  174. with values
  175. .Dv NULL ,
  176. .Dv NULL ,
  177. .Dv 0 ,
  178. and
  179. .Dv SBUF_AUTOEXTEND .
  180. .Pp
  181. The
  182. .Fn sbuf_new_for_sysctl
  183. function will set up an sbuf with a drain function to use
  184. .Fn SYSCTL_OUT
  185. when the internal buffer fills.
  186. Note that if the various functions which append to an sbuf are used while
  187. a non-sleepable lock is held, the user buffer should be wired using
  188. .Fn sysctl_wire_old_buffer .
  189. .Pp
  190. The
  191. .Fn sbuf_delete
  192. function clears the
  193. .Fa sbuf
  194. and frees any memory allocated for it.
  195. There must be a call to
  196. .Fn sbuf_delete
  197. for every call to
  198. .Fn sbuf_new .
  199. Any attempt to access the sbuf after it has been deleted will fail.
  200. .Pp
  201. The
  202. .Fn sbuf_clear
  203. function invalidates the contents of the
  204. .Fa sbuf
  205. and resets its position to zero.
  206. .Pp
  207. The
  208. .Fn sbuf_setpos
  209. function sets the
  210. .Fa sbuf Ns 's
  211. end position to
  212. .Fa pos ,
  213. which is a value between zero and one less than the size of the
  214. storage buffer.
  215. This effectively truncates the sbuf at the new position.
  216. .Pp
  217. The
  218. .Fn sbuf_bcat
  219. function appends the first
  220. .Fa len
  221. bytes from the buffer
  222. .Fa buf
  223. to the
  224. .Fa sbuf .
  225. .Pp
  226. The
  227. .Fn sbuf_bcopyin
  228. function copies
  229. .Fa len
  230. bytes from the specified userland address into the
  231. .Fa sbuf .
  232. .Pp
  233. The
  234. .Fn sbuf_bcpy
  235. function replaces the contents of the
  236. .Fa sbuf
  237. with the first
  238. .Fa len
  239. bytes from the buffer
  240. .Fa buf .
  241. .Pp
  242. The
  243. .Fn sbuf_cat
  244. function appends the NUL-terminated string
  245. .Fa str
  246. to the
  247. .Fa sbuf
  248. at the current position.
  249. .Pp
  250. The
  251. .Fn sbuf_set_drain
  252. function sets a drain function
  253. .Fa func
  254. for the
  255. .Fa sbuf ,
  256. and records a pointer
  257. .Fa arg
  258. to be passed to the drain on callback.
  259. The drain function cannot be changed while
  260. .Fa sbuf_len
  261. is non-zero.
  262. .Pp
  263. The registered drain function
  264. .Vt sbuf_drain_func
  265. will be called with the argument
  266. .Fa arg
  267. provided to
  268. .Fn sbuf_set_drain ,
  269. a pointer
  270. .Fa data
  271. to a byte string that is the contents of the sbuf, and the length
  272. .Fa len
  273. of the data.
  274. If the drain function exists, it will be called when the sbuf internal
  275. buffer is full, or on behalf of
  276. .Fn sbuf_finish .
  277. The drain function may drain some or all of the data, but must drain
  278. at least 1 byte.
  279. The return value from the drain function, if positive, indicates how
  280. many bytes were drained.
  281. If negative, the return value indicates the negative error code which
  282. will be returned from this or a later call to
  283. .Fn sbuf_finish .
  284. The returned drained length cannot be zero.
  285. To do unbuffered draining, initialize the sbuf with a two-byte buffer.
  286. The drain will be called for every byte added to the sbuf.
  287. The
  288. .Fn sbuf_bcopyin ,
  289. .Fn sbuf_copyin ,
  290. .Fn sbuf_trim ,
  291. and
  292. .Fn sbuf_data
  293. functions cannot be used on an sbuf with a drain.
  294. .Pp
  295. The
  296. .Fn sbuf_copyin
  297. function copies a NUL-terminated string from the specified userland
  298. address into the
  299. .Fa sbuf .
  300. If the
  301. .Fa len
  302. argument is non-zero, no more than
  303. .Fa len
  304. characters (not counting the terminating NUL) are copied; otherwise
  305. the entire string, or as much of it as can fit in the
  306. .Fa sbuf ,
  307. is copied.
  308. .Pp
  309. The
  310. .Fn sbuf_cpy
  311. function replaces the contents of the
  312. .Fa sbuf
  313. with those of the NUL-terminated string
  314. .Fa str .
  315. This is equivalent to calling
  316. .Fn sbuf_cat
  317. with a fresh
  318. .Fa sbuf
  319. or one which position has been reset to zero with
  320. .Fn sbuf_clear
  321. or
  322. .Fn sbuf_setpos .
  323. .Pp
  324. The
  325. .Fn sbuf_printf
  326. function formats its arguments according to the format string pointed
  327. to by
  328. .Fa fmt
  329. and appends the resulting string to the
  330. .Fa sbuf
  331. at the current position.
  332. .Pp
  333. The
  334. .Fn sbuf_vprintf
  335. function behaves the same as
  336. .Fn sbuf_printf
  337. except that the arguments are obtained from the variable-length argument list
  338. .Fa ap .
  339. .Pp
  340. The
  341. .Fn sbuf_putc
  342. function appends the character
  343. .Fa c
  344. to the
  345. .Fa sbuf
  346. at the current position.
  347. .Pp
  348. The
  349. .Fn sbuf_trim
  350. function removes trailing whitespace from the
  351. .Fa sbuf .
  352. .Pp
  353. The
  354. .Fn sbuf_error
  355. function returns any error value that the
  356. .Fa sbuf
  357. may have accumulated, either from the drain function, or ENOMEM if the
  358. .Fa sbuf
  359. overflowed.
  360. This function is generally not needed and instead the error code from
  361. .Fn sbuf_finish
  362. is the preferred way to discover whether an sbuf had an error.
  363. .Pp
  364. The
  365. .Fn sbuf_finish
  366. function will call the attached drain function if one exists until all
  367. the data in the
  368. .Fa sbuf
  369. is flushed.
  370. If there is no attached drain,
  371. .Fn sbuf_finish
  372. NUL-terminates the
  373. .Fa sbuf .
  374. In either case it marks the
  375. .Fa sbuf
  376. as finished, which means that it may no longer be modified using
  377. .Fn sbuf_setpos ,
  378. .Fn sbuf_cat ,
  379. .Fn sbuf_cpy ,
  380. .Fn sbuf_printf
  381. or
  382. .Fn sbuf_putc ,
  383. until
  384. .Fn sbuf_clear
  385. is used to reset the sbuf.
  386. .Pp
  387. The
  388. .Fn sbuf_data
  389. function returns the actual string;
  390. .Fn sbuf_data
  391. only works on a finished
  392. .Fa sbuf .
  393. The
  394. .Fn sbuf_len
  395. function returns the length of the string.
  396. For an
  397. .Fa sbuf
  398. with an attached drain,
  399. .Fn sbuf_len
  400. returns the length of the un-drained data.
  401. .Fn sbuf_done
  402. returns non-zero if the
  403. .Fa sbuf
  404. is finished.
  405. .Sh NOTES
  406. If an operation caused an
  407. .Fa sbuf
  408. to overflow, most subsequent operations on it will fail until the
  409. .Fa sbuf
  410. is finished using
  411. .Fn sbuf_finish
  412. or reset using
  413. .Fn sbuf_clear ,
  414. or its position is reset to a value between 0 and one less than the
  415. size of its storage buffer using
  416. .Fn sbuf_setpos ,
  417. or it is reinitialized to a sufficiently short string using
  418. .Fn sbuf_cpy .
  419. .Pp
  420. Drains in user-space will not always function as indicated.
  421. While the drain function will be called immediately on overflow from
  422. the
  423. .Fa sbuf_putc ,
  424. .Fa sbuf_bcat ,
  425. .Fa sbuf_cat
  426. functions,
  427. .Fa sbuf_printf
  428. and
  429. .Fa sbuf_vprintf
  430. currently have no way to determine whether there will be an overflow
  431. until after it occurs, and cannot do a partial expansion of the format
  432. string.
  433. Thus when using libsbuf the buffer may be extended to allow completion
  434. of a single printf call, even though a drain is attached.
  435. .Sh RETURN VALUES
  436. The
  437. .Fn sbuf_new
  438. function returns
  439. .Dv NULL
  440. if it failed to allocate a storage buffer, and a pointer to the new
  441. .Fa sbuf
  442. otherwise.
  443. .Pp
  444. The
  445. .Fn sbuf_setpos
  446. function returns \-1 if
  447. .Fa pos
  448. was invalid, and zero otherwise.
  449. .Pp
  450. The
  451. .Fn sbuf_cat ,
  452. .Fn sbuf_cpy ,
  453. .Fn sbuf_printf ,
  454. .Fn sbuf_putc ,
  455. and
  456. .Fn sbuf_trim
  457. functions
  458. all return \-1 if the buffer overflowed, and zero otherwise.
  459. .Pp
  460. The
  461. .Fn sbuf_error
  462. function returns a non-zero value if the buffer has an overflow or
  463. drain error, and zero otherwise.
  464. .Pp
  465. The
  466. .Fn sbuf_len
  467. function returns \-1 if the buffer overflowed.
  468. .Pp
  469. The
  470. .Fn sbuf_copyin
  471. function
  472. returns \-1 if copying string from userland failed, and number of bytes
  473. copied otherwise.
  474. .Pp
  475. The
  476. .Fn sbuf_finish 9
  477. function (the kernel version) returns ENOMEM if the sbuf overflowed before
  478. being finished,
  479. or returns the error code from the drain if one is attached.
  480. .Pp
  481. The
  482. .Fn sbuf_finish 3
  483. function (the userland version)
  484. will return zero for success and \-1 and set errno on error.
  485. .Sh EXAMPLES
  486. .Bd -literal -compact
  487. #include <sys/sbuf.h>
  488. struct sbuf *sb;
  489. sb = sbuf_new_auto();
  490. sbuf_cat(sb, "Customers found:\en");
  491. TAILQ_FOREACH(foo, &foolist, list) {
  492. sbuf_printf(sb, " %4d %s\en", foo->index, foo->name);
  493. sbuf_printf(sb, " Address: %s\en", foo->address);
  494. sbuf_printf(sb, " Zip: %s\en", foo->zipcode);
  495. }
  496. if (sbuf_finish(sb) != 0) /* Check for any and all errors */
  497. err(1, "Could not generate message");
  498. transmit_msg(sbuf_data(sb), sbuf_len(sb));
  499. sbuf_delete(sb);
  500. .Ed
  501. .Sh SEE ALSO
  502. .Xr printf 3 ,
  503. .Xr strcat 3 ,
  504. .Xr strcpy 3 ,
  505. .Xr copyin 9 ,
  506. .Xr copyinstr 9 ,
  507. .Xr printf 9
  508. .Sh HISTORY
  509. The
  510. .Nm
  511. family of functions first appeared in
  512. .Fx 4.4 .
  513. .Sh AUTHORS
  514. .An -nosplit
  515. The
  516. .Nm
  517. family of functions was designed by
  518. .An Poul-Henning Kamp Aq phk@FreeBSD.org
  519. and implemented by
  520. .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
  521. Additional improvements were suggested by
  522. .An Justin T. Gibbs Aq gibbs@FreeBSD.org .
  523. Auto-extend support added by
  524. .An Kelly Yancey Aq kbyanc@FreeBSD.org .
  525. Drain functionality added by
  526. .An Matthew Fleming Aq mdf@FreeBSD.org .
  527. .Pp
  528. This manual page was written by
  529. .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .