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 December 10, 2000 29.Dt sbuf 9 30.Os FreeBSD 31.Sh NAME 32.Nm sbuf_new , 33.Nm sbuf_setpos , 34.Nm sbuf_cat , 35.Nm sbuf_cpy , 36.Nm sbuf_printf , 37.Nm sbuf_putc , 38.Nm sbuf_finish , 39.Nm sbuf_data , 40.Nm sbuf_len , 41.Nm sbuf_delete 42.Nd safe string formatting 43.Sh SYNOPSIS 44.Fd #include <sys/sbuf.h> 45.Ft int 46.Fn sbuf_new "struct sbuf *s" "char *buf" "size_t length" "int flags" 47.Ft int 48.Fn sbuf_setpos "struct sbuf *s" "size_t pos" 49.Ft int 50.Fn sbuf_cat "struct sbuf *s" "char *str" 51.Ft int 52.Fn sbuf_cpy "struct sbuf *s" "char *str" 53.Ft int 54.Fn sbuf_printf "struct sbuf *s" "char *fmt" "..." 55.Ft int 56.Fn sbuf_putc "struct sbuf *s" "int c" 57.Ft int 58.Fn sbuf_finish "struct sbuf *s" 59.Ft char * 60.Fn sbuf_data "struct sbuf *s" 61.Ft size_t 62.Fn sbuf_len "struct sbuf *s" 63.Ft void 64.Fn sbuf_delete "struct sbuf *s" 65.Sh DESCRIPTION 66The 67.Nm sbuf 68family of functions allows one to safely allocate, construct and 69release bounded null-terminated strings in kernel space. 70Instead of arrays of characters, these functions operate on structures 71called 72.Fa sbufs , 73defined in 74.Aq Pa sys/sbuf.h . 75.Pp 76The 77.Fn sbuf_new 78function initializes the 79.Fa sbuf 80pointed to by its first argument. 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 91is the intended size of the storage buffer. 92The fourth argument, 93.Fa flags , 94is currently unused and should always be set to zero. 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. 103.Pp 104The 105.Fn sbuf_setpos 106function sets the 107.Fa sbuf Ns 's 108current position to 109.Fa pos , 110which is a value between zero and one less than the size of the 111storage buffer. 112.Pp 113The 114.Fn sbuf_cat 115function appends the string 116.Fa str 117to the 118.Fa sbuf 119at the current position. 120.Pp 121The 122.Fn sbuf_cpy 123function replaces the contents of the 124.Fa sbuf 125with those of the string 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 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 144.Fn sbuf_putc 145function appends the character 146.Fa c 147to the 148.Fa sbuf 149at the current position. 150.Pp 151The 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 , 159.Fn sbuf_cpu , 160.Fn sbuf_printf 161or 162.Fn sbuf_putc . 163.Pp 164The 165.Fn sbuf_data 166and 167.Fn sbuf_len 168functions return the actual string and its length, respectively, and 169only work on a finished and non-overflowed 170.Fa sbuf . 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 . 178.Sh NOTES 179If an operation caused an 180.Fa sbuf 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 187.Fn sbuf_setpos , 188or it is reinitialized to a sufficiently short string using 189.Fn sbuf_cpy . 190.Sh RETURN VALUES 191.Fn sbuf_new 192returns \-1 if it failed to allocate a storage buffer, and zero 193otherwise. 194.Pp 195.Fn sbuf_setpos 196returns \-1 if 197.Fa pos 198was invalid, and zero otherwise. 199.Pp 200.Fn sbuf_cat , 201.Fn sbuf_cpy , 202.Fn sbuf_printf , 203.Fn sbuf_putc , 204and 205.Fn sbuf_finish 206all return \-1 if the buffer overflowed, and zero otherwise. 207.Pp 208.Fn sbuf_data 209and 210.Fn sbuf_len 211return 212.Dv NULL 213and 0, respectively, if the buffer overflowed. 214.Sh SEE ALSO 215.Xr printf 3 , 216.Xr strcat 3 , 217.Xr strcpy 3 218.Sh HISTORY 219The 220.Nm sbuf 221family of functions first appeared in 222.Fx 4.3 . 223.Sh AUTHORS 224.An -nosplit 225The 226.Nm sbuf 227family of functions was designed by 228.An Poul-Henning Kamp Aq phk@FreeBSD.org 229and implemented by 230.An Dag-Erling Co\(:idan Sm\(/orgrav Aq des@FreeBSD.org . 231.Pp 232This manual page was written by 233.An Dag-Erling Co\(:idan Sm\(/orgrav . 234