The OpenNET Project / Index page

[ новости /+++ | форум | теги | ]

Интерактивная система просмотра системных руководств (man-ов)

 ТемаНаборКатегория 
 
 [Cписок руководств | Печать]

sbuf (9)
  • >> sbuf (9) ( FreeBSD man: Ядро )

  • BSD mandoc
     

    NAME

    
    
    sbuf
    
     
    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

       #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 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 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 .

    The sbuf_new ();
    function initializes the Fa sbuf pointed to by its first argument. If that pointer is NULL sbuf_new ();
    allocates a Vt struct sbuf using malloc(9). The Fa 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 Fa length is the initial size of the storage buffer. The fourth argument, Fa 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 Fa buf is not 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.

    The sbuf_delete ();
    function clears the Fa 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 Fa sbuf and resets its position to zero.

    The 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.

    The sbuf_bcat ();
    function appends the first Fa len bytes from the buffer Fa buf to the Fa sbuf .

    The sbuf_bcopyin ();
    function copies Fa len bytes from the specified userland address into the Fa sbuf .

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

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

    The 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.

    The sbuf_cpy ();
    function replaces the contents of the Fa sbuf with those of the NUL-terminated string Fa str . This is equivalent to calling sbuf_cat ();
    with a fresh Fa 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 Fa fmt and appends the resulting string to the Fa 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 Fa ap .

    The sbuf_putc ();
    function appends the character Fa c to the Fa sbuf at the current position.

    The sbuf_trim ();
    function removes trailing whitespace from the Fa sbuf .

    The sbuf_overflowed ();
    function returns a non-zero value if the Fa sbuf overflowed.

    The sbuf_finish ();
    function null-terminates the Fa 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 Fa sbuf . sbuf_done ();
    returns non-zero if the sbuf is finished.  

    NOTES

    If an operation caused an Fa sbuf to overflow, most subsequent operations on it will fail until the Fa 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

    The sbuf_new ();
    function returns NULL if it failed to allocate a storage buffer, and a pointer to the new Fa sbuf otherwise.

    The sbuf_setpos ();
    function returns -1 if Fa pos was invalid, and zero otherwise.

    The sbuf_cat (,);
    sbuf_cpy (,);
    sbuf_printf (,);
    sbuf_putc (,);
    and sbuf_trim ();
    functions all return -1 if the buffer overflowed, and zero otherwise.

    The sbuf_overflowed ();
    function returns a non-zero value if the buffer overflowed, and zero otherwise.

    The sbuf_data ();
    and sbuf_len ();
    functions return NULL and -1, respectively, if the buffer overflowed.

    The sbuf_copyin ();
    function returns -1 if copying string from userland failed, and number of bytes copied otherwise.  

    SEE ALSO

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

    HISTORY

    The family of functions first appeared in Fx 4.4 .  

    AUTHORS

    An -nosplit The family of functions was designed by An Poul-Henning Kamp Aq [email protected] and implemented by An Dag-Erling Sm/orgrav Aq [email protected] . Additional improvements were suggested by An Justin T. Gibbs Aq [email protected] . Auto-extend support added by An Kelly Yancey Aq [email protected] .

    This manual page was written by An Dag-Erling Sm/orgrav Aq [email protected] .


     

    Index

    NAME
    SYNOPSIS
    DESCRIPTION
    NOTES
    RETURN VALUES
    SEE ALSO
    HISTORY
    AUTHORS


    Поиск по тексту MAN-ов: 




    Партнёры:
    PostgresPro
    Inferno Solutions
    Hosting by Hoster.ru
    Хостинг:

    Закладки на сайте
    Проследить за страницей
    Created 1996-2024 by Maxim Chirkov
    Добавить, Поддержать, Вебмастеру