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