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