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 VtConn*	vtdial(char *addr)
32 .PP
33 .B
34 int	vtversion(VtConn *z)
35 .PP
36 .B
37 int	vtsend(VtConn *z, Packet *p)
38 .PP
39 .B
40 Packet*	vtrecv(VtConn *z)
41 .PP
42 .B
43 void	vtrecvproc(void *z)
44 .PP
45 .B
46 void	vtsendproc(void *z)
47 .PP
48 .B
49 void	vtdebug(VtConn *z, char *fmt, ...)
50 .PP
51 .B
52 void	vthangup(VtConn *z)
53 .PP
54 .B
55 void	vtfreeconn(VtConn *z)
56 .PP
57 .B
58 extern int	chattyventi;	/* default 0 */
59 .SH DESCRIPTION
60 A
61 .B VtConn
62 structure represents a connection to a Venti server
63 (when used by a client) or to a client (when used by a server).
64 .PP
65 .I Vtconn
66 initializes a new connection structure using file descriptors
67 .I infd
68 and
69 .I outfd
70 (which may be the same)
71 for reading and writing.
72 .I Vtdial
73 dials the given network address
74 (see
75 .IR dial (3))
76 and returns a corresponding connection.
77 It returns nil if the connection cannot be established.
78 .PP
79 .I Vtversion
80 exchanges version information with the remote side
81 as described in
82 .IR venti (7).
83 The negotiated version is stored in
84 .IB z -> version \fR.
85 .PP
86 .I Vtsend
87 writes a packet
88 (see
89 .IR venti-packet (3))
90 on the connection
91 .IR z .
92 The packet
93 .IR p
94 should be a formatted Venti message as might
95 be returned by
96 .IR vtfcallpack ;
97 .I vtsend
98 will add the two-byte length field
99 (see
100 .IR venti (7))
101 at the begnning.
102 .I Vtsend
103 frees
104 .IR p ,
105 even on error.
106 .PP
107 .I Vtrecv
108 reads a packet from the connection
109 .IR z .
110 Analogous to
111 .IR vtsend ,
112 the data read from the connection must start with
113 a two-byte length, but the returned packet will omit them.
114 .PP
115 By default, 
116 .I vtsend
117 and
118 .I vtrecv
119 block until the packet can be written or read from the network.
120 In a threaded program
121 (see
122 .IR thread (3)),
123 this may not be desirable.
124 If the caller arranges for
125 .IR vtsendproc
126 and
127 .IR vtrecvproc
128 to run in their own procs
129 (typically by calling
130 .IR proccreate ),
131 then
132 .I vtsend
133 and
134 .I vtrecv
135 will yield the proc in which they are run
136 to other threads when waiting on the network.
137 The
138 .B void*
139 argument to
140 .I vtsendproc
141 and
142 .I vtrecvproc
143 must be the connection structure
144 .IR z .
145 .PP
146 .I Vtdebug
147 prints the formatted message to standard error
148 when
149 .IB z -> debug
150 is set.  Otherwise it is a no-op.
151 .PP
152 .I Vthangup
153 hangs up a connection.
154 It closes the associated file descriptors
155 and shuts down send and receive procs if they have been
156 started.
157 Future calls to
158 .IR vtrecv
159 or
160 .IR vtsend
161 will return errors.
162 Additional calls to
163 .I vthangup
164 will have no effect.
165 .PP
166 .I Vtfreeconn
167 frees the connection structure, hanging it up first
168 if necessary.
169 .PP
170 If the global variable
171 .I chattyventi
172 is set, the library prints all Venti RPCs to standard error
173 as they are sent or received.
174 .SH SOURCE
175 .B \*9/src/libventi
176 .SH SEE ALSO
177 .IR venti (1),
178 .IR venti (3),
179 .IR venti-client (3),
180 .IR venti-packet (3),
181 .IR venti-server (3),
182 .IR venti (7)
183 .SH DIAGNOSTICS
184 Routines that return pointers return nil on error.
185 Routines returning integers return 0 on success, \-1 on error.
186 All routines set
187 .I errstr
188 on error.