fcall.3 (7055B)
1 .TH FCALL 3 2 .SH NAME 3 Fcall, convS2M, convD2M, convM2S, convM2D, fcallfmt, dirfmt, dirmodefmt, read9pmsg, statcheck, sizeS2M, sizeD2M \- interface to Plan 9 File protocol 4 .SH SYNOPSIS 5 .B #include <u.h> 6 .br 7 .B #include <libc.h> 8 .br 9 .br 10 .B #include <fcall.h> 11 .PP 12 .B 13 uint convS2M(Fcall *f, uchar *ap, uint nap) 14 .PP 15 .B 16 uint convD2M(Dir *d, uchar *ap, uint nap) 17 .PP 18 .B 19 uint convM2S(uchar *ap, uint nap, Fcall *f) 20 .PP 21 .B 22 uint convM2D(uchar *ap, uint nap, Dir *d, char *strs) 23 .PP 24 .B 25 int dirfmt(Fmt*) 26 .PP 27 .B 28 int fcallfmt(Fmt*) 29 .PP 30 .B 31 int dirmodefmt(Fmt*) 32 .PP 33 .B 34 int read9pmsg(int fd, uchar *buf, uint nbuf) 35 .PP 36 .B 37 int statcheck(uchar *buf, uint nbuf) 38 .PP 39 .B 40 uint sizeS2M(Fcall *f) 41 .PP 42 .B 43 uint sizeD2M(Dir *d) 44 .SH DESCRIPTION 45 These 46 routines convert messages in the machine-independent format of 47 the Plan 9 file protocol, 48 9P, to and from a more convenient form, 49 an 50 .B Fcall 51 structure: 52 .PP 53 .EX 54 .if n .ta 4n +6n +5n +6n +18n +4n 55 .if t .ta \w'xxxx'u +\w'short 'u +\w'xxxx'u +\w'ushort 'u +\w'ticket[TICKETLEN]; 'u +\w'/* 'u 56 #define MAXWELEM 16 57 58 typedef 59 struct Fcall 60 { 61 uchar type; 62 u32int fid; 63 ushort tag; 64 union { 65 struct { 66 u32int msize; /* Tversion, Rversion */ 67 char *version; /* Tversion, Rversion */ 68 }; 69 struct { 70 ushort oldtag; /* Tflush */ 71 }; 72 struct { 73 char *ename; /* Rerror */ 74 }; 75 struct { 76 Qid qid; /* Rattach, Ropen, Rcreate */ 77 u32int iounit; /* Ropen, Rcreate */ 78 }; 79 struct { 80 Qid aqid; /* Rauth */ 81 }; 82 struct { 83 u32int afid; /* Tauth, Tattach */ 84 char *uname; /* Tauth, Tattach */ 85 char *aname; /* Tauth, Tattach */ 86 }; 87 struct { 88 u32int perm; /* Tcreate */ 89 char *name; /* Tcreate */ 90 uchar mode; /* Tcreate, Topen */ 91 }; 92 struct { 93 u32int newfid; /* Twalk */ 94 ushort nwname; /* Twalk */ 95 char *wname[MAXWELEM]; /* Twalk */ 96 }; 97 struct { 98 ushort nwqid; /* Rwalk */ 99 Qid wqid[MAXWELEM]; /* Rwalk */ 100 }; 101 struct { 102 vlong offset; /* Tread, Twrite */ 103 u32int count; /* Tread, Twrite, Rread */ 104 char *data; /* Twrite, Rread */ 105 }; 106 struct { 107 ushort nstat; /* Twstat, Rstat */ 108 uchar *stat; /* Twstat, Rstat */ 109 }; 110 }; 111 } Fcall; 112 .EE 113 .EX 114 115 /* these are implemented as macros */ 116 117 uchar GBIT8(uchar*) 118 ushort GBIT16(uchar*) 119 ulong GBIT32(uchar*) 120 vlong GBIT64(uchar*) 121 122 void PBIT8(uchar*, uchar) 123 void PBIT16(uchar*, ushort) 124 void PBIT32(uchar*, ulong) 125 void PBIT64(uchar*, vlong) 126 127 #define BIT8SZ 1 128 #define BIT16SZ 2 129 #define BIT32SZ 4 130 #define BIT64SZ 8 131 .EE 132 .PP 133 This structure is defined in 134 .BR <fcall.h> . 135 See section 5 136 for a full description of 9P messages and their encoding. 137 For all message types, the 138 .B type 139 field of an 140 .B Fcall 141 holds one of 142 .BR Tversion , 143 .BR Rversion , 144 .BR Tattach , 145 .BR Rattach , 146 etc. (defined in an enumerated type in 147 .BR <fcall.h> ). 148 .B Fid 149 is used by most messages, and 150 .B tag 151 is used by all messages. 152 The other fields are used selectively by the message types 153 given in comments. 154 .PP 155 .I ConvM2S 156 takes a 9P message at 157 .I ap 158 of length 159 .IR nap , 160 and uses it to fill in 161 .B Fcall 162 structure 163 .IR f . 164 If the passed message 165 including any data for 166 .B Twrite 167 and 168 .B Rread 169 messages 170 is formatted properly, 171 the return value is the number of bytes the message occupied in the buffer 172 .IR ap , 173 which will always be less than or equal to 174 .IR nap ; 175 otherwise it is 0. 176 For 177 .B Twrite 178 and 179 .B Tread 180 messages, 181 .B data 182 is set to a pointer into the argument message, 183 not a copy. 184 .PP 185 .I ConvS2M 186 does the reverse conversion, turning 187 .I f 188 into a message starting at 189 .IR ap . 190 The length of the resulting message is returned. 191 For 192 .B Twrite 193 and 194 .B Rread 195 messages, 196 .B count 197 bytes starting at 198 .B data 199 are copied into the message. 200 .PP 201 The constant 202 .B IOHDRSZ 203 is a suitable amount of buffer to reserve for storing 204 the 9P header; 205 the data portion of a 206 .B Twrite 207 or 208 .B Rread 209 will be no more than the buffer size negotiated in the 210 .BR Tversion/Rversion 211 exchange, minus 212 .BR IOHDRSZ . 213 .PP 214 The routine 215 .I sizeS2M 216 returns the number of bytes required to store the machine-independent representation of the 217 .B Fcall 218 structure 219 .IR f , 220 including its initial 32-bit size field. 221 In other words, it reports the number of bytes produced 222 by a successful call to 223 .IR convS2M . 224 .PP 225 Another structure is 226 .BR Dir , 227 used by the routines described in 228 .MR stat (3) . 229 .I ConvM2D 230 converts the machine-independent form starting at 231 .I ap 232 into 233 .IR d 234 and returns the length of the machine-independent encoding. 235 The strings in the returned 236 .B Dir 237 structure are stored at successive locations starting at 238 .BR strs . 239 Usually 240 .B strs 241 will point to storage immediately after the 242 .B Dir 243 itself. 244 It can also be a 245 .B nil 246 pointer, in which case the string pointers in the returned 247 .B Dir 248 are all 249 .BR nil ; 250 however, the return value still includes their length. 251 .PP 252 .I ConvD2M 253 does the reverse translation, 254 also returning the length of the encoding. 255 If the buffer is too short, the return value will be 256 .B BIT16SZ 257 and the correct size will be returned in the first 258 .B BIT16SZ 259 bytes. 260 (If the buffer is less that 261 .BR BIT16SZ , 262 the return value is zero; therefore a correct test for 263 complete packing of the message is that the return value is 264 greater than 265 .BR BIT16SZ ). 266 The macro 267 .B GBIT16 268 can be used to extract the correct value. 269 The related macros with different sizes retrieve the corresponding-sized quantities. 270 .B PBIT16 271 and its brethren place values in messages. 272 With the exception of handling short buffers in 273 .IR convD2M , 274 these macros are not usually needed except by internal routines. 275 .PP 276 Analogous to 277 .IR sizeS2M , 278 .I sizeD2M 279 returns the number of bytes required to store the machine-independent representation of the 280 .B Dir 281 structure 282 .IR d , 283 including its initial 16-bit size field. 284 .PP 285 The routine 286 .B statcheck 287 checks whether the 288 .I nbuf 289 bytes of 290 .I buf 291 contain a validly formatted machine-independent 292 .B Dir 293 entry suitable as an argument, for example, for the 294 .B wstat 295 (see 296 .MR stat (3) ) 297 system call. 298 It checks that the sizes of all the elements of the the entry sum to exactly 299 .IR nbuf , 300 which is a simple but effective test of validity. 301 .I Nbuf 302 and 303 .I buf 304 should include the second two-byte (16-bit) length field that precedes the entry when 305 formatted in a 9P message (see 306 .IR stat (9p)); 307 in other words, 308 .I nbuf 309 is 2 plus the sum of the sizes of the entry itself. 310 .I Statcheck 311 also verifies that the length field has the correct value (that is, 312 .IB nbuf -2\f1). 313 It returns 314 .B 0 315 for a valid entry and 316 .B -1 317 for an incorrectly formatted entry. 318 .PP 319 .IR Dirfmt , 320 .IR fcallfmt , 321 and 322 .I dirmodefmt 323 are formatting routines, suitable for 324 .MR fmtinstall (3) . 325 They convert 326 .BR Dir* , 327 .BR Fcall* , 328 and 329 .BR long 330 values into string representations of the directory buffer, 331 .B Fcall 332 buffer, 333 or file mode value. 334 .I Fcallfmt 335 assumes that 336 .I dirfmt 337 has been installed with format letter 338 .L D 339 and 340 .I dirmodefmt 341 with format letter 342 .LR M . 343 .PP 344 .I Read9pmsg 345 calls 346 .MR read (3) 347 multiple times, if necessary, to read an entire 9P message into 348 .BR buf . 349 The return value is 0 for end of file, or -1 for error; it does not return 350 partial messages. 351 .SH SOURCE 352 .B \*9/src/lib9 353 .SH SEE ALSO 354 .MR intro (3) , 355 .MR 9p (3) , 356 .MR stat (3) , 357 .IR intro (9p)