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