venti-fcall.3 (4744B)
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.