aboutsummaryrefslogtreecommitdiff
path: root/man/man3/fcall.3
blob: 1219cf2042e4db884505c16d56de11c526cbb374 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
.TH FCALL 3
.SH NAME
Fcall, convS2M, convD2M, convM2S, convM2D, fcallfmt, dirfmt, dirmodefmt, read9pmsg, statcheck, sizeS2M, sizeD2M \- interface to Plan 9 File protocol
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.br
.B #include <fcall.h>
.PP
.B
uint convS2M(Fcall *f, uchar *ap, uint nap)
.PP
.B
uint convD2M(Dir *d, uchar *ap, uint nap)
.PP
.B
uint convM2S(uchar *ap, uint nap, Fcall *f)
.PP
.B
uint convM2D(uchar *ap, uint nap, Dir *d, char *strs)
.PP
.B
int dirfmt(Fmt*)
.PP
.B
int fcallfmt(Fmt*)
.PP
.B
int dirmodefmt(Fmt*)
.PP
.B
int read9pmsg(int fd, uchar *buf, uint nbuf)
.PP
.B
int statcheck(uchar *buf, uint nbuf)
.PP
.B
uint sizeS2M(Fcall *f)
.PP
.B
uint sizeD2M(Dir *d)
.SH DESCRIPTION
These
routines convert messages in the machine-independent format of
the Plan 9 file protocol,
9P, to and from a more convenient form,
an
.B Fcall
structure:
.PP
.EX
.if n .ta 4n +6n +5n +6n +18n +4n
.if t .ta \w'xxxx'u +\w'short 'u +\w'xxxx'u +\w'ushort 'u +\w'ticket[TICKETLEN]; 'u +\w'/* 'u
#define MAXWELEM 16

typedef
struct Fcall
{
	uchar	type;
	u32int	fid;
	ushort	tag;
	union {
		struct {
			u32int	msize;	/* Tversion, Rversion */
			char	*version;	/* Tversion, Rversion */
		};
		struct {
			ushort	oldtag;	/* Tflush */
		};
		struct {
			char	*ename;	/* Rerror */
		};
		struct {
			Qid	qid;	/* Rattach, Ropen, Rcreate */
			u32int	iounit;	/* Ropen, Rcreate */
		};
		struct {
			Qid	aqid;	/* Rauth */
		};
		struct {
			u32int	afid;	/* Tauth, Tattach */
			char	*uname;	/* Tauth, Tattach */
			char	*aname;	/* Tauth, Tattach */
		};
		struct {
			u32int	perm;	/* Tcreate */ 
			char	*name;	/* Tcreate */
			uchar	mode;	/* Tcreate, Topen */
		};
		struct {
			u32int	newfid;	/* Twalk */
			ushort	nwname;	/* Twalk */
			char	*wname[MAXWELEM];	/* Twalk */
		};
		struct {
			ushort	nwqid;	/* Rwalk */
			Qid	wqid[MAXWELEM];	/* Rwalk */
		};
		struct {
			vlong	offset;	/* Tread, Twrite */
			u32int	count;	/* Tread, Twrite, Rread */
			char	*data;	/* Twrite, Rread */
		};
		struct {
			ushort	nstat;	/* Twstat, Rstat */
			uchar	*stat;	/* Twstat, Rstat */
		};
	};
} Fcall;
.EE
.EX

/* these are implemented as macros */

uchar	GBIT8(uchar*)
ushort	GBIT16(uchar*)
ulong	GBIT32(uchar*)
vlong	GBIT64(uchar*)

void	PBIT8(uchar*, uchar)
void	PBIT16(uchar*, ushort)
void	PBIT32(uchar*, ulong)
void	PBIT64(uchar*, vlong)

#define	BIT8SZ	1
#define	BIT16SZ	2
#define	BIT32SZ	4
#define	BIT64SZ	8
.EE
.PP
This structure is defined in
.BR <fcall.h> .
See section 5
for a full description of 9P messages and their encoding.
For all message types, the
.B type
field of an
.B Fcall
holds one of
.BR Tversion ,
.BR Rversion ,
.BR Tattach ,
.BR Rattach ,
etc. (defined in an enumerated type in
.BR <fcall.h> ).
.B Fid
is used by most messages, and
.B tag
is used by all messages.
The other fields are used selectively by the message types
given in comments.
.PP
.I ConvM2S
takes a 9P message at
.I ap
of length
.IR nap ,
and uses it to fill in
.B Fcall
structure
.IR f .
If the passed message
including any data for
.B Twrite
and
.B Rread
messages
is formatted properly,
the return value is the number of bytes the message occupied in the buffer
.IR ap ,
which will always be less than or equal to
.IR nap ;
otherwise it is 0.
For
.B Twrite
and
.B Tread
messages,
.B data
is set to a pointer into the argument message,
not a copy.
.PP
.I ConvS2M
does the reverse conversion, turning
.I f
into a message starting at
.IR ap .
The length of the resulting message is returned.
For
.B Twrite
and
.B Rread
messages,
.B count
bytes starting at
.B data
are copied into the message.
.PP
The constant
.B IOHDRSZ
is a suitable amount of buffer to reserve for storing
the 9P header;
the data portion of a
.B Twrite
or
.B Rread
will be no more than the buffer size negotiated in the
.BR Tversion/Rversion
exchange, minus
.BR IOHDRSZ .
.PP
The routine
.I sizeS2M
returns the number of bytes required to store the machine-independent representation of the
.B Fcall
structure
.IR f ,
including its initial 32-bit size field.
In other words, it reports the number of bytes produced
by a successful call to
.IR convS2M .
.PP
Another structure is
.BR Dir ,
used by the routines described in
.IR stat (2).
.I ConvM2D
converts the machine-independent form starting at
.I ap
into
.IR d
and returns the length of the machine-independent encoding.
The strings in the returned
.B Dir
structure are stored at successive locations starting at
.BR strs .
Usually
.B strs
will point to storage immediately after the
.B Dir
itself.
It can also be a
.B nil
pointer, in which case the string pointers in the returned
.B Dir
are all
.BR nil ;
however, the return value still includes their length.
.PP
.I ConvD2M
does the reverse translation,
also returning the length of the encoding.
If the buffer is too short, the return value will be
.B BIT16SZ
and the correct size will be returned in the first
.B BIT16SZ
bytes.
(If the buffer is less that
.BR BIT16SZ ,
the return value is zero; therefore a correct test for
complete packing of the message is that the return value is
greater than
.BR BIT16SZ ).
The macro
.B GBIT16
can be used to extract the correct value.
The related macros with different sizes retrieve the corresponding-sized quantities.
.B PBIT16
and its brethren place values in messages.
With the exception of handling short buffers in
.IR convD2M ,
these macros are not usually needed except by internal routines.
.PP
Analogous to
.IR sizeS2M ,
.I sizeD2M
returns the number of bytes required to store the machine-independent representation of the
.B Dir
structure
.IR d ,
including its initial 16-bit size field.
.PP
The routine
.B statcheck
checks whether the
.I nbuf
bytes of
.I buf
contain a validly formatted machine-independent
.B Dir
entry suitable as an argument, for example, for the
.B wstat
(see
.IR stat (2))
system call.
It checks that the sizes of all the elements of the the entry sum to exactly
.IR nbuf ,
which is a simple but effective test of validity.
.I Nbuf
and
.I buf
should include the second two-byte (16-bit) length field that precedes the entry when
formatted in a 9P message (see
.IR stat (5));
in other words,
.I nbuf
is 2 plus the sum of the sizes of the entry itself.
.I Statcheck
also verifies that the length field has the correct value (that is,
.IB nbuf -2\f1).
It returns
.B 0
for a valid entry and
.B -1
for an incorrectly formatted entry.
.PP
.IR Dirfmt ,
.IR fcallfmt ,
and
.I dirmodefmt
are formatting routines, suitable for
.IR fmtinstall (2).
They convert
.BR Dir* ,
.BR Fcall* ,
and
.BR long
values into string representations of the directory buffer,
.B Fcall
buffer,
or file mode value.
.I Fcallfmt
assumes that
.I dirfmt
has been installed with format letter
.L D
and
.I dirmodefmt
with format letter
.LR M .
.PP
.I Read9pmsg
calls
.IR read (2)
multiple times, if necessary, to read an entire 9P message into
.BR buf .
The return value is 0 for end of file, or -1 for error; it does not return
partial messages.
.SH SOURCE
.B /sys/src/libc/9sys
.SH SEE ALSO
.IR intro (2),
.IR 9p (2),
.IR stat (2),
.IR intro (5)