venti-conn.3 (3704B)
1 .TH VENTI-CONN 3 2 .SH NAME 3 VtConn, vtconn, vtdial, vtfreeconn, vtsend, vtrecv, vtversion, 4 vtdebug, vthangup \- Venti network connections 5 .SH SYNOPSIS 6 .PP 7 .ft L 8 #include <u.h> 9 .br 10 #include <libc.h> 11 .br 12 #include <venti.h> 13 .PP 14 .ft L 15 .nf 16 .ta +\w'\fL 'u 17 typedef struct VtConn { 18 int debug; 19 char *version; 20 char *uid; 21 char *sid; 22 char addr[256]; 23 ... 24 } VtConn; 25 .PP 26 .ta \w'\fLextern int 'u 27 .B 28 VtConn* vtconn(int infd, int outfd) 29 .PP 30 .B 31 int vtreconn(VtConn *z, int infd, int outfd) 32 .PP 33 .B 34 VtConn* vtdial(char *addr) 35 .PP 36 .B 37 int vtredial(VtConn *z, char *addr) 38 .PP 39 .B 40 int vtversion(VtConn *z) 41 .PP 42 .B 43 int vtsend(VtConn *z, Packet *p) 44 .PP 45 .B 46 Packet* vtrecv(VtConn *z) 47 .PP 48 .B 49 void vtrecvproc(void *z) 50 .PP 51 .B 52 void vtsendproc(void *z) 53 .PP 54 .B 55 void vtdebug(VtConn *z, char *fmt, ...) 56 .PP 57 .B 58 void vthangup(VtConn *z) 59 .PP 60 .B 61 void vtfreeconn(VtConn *z) 62 .PP 63 .B 64 extern int chattyventi; /* default 0 */ 65 .SH DESCRIPTION 66 A 67 .B VtConn 68 structure represents a connection to a Venti server 69 (when used by a client) or to a client (when used by a server). 70 It contains the following user-visible fields: 71 .BR debug , 72 a flag enabling debugging prints; 73 .BR version , 74 the protocol version in use; 75 .BR uid , 76 the (unverified) name of the client; 77 .BR sid , 78 the (unverified) name of the server; 79 and 80 .BR addr , 81 the network address of the remote side. 82 .PP 83 .I Vtconn 84 initializes a new connection structure using file descriptors 85 .I infd 86 and 87 .I outfd 88 (which may be the same) 89 for reading and writing. 90 .I Vtdial 91 dials the given network address 92 (see 93 .MR dial (3) ) 94 and returns a corresponding connection. 95 It returns nil if the connection cannot be established. 96 .PP 97 .I Vtversion 98 exchanges version information with the remote side 99 as described in 100 .MR venti (7) . 101 The negotiated version is stored in 102 .IB z ->version \fR. 103 .PP 104 .I Vtsend 105 writes a packet 106 (see 107 .MR venti-packet (3) ) 108 on the connection 109 .IR z . 110 The packet 111 .IR p 112 should be a formatted Venti message as might 113 be returned by 114 .IR vtfcallpack ; 115 .I vtsend 116 will add the two-byte length field 117 (see 118 .MR venti (7) ) 119 at the begnning. 120 .I Vtsend 121 frees 122 .IR p , 123 even on error. 124 .PP 125 .I Vtrecv 126 reads a packet from the connection 127 .IR z . 128 Analogous to 129 .IR vtsend , 130 the data read from the connection must start with 131 a two-byte length, but the returned packet will omit them. 132 .PP 133 By default, 134 .I vtsend 135 and 136 .I vtrecv 137 block until the packet can be written or read from the network. 138 In a threaded program 139 (see 140 .MR thread (3) ), 141 this may not be desirable. 142 If the caller arranges for 143 .IR vtsendproc 144 and 145 .IR vtrecvproc 146 to run in their own procs 147 (typically by calling 148 .IR proccreate ), 149 then 150 .I vtsend 151 and 152 .I vtrecv 153 will yield the proc in which they are run 154 to other threads when waiting on the network. 155 The 156 .B void* 157 argument to 158 .I vtsendproc 159 and 160 .I vtrecvproc 161 must be the connection structure 162 .IR z . 163 .PP 164 .I Vtdebug 165 prints the formatted message to standard error 166 when 167 .IB z ->debug 168 is set. Otherwise it is a no-op. 169 .PP 170 .I Vthangup 171 hangs up a connection. 172 It closes the associated file descriptors 173 and shuts down send and receive procs if they have been 174 started. 175 Future calls to 176 .IR vtrecv 177 or 178 .IR vtsend 179 will return errors. 180 Additional calls to 181 .I vthangup 182 will have no effect. 183 .PP 184 .I Vtfreeconn 185 frees the connection structure, hanging it up first 186 if necessary. 187 .PP 188 If the global variable 189 .I chattyventi 190 is set, the library prints all Venti RPCs to standard error 191 as they are sent or received. 192 .SH SOURCE 193 .B \*9/src/libventi 194 .SH SEE ALSO 195 .MR venti (1) , 196 .MR venti (3) , 197 .MR venti-client (3) , 198 .MR venti-packet (3) , 199 .MR venti-server (3) , 200 .MR venti (7) 201 .SH DIAGNOSTICS 202 Routines that return pointers return nil on error. 203 Routines returning integers return 0 on success, \-1 on error. 204 All routines set 205 .I errstr 206 on error.