vrb_new(3) [debian man page]

vrb_new(3)						      VRB Programmer's Manual							vrb_new(3)

NAME

       vrb_new - create a new virtual ring buffer

LIBRARY

       -lvrb

SYNOPSIS

       #include <vrb.h>

       vrb_p vrb_new(size_t size, const char *name);

DESCRIPTION

       vrb_new creates a new instance of a virtual ring buffer.

       A  virtual ring buffer is a character FIFO queue with the special property that any sequence of characters in the buffer may be accessed as
       a single contiguous block of memory, eliminating the need to split any sequence to handle a buffer wraparound.

ARGUMENTS

       size_t size
       specifies the requested minimum buffer size to be allocated.  The given value will be rounded up to the nearest or equal whole multiple	of
       the  system  page  size.  The virtual ring buffer is implemented by mapping two adjacent blocks of memory to the same memory object.  Thus,
       twice as much virtual address space will be used and the specified size must be less than half of the available virtual address	space  for
       this process.

       const char *name
       specifies an optional temporary name pattern or an actual name of a file to be used as backing store via mmap(2) in a mounted filesystem in
       which the process has write permission.	If the name string ends in "XXXXXX" then mkstemp(3) will be used to make the file unique.   Other-
       wise  it  will  be  used as is.	If the named file already exists or otherwise cannot be opened for write, an error will occur.	If NULL is
       given, swap space will be used as backing store via shmat(2).

RETURN VALUE

       vrb_p
       On success, a handle (pointer) to the newly created virtual ring buffer is returned.  On error, NULL is returned.

ERRORS

       If an error is returned, then errno will have one of the following values:

       EINVAL A buffer size was requested which is too large for address space allocation arithmetic.

       ENOMEM Out of memory allocating the virtual ring buffer structure.

       -      An errno value set by a failing system call.

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_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_new(3)

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)