venti-client.3 (3343B)
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.