*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->FreeBSD man pages -> sbuf (9)              
Title
Content
Arch
Section
 

SBUF(9)

Contents


NAME    [Toc]    [Back]

     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

SYNOPSIS    [Toc]    [Back]

     #include <sys/types.h>
     #include <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 char *str, size_t len);

     int
     sbuf_bcopyin(struct sbuf *s, const void *uaddr, size_t len);

     int
     sbuf_bcpy(struct sbuf *s, const char *str, 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    [Toc]    [Back]

     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 <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 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 contents of the provided buffer are undefined; to
     retrieve the sbuf data sbuf_data() must be called on the finished sbuf.

     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 byte string
     str 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 byte string str.

     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.

     Finally, the sbuf_delete() function clears the sbuf and frees its storage
     buffer if it was allocated by sbuf_new().

NOTES    [Toc]    [Back]

     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    [Toc]    [Back]

     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    [Toc]    [Back]

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

HISTORY    [Toc]    [Back]

     The sbuf family of functions first appeared in FreeBSD 4.4.

AUTHORS    [Toc]    [Back]

     The sbuf family of functions was designed by Poul-Henning Kamp
     <phk@FreeBSD.org> and implemented by Dag-Erling Coidan Smorgrav
     <des@FreeBSD.org>.  Additional improvements were suggested by Justin T.
     Gibbs <gibbs@FreeBSD.org>.  Auto-extend support added by Kelly Yancey
     <kbyanc@FreeBSD.org>.

     This manual page was written by Dag-Erling Coidan Smorgrav.


FreeBSD 5.2.1			January 3, 2002 		 FreeBSD 5.2.1
[ Back ]
 Similar pages
Name OS Title
pthread_once IRIX thread-safe initialization
tempfile Linux create a temporary file in a safe manner
mvGrabRelease IRIX provide safe usage of graphics libraries from Movie Playback Library clients
perlipc OpenBSD Perl interprocess communication (signals, fifos, pipes, safe subprocesses, sockets, and semaphores)
perlipc IRIX Perl interprocess communication (signals, fifos, pipes, safe subprocesses, sockets, and semaphores)
setlocale OpenBSD natural language formatting for C
man HP-UX macros for formatting manpages
localeconv FreeBSD natural language formatting for C
ios IRIX input/output formatting
setlocale FreeBSD natural language formatting for C
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service