1 .TH VENTI-SERVER 3
2 .SH NAME
3 vtsrvhello, vtlisten, vtgetreq, vtrespond \- Venti server
4 .SH SYNOPSIS
5 .PP
6 .ft L
7 #include <u.h>
8 .br
9 #include <libc.h>
10 .br
11 #include <venti.h>
12 .ta +\w'\fLVtReq* 'u
13 .PP
14 .ft L
15 .nf
16 typedef struct VtReq
17 {
18 	VtFcall tx;
19 	VtFcall rx;
20 	...
21 } VtReq;
22 .PP
23 .B
24 int	vtsrvhello(VtConn *z)
25 .PP
26 .B
27 VtSrv*	vtlisten(char *addr)
28 .PP
29 .B
30 VtReq*	vtgetreq(VtSrv *srv)
31 .PP
32 .B
33 void	vtrespond(VtReq *req)
34 .SH DESCRIPTION
35 These routines execute the server side of the
36 .MR venti (7)
37 protocol.
38 .PP
39 .I Vtsrvhello
40 executes the server side of the initial
41 .B hello
42 transaction.
43 It sets
44 .IB z -> uid
45 with the user name claimed by the other side.
46 Each new connection must be initialized by running
47 .I vtversion
48 and then
49 .IR vtsrvhello .
50 The framework below takes care of this detail automatically;
51 .I vtsrvhello
52 is provided for programs that do not use the functions below.
53 .PP
54 .IR Vtlisten ,
55 .IR vtgetreq ,
56 and
57 .I vtrespond
58 provide a simple framework for writing Venti servers.
59 .PP
60 .I Vtlisten
61 announces at the network address
62 .IR addr ,
63 returning a fresh
64 .B VtSrv
65 structure representing the service.
66 .PP
67 .I Vtgetreq
68 waits for and returns
69 the next 
70 .BR read ,
71 .BR write ,
72 .BR sync ,
73 or
74 .B ping
75 request from any client connected to
76 the service
77 .IR srv .
78 .B Hello
79 and
80 .B goodbye
81 messages are handled internally and not returned to the client.
82 The interface does not distinguish between the
83 different clients that may be connected at any given time.
84 The request can be found in the
85 .I tx
86 field of the returned
87 .BR VtReq .
88 .PP
89 Once a request has been served and a response stored in
90 .IB r ->rx \fR,
91 the server should call
92 .IR vtrespond
93 to send the response to the client.
94 .I Vtrespond
95 frees the structure
96 .I r
97 as well as the packets
98 .IB r ->tx.data
99 and
100 .IB r ->rx.data \fR.
101 .SH EXAMPLE
102 .B \*9/src/venti/cmd
103 contains two simple Venti servers 
104 .B ro.c
105 and
106 .B devnull.c
107 written using these routines.
108 .I Ro
109 is a read-only Venti proxy (it rejects
110 .B write
111 requests).
112 .I Devnull
113 is a dangerous write-only Venti server: it discards all
114 blocks written to it and returns error on all reads.
115 .SH SOURCE
116 .B \*9/src/libventi
117 .SH SEE ALSO
118 .MR venti (3) ,
119 .MR venti-conn (3) ,
120 .MR venti-packet (3) ,
121 .MR venti (7) ,
122 .MR venti (8)