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