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