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