aboutsummaryrefslogtreecommitdiffstats
path: root/man/rb_write.3
blob: c580315b7fb1f298d31760449b2368bfbb158ce5 (plain)
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
.TH "rb_write" "3" " 9 February 2018 (v1.0.0)" "bofc.pl"
.SH NAME
.PP
.BR rb_write,
.B rb_send
- functions to put data on ring buffer
.SH SYNOPSIS
.PP
.BI "#include <librb.h>"
.PP
.BI "long rb_write(struct rb *" rb ", const void *" buffer ", \
size_t " count ");"
.br
.BI "long rb_send(struct rb *" rb ", const void *" buffer ", \
size_t " count ", unsigned long " flags ");"
.SH DESCRIPTION
.PP
.BR rb_write (3)
copies at most
.I count
.B elements
from
.I buffer
to
.I rb
buffer.
.PP
Note 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 from
.I buffer
.PP
Write functions works the same way in multi/single-threaded mode as read ones.
Please see
.BR rb_read (3)
description for more details.
.PP
.BR rb_send (3)
works the same way as
.BR rb_write (3)
but also accepts following
.IR flags :
.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 free
.B elements
than passed in
.IR count,
function will copy all
.B elements
from
.I buffer
into
.I rb
and will return immediately.
.SH RETURN VALUES
.PP
On successfull write, function will return number of
.B elements
it stored in
.IR rb.
Returned value can be less than
.I count
if
.I rb
doesn't contain enough free space and function operates in non blocking mode.
In such case it is also ok for function to return 0 - meaning
.I rb
is full.
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 place in
.I rb
to write data from
.I buffer
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_clear (3),
.BR rb_count (3),
.BR rb_space (3),
.BR rb_version (3)