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