397 lines
8.6 KiB
Groff
397 lines
8.6 KiB
Groff
.\"-
|
|
.\" Copyright (c) 2000 Poul-Henning Kamp and Dag-Erling Coïdan Smørgrav
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd May 17, 2009
|
|
.Dt SBUF 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm sbuf ,
|
|
.Nm sbuf_new ,
|
|
.Nm sbuf_new_auto ,
|
|
.Nm sbuf_clear ,
|
|
.Nm sbuf_setpos ,
|
|
.Nm sbuf_bcat ,
|
|
.Nm sbuf_bcopyin ,
|
|
.Nm sbuf_bcpy ,
|
|
.Nm sbuf_cat ,
|
|
.Nm sbuf_copyin ,
|
|
.Nm sbuf_cpy ,
|
|
.Nm sbuf_printf ,
|
|
.Nm sbuf_vprintf ,
|
|
.Nm sbuf_putc ,
|
|
.Nm sbuf_trim ,
|
|
.Nm sbuf_overflowed ,
|
|
.Nm sbuf_finish ,
|
|
.Nm sbuf_data ,
|
|
.Nm sbuf_len ,
|
|
.Nm sbuf_done ,
|
|
.Nm sbuf_delete
|
|
.Nd safe string formatting
|
|
.Sh SYNOPSIS
|
|
.In sys/types.h
|
|
.In sys/sbuf.h
|
|
.Ft struct sbuf *
|
|
.Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags"
|
|
.Ft struct sbuf *
|
|
.Fn sbuf_new_auto
|
|
.Ft void
|
|
.Fn sbuf_clear "struct sbuf *s"
|
|
.Ft int
|
|
.Fn sbuf_setpos "struct sbuf *s" "int pos"
|
|
.Ft int
|
|
.Fn sbuf_bcat "struct sbuf *s" "const void *buf" "size_t len"
|
|
.Ft int
|
|
.Fn sbuf_bcopyin "struct sbuf *s" "const void *uaddr" "size_t len"
|
|
.Ft int
|
|
.Fn sbuf_bcpy "struct sbuf *s" "const void *buf" "size_t len"
|
|
.Ft int
|
|
.Fn sbuf_cat "struct sbuf *s" "const char *str"
|
|
.Ft int
|
|
.Fn sbuf_copyin "struct sbuf *s" "const void *uaddr" "size_t len"
|
|
.Ft int
|
|
.Fn sbuf_cpy "struct sbuf *s" "const char *str"
|
|
.Ft int
|
|
.Fn sbuf_printf "struct sbuf *s" "const char *fmt" "..."
|
|
.Ft int
|
|
.Fn sbuf_vprintf "struct sbuf *s" "const char *fmt" "va_list ap"
|
|
.Ft int
|
|
.Fn sbuf_putc "struct sbuf *s" "int c"
|
|
.Ft int
|
|
.Fn sbuf_trim "struct sbuf *s"
|
|
.Ft int
|
|
.Fn sbuf_overflowed "struct sbuf *s"
|
|
.Ft void
|
|
.Fn sbuf_finish "struct sbuf *s"
|
|
.Ft char *
|
|
.Fn sbuf_data "struct sbuf *s"
|
|
.Ft int
|
|
.Fn sbuf_len "struct sbuf *s"
|
|
.Ft int
|
|
.Fn sbuf_done "struct sbuf *s"
|
|
.Ft void
|
|
.Fn sbuf_delete "struct sbuf *s"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
family of functions allows one to safely allocate, construct and
|
|
release bounded null-terminated strings in kernel space.
|
|
Instead of arrays of characters, these functions operate on structures
|
|
called
|
|
.Fa sbufs ,
|
|
defined in
|
|
.In sys/sbuf.h .
|
|
.Pp
|
|
The
|
|
.Fn sbuf_new
|
|
function initializes the
|
|
.Fa sbuf
|
|
pointed to by its first argument.
|
|
If that pointer is
|
|
.Dv NULL ,
|
|
.Fn sbuf_new
|
|
allocates a
|
|
.Vt struct sbuf
|
|
using
|
|
.Xr malloc 9 .
|
|
The
|
|
.Fa buf
|
|
argument is a pointer to a buffer in which to store the actual string;
|
|
if it is
|
|
.Dv NULL ,
|
|
.Fn sbuf_new
|
|
will allocate one using
|
|
.Xr malloc 9 .
|
|
The
|
|
.Fa length
|
|
is the initial size of the storage buffer.
|
|
The fourth argument,
|
|
.Fa flags ,
|
|
may be comprised of the following flags:
|
|
.Bl -tag -width ".Dv SBUF_AUTOEXTEND"
|
|
.It Dv SBUF_FIXEDLEN
|
|
The storage buffer is fixed at its initial size.
|
|
Attempting to extend the sbuf beyond this size results in an overflow condition.
|
|
.It Dv SBUF_AUTOEXTEND
|
|
This indicates that the storage buffer may be extended as necessary, so long
|
|
as resources allow, to hold additional data.
|
|
.El
|
|
.Pp
|
|
Note that if
|
|
.Fa buf
|
|
is not
|
|
.Dv NULL ,
|
|
it must point to an array of at least
|
|
.Fa length
|
|
characters.
|
|
The result of accessing that array directly while it is in use by the
|
|
sbuf is undefined.
|
|
.Pp
|
|
The
|
|
.Fn sbuf_new_auto
|
|
function is a shortcut for creating a completely dynamic
|
|
.Nm .
|
|
It is the equivalent of calling
|
|
.Fn sbuf_new
|
|
with values
|
|
.Dv NULL ,
|
|
.Dv NULL ,
|
|
.Dv 0 ,
|
|
and
|
|
.Dv SBUF_AUTOEXTEND .
|
|
.Pp
|
|
The
|
|
.Fn sbuf_delete
|
|
function clears the
|
|
.Fa sbuf
|
|
and frees any memory allocated for it.
|
|
There must be a call to
|
|
.Fn sbuf_delete
|
|
for every call to
|
|
.Fn sbuf_new .
|
|
Any attempt to access the sbuf after it has been deleted will fail.
|
|
.Pp
|
|
The
|
|
.Fn sbuf_clear
|
|
function invalidates the contents of the
|
|
.Fa sbuf
|
|
and resets its position to zero.
|
|
.Pp
|
|
The
|
|
.Fn sbuf_setpos
|
|
function sets the
|
|
.Fa sbuf Ns 's
|
|
end position to
|
|
.Fa pos ,
|
|
which is a value between zero and one less than the size of the
|
|
storage buffer.
|
|
This effectively truncates the sbuf at the new position.
|
|
.Pp
|
|
The
|
|
.Fn sbuf_bcat
|
|
function appends the first
|
|
.Fa len
|
|
bytes from the buffer
|
|
.Fa buf
|
|
to the
|
|
.Fa sbuf .
|
|
.Pp
|
|
The
|
|
.Fn sbuf_bcopyin
|
|
function copies
|
|
.Fa len
|
|
bytes from the specified userland address into the
|
|
.Fa sbuf .
|
|
.Pp
|
|
The
|
|
.Fn sbuf_bcpy
|
|
function replaces the contents of the
|
|
.Fa sbuf
|
|
with the first
|
|
.Fa len
|
|
bytes from the buffer
|
|
.Fa buf .
|
|
.Pp
|
|
The
|
|
.Fn sbuf_cat
|
|
function appends the NUL-terminated string
|
|
.Fa str
|
|
to the
|
|
.Fa sbuf
|
|
at the current position.
|
|
.Pp
|
|
The
|
|
.Fn sbuf_copyin
|
|
function copies a NUL-terminated string from the specified userland
|
|
address into the
|
|
.Fa sbuf .
|
|
If the
|
|
.Fa len
|
|
argument is non-zero, no more than
|
|
.Fa len
|
|
characters (not counting the terminating NUL) are copied; otherwise
|
|
the entire string, or as much of it as can fit in the
|
|
.Fa sbuf ,
|
|
is copied.
|
|
.Pp
|
|
The
|
|
.Fn sbuf_cpy
|
|
function replaces the contents of the
|
|
.Fa sbuf
|
|
with those of the NUL-terminated string
|
|
.Fa str .
|
|
This is equivalent to calling
|
|
.Fn sbuf_cat
|
|
with a fresh
|
|
.Fa sbuf
|
|
or one which position has been reset to zero with
|
|
.Fn sbuf_clear
|
|
or
|
|
.Fn sbuf_setpos .
|
|
.Pp
|
|
The
|
|
.Fn sbuf_printf
|
|
function formats its arguments according to the format string pointed
|
|
to by
|
|
.Fa fmt
|
|
and appends the resulting string to the
|
|
.Fa sbuf
|
|
at the current position.
|
|
.Pp
|
|
The
|
|
.Fn sbuf_vprintf
|
|
function behaves the same as
|
|
.Fn sbuf_printf
|
|
except that the arguments are obtained from the variable-length argument list
|
|
.Fa ap .
|
|
.Pp
|
|
The
|
|
.Fn sbuf_putc
|
|
function appends the character
|
|
.Fa c
|
|
to the
|
|
.Fa sbuf
|
|
at the current position.
|
|
.Pp
|
|
The
|
|
.Fn sbuf_trim
|
|
function removes trailing whitespace from the
|
|
.Fa sbuf .
|
|
.Pp
|
|
The
|
|
.Fn sbuf_overflowed
|
|
function returns a non-zero value if the
|
|
.Fa sbuf
|
|
overflowed.
|
|
.Pp
|
|
The
|
|
.Fn sbuf_finish
|
|
function null-terminates the
|
|
.Fa sbuf
|
|
and marks it as finished, which means that it may no longer be
|
|
modified using
|
|
.Fn sbuf_setpos ,
|
|
.Fn sbuf_cat ,
|
|
.Fn sbuf_cpy ,
|
|
.Fn sbuf_printf
|
|
or
|
|
.Fn sbuf_putc .
|
|
.Pp
|
|
The
|
|
.Fn sbuf_data
|
|
and
|
|
.Fn sbuf_len
|
|
functions return the actual string and its length, respectively;
|
|
.Fn sbuf_data
|
|
only works on a finished
|
|
.Fa sbuf .
|
|
.Fn sbuf_done
|
|
returns non-zero if the sbuf is finished.
|
|
.Sh NOTES
|
|
If an operation caused an
|
|
.Fa sbuf
|
|
to overflow, most subsequent operations on it will fail until the
|
|
.Fa sbuf
|
|
is finished using
|
|
.Fn sbuf_finish
|
|
or reset using
|
|
.Fn sbuf_clear ,
|
|
or its position is reset to a value between 0 and one less than the
|
|
size of its storage buffer using
|
|
.Fn sbuf_setpos ,
|
|
or it is reinitialized to a sufficiently short string using
|
|
.Fn sbuf_cpy .
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn sbuf_new
|
|
function returns
|
|
.Dv NULL
|
|
if it failed to allocate a storage buffer, and a pointer to the new
|
|
.Fa sbuf
|
|
otherwise.
|
|
.Pp
|
|
The
|
|
.Fn sbuf_setpos
|
|
function returns \-1 if
|
|
.Fa pos
|
|
was invalid, and zero otherwise.
|
|
.Pp
|
|
The
|
|
.Fn sbuf_cat ,
|
|
.Fn sbuf_cpy ,
|
|
.Fn sbuf_printf ,
|
|
.Fn sbuf_putc ,
|
|
and
|
|
.Fn sbuf_trim
|
|
functions
|
|
all return \-1 if the buffer overflowed, and zero otherwise.
|
|
.Pp
|
|
The
|
|
.Fn sbuf_overflowed
|
|
function
|
|
returns a non-zero value if the buffer overflowed, and zero otherwise.
|
|
.Pp
|
|
The
|
|
.Fn sbuf_data
|
|
and
|
|
.Fn sbuf_len
|
|
functions return
|
|
.Dv NULL
|
|
and \-1, respectively, if the buffer overflowed.
|
|
.Pp
|
|
The
|
|
.Fn sbuf_copyin
|
|
function
|
|
returns \-1 if copying string from userland failed, and number of bytes
|
|
copied otherwise.
|
|
.Sh SEE ALSO
|
|
.Xr printf 3 ,
|
|
.Xr strcat 3 ,
|
|
.Xr strcpy 3 ,
|
|
.Xr copyin 9 ,
|
|
.Xr copyinstr 9 ,
|
|
.Xr printf 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
family of functions first appeared in
|
|
.Fx 4.4 .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The
|
|
.Nm
|
|
family of functions was designed by
|
|
.An Poul-Henning Kamp Aq phk@FreeBSD.org
|
|
and implemented by
|
|
.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
|
|
Additional improvements were suggested by
|
|
.An Justin T. Gibbs Aq gibbs@FreeBSD.org .
|
|
Auto-extend support added by
|
|
.An Kelly Yancey Aq kbyanc@FreeBSD.org .
|
|
.Pp
|
|
This manual page was written by
|
|
.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
|