1 .TH VENTI-CLIENT 3
2 .SH NAME
3 vtconnect, vthello, vtread, vtwrite, vtreadpacket, vtwritepacket, vtsync, vtping, vtrpc, ventidoublechecksha1 \- Venti client
4 .SH SYNOPSIS
5 .ft L
6 #include <u.h>
7 .br
8 #include <libc.h>
9 .br
10 #include <venti.h>
11 .ta +\w'\fLextern int 'u +\w'\fLxxxxxxxx'u
12 .PP
13 .B
14 Packet*	vtrpc(VtConn *z, Packet *p)
15 .PP
16 .B
17 int	vthello(VtConn *z)
18 .PP
19 .B
20 int	vtconnect(VtConn *z)
21 .PP
22 .B
23 int	vtread(VtConn *z, uchar score[VtScoreSize],
24 .br
25 .B
26 		uint type, uchar *buf, int n)
27 .PP
28 .B
29 int	vtwrite(VtConn *z, uchar score[VtScoreSize],
30 .br
31 .B
32 		uint type, uchar *buf, int n)
33 .PP
34 .B
35 Packet*	vtreadpacket(VtConn *z, uchar score[VtScoreSize],
36 .br
37 .B
38 		uint type, int n)
39 .PP
40 .B
41 int	vtwritepacket(VtConn *z, uchar score[VtScoreSize],
42 .br
43 .B
44 		uint type, Packet *p)
45 .PP
46 .B
47 int	vtsync(VtConn *z)
48 .PP
49 .B
50 int	vtping(VtConn *z)
51 .PP
52 .B
53 extern int	ventidoublechecksha1;	/* default 1 */
54 .SH DESCRIPTION
55 These routines execute the client side of the 
56 .IR venti (7)
57 protocol.
58 .PP
59 .I Vtrpc
60 executes a single Venti RPC transaction, sending the request 
61 packet
62 .IR p
63 and then waiting for and returning the response packet.
64 .I Vtrpc
65 will set the tag in the packet.
66 .I Vtrpc
67 frees
68 .IR p ,
69 even on error.
70 .I Vtrpc
71 is typically called only indirectly, via the functions below.
72 .PP
73 .I Vthello
74 executes a
75 .B hello
76 transaction
77 (see
78 .IR venti (7)), setting
79 .IB z -> sid
80 to the name used by the server.
81 .I Vthello
82 is typically called only indirectly, via
83 .IR vtconnect .
84 .PP
85 .I Vtconnect
86 calls
87 .I vtversion
88 (see
89 .IR venti-conn (3))
90 and
91 .IR vthello ,
92 in that order, returning success only
93 if both succeed.
94 This sequence (calling 
95 .I vtversion
96 and then
97 .IR vthello )
98 must be done before the functions below can be called.
99 .PP
100 .I Vtread
101 reads the block with the given
102 .I score
103 and
104 .I type
105 from the server,
106 writes the returned data
107 to
108 .IR buf ,
109 and returns the number of bytes retrieved.
110 If the stored block has size larger than
111 .IR n ,
112 .I vtread 
113 does not modify
114 .I buf
115 and
116 returns an error.
117 .PP
118 .I Vtwrite
119 writes the
120 .I n
121 bytes in 
122 .I buf
123 with type
124 .IR type ,
125 setting 
126 .IR score .
127 .PP
128 .I Vtreadpacket
129 and
130 .I vtwritepacket
131 are like
132 .I vtread
133 and
134 .I vtwrite
135 but return or accept the block contents in the
136 form of a
137 .BR Packet .
138 They avoid making a copy of the data.
139 .PP
140 .I Vtsync
141 causes the server to flush all pending write requests
142 to disk before returning.
143 .PP
144 .I Vtping
145 executes a ping transaction with the server.
146 .PP
147 By default,
148 .I vtread
149 and
150 .I vtreadpacket
151 check that the SHA1 hash of the returned data 
152 matches the requested
153 .IR score ,
154 and
155 .I vtwrite
156 and
157 .I vtwritepacket
158 check that the returned
159 .I score
160 matches the SHA1 hash of the written data.
161 Setting
162 .I ventidoublechecksha1
163 to zero disables these extra checks,
164 mainly for benchmarking purposes.
165 Doing so in production code is not recommended.
166 .PP
167 These functions can be called from multiple threads
168 or procs simultaneously to issue requests 
169 in parallel.
170 Programs that issue requests from multiple threads
171 in the same proc should start separate procs running
172 .I vtsendproc
173 and
174 .I vtrecvproc
175 as described in
176 .IR venti-conn (3).
177 .SH SOURCE
178 .B \*9/src/libventi
179 .SH SEE ALSO
180 .IR venti (1),
181 .IR venti (3),
182 .IR venti-conn (3),
183 .IR venti-packet (3),
184 .IR venti (7)
185 .SH DIAGNOSTICS
186 .I Vtrpc
187 and
188 .I vtpacket
189 return nil on error.
190 The other routines return \-1 on error.
191 .PP
192 .I Vtwrite
193 returns 0 on success,
194 meaning it wrote the entire block.