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