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
|
<head>
<title>fcall(3) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>FCALL(3)</b><td align=right><b>FCALL(3)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
Fcall, convS2M, convD2M, convM2S, convM2D, fcallfmt, dirfmt, dirmodefmt,
read9pmsg, statcheck, sizeS2M, sizeD2M – interface to Plan 9 File
protocol<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>#include <u.h><br>
#include <libc.h><br>
#include <fcall.h>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>uint convS2M(Fcall *f, uchar *ap, uint nap)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>uint convD2M(Dir *d, uchar *ap, uint nap)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>uint convM2S(uchar *ap, uint nap, Fcall *f)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>uint convM2D(uchar *ap, uint nap, Dir *d, char *strs)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int dirfmt(Fmt*)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int fcallfmt(Fmt*)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int dirmodefmt(Fmt*)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int read9pmsg(int fd, uchar *buf, uint nbuf)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int statcheck(uchar *buf, uint nbuf)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>uint sizeS2M(Fcall *f)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>uint sizeD2M(Dir *d)<br>
</font></tt>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
These routines convert messages in the machine-independent format
of the Plan 9 file protocol, 9P, to and from a more convenient
form, an <tt><font size=+1>Fcall</font></tt> structure:
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<tt><font size=+1>#define MAXWELEM 16<br>
typedef<br>
struct Fcall<br>
{<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
uchar type;<br>
u32int fid;<br>
ushort tag;<br>
union {<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
struct {<br>
u32int msize; /* Tversion, Rversion */<br>
char *version; /* Tversion, Rversion */<br>
};<br>
struct {<br>
ushort oldtag; /* Tflush */<br>
};<br>
struct {<br>
char *ename; /* Rerror */<br>
};<br>
struct {<br>
Qid qid; /* Rattach, Ropen, Rcreate */<br>
u32int iounit; /* Ropen, Rcreate */<br>
};<br>
struct {<br>
Qid aqid; /* Rauth */<br>
};<br>
struct {<br>
u32int afid; /* Tauth, Tattach */<br>
char *uname; /* Tauth, Tattach */<br>
char *aname; /* Tauth, Tattach */<br>
};<br>
struct {<br>
u32int perm; /* Tcreate */ <br>
char *name; /* Tcreate */<br>
uchar mode; /* Tcreate, Topen */<br>
};<br>
struct {<br>
u32int newfid; /* Twalk */<br>
ushort nwname; /* Twalk */<br>
char *wname[MAXWELEM]; /* Twalk */<br>
};<br>
struct {<br>
ushort nwqid; /* Rwalk */<br>
Qid wqid[MAXWELEM]; /* Rwalk */<br>
};<br>
struct {<br>
vlong offset; /* Tread, Twrite */<br>
u32int count; /* Tread, Twrite, Rread */<br>
char *data; /* Twrite, Rread */<br>
};<br>
struct {<br>
ushort nstat; /* Twstat, Rstat */<br>
uchar *stat; /* Twstat, Rstat */<br>
};<br>
</table>
};<br>
</table>
} Fcall;<br>
/* these are implemented as macros */<br>
uchar GBIT8(uchar*)<br>
ushort GBIT16(uchar*)<br>
ulong GBIT32(uchar*)<br>
vlong GBIT64(uchar*)<br>
void PBIT8(uchar*, uchar)<br>
void PBIT16(uchar*, ushort)<br>
void PBIT32(uchar*, ulong)<br>
void PBIT64(uchar*, vlong)<br>
#define BIT8SZ 1<br>
#define BIT16SZ 2<br>
#define BIT32SZ 4<br>
#define BIT64SZ 8<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
This structure is defined in <tt><font size=+1><fcall.h></font></tt>. See section 5 for a full
description of 9P messages and their encoding. For all message
types, the <tt><font size=+1>type</font></tt> field of an <tt><font size=+1>Fcall</font></tt> holds one of <tt><font size=+1>Tversion</font></tt>, <tt><font size=+1>Rversion</font></tt>,
<tt><font size=+1>Tattach</font></tt>, <tt><font size=+1>Rattach</font></tt>, etc. (defined in an enumerated type in <tt><font size=+1><fcall.h></font></tt>).
<tt><font size=+1>Fid</font></tt> is used by most messages, and
<tt><font size=+1>tag</font></tt> is used by all messages. The other fields are used selectively
by the message types given in comments.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>ConvM2S</i> takes a 9P message at <i>ap</i> of length <i>nap</i>, and uses it to
fill in <tt><font size=+1>Fcall</font></tt> structure <i>f</i>. If the passed message including any
data for <tt><font size=+1>Twrite</font></tt> and <tt><font size=+1>Rread</font></tt> messages is formatted properly, the
return value is the number of bytes the message occupied in the
buffer <i>ap</i>, which will always be less than or equal to <i>nap</i>;
otherwise it is 0. For <tt><font size=+1>Twrite</font></tt> and <tt><font size=+1>Tread</font></tt> messages, <tt><font size=+1>data</font></tt> is set
to a pointer into the argument message, not a copy.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>ConvS2M</i> does the reverse conversion, turning <i>f</i> into a message
starting at <i>ap</i>. The length of the resulting message is returned.
For <tt><font size=+1>Twrite</font></tt> and <tt><font size=+1>Rread</font></tt> messages, <tt><font size=+1>count</font></tt> bytes starting at <tt><font size=+1>data</font></tt> are
copied into the message.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The constant <tt><font size=+1>IOHDRSZ</font></tt> is a suitable amount of buffer to reserve
for storing the 9P header; the data portion of a <tt><font size=+1>Twrite</font></tt> or <tt><font size=+1>Rread</font></tt>
will be no more than the buffer size negotiated in the <tt><font size=+1>Tversion/Rversion</font></tt>
exchange, minus <tt><font size=+1>IOHDRSZ</font></tt>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The routine <i>sizeS2M</i> returns the number of bytes required to store
the machine-independent representation of the <tt><font size=+1>Fcall</font></tt> structure
<i>f</i>, including its initial 32-bit size field. In other words, it
reports the number of bytes produced by a successful call to <i>convS2M</i>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Another structure is <tt><font size=+1>Dir</font></tt>, used by the routines described in <a href="../man3/stat.html"><i>stat</i>(3)</a>.
<i>ConvM2D</i> converts the machine-independent form starting at <i>ap</i> into
<i>d</i> and returns the length of the machine-independent encoding.
The strings in the returned <tt><font size=+1>Dir</font></tt> structure are stored at successive
locations starting at <tt><font size=+1>strs</font></tt>. Usually <tt><font size=+1>strs</font></tt> will
point to storage immediately after the <tt><font size=+1>Dir</font></tt> itself. It can also
be a <tt><font size=+1>nil</font></tt> pointer, in which case the string pointers in the returned
<tt><font size=+1>Dir</font></tt> are all <tt><font size=+1>nil</font></tt>; however, the return value still includes their
length.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>ConvD2M</i> does the reverse translation, also returning the length
of the encoding. If the buffer is too short, the return value
will be <tt><font size=+1>BIT16SZ</font></tt> and the correct size will be returned in the first
<tt><font size=+1>BIT16SZ</font></tt> bytes. (If the buffer is less that <tt><font size=+1>BIT16SZ</font></tt>, the return
value is zero; therefore a correct test for complete packing of
the
message is that the return value is greater than <tt><font size=+1>BIT16SZ</font></tt>). The
macro <tt><font size=+1>GBIT16</font></tt> can be used to extract the correct value. The related
macros with different sizes retrieve the corresponding-sized quantities.
<tt><font size=+1>PBIT16</font></tt> and its brethren place values in messages. With the exception
of handling short buffers in <i>convD2M</i>,
these macros are not usually needed except by internal routines.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Analogous to <i>sizeS2M</i>, <i>sizeD2M</i> returns the number of bytes required
to store the machine-independent representation of the <tt><font size=+1>Dir</font></tt> structure
<i>d</i>, including its initial 16-bit size field.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The routine <tt><font size=+1>statcheck</font></tt> checks whether the <i>nbuf</i> bytes of <i>buf</i> contain
a validly formatted machine-independent <tt><font size=+1>Dir</font></tt> entry suitable as
an argument, for example, for the <tt><font size=+1>wstat</font></tt> (see <a href="../man3/stat.html"><i>stat</i>(3)</a>) system call.
It checks that the sizes of all the elements of the the entry
sum to exactly <i>nbuf</i>, which is a simple but effective test
of validity. <i>Nbuf</i> and <i>buf</i> should include the second two-byte (16-bit)
length field that precedes the entry when formatted in a 9P message
(see <i>stat</i>(9p)); in other words, <i>nbuf</i> is 2 plus the sum of the
sizes of the entry itself. <i>Statcheck</i> also verifies that the length
field has the correct value (that is, <i>nbuf</i><tt><font size=+1>−2</font></tt>). It returns <tt><font size=+1>0
</font></tt>for a valid entry and <tt><font size=+1>−1</font></tt> for an incorrectly formatted entry.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Dirfmt</i>, <i>fcallfmt</i>, and <i>dirmodefmt</i> are formatting routines, suitable
for <a href="../man3/fmtinstall.html"><i>fmtinstall</i>(3)</a>. They convert <tt><font size=+1>Dir*</font></tt>, <tt><font size=+1>Fcall*</font></tt>, and <tt><font size=+1>long</font></tt> values
into string representations of the directory buffer, <tt><font size=+1>Fcall</font></tt> buffer,
or file mode value. <i>Fcallfmt</i> assumes that <i>dirfmt</i> has been installed
with format letter <tt><font size=+1>D</font></tt> and <i>dirmodefmt</i> with format
letter <tt><font size=+1>M</font></tt>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Read9pmsg</i> calls <a href="../man3/read.html"><i>read</i>(3)</a> multiple times, if necessary, to read
an entire 9P message into <tt><font size=+1>buf</font></tt>. The return value is 0 for end of
file, or -1 for error; it does not return partial messages.<br>
</table>
<p><font size=+1><b>SOURCE </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>/usr/local/plan9/src/lib9<br>
</font></tt>
</table>
<p><font size=+1><b>SEE ALSO </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<a href="../man3/intro.html"><i>intro</i>(3)</a>, <a href="../man3/9p.html"><i>9p</i>(3)</a>, <a href="../man3/stat.html"><i>stat</i>(3)</a>, <i>intro</i>(9p)<br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>
|