1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
.TH "rb_read" "3" "25 January 2018 (v2.1.2)" "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
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 (if buffer wasn't created with
.B O_NONBLOCK
flag), every read and will block until it reads all element passed to the
function.
When read function blocks, caller thread is put to sleep, so it doesn't use any
processor time, until it is waked by opossite write call, ie. when ring buffer
is empty, and user calls
.BR rb_read (3),
thread will sleep until another thread calls
.BR rb_write (3)
and puts some data for read operation.
.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 EINVAL
.B MSG_PEEK
was passed but
.I rb
is operating in multi-threaded mode.
.TP
.B EAGAIN
This error will be set, when
.I rb
is operating in non blocking mode, and
.I rb
buffer contains less
.B elements
than requested by
.IR count .
Note, this is not an actual error, and will not happen when function returns -1.
.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_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)
|
