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