aboutsummaryrefslogtreecommitdiff
path: root/man/man3/venti-client.3
blob: ec18fc4e7f659dbf96c92ffb0377323937d18b9b (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
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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
.TH VENTI-CLIENT 3
.SH NAME
vtconnect, vthello, vtread, vtwrite, vtreadpacket, vtwritepacket, vtsync, vtping, vtrpc, ventidoublechecksha1 \- Venti client
.SH SYNOPSIS
.ft L
#include <u.h>
.br
#include <libc.h>
.br
#include <venti.h>
.ta +\w'\fLextern int 'u +\w'\fLxxxxxxxx'u
.PP
.B
Packet*	vtrpc(VtConn *z, Packet *p)
.PP
.B
int	vthello(VtConn *z)
.PP
.B
int	vtconnect(VtConn *z)
.PP
.B
int	vtread(VtConn *z, uchar score[VtScoreSize],
.br
.B
		uint type, uchar *buf, int n)
.PP
.B
int	vtwrite(VtConn *z, uchar score[VtScoreSize],
.br
.B
		uint type, uchar *buf, int n)
.PP
.B
Packet*	vtreadpacket(VtConn *z, uchar score[VtScoreSize],
.br
.B
		uint type, int n)
.PP
.B
int	vtwritepacket(VtConn *z, uchar score[VtScoreSize],
.br
.B
		uint type, Packet *p)
.PP
.B
int	vtsync(VtConn *z)
.PP
.B
int	vtping(VtConn *z)
.PP
.B
extern int	ventidoublechecksha1;	/* default 1 */
.SH DESCRIPTION
These routines execute the client side of the 
.IR venti (7)
protocol.
.PP
.I Vtrpc
executes a single Venti RPC transaction, sending the request 
packet
.IR p
and then waiting for and returning the response packet.
.I Vtrpc
will set the tag in the packet.
.I Vtrpc
frees
.IR p ,
even on error.
.I Vtrpc
is typically called only indirectly, via the functions below.
.PP
.I Vthello
executes a
.B hello
transaction
(see
.IR venti (7)), setting
.IB z -> sid
to the name used by the server.
.I Vthello
is typically called only indirectly, via
.IR vtconnect .
.PP
.I Vtconnect
calls
.I vtversion
(see
.IR venti-conn (3))
and
.IR vthello ,
in that order, returning success only
if both succeed.
This sequence (calling 
.I vtversion
and then
.IR vthello )
must be done before the functions below can be called.
.PP
.I Vtread
reads the block with the given
.I score
and
.I type
from the server,
writes the returned data
to
.IR buf ,
and returns the number of bytes retrieved.
If the stored block has size larger than
.IR n ,
.I vtread 
does not modify
.I buf
and
returns an error.
.PP
.I Vtwrite
writes the
.I n
bytes in 
.I buf
with type
.IR type ,
setting 
.IR score .
.PP
.I Vtreadpacket
and
.I vtwritepacket
are like
.I vtread
and
.I vtwrite
but return or accept the block contents in the
form of a
.BR Packet .
They avoid making a copy of the data.
.PP
.I Vtsync
causes the server to flush all pending write requests
to disk before returning.
.PP
.I Vtping
executes a ping transaction with the server.
.PP
By default,
.I vtread
and
.I vtreadpacket
check that the SHA1 hash of the returned data 
matches the requested
.IR score ,
and
.I vtwrite
and
.I vtwritepacket
check that the returned
.I score
matches the SHA1 hash of the written data.
Setting
.I ventidoublechecksha1
to zero disables these extra checks,
mainly for benchmarking purposes.
Doing so in production code is not recommended.
.PP
These functions can be called from multiple threads
or procs simultaneously to issue requests 
in parallel.
Programs that issue requests from multiple threads
in the same proc should start separate procs running
.I vtsendproc
and
.I vtrecvproc
as described in
.IR venti-conn (3).
.SH SOURCE
.B \*9/src/libventi
.SH SEE ALSO
.IR venti (1),
.IR venti (3),
.IR venti-conn (3),
.IR venti-packet (3),
.IR venti (7)
.SH DIAGNOSTICS
.I Vtrpc
and
.I vtpacket
return nil on error.
The other routines return \-1 on error.
.PP
.I Vtwrite
returns 0 on success,
meaning it wrote the entire block.