1 .TH VENTI-FCALL 3
2 .SH NAME
3 VtEntry, VtFcall, VtRoot,
4 vtentrypack,
5 vtentryunpack,
6 vtfcallclear,
7 vtfcallfmt,
8 vtfcallpack,
9 vtfcallunpack,
10 vtfromdisktype,
11 vttodisktype,
12 vtgetstring,
13 vtputstring,
14 vtrootpack,
15 vtrootunpack,
16 vtparsescore,
17 vtscorefmt \- Venti external data representation
18 .SH SYNOPSIS
19 .PP
20 .ft L
21 #include <u.h>
22 .br
23 #include <libc.h>
24 .br
25 #include <venti.h>
26 .ta +\w'\fLxxxx'u
27 .PP
28 .ft L
29 .nf
30 enum
31 {
32 	VtEntrySize = 40,
33 	VtRootSize = 300,
34 	VtRootVersion = 2,
35 	VtScoreSize = 20,
36 };
37 .PP
38 .ft L
39 .nf
40 typedef struct VtEntry
41 {
42 	ulong gen;			/* generation number */
43 	ushort psize;			/* pointer block size */
44 	ushort dsize;			/* data block size */
45 	uchar type;
46 	uchar flags;
47 	uvlong size;
48 	uchar score[VtScoreSize];
49 } VtEntry;
50 .PP
51 .ft L
52 .nf
53 typedef struct VtRoot
54 {
55 	char name[128];
56 	char type[128];
57 	uchar score[VtScoreSize];	/* to a Dir block */
58 	ushort blocksize;		/* maximum block size */
59 	uchar prev[VtScoreSize];	/* previous root block */
60 } VtRoot;
61 .ta +\w'\fLPacket* 'u
62 .PP
63 .B
64 void	vtentrypack(VtEntry *e, uchar *buf, int index)
65 .br
66 .B
67 int	vtentryunpack(VtEntry *e, uchar *buf, int index)
68 .PP
69 .B
70 Packet*	vtfcallpack(VtFcall *f)
71 .br
72 .B
73 int	vtfcallunpack(VtFcall *f, Packet *p)
74 .PP
75 .B
76 void vtfcallclear(VtFcall *f)
77 .PP
78 .B
79 uint	vttodisktype(uint type)
80 .br
81 .B
82 uint	vtfromdisktype(uint type)
83 .PP
84 .B
85 int	vtputstring(Packet *p, char *s)
86 .br
87 .B
88 int	vtgetstring(Packet *p, char **s)
89 .PP
90 .B
91 void	vtrootpack(VtRoot *r, uchar *buf)
92 .br
93 .B
94 int	vtrootunpack(VtRoot *r, uchar *buf)
95 .PP
96 .B
97 int	vtparsescore(char *s, char **prefix, uchar score[VtScoreSize])
98 .PP
99 .B
100 int	vtfcallfmt(Fmt *fmt)
101 .B
102 int	vtscorefmt(Fmt *fmt)
103 .SH DESCRIPTION
104 These routines convert between C representations of Venti
105 structures and serialized representations used on disk and
106 on the network.
107 .PP
108 .I Vtentrypack
109 converts a
110 .B VtEntry
111 structure describing a Venti file
112 (see
113 .IR venti (1))
114 into a 40-byte
115 .RB ( VtEntrySize )
116 structure at
117 .IB buf + index *40 \fR.
118 Vtentryunpack
119 does the reverse conversion.
120 .PP
121 .I Vtfcallpack
122 converts a
123 .B VtFcall
124 structure describing a Venti protocol message
125 (see
126 .IR venti (7))
127 into a packet.
128 .I Vtfcallunpack
129 does the reverse conversion.
130 .PP
131 The fields in a
132 .B VtFcall
133 are named after the protocol fields described in
134 .IR venti (7),
135 except that the
136 .B type
137 field is renamed
138 .BR blocktype .
139 The
140 .B msgtype
141 field holds the one-byte message type:
142 .BR VtThello ,
143 .BR VtRhello ,
144 and so on.
145 .PP
146 .I Vtfcallclear
147 frees the strings
148 .IB f ->error \fR,
149 .IB f ->version \fR,
150 .IB f ->uid \fR,
151 .IB f ->sid \fR,
152 the buffers
153 .I f ->crypto
154 and
155 .IB f ->codec \fR,
156 and the packet
157 .IB f ->data \fR.
158 .PP
159 The block type enumeration defined in
160 .B <venti.h>
161 (presented in 
162 .IR venti (1))
163 differs from the one used on disk and in the network
164 protocol.
165 The disk and network representation uses different
166 constants does not distinguish between
167 .BI VtDataType+ n
168 and
169 .BI VtDirType+ n
170 blocks.
171 .I Vttodisktype
172 converts a
173 .B <venti.h>
174 enumeration value to the disk value;
175 .I vtfromdisktype
176 converts a disk value to the enumeration value.
177 The
178 .B VtFcall
179 field
180 .B blocktype
181 is an enumeration value
182 .RI ( vtfcallpack
183 and
184 .I vtfcallunpack
185 convert to and from the disk values used in packets
186 automatically),
187 so most programs will not need to call these functions.
188 .PP
189 .I Vtputstring
190 appends the Venti protocol representation of the string
191 .I s
192 to the packet
193 .IR p .
194 .I Vtgetstring
195 reads a string from the packet, returning a pointer to a copy
196 of the string in
197 .BI * s \fR.
198 The copy must be freed by the caller.
199 These functions are used by
200 .I vtfcallpack
201 and
202 .IR vtfcallunpack ;
203 most programs will not need to call them directly.
204 .PP
205 .I Vtrootpack
206 converts a
207 .B VtRoot
208 structure describing a Venti file tree
209 into the 300-byte 
210 .RB ( VtRootSize )
211 buffer pointed to by
212 .IR buf .
213 .I Vtrootunpack does the reverse conversion.
214 .PP
215 .I Vtparsescore
216 parses the 40-digit hexadecimal string
217 .IR s ,
218 writing its value
219 into
220 .IR score .
221 If the hexadecimal string is prefixed with
222 a text label followed by a colon, a copy of that
223 label is returned in
224 .BI * prefix \fR.
225 If
226 .I prefix
227 is nil, the label is ignored.
228 .PP
229 .I Vtfcallfmt
230 and
231 .I vtscorefmt
232 are
233 .IR print (3)
234 formatters to print
235 .B VtFcall
236 structures and scores.
237 .I Vtfcallfmt
238 assumes that
239 .I vtscorefmt
240 is installed as
241 .BR %V .
242 .SH SOURCE
243 .B \*9/src/libventi
244 .SH SEE ALSO
245 .IR venti (1),
246 .IR venti (3),
247 .IR venti (7)
248 .SH DIAGNOSTICS
249 .IR Vtentrypack ,
250 .IR vtfcallpack ,
251 .IR vtrootpack ,
252 and
253 .I vtfcallclear
254 cannot fail.
255 .PP
256 .IR Vtentryunpack ,
257 .IR vtrootunpack ,
258 .IR vtputstring ,
259 .IR vtgetstring ,
260 and
261 .I vtparsescore
262 return 0 on success, \-1 on error.
263 .PP
264 .I Vtfcallpack
265 returns a packet on success, nil on error.
266 .PP
267 .I Vttodisktype
268 and
269 .I vtfromdisktype
270 return
271 .B VtCorruptType
272 (255)
273 when presented with invalid input.