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'\fLPacket* '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 .MR 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, setting
77 .IB z ->sid
78 to the name used by the server.
79 .I Vthello
80 is typically called only indirectly, via
81 .IR vtconnect .
82 .PP
83 .I Vtconnect
84 calls
85 .I vtversion
86 (see
87 .MR venti-conn (3) )
88 and
89 .IR vthello ,
90 in that order, returning success only
91 if both succeed.
92 This sequence (calling 
93 .I vtversion
94 and then
95 .IR vthello )
96 must be done before the functions below can be called.
97 .PP
98 .I Vtread
99 reads the block with the given
100 .I score
101 and
102 .I type
103 from the server,
104 stores the returned data
105 in memory at
106 .IR buf ,
107 and returns the number of bytes read.
108 If the server's block has size larger than
109 .IR n ,
110 .I vtread 
111 does not modify
112 .I buf
113 and
114 returns an error.
115 .PP
116 .I Vtwrite
117 writes the
118 .I n
119 bytes in 
120 .I buf
121 as a block of the given
122 .IR type ,
123 setting 
124 .IR score .
125 .PP
126 .I Vtreadpacket
127 and
128 .I vtwritepacket
129 are like
130 .I vtread
131 and
132 .I vtwrite
133 but return or accept the block contents in the
134 form of a
135 .BR Packet .
136 They avoid making a copy of the data.
137 .PP
138 .I Vtsync
139 causes the server to flush all pending write requests
140 to disk before returning.
141 .PP
142 .I Vtping
143 executes a ping transaction with the server.
144 .PP
145 By default,
146 .I vtread
147 and
148 .I vtreadpacket
149 check that the SHA1 hash of the returned data 
150 matches the requested
151 .IR score ,
152 and
153 .I vtwrite
154 and
155 .I vtwritepacket
156 check that the returned
157 .I score
158 matches the SHA1 hash of the written data.
159 Setting
160 .I ventidoublechecksha1
161 to zero disables these extra checks,
162 mainly for benchmarking purposes.
163 Doing so in production code is not recommended.
164 .PP
165 These functions can be called from multiple threads
166 or procs simultaneously to issue requests 
167 in parallel.
168 Programs that issue requests from multiple threads
169 in the same proc should start separate procs running
170 .I vtsendproc
171 and
172 .I vtrecvproc
173 as described in
174 .MR venti-conn (3) .
175 .SH SOURCE
176 .B \*9/src/libventi
177 .SH SEE ALSO
178 .MR venti (3) ,
179 .MR venti-conn (3) ,
180 .MR venti-packet (3) ,
181 .MR venti (7)
182 .SH DIAGNOSTICS
183 .I Vtrpc
184 and
185 .I vtpacket
186 return nil on error.
187 The other routines return \-1 on error.
188 .PP
189 .I Vtwrite
190 returns 0 on success: there are no partial writes.