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