sbuf.9 (2e370a5c7a5528afb124f6273136736e5d5fb798) sbuf.9 (863edaec4d32fbcaf33215112d81ab15f4f30ec7)
1.\"-
1.\"-
2.\" Copyright (c) 2000 Poul-Henning Kamp and Dag-Erling Co�dan Sm�rgrav
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

--- 9 unchanged lines hidden (view full) ---

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.\"
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

--- 9 unchanged lines hidden (view full) ---

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 May 17, 2009
29.Dt SBUF 9
30.Os
28.Dd December 10, 2000
29.Dt sbuf 9
30.Os FreeBSD
31.Sh NAME
31.Sh NAME
32.Nm sbuf ,
33.Nm sbuf_new ,
32.Nm sbuf_new ,
34.Nm sbuf_new_auto ,
35.Nm sbuf_clear ,
36.Nm sbuf_setpos ,
33.Nm sbuf_setpos ,
37.Nm sbuf_bcat ,
38.Nm sbuf_bcopyin ,
39.Nm sbuf_bcpy ,
40.Nm sbuf_cat ,
34.Nm sbuf_cat ,
41.Nm sbuf_copyin ,
42.Nm sbuf_cpy ,
43.Nm sbuf_printf ,
35.Nm sbuf_cpy ,
36.Nm sbuf_printf ,
44.Nm sbuf_vprintf ,
45.Nm sbuf_putc ,
37.Nm sbuf_putc ,
46.Nm sbuf_trim ,
47.Nm sbuf_overflowed ,
48.Nm sbuf_finish ,
49.Nm sbuf_data ,
50.Nm sbuf_len ,
38.Nm sbuf_finish ,
39.Nm sbuf_data ,
40.Nm sbuf_len ,
51.Nm sbuf_done ,
52.Nm sbuf_delete
53.Nd safe string formatting
54.Sh SYNOPSIS
41.Nm sbuf_delete
42.Nd safe string formatting
43.Sh SYNOPSIS
55.In sys/types.h
56.In sys/sbuf.h
57.Ft struct sbuf *
58.Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags"
59.Ft struct sbuf *
60.Fn sbuf_new_auto
61.Ft void
62.Fn sbuf_clear "struct sbuf *s"
44.Fd #include <sys/sbuf.h>
63.Ft int
45.Ft int
64.Fn sbuf_setpos "struct sbuf *s" "int pos"
46.Fn sbuf_new "struct sbuf *s" "char *buf" "size_t length" "int flags"
65.Ft int
47.Ft int
66.Fn sbuf_bcat "struct sbuf *s" "const void *buf" "size_t len"
48.Fn sbuf_setpos "struct sbuf *s" "size_t pos"
67.Ft int
49.Ft int
68.Fn sbuf_bcopyin "struct sbuf *s" "const void *uaddr" "size_t len"
50.Fn sbuf_cat "struct sbuf *s" "char *str"
69.Ft int
51.Ft int
70.Fn sbuf_bcpy "struct sbuf *s" "const void *buf" "size_t len"
52.Fn sbuf_cpy "struct sbuf *s" "char *str"
71.Ft int
53.Ft int
72.Fn sbuf_cat "struct sbuf *s" "const char *str"
54.Fn sbuf_printf "struct sbuf *s" "char *fmt" "..."
73.Ft int
55.Ft int
74.Fn sbuf_copyin "struct sbuf *s" "const void *uaddr" "size_t len"
75.Ft int
76.Fn sbuf_cpy "struct sbuf *s" "const char *str"
77.Ft int
78.Fn sbuf_printf "struct sbuf *s" "const char *fmt" "..."
79.Ft int
80.Fn sbuf_vprintf "struct sbuf *s" "const char *fmt" "va_list ap"
81.Ft int
82.Fn sbuf_putc "struct sbuf *s" "int c"
83.Ft int
56.Fn sbuf_putc "struct sbuf *s" "int c"
57.Ft int
84.Fn sbuf_trim "struct sbuf *s"
85.Ft int
86.Fn sbuf_overflowed "struct sbuf *s"
87.Ft void
88.Fn sbuf_finish "struct sbuf *s"
89.Ft char *
90.Fn sbuf_data "struct sbuf *s"
58.Fn sbuf_finish "struct sbuf *s"
59.Ft char *
60.Fn sbuf_data "struct sbuf *s"
91.Ft int
61.Ft size_t
92.Fn sbuf_len "struct sbuf *s"
62.Fn sbuf_len "struct sbuf *s"
93.Ft int
94.Fn sbuf_done "struct sbuf *s"
95.Ft void
96.Fn sbuf_delete "struct sbuf *s"
97.Sh DESCRIPTION
98The
63.Ft void
64.Fn sbuf_delete "struct sbuf *s"
65.Sh DESCRIPTION
66The
99.Nm
100family of functions allows one to safely allocate, construct and
67.Nm sbuf
68family of functions allow one to safely allocate, construct and
101release bounded null-terminated strings in kernel space.
102Instead of arrays of characters, these functions operate on structures
103called
104.Fa sbufs ,
105defined in
69release bounded null-terminated strings in kernel space.
70Instead of arrays of characters, these functions operate on structures
71called
72.Fa sbufs ,
73defined in
106.In sys/sbuf.h .
74.Aq Pa sys/sbuf.h .
107.Pp
108The
109.Fn sbuf_new
110function initializes the
111.Fa sbuf
112pointed to by its first argument.
75.Pp
76The
77.Fn sbuf_new
78function initializes the
79.Fa sbuf
80pointed to by its first argument.
113If that pointer is
114.Dv NULL ,
115.Fn sbuf_new
116allocates a
117.Vt struct sbuf
118using
119.Xr malloc 9 .
120The
121.Fa buf
122argument is a pointer to a buffer in which to store the actual string;
123if it is
124.Dv NULL ,
125.Fn sbuf_new
126will allocate one using
127.Xr malloc 9 .
128The
129.Fa length
81The
82.Fa buf
83argument is a pointer to a buffer in which to store the actual string;
84if it is
85.Dv NULL ,
86.Fn sbuf_new
87will allocate one using
88.Xr malloc 9 .
89The
90.Fa length
130is the initial size of the storage buffer.
91is the intended size of the storage buffer.
131The fourth argument,
132.Fa flags ,
92The fourth argument,
93.Fa flags ,
133may be comprised of the following flags:
134.Bl -tag -width ".Dv SBUF_AUTOEXTEND"
135.It Dv SBUF_FIXEDLEN
136The storage buffer is fixed at its initial size.
137Attempting to extend the sbuf beyond this size results in an overflow condition.
138.It Dv SBUF_AUTOEXTEND
139This indicates that the storage buffer may be extended as necessary, so long
140as resources allow, to hold additional data.
141.El
94is currently unused and should always be set to zero.
142.Pp
143Note that if
144.Fa buf
145is not
146.Dv NULL ,
147it must point to an array of at least
148.Fa length
149characters.
95.Pp
96Note that if
97.Fa buf
98is not
99.Dv NULL ,
100it must point to an array of at least
101.Fa length
102characters.
150The result of accessing that array directly while it is in use by the
151sbuf is undefined.
152.Pp
153The
103.Pp
104The
154.Fn sbuf_new_auto
155function is a shortcut for creating a completely dynamic
156.Nm .
157It is the equivalent of calling
158.Fn sbuf_new
159with values
160.Dv NULL ,
161.Dv NULL ,
162.Dv 0 ,
163and
164.Dv SBUF_AUTOEXTEND .
165.Pp
166The
167.Fn sbuf_delete
168function clears the
169.Fa sbuf
170and frees any memory allocated for it.
171There must be a call to
172.Fn sbuf_delete
173for every call to
174.Fn sbuf_new .
175Any attempt to access the sbuf after it has been deleted will fail.
176.Pp
177The
178.Fn sbuf_clear
179function invalidates the contents of the
180.Fa sbuf
181and resets its position to zero.
182.Pp
183The
184.Fn sbuf_setpos
185function sets the
186.Fa sbuf Ns 's
105.Fn sbuf_setpos
106function sets the
107.Fa sbuf Ns 's
187end position to
108current position to
188.Fa pos ,
189which is a value between zero and one less than the size of the
190storage buffer.
109.Fa pos ,
110which is a value between zero and one less than the size of the
111storage buffer.
191This effectively truncates the sbuf at the new position.
192.Pp
193The
112.Pp
113The
194.Fn sbuf_bcat
195function appends the first
196.Fa len
197bytes from the buffer
198.Fa buf
199to the
200.Fa sbuf .
201.Pp
202The
203.Fn sbuf_bcopyin
204function copies
205.Fa len
206bytes from the specified userland address into the
207.Fa sbuf .
208.Pp
209The
210.Fn sbuf_bcpy
211function replaces the contents of the
212.Fa sbuf
213with the first
214.Fa len
215bytes from the buffer
216.Fa buf .
217.Pp
218The
219.Fn sbuf_cat
114.Fn sbuf_cat
220function appends the NUL-terminated string
115function appends the string
221.Fa str
222to the
223.Fa sbuf
224at the current position.
225.Pp
226The
116.Fa str
117to the
118.Fa sbuf
119at the current position.
120.Pp
121The
227.Fn sbuf_copyin
228function copies a NUL-terminated string from the specified userland
229address into the
230.Fa sbuf .
231If the
232.Fa len
233argument is non-zero, no more than
234.Fa len
235characters (not counting the terminating NUL) are copied; otherwise
236the entire string, or as much of it as can fit in the
237.Fa sbuf ,
238is copied.
239.Pp
240The
241.Fn sbuf_cpy
242function replaces the contents of the
243.Fa sbuf
122.Fn sbuf_cpy
123function replaces the contents of the
124.Fa sbuf
244with those of the NUL-terminated string
125with those of the string
245.Fa str .
246This is equivalent to calling
247.Fn sbuf_cat
248with a fresh
249.Fa sbuf
250or one which position has been reset to zero with
126.Fa str .
127This is equivalent to calling
128.Fn sbuf_cat
129with a fresh
130.Fa sbuf
131or one which position has been reset to zero with
251.Fn sbuf_clear
252or
253.Fn sbuf_setpos .
254.Pp
255The
256.Fn sbuf_printf
257function formats its arguments according to the format string pointed
258to by
259.Fa fmt
260and appends the resulting string to the
261.Fa sbuf
262at the current position.
263.Pp
264The
132.Fn sbuf_setpos .
133.Pp
134The
135.Fn sbuf_printf
136function formats its arguments according to the format string pointed
137to by
138.Fa fmt
139and appends the resulting string to the
140.Fa sbuf
141at the current position.
142.Pp
143The
265.Fn sbuf_vprintf
266function behaves the same as
267.Fn sbuf_printf
268except that the arguments are obtained from the variable-length argument list
269.Fa ap .
270.Pp
271The
272.Fn sbuf_putc
273function appends the character
274.Fa c
275to the
276.Fa sbuf
277at the current position.
278.Pp
279The
144.Fn sbuf_putc
145function appends the character
146.Fa c
147to the
148.Fa sbuf
149at the current position.
150.Pp
151The
280.Fn sbuf_trim
281function removes trailing whitespace from the
282.Fa sbuf .
283.Pp
284The
285.Fn sbuf_overflowed
286function returns a non-zero value if the
287.Fa sbuf
288overflowed.
289.Pp
290The
291.Fn sbuf_finish
292function null-terminates the
293.Fa sbuf
294and marks it as finished, which means that it may no longer be
295modified using
296.Fn sbuf_setpos ,
297.Fn sbuf_cat ,
152.Fn sbuf_finish
153function null-terminates the
154.Fa sbuf
155and marks it as finished, which means that it may no longer be
156modified using
157.Fn sbuf_setpos ,
158.Fn sbuf_cat ,
298.Fn sbuf_cpy ,
159.Fn sbuf_cpu ,
299.Fn sbuf_printf
300or
301.Fn sbuf_putc .
302.Pp
303The
304.Fn sbuf_data
305and
306.Fn sbuf_len
160.Fn sbuf_printf
161or
162.Fn sbuf_putc .
163.Pp
164The
165.Fn sbuf_data
166and
167.Fn sbuf_len
307functions return the actual string and its length, respectively;
308.Fn sbuf_data
309only works on a finished
168functions return the actual string and its length, respectively, and
169only work on a finished and non-overflowed
310.Fa sbuf .
170.Fa sbuf .
311.Fn sbuf_done
312returns non-zero if the sbuf is finished.
171.Pp
172Finally, the
173.Fn sbuf_delete
174function clears the
175.Fa sbuf
176and frees its storage buffer if it was allocated by
177.Fn sbuf_new .
313.Sh NOTES
314If an operation caused an
315.Fa sbuf
178.Sh NOTES
179If an operation caused an
180.Fa sbuf
316to overflow, most subsequent operations on it will fail until the
317.Fa sbuf
318is finished using
319.Fn sbuf_finish
320or reset using
321.Fn sbuf_clear ,
322or its position is reset to a value between 0 and one less than the
323size of its storage buffer using
181to overflow, most subsequent operations (including
182.Fn sbuf_finish )
183on it will fail until the
184.Fa sbuf Ns 's
185position is reset to a value between 0 and one less than the size of
186its storage buffer using
324.Fn sbuf_setpos ,
325or it is reinitialized to a sufficiently short string using
326.Fn sbuf_cpy .
327.Sh RETURN VALUES
187.Fn sbuf_setpos ,
188or it is reinitialized to a sufficiently short string using
189.Fn sbuf_cpy .
190.Sh RETURN VALUES
328The
329.Fn sbuf_new
191.Fn sbuf_new
330function returns
331.Dv NULL
332if it failed to allocate a storage buffer, and a pointer to the new
333.Fa sbuf
192returns \-1 if it failed to allocate a storage buffer, and zero
334otherwise.
335.Pp
193otherwise.
194.Pp
336The
337.Fn sbuf_setpos
195.Fn sbuf_setpos
338function returns \-1 if
196returns \-1 if
339.Fa pos
340was invalid, and zero otherwise.
341.Pp
197.Fa pos
198was invalid, and zero otherwise.
199.Pp
342The
343.Fn sbuf_cat ,
344.Fn sbuf_cpy ,
345.Fn sbuf_printf ,
346.Fn sbuf_putc ,
347and
200.Fn sbuf_cat ,
201.Fn sbuf_cpy ,
202.Fn sbuf_printf ,
203.Fn sbuf_putc ,
204and
348.Fn sbuf_trim
349functions
205.Fn sbuf_finish
350all return \-1 if the buffer overflowed, and zero otherwise.
351.Pp
206all return \-1 if the buffer overflowed, and zero otherwise.
207.Pp
352The
353.Fn sbuf_overflowed
354function
355returns a non-zero value if the buffer overflowed, and zero otherwise.
356.Pp
357The
358.Fn sbuf_data
359and
360.Fn sbuf_len
208.Fn sbuf_data
209and
210.Fn sbuf_len
361functions return
211return
362.Dv NULL
212.Dv NULL
363and \-1, respectively, if the buffer overflowed.
364.Pp
365The
366.Fn sbuf_copyin
367function
368returns \-1 if copying string from userland failed, and number of bytes
369copied otherwise.
213and 0, respectively, if the buffer overflowed.
370.Sh SEE ALSO
371.Xr printf 3 ,
372.Xr strcat 3 ,
214.Sh SEE ALSO
215.Xr printf 3 ,
216.Xr strcat 3 ,
373.Xr strcpy 3 ,
374.Xr copyin 9 ,
375.Xr copyinstr 9 ,
376.Xr printf 9
217.Xr strcpy 3
377.Sh HISTORY
378The
218.Sh HISTORY
219The
379.Nm
220.Nm sbuf
380family of functions first appeared in
221family of functions first appeared in
381.Fx 4.4 .
222.Fx 4.3 .
382.Sh AUTHORS
383.An -nosplit
384The
223.Sh AUTHORS
224.An -nosplit
225The
385.Nm
226.Nm sbuf
386family of functions was designed by
387.An Poul-Henning Kamp Aq phk@FreeBSD.org
388and implemented by
227family of functions was designed by
228.An Poul-Henning Kamp Aq phk@FreeBSD.org
229and implemented by
389.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
390Additional improvements were suggested by
391.An Justin T. Gibbs Aq gibbs@FreeBSD.org .
392Auto-extend support added by
393.An Kelly Yancey Aq kbyanc@FreeBSD.org .
230.An Dag-Erling Co\(:idan Sm\(/orgrav Aq des@FreeBSD.org .
394.Pp
395This manual page was written by
231.Pp
232This manual page was written by
396.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
233.An Dag-Erling Co\(:idan Sm\(/orgrav .