GopherProxy

	tventi-fcall.3 - plan9port - [fork] Plan 9 from user space
	git clone git://src.adamsgaard.dk/plan9port
	Log
	Files
	Refs
	README
	LICENSE
	---
	tventi-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.