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