tventi-conn.3 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tventi-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.