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