Man Linux: Main Page and Category List

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.
       Otherwise 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)