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 be7cbb4e 2005-07-12 devnull VtConn* vtdial(char *addr)
34 be7cbb4e 2005-07-12 devnull int vtversion(VtConn *z)
37 be7cbb4e 2005-07-12 devnull int vtsend(VtConn *z, Packet *p)
40 be7cbb4e 2005-07-12 devnull Packet* vtrecv(VtConn *z)
43 be7cbb4e 2005-07-12 devnull void vtrecvproc(void *z)
46 be7cbb4e 2005-07-12 devnull void vtsendproc(void *z)
49 be7cbb4e 2005-07-12 devnull void vtdebug(VtConn *z, char *fmt, ...)
52 be7cbb4e 2005-07-12 devnull void vthangup(VtConn *z)
55 be7cbb4e 2005-07-12 devnull void vtfreeconn(VtConn *z)
58 be7cbb4e 2005-07-12 devnull extern int chattyventi; /* default 0 */
59 be7cbb4e 2005-07-12 devnull .SH DESCRIPTION
61 be7cbb4e 2005-07-12 devnull .B VtConn
62 be7cbb4e 2005-07-12 devnull structure represents a connection to a Venti server
63 be7cbb4e 2005-07-12 devnull (when used by a client) or to a client (when used by a server).
64 3aec33fe 2005-07-18 devnull It contains the following user-visible fields:
65 3aec33fe 2005-07-18 devnull .BR debug ,
66 3aec33fe 2005-07-18 devnull a flag enabling debugging prints;
67 3aec33fe 2005-07-18 devnull .BR version ,
68 3aec33fe 2005-07-18 devnull the protocol version in use;
69 3aec33fe 2005-07-18 devnull .BR uid ,
70 3aec33fe 2005-07-18 devnull the (unverified) name of the client;
71 3aec33fe 2005-07-18 devnull .BR sid ,
72 3aec33fe 2005-07-18 devnull the (unverified) name of the server;
74 3aec33fe 2005-07-18 devnull .BR addr ,
75 3aec33fe 2005-07-18 devnull the network address of the remote side.
77 be7cbb4e 2005-07-12 devnull .I Vtconn
78 be7cbb4e 2005-07-12 devnull initializes a new connection structure using file descriptors
82 be7cbb4e 2005-07-12 devnull (which may be the same)
83 be7cbb4e 2005-07-12 devnull for reading and writing.
84 be7cbb4e 2005-07-12 devnull .I Vtdial
85 be7cbb4e 2005-07-12 devnull dials the given network address
87 be7cbb4e 2005-07-12 devnull .IR dial (3))
88 be7cbb4e 2005-07-12 devnull and returns a corresponding connection.
89 be7cbb4e 2005-07-12 devnull It returns nil if the connection cannot be established.
91 be7cbb4e 2005-07-12 devnull .I Vtversion
92 be7cbb4e 2005-07-12 devnull exchanges version information with the remote side
93 be7cbb4e 2005-07-12 devnull as described in
94 be7cbb4e 2005-07-12 devnull .IR venti (7).
95 be7cbb4e 2005-07-12 devnull The negotiated version is stored in
96 3aec33fe 2005-07-18 devnull .IB z ->version \fR.
98 be7cbb4e 2005-07-12 devnull .I Vtsend
99 be7cbb4e 2005-07-12 devnull writes a packet
101 be7cbb4e 2005-07-12 devnull .IR venti-packet (3))
102 be7cbb4e 2005-07-12 devnull on the connection
104 be7cbb4e 2005-07-12 devnull The packet
106 be7cbb4e 2005-07-12 devnull should be a formatted Venti message as might
107 be7cbb4e 2005-07-12 devnull be returned by
108 be7cbb4e 2005-07-12 devnull .IR vtfcallpack ;
109 be7cbb4e 2005-07-12 devnull .I vtsend
110 be7cbb4e 2005-07-12 devnull will add the two-byte length field
112 be7cbb4e 2005-07-12 devnull .IR venti (7))
113 be7cbb4e 2005-07-12 devnull at the begnning.
114 be7cbb4e 2005-07-12 devnull .I Vtsend
117 be7cbb4e 2005-07-12 devnull even on error.
119 be7cbb4e 2005-07-12 devnull .I Vtrecv
120 be7cbb4e 2005-07-12 devnull reads a packet from the connection
122 be7cbb4e 2005-07-12 devnull Analogous to
123 be7cbb4e 2005-07-12 devnull .IR vtsend ,
124 be7cbb4e 2005-07-12 devnull the data read from the connection must start with
125 be7cbb4e 2005-07-12 devnull a two-byte length, but the returned packet will omit them.
127 be7cbb4e 2005-07-12 devnull By default,
128 be7cbb4e 2005-07-12 devnull .I vtsend
130 be7cbb4e 2005-07-12 devnull .I vtrecv
131 be7cbb4e 2005-07-12 devnull block until the packet can be written or read from the network.
132 be7cbb4e 2005-07-12 devnull In a threaded program
134 be7cbb4e 2005-07-12 devnull .IR thread (3)),
135 be7cbb4e 2005-07-12 devnull this may not be desirable.
136 be7cbb4e 2005-07-12 devnull If the caller arranges for
137 be7cbb4e 2005-07-12 devnull .IR vtsendproc
139 be7cbb4e 2005-07-12 devnull .IR vtrecvproc
140 be7cbb4e 2005-07-12 devnull to run in their own procs
141 be7cbb4e 2005-07-12 devnull (typically by calling
142 be7cbb4e 2005-07-12 devnull .IR proccreate ),
144 be7cbb4e 2005-07-12 devnull .I vtsend
146 be7cbb4e 2005-07-12 devnull .I vtrecv
147 be7cbb4e 2005-07-12 devnull will yield the proc in which they are run
148 be7cbb4e 2005-07-12 devnull to other threads when waiting on the network.
150 be7cbb4e 2005-07-12 devnull .B void*
151 be7cbb4e 2005-07-12 devnull argument to
152 be7cbb4e 2005-07-12 devnull .I vtsendproc
154 be7cbb4e 2005-07-12 devnull .I vtrecvproc
155 be7cbb4e 2005-07-12 devnull must be the connection structure
158 be7cbb4e 2005-07-12 devnull .I Vtdebug
159 be7cbb4e 2005-07-12 devnull prints the formatted message to standard error
161 3aec33fe 2005-07-18 devnull .IB z ->debug
162 be7cbb4e 2005-07-12 devnull is set. Otherwise it is a no-op.
164 be7cbb4e 2005-07-12 devnull .I Vthangup
165 be7cbb4e 2005-07-12 devnull hangs up a connection.
166 be7cbb4e 2005-07-12 devnull It closes the associated file descriptors
167 be7cbb4e 2005-07-12 devnull and shuts down send and receive procs if they have been
168 be7cbb4e 2005-07-12 devnull started.
169 be7cbb4e 2005-07-12 devnull Future calls to
170 be7cbb4e 2005-07-12 devnull .IR vtrecv
172 be7cbb4e 2005-07-12 devnull .IR vtsend
173 be7cbb4e 2005-07-12 devnull will return errors.
174 be7cbb4e 2005-07-12 devnull Additional calls to
175 be7cbb4e 2005-07-12 devnull .I vthangup
176 be7cbb4e 2005-07-12 devnull will have no effect.
178 be7cbb4e 2005-07-12 devnull .I Vtfreeconn
179 be7cbb4e 2005-07-12 devnull frees the connection structure, hanging it up first
180 be7cbb4e 2005-07-12 devnull if necessary.
182 be7cbb4e 2005-07-12 devnull If the global variable
183 be7cbb4e 2005-07-12 devnull .I chattyventi
184 be7cbb4e 2005-07-12 devnull is set, the library prints all Venti RPCs to standard error
185 be7cbb4e 2005-07-12 devnull as they are sent or received.
186 be7cbb4e 2005-07-12 devnull .SH SOURCE
187 be7cbb4e 2005-07-12 devnull .B \*9/src/libventi
188 be7cbb4e 2005-07-12 devnull .SH SEE ALSO
189 be7cbb4e 2005-07-12 devnull .IR venti (1),
190 be7cbb4e 2005-07-12 devnull .IR venti (3),
191 be7cbb4e 2005-07-12 devnull .IR venti-client (3),
192 be7cbb4e 2005-07-12 devnull .IR venti-packet (3),
193 be7cbb4e 2005-07-12 devnull .IR venti-server (3),
194 be7cbb4e 2005-07-12 devnull .IR venti (7)
195 be7cbb4e 2005-07-12 devnull .SH DIAGNOSTICS
196 be7cbb4e 2005-07-12 devnull Routines that return pointers return nil on error.
197 be7cbb4e 2005-07-12 devnull Routines returning integers return 0 on success, \-1 on error.
198 be7cbb4e 2005-07-12 devnull All routines set
199 be7cbb4e 2005-07-12 devnull .I errstr
200 be7cbb4e 2005-07-12 devnull on error.
