GSP
Quick Navigator

Search Site

Linux VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  - SBUF (9)

NAME

sbuf_new, sbuf_clear, sbuf_setpos, sbuf_bcat, sbuf_bcopyin, sbuf_bcpy, sbuf_cat, sbuf_copyin, sbuf_cpy, sbuf_printf, sbuf_vprintf, sbuf_putc, sbuf_trim, sbuf_overflowed, sbuf_finish, sbuf_data, sbuf_len, sbuf_done, sbuf_delete - safe string formatting

CONTENTS

Synopsis
Description
Notes
Return Values
See Also
History
Authors

SYNOPSIS


.In sys/types.h
.In sys/sbuf.h struct sbuf * sbuf_new struct sbuf *s char *buf int length int flags void sbuf_clear struct sbuf *s int sbuf_setpos struct sbuf *s int pos int sbuf_bcat struct sbuf *s const void *buf size_t len int sbuf_bcopyin struct sbuf *s const void *uaddr size_t len int sbuf_bcpy struct sbuf *s const void *buf size_t len int sbuf_cat struct sbuf *s const char *str int sbuf_copyin struct sbuf *s const void *uaddr size_t len int sbuf_cpy struct sbuf *s const char *str int sbuf_printf struct sbuf *s const char *fmt ... int sbuf_vprintf struct sbuf *s const char *fmt va_list ap int sbuf_putc struct sbuf *s int c int sbuf_trim struct sbuf *s int sbuf_overflowed struct sbuf *s void sbuf_finish struct sbuf *s char * sbuf_data struct sbuf *s int sbuf_len struct sbuf *s int sbuf_done struct sbuf *s void sbuf_delete struct sbuf *s

DESCRIPTION

The sbuf 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 sbufs, defined in
.In sys/sbuf.h .

The sbuf_new function initializes the sbuf pointed to by its first argument. If that pointer is NULL, sbuf_new allocates a
.Vt struct sbuf using malloc(9). The buf argument is a pointer to a buffer in which to store the actual string; if it is NULL, sbuf_new will allocate one using malloc(9). The length is the initial size of the storage buffer. The fourth argument, flags, may be comprised of the following flags:
SBUF_FIXEDLEN The storage buffer is fixed at its initial size. Attempting to extend the sbuf beyond this size results in an overflow condition.
SBUF_AUTOEXTEND
  This indicates that the storage buffer may be extended as necessary, so long as resources allow, to hold additional data.

Note that if buf is not NULL, it must point to an array of at least length characters. The result of accessing that array directly while it is in use by the sbuf is undefined.

The sbuf_delete function clears the sbuf and frees any memory allocated for it. There must be a call to sbuf_delete for every call to sbuf_new. Any attempt to access the sbuf after it has been deleted will fail.

The sbuf_clear function invalidates the contents of the sbuf and resets its position to zero.

The sbuf_setpos function sets the sbuf ’s end position to 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.

The sbuf_bcat function appends the first len bytes from the buffer buf to the sbuf.

The sbuf_bcopyin function copies len bytes from the specified userland address into the sbuf.

The sbuf_bcpy function replaces the contents of the sbuf with the first len bytes from the buffer buf.

The sbuf_cat function appends the NUL-terminated string str to the sbuf at the current position.

The sbuf_copyin function copies a NUL-terminated string from the specified userland address into the sbuf. If the len argument is non-zero, no more than len characters (not counting the terminating NUL) are copied; otherwise the entire string, or as much of it as can fit in the sbuf, is copied.

The sbuf_cpy function replaces the contents of the sbuf with those of the NUL-terminated string str. This is equivalent to calling sbuf_cat with a fresh sbuf or one which position has been reset to zero with sbuf_clear or sbuf_setpos.

The sbuf_printf function formats its arguments according to the format string pointed to by fmt and appends the resulting string to the sbuf at the current position.

The sbuf_vprintf function behaves the same as sbuf_printf except that the arguments are obtained from the variable-length argument list ap.

The sbuf_putc function appends the character c to the sbuf at the current position.

The sbuf_trim function removes trailing whitespace from the sbuf.

The sbuf_overflowed function returns a non-zero value if the sbuf overflowed.

The sbuf_finish function null-terminates the sbuf and marks it as finished, which means that it may no longer be modified using sbuf_setpos, sbuf_cat, sbuf_cpy, sbuf_printf or sbuf_putc.

The sbuf_data and sbuf_len functions return the actual string and its length, respectively; sbuf_data only works on a finished sbuf. sbuf_done returns non-zero if the sbuf is finished.

NOTES

If an operation caused an sbuf to overflow, most subsequent operations on it will fail until the sbuf is finished using sbuf_finish or reset using sbuf_clear, or its position is reset to a value between 0 and one less than the size of its storage buffer using sbuf_setpos, or it is reinitialized to a sufficiently short string using sbuf_cpy.

RETURN VALUES

sbuf_new returns NULL if it failed to allocate a storage buffer, and a pointer to the new sbuf otherwise.

sbuf_setpos returns -1 if pos was invalid, and zero otherwise.

sbuf_cat, sbuf_cpy, sbuf_printf, sbuf_putc, and sbuf_trim all return -1 if the buffer overflowed, and zero otherwise.

sbuf_overflowed returns a non-zero value if the buffer overflowed, and zero otherwise.

sbuf_data and sbuf_len return NULL and -1, respectively, if the buffer overflowed.

SEE ALSO

printf(3), strcat(3), strcpy(3), copyin(9), copyinstr(9), printf(9)

HISTORY

The sbuf family of functions first appeared in
.Fx 4.4 .

AUTHORS


.An -nosplit The sbuf 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 .

This manual page was written by
.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .

Search for    or go to Top of page |  Section 9 |  Main Index


July 9, 2004 SBUF (9)

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.