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