.TH "rb_read" "3" " 5 February 2018 (v3.0.0)" "bofc.pl"
.SH NAME
.PP
.BR rb_read ,
.B rb_recv
- functions to retrieve data from ring buffer
.SH SYNOPSIS
.PP
.BI "#include <librb.h>"
.PP
.BI "long rb_read(struct rb *" rb ", void *" buffer ", size_t " count ");"
.br
.BI "long rb_recv(struct rb *" rb ", void *" buffer ", size_t " count ", \
unsigned long " flags ");"
.fi
.SH DESCRIPTION
.PP
.BR rb_read (3)
copies at most
.I count
.B elements
from ring buffer
.I rb
to memory pointed by
.I buffer
.PP
Note that by
.B elements
n
we don't mean
.BR bytes .
For example if
.B object_size
is 4 bytes, and
.I count
is 3, this will copy 4 * 3 = 12 bytes into
.I buffer
Functions can and will try to commit as many bytes as possible in a single
burst, so it is better to call these function once with big
.I count
number than call it in a loop with
.I count
== 1.
.PP
By default buffer works in single-threaded mode.
In this mode all calls on
.I rb
object are non blocking.
This means if
.I count
.B elements
you want to read is higher than there is inside buffer, function
will copy only as much
.B elements
as there are inside
.I rb
and will return.
If
.BR read (3)
is called when buffer is empty,
.B EAGAIN
error will be returned.
.PP
If library has been built with
.B pthread
support, and
.I rb
was created with
.B O_MULTITHREAD
flag, all functions will be blocking calls.
That means if you want to copy more
.B elements
then there is inside
.I rb
object, calling thread will be put to sleep - and thus will use no CPU - until
someone else calls
.BR rb_write (3)
to write data to buffer and total
.I count
.B elements
have been copied into
.IR buffer .
.I rb
object in multi-threaded applications without mutexes.
.PP
.BR rb_recv (3)
works the same but it also accepts
.IR flags .
Possible
.I flags
are:
.TP
.B MSG_DONTWAIT
Only works in multi threaded environment, on single threaded mode this is
default.
When passed and
.I rb
buffer contains less
.B elements
than passed in
.IR count ,
function will copy all bytes from
.I rb
into
.I buffer
and will return immediately.
This means, function will never block, no matter what.
.TP
.B MSG_PEEK
Reads from
.I rb
into
.I buffer
as normal, but doesn't remove data from
.IR rb,
so consecutive calls to this function will return same data (provided
that nobody called
.BR rb_recv (3)
without this flag).
When this is called in threaded environment enabled, functions will act as if
.B MSG_DONTWAIT
flag was also passed.
It is guaranteed that calling function with this flag, will not alter internal
state of
.I rb object.
.SH RETURN VALUES
.PP
On successfull read, function will return number of
.B elements
it read and stored in
.IR buffer .
Returned value can be less than
.I count
if
.I rb
doesn't contain enough data and function operates in non blocking mode.
In such case it is also ok for function to return 0 - meaning buffer is empty.
On errors function returns -1, in such case,
.I rb
buffer is left intact.
.SH ERRORS
.TP
.B EINVAL
Any of the passed pointers is NULL.
.TP
.B EAGAIN
This error will be set, when
.I rb
is operating in non blocking mode, and there is no data to be read from
.I rb
immediately.
.TP
.B ECANCELED
.BR rb_stop (3)
was called, and operation was cancelled, because
.I rb
object is abou to be destroyed.
You should not access
.I rb
object after you receive this error.
Otherwise you will probably get deadlock or application will crash.
Returned only if threads are enabled.
.SH SEE ALSO
.PP
.BR rb_overview (7),
.BR rb_new (3),
.BR rb_destroy (3),
.BR rb_discard (3),
.BR rb_stop (3),
.BR rb_read (3),
.BR rb_recv (3),
.BR rb_write (3),
.BR rb_send (3),
.BR rb_clear (3),
.BR rb_count (3),
.BR rb_space (3),
.BR rb_version (3)