Provided by: libvrb0-dev_0.5.1-5.1_amd64 bug

NAME

       vrb - virtual ring buffer

LIBRARY

       -lvrb

HEADERS

       #include <vrb.h>

DESCRIPTION

       A  virtual  ring  buffer  is  a  character  FIFO  queue with the special property that any
       sequence of characters, either the data present in the buffer, or any empty space, may  be
       accessed  as a single contiguous block of memory, eliminating the need to deal with breaks
       in string continuity to test for wraparounds or splits, and allowing  the  direct  use  of
       string construction or parsing tools, such as snprintf(3), or sscanf(3).

       As  a  character  FIFO  queue,  data comes out in the same order as it was put it.  Unlike
       other FIFO queues and ring buffers, which have to chop up the  data  into  pieces,  and/or
       copy  the  data  between caller space and buffer space, the virtual ring buffer allows the
       calling program to access the buffer space directly because the data to be accessed to get
       from  the  buffer,  or  the  space  to  be accessed to put data into the buffer, is always
       addressesable as a single linear contiguous range of addresses.  When the caller is  going
       to  have  data  to  place  into the buffer, it obtains the pointer and length of available
       space, and can place the data directly into the buffer, usually eliminating  one  step  of
       copying.   For  example,  the  caller  can  use the pointer to read data directly into the
       buffer.  Or it can call functions, such as  snprintf(3),  to  make  conversions  directly.
       Likewise, when the caller is going to extract data from the buffer, it obtains the pointer
       and length of the data, and can directly address it in place.

       Once data has been placed into empty space, or extracted from a  data  space,  the  caller
       indicates how much was put in or taken out, and pointers are then updated accordingly.

       The VRB functions never copy data around within the buffer.  The property of always have a
       linear range of memory for both all the data in the buffer as well as all the empty  space
       in  the  buffer  is  implemented  by  memory mapping two virtual memory ranges to the same
       memory object, and making those two ranges immediately adjacent.   Thus  anything  in  the
       first  range  is seen identically in the second range.  A span of data or empty space that
       would wrap around is now simply extended from the first range into the second range.

FUNCTIONS

       vrb_new
              Create a new virtual ring buffer.

       vrb_new_opt
              Create a new virtual ring buffer with options.

       vrb_destroy
              Destroy an allocated virtual ring buffer.

       vrb_init
              Initialize a virtual ring buffer in a static struct.

       vrb_init_opt
              Initialize a virtual ring buffer in a static struct with options.

       vrb_uninit
              Uninitialize a virtual ring buffer in a static struct.

       vrb_capacity
              Obtain the total buffer capacity of a VRB.

       vrb_data_len
              Obtain the length of data in the buffer.

       vrb_data_ptr
              Obtain the pointer to the data in the buffer.

       vrb_space_len
              Obtain the length of empty space in the buffer.

       vrb_space_ptr
              Obtain the pointer to the empty space in the buffer.

       vrb_is_empty
              Determine if the buffer is currently empty.

       vrb_is_full
              Determine if the buffer is currently full.

       vrb_is_not_empty
              Determine if there is at least some data in the buffer.

       vrb_is_not_full
              Determine if there is at least some empty space in the buffer.

       vrb_give
              Indicate how much empty space had data put in by the caller.

       vrb_take
              Indicate how much data in the buffer was used by the caller.

       vrb_get
              Copy data from the virtual ring buffer to a caller location.

       vrb_get_min
              Copy a minimum amount of data from the VRB only if it will fit.

       vrb_put
              Copy data from a caller location to the virtual ring buffer.

       vrb_put_all
              Copy data to the VRB only if all of it will fit.

       vrb_read
              read(2) data into a VRB until EOF or full, or I/O would block.

       vrb_read_min
              read(2) a minimum amount of data into a VRB until EOF or full, or I/O would block.

       vrb_write
              write(2) data from a VRB until empty, or I/O would block.

       vrb_resize
              Change the size of a VRB while keeping any data in the buffer.

       vrb_move
              Move data from one VRB to another.

SEE ALSO

       vrb_capacity(3),    vrb_data_len(3),    vrb_data_ptr(3),    vrb_destroy(3),    vrb_get(3),
       vrb_get_min(3),     vrb_give(3),     vrb_init(3),     vrb_init_opt(3),    vrb_is_empty(3),
       vrb_is_full(3),   vrb_is_not_empty(3),   vrb_is_not_full(3),   vrb_move(3),    vrb_new(3),
       vrb_new_opt(3),  vrb_put(3),  vrb_put_all(3), vrb_read(3), vrb_read_min(3), vrb_resize(3),
       vrb_space_len(3),    vrb_space_ptr(3),    vrb_take(3),    vrb_uninit(3),     vrb_write(3),
       vrb_write_min(3)