vrb_take(3) [debian man page]
vrb_take(3) VRB Programmer's Manual vrb_take(3) NAME
vrb_take - take data from a VRB LIBRARY
-lvrb SYNOPSIS
#include <vrb.h> vrb_p vrb_take(vrb_p vrb, size_t size); DESCRIPTION
vrb_take specifies how much data has been obtained from the data portion of the virtual ring buffer by the caller. The caller will have called vrb_data_len(3) and vrb_data_ptr(3) to get the length of data in the buffer and a pointer to it, and having extract some data from the buffer, starting from the pointer obtained and extrating no more that the length obtained. ARGUMENTS
vrb_p vrb specifies which virtual ring buffer. size_t size specifies the length of data that has been obtained from the virtual ring buffer by the caller. RETURN VALUE
int On success, 0 is returned. On error, -1 is returned. ERRORS
If an error is returned, then errno will have one of the following values: EINVAL An invalid virtual ring buffer pointer was specified. ENOSPC The specified length is greater than the data in the virtual ring buffer. SEE ALSO
vrb(3), 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_uninit(3), vrb_write(3), vrb_write_min(3) vrb 2002-09-30 vrb_take(3)
Check Out this Related Man Page
vrb(3) VRB Programmer's Manual vrb(3) 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 con- tinuity 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 pro- gram 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) vrb 2002-09-30 vrb(3)