libstash_buf(3s)

NAME
buf, bufc - Reference-counted extensible buffer.

SYNOPSIS

  Single-threaded
#define _LIBSTASH_USE_BUF
#include <libstash/libstash.h> cw_buf_t *
buf_new (cw_buf_t * a_buf)

  Multi-threaded
#define _LIBSTASH_USE_BUF
#include <libstash/libstash_r.h> cw_buf_t *
buf_new (cw_buf_t * a_buf) cw_buf_t *
buf_new_r (cw_buf_t * a_buf)

  General
void
buf_delete (cw_buf_t * a_buf) void
buf_dump (cw_buf_t * a_buf, const char * a_prefix) cw_sint32_t
buf_get_size (cw_buf_t * a_buf) cw_uint32_t
buf_get_num_bufels (cw_buf_t * a_buf) const struct iovec *
buf_get_iovec (cw_buf_t * a_buf, cw_uint32_t a_max_data, cw_bool_t a_is_sys_iovec, int * r_iovec_count) cw_bool_t
buf_catenate_buf (cw_buf_t * a_a, cw_buf_t * a_b, cw_bool_t a_preserve) cw_bool_t
buf_split (cw_buf_t * a_a, cw_buf_t * a_b, cw_uint32_t a_offset) cw_bool_t
buf_prepend_bufc (cw_buf_t * a_buf, cw_bufc_t * a_bufc, cw_uint32_t a_beg_offset, cw_uint32_t a_end_offset) cw_bool_t
buf_append_bufc (cw_buf_t * a_buf, cw_bufc_t * a_bufc, cw_uint32_t a_beg_offset, cw_uint32_t a_end_offset) cw_bool_t
buf_release_head_data (cw_buf_t * a_buf, cw_uint32_t a_amount) cw_bool_t
buf_release_tail_data (cw_buf_t * a_buf, cw_uint32_t a_amount) cw_uint8_t
buf_get_uint8 (cw_buf_t * a_buf, cw_uint32_t a_offset) cw_uint32_t
buf_get_uint32 (cw_buf_t * a_buf, cw_uint32_t a_offset) cw_uint64_t
buf_get_uint64 (cw_buf_t * a_buf, cw_uint32_t a_offset) cw_bool_t
buf_set_uint8 (cw_buf_t * a_buf, cw_uint32_t a_offset, cw_uint_t32 a_val) cw_bool_t
buf_set_uint32 (cw_buf_t * a_buf, cw_uint32_t a_offset, cw_uint32_t a_val) cw_bool_t
buf_set_uint64 (cw_buf_t * a_buf, cw_uint32_t a_offset, cw_uint64_t a_val) cw_bool_t
buf_set_range (cw_buf_t * a_buf, cw_uint32_t a_offset, cw_uint32_t a_length, cw_uint8_t * a_val, cw_bool_t a_is_writeable) cw_bufc_t *
bufc_new (cw_bufc_t * a_bufc, void (*a_dealloc_func)(void * dealloc_arg, void * bufel), void * a_dealloc_arg)) void
bufc_delete (cw_bufc_t * a_bufc) void
bufc_set_buffer (cw_bufc_t * a_bufc, void * a_buffer, cw_uint32_t a_size , cw_bool_t a_is_writeable, void (*a_dealloc_func)(void * dealloc_arg, void * buffer, void * a_dealloc_arg) cw_uint32_t
bufc_get_size (cw_bufc_t * a_bufc)

  Debugging (dbg) symbols
None.

DESCRIPTION
The buf and bufc classes implement a buffer abstraction. These classes are designed specifically to handle streaming and transparent extensible buffering of data for applications such as socket programs. buf's are dynamically extensible and contractible, as well as reference counted. This means that data can be passed and internally shared among buf's without copying or worry of memory leaks. Depending on the application, this also allows for very compact use of memory buffers. Internally, a buf consists of an array of buffer elements, bufels, that reference bufc's. The bufc's are reference counted, such that each bufel reference to a bufc increases the bufc reference count. In addition, the library user has a reference to each bufc as when it is initialized. When data are passed among buf's, references are added to the affected bufc's, but no data are actually copied. When data are modified, they must be copied if there are multiple references, or if the bufc was marked as non-writeable in the bufc_set_buffer() call. Otherwise, data can be modified in place. Random access to data is O(log n), where n is the number of bufel's in the buf. Linear access, either forward or backward, is optimized to be fast in the general case. The most recent access is cached, so if the next access is in the same bufel, the cost for that access is O(1). The buf code provides an iovec (see readv(2)/writev(2)) interface for accessing the internals for read-only operations. In general, this interface shouldn't be needed except when using the writev() function. Once a bufc has been passed to buf_{pre,ap}pend_bufc(), its data must be treated as read-only. That is, the bufc must be treated as opaque as soon as any buf has a reference to it.

USAGE
cw_buf_t *
buf_new (cw_buf_t * a_buf)
cw_buf_t *
buf_new_r (cw_buf_t * a_buf)
    Input(s):
        a_buf:
            Pointer to space for a buf, or NULL.
    Output(s):
        retval:
            non-NULL: Pointer to a buf.
            NULL: Memory allocation. Can only occur if (NULL == a_buf).
    Description:
        Non-thread-safe and thread-safe constructors.
void
buf_delete (cw_buf_t * a_buf)
    Input(s):
        a_buf:
            Pointer to a buf.
    Output(s):
        None
    Description:
        Destructor.
void
buf_dump (cw_buf_t * a_buf, const char * a_prefix)
    Input(s):
        a_buf:
            Pointer to a buf.
        a_prefix:
            Pointer to a string that represents a string to be prefixed to each line of output.
    Output(s):
        a_buf's internals printed to cw_g_out.
    Description:
        Dump the internal state of a_buf to cw_g_out.
cw_sint32_t
buf_get_size (cw_buf_t * a_buf)
    Input(s):
        a_buf:
            Pointer to a buf.
    Output(s):
        retval:
            Number of bytes of valid data.
    Description:
        Return the amout of valid data in bytes.
cw_uint32_t
buf_get_num_bufels (cw_buf_t * a_buf)
    Input(s):
        a_buf:
            Pointer to a buf.
    Output(s):
        retval:
            Number of bufel's (internal buffer elements) in a_buf (same as iovec count in buf_get_iovec()).
    Description:
        Return the number of bufel's in a_buf.
const struct iovec *
buf_get_iovec (cw_buf_t * a_buf, cw_uint32_t a_max_data, cw_bool_t a_is_sys_iovec, int * r_iovec_count)
    Input(s):
        a_buf:
            Pointer to a buf.
        a_max_data:
            Maximum number of bytes of space to include in the iovec.
        a_is_sys_iovec:
            If TRUE, limit *r_iovec_count to the maximum iovec count supported by this system for readv()/writev().
        r_iovec_count:
            Pointer to an int.
    Output(s):
        retval:
            Pointer to an iovec array that represents the internal data buffers in a_buf.
        *r_iovec_count:
            Number of valid iovec structures in retval.
    Description:
        Build an iovec array that represents the valid data in a_buf's internal buffers (up to a_max_data bytes) and return a pointer to it.
cw_bool_t
buf_catenate_buf (cw_buf_t * a_a, cw_buf_t * a_b, cw_bool_t a_preserve)
    Input(s):
        a_a:
            Pointer to a buf.
        a_b:
            Pointer to a buf.
        a_preserve:
            If TRUE, preserve a_b (don't modify it). If FALSE, release the data in a_b after catenating a_b to a_a.
    Output(s):
        retval:
            FALSE: Success.
            TRUE: Memory allocation error.
    Description:
        Catenate two buf's. a_b is left unmodifed if a_preserve is TRUE; otherwise a_b is emptied.
cw_bool_t
buf_split (cw_buf_t * a_a, cw_buf_t * a_b, cw_uint32_t a_offset)
    Input(s):
        a_a:
            Pointer to a buf.
        a_b:
            Pointer to a buf.
        a_offset:
            Offset at which to split a_b.
    Output(s):
        retval:
            FALSE: Success.
            TRUE: Memory allocation error. a_a and a_b are unmodified.
    Description:
        Split a_b at offset a_offset. Append the data before a_offset to a_a, and leave the remainder in a_b.
cw_bool_t
buf_prepend_bufc (cw_buf_t * a_buf, cw_bufc_t * a_bufc, cw_uint32_t a_beg_offset, cw_uint32_t a_end_offset)
    Input(s):
        a_buf:
            Pointer to a buf.
        a_bufc:
            Pointer to a bufc.
        a_beg_offset:
            Offset of first valid byte in a_bufc's memory buffer.
        a_end_offset:
            Offset of first byte past the valid range of bytes in a_bufc's memory buffer.
    Output(s):
        retval:
            FALSE: Success.
            TRUE: Memory allocation error. a_buf and a_bufc are unmodified.
    Description:
        Prepend a_bufc, bytes a_beg_offset through (a_end_offset - 1) to a_buf.
cw_bool_t
buf_append_bufc (cw_buf_t * a_buf, cw_bufc_t * a_bufc, cw_uint32_t a_beg_offset, cw_uint32_t a_end_offset)
    Input(s):
        a_buf:
            Pointer to a buf.
        a_bufc:
            Pointer to a bufc.
        a_beg_offset:
            Offset of first valid byte in a_bufc's memory buffer.
        a_end_offset:
            Offset of first byte past the valid range of bytes in a_bufc's memory buffer.
    Output(s):
        retval:
            FALSE: Success.
            TRUE: Memory allocation error. a_buf and a_bufc are unmodified.
    Description:
        Append a_bufc, bytes a_beg_offset through (a_end_offset - 1) to a_buf.
cw_bool_t
buf_release_head_data (cw_buf_t * a_buf, cw_uint32_t a_amount)
    Input(s):
        a_buf:
            Pointer to a buf.
        a_amount:
            Number of bytes of data to release from the head of a_buf.
    Output(s):
        retval:
            FALSE: Success.
            TRUE: Error. (a_amount > buf_get_size(a_buf)).
    Description:
        Release a_amount bytes from the head of a_buf.
cw_bool_t
buf_release_tail_data (cw_buf_t * a_buf, cw_uint32_t a_amount)
    Input(s):
        a_buf:
            Pointer to a buf.
        a_amount:
            Number of bytes of data to release from the tail of a_buf.
    Output(s):
        retval:
            FALSE: Success.
            TRUE: Error. (a_amount > buf_get_size(a_buf)).
    Description:
        Release a_amount bytes from the tail of a_buf.
cw_uint8_t
buf_get_uint8 (cw_buf_t * a_buf, cw_uint32_t a_offset)
    Input(s):
        a_buf:
            Pointer to a buf.
        a_offset:
            Offset in bytes of uint8 to return.
    Output(s):
        retval:
            Value of the uint8 at offset a_offset in a_buf.
    Description:
        Return the uint8 at offset a_offset.
cw_uint32_t
buf_get_uint32 (cw_buf_t * a_buf, cw_uint32_t a_offset)
    Input(s):
        a_buf:
            Pointer to a buf.
        a_offset:
            Offset in bytes of uint32 to return.
    Output(s):
        retval:
            Value of the uint32 at offset a_offset in a_buf.
    Description:
        Return the uint32 at offset a_offset.
cw_uint64_t
buf_get_uint64 (cw_buf_t * a_buf, cw_uint32_t a_offset)
    Input(s):
        a_buf:
            Pointer to a buf.
        a_offset:
            Offset in bytes of uint64 to return.
    Output(s):
        retval:
            Value of the uint64 at offset a_offset in a_buf.
    Description:
        Return the uint64 at offset a_offset.
cw_bool_t
buf_set_uint8 (cw_buf_t * a_buf, cw_uint32_t a_offset, cw_uint_t32 a_val)
    Input(s):
        a_buf:
            Pointer to a buf.
        a_offset:
            Offset in bytes of data to set. (a_offset <= buf_get_size(a_buf)).
        a_val:
            Value to set data at a_offset to.
    Output(s):
        retval:
            FALSE: Success.
            TRUE: Memory allocation error.
    Description:
        Set the uint8 at a_offset to a_val.
cw_bool_t
buf_set_uint32 (cw_buf_t * a_buf, cw_uint32_t a_offset, cw_uint32_t a_val)
    Input(s):
        a_buf:
            Pointer to a buf.
        a_offset:
            Offset in bytes of data to set. (a_offset <= buf_get_size(a_buf)).
        a_val:
            Value to set data at a_offset to.
    Output(s):
        retval:
            FALSE: Success.
            TRUE: Memory allocation error.
    Description:
        Set the uint32 at a_offset to a_val.
cw_bool_t
buf_set_uint64 (cw_buf_t * a_buf, cw_uint32_t a_offset, cw_uint64_t a_val)
    Input(s):
        a_buf:
            Pointer to a buf.
        a_offset:
            Offset in bytes of data to set. (a_offset <= buf_get_size(a_buf)).
        a_val:
            Value to set data at a_offset to.
    Output(s):
        retval:
            FALSE: Success.
            TRUE: Memory allocation error.
    Description:
        Set the uint64 at a_offset to a_val.
cw_bool_t
buf_set_range (cw_buf_t * a_buf, cw_uint32_t a_offset, cw_uint32_t a_length, cw_uint8_t * a_val, cw_bool_t a_is_writeable)
    Input(s):
        a_buf:
            Pointer to a buf.
        a_offset:
            Offset in bytes of data to set. (a_offset <= buf_get_size(a_buf)).
        a_length:
            Number of bytes to copy from a_val.
        a_val:
            Value to set data at a_offset to.
        a_is_writeable:
            FALSE: Non-writeable buffer.
            TRUE: Writeable buffer.
    Output(s):
        retval:
            FALSE: Success.
            TRUE: Memory allocation error.
    Description:
        Copy a_offset bytes from a_val to a_buf at offset a_offset.
cw_bufc_t *
bufc_new (cw_bufc_t * a_bufc, void (*a_dealloc_func)(void * dealloc_arg, void * bufel), void * a_dealloc_arg))
    Input(s):
        a_bufc:
            Pointer to a bufc.
        a_dealloc_func:
            non-NULL: Pointer to a deallocation function.
            NULL: No deallocation function.
            Ignored if (NULL == a_bufc).
        a_dealloc_arg:
            First argument to a_dealloc_func.
    Output(s):
        retval:
            non-NULL: Pointer to a bufc.
            NULL: Memory allocation error.
    Description:
        Constructor.
void
bufc_delete (cw_bufc_t * a_bufc)
    Input(s):
        a_bufc:
            Pointer to a bufc.
    Output(s):
        None.
    Description:
        Destructor.
void
bufc_set_buffer (cw_bufc_t * a_bufc, void * a_buffer, cw_uint32_t a_size , cw_bool_t a_is_writeable, void (*a_dealloc_func)(void * dealloc_arg, void * buffer, void * a_dealloc_arg)
    Input(s):
        a_bufc:
            Pointer to a bufc.
        a_buffer:
            Pointer to a buffer.
        a_size:
            Size of buffer pointed to by a_buffer.
        a_is_writeable:
            FALSE: a_buffer may not be modified.
            TRUE: a_buffer may be modified if there is only one reference to it.
        a_dealloc_func:
            non-NULL: Pointer to a deallocation function.
            NULL: No deallocation function.
        a_dealloc_arg:
            First argument to a_dealloc_func.
    Output(s):
        None.
    Description:
        Set a_bufc's internal data buffer to a_buffer, with size a_size, and deallocation function a_dealloc_func(a_dealloc_arg, a_buffer). This function is not reentrant, and assumes that no other references to a_bufc exist (or at least they don't rely on the bufc's state). In other words, don't call this function after the bufc has been inserted into one or more buf's.
cw_uint32_t
bufc_get_size (cw_bufc_t * a_bufc)
    Input(s):
        a_bufc:
            Pointer to a bufc.
    Output(s):
        retval:
            Size of a_bufc's internal buffer.
    Description:
        Return the number of bytes in a_bufc's internal buffer.

SEE ALSO
libstash(3s), readv(2), writev(2).

HISTORY
Written by Jason Evans <jasone@canonware.com>.