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