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
|
<head>
<title>9pclient(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>9PCLIENT(3)</b><td align=right><b>9PCLIENT(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>
CFid, CFsys, fsinit, fsmount, fsroot, fssetroot, fsunmount, nsmount,
fsversion, fsauth, fsattach, fsclose, fscreate, fsdirread, fsdirreadall,
fsdirstat, fsdirfstat, fsdirwstat, fsdirfwstat, fsopen, fsopenfd,
fspread, fspwrite, fsread, fsreadn, fswrite – 9P client library<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>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>#include <libc.h>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>#include <fcall.h>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>#include <9pclient.h>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>CFsys* fsmount(int fd, char *aname)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>CFsys* nsmount(char *name, char *aname)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>CFid* fsroot(CFsys *fsys)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void fsunmount(CFsys *fsys)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>CFsys* fsinit(int fd)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int fsversion(CFsys *fsys, int msize, char *version, int nversion)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>CFid *fsauth(CFsys *fsys, char *uname, char *aname)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>CFid *fsattach(CFsys *fsys, CFid *afid, char *uname, char *aname)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void fssetroot(CFsys *fsys, CFid *fid)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void fsclose(CFid *fid)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>CFid *fscreate(CFsys *fs, char *path, int mode, ulong perm)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>CFid* fsopen(CFsys *fs, char *path, int mode)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>long fspread(CFid *fid, void *buf, long n, vlong offset)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>long fspwrite(CFid *fid, void *buf, long n, vlong offset)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>long fsread(CFid *fid, void *buf, long n)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>long fsreadn(CFid *fid, void *buf, long n)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>long fswrite(CFid *fid, void *buf, long n)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>long fsdirread(CFid *fid, Dir **d)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>long fsdirreadall(CFid *fid, Dir **d)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>Dir* fsdirstat(CFsys *fs, char *path)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>Dir* fsdirfstat(CFid *fid)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int fsdirwstat(CFsys *fs, char *path, Dir *d)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int fsdirfwstat(CFid *fid, Dir *d)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int fsopenfd(CFsys *fs, char *path, int mode)<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>
The <i>9pclient</i> library helps client programs interact with 9P servers.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
A <tt><font size=+1>CFsys*</font></tt> represents a connection to a 9P server. A <tt><font size=+1>CFid*</font></tt> represents
an active fid on some connection; see <i>intro</i>(9p).
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
A new connection to a 9P server is typically established by <i>fsmount</i>
or <i>nsmount</i>. <i>Fsmount</i> initializes a new 9P conversation on the open
file descriptor <i>fd</i>; <i>nsmount</i> connects to a service named <i>name</i> in
the current name space directory (see <a href="../man4/intro.html"><i>intro</i>(4)</a>). Both attach to
the root of the file system using the attach name <i>aname</i>.
<i>Fsroot</i> returns the <tt><font size=+1>CFid*</font></tt> corresponding to this root.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Fsinit</i>, <i>fsversion</i>, <i>fsauth</i>, <i>fsattach</i>, and <i>fssetroot</i> provide more
detailed control over the file system connection than <i>fsmount</i>
and <i>nsmount</i>. <i>Fsinit</i> allocates a new <tt><font size=+1>CFsys*</font></tt> corresponding to a
9P conversation on the file descriptor <i>fd</i>. <i>Fsversion</i> executes
a <i>version</i>(9p) transaction to establish maximum message size and
9P
version. <i>Fsauth</i> executes an <i>auth</i>(9p) transaction, returning the
new auth fid. (<i>Fsread</i> and <i>fswrite</i> can then be used to run the
authentication protocol over the fid.) <i>Fsattach</i> executes an <i>attach</i>(9p)
transaction to connect to the root of a file tree served by the
server. It presents <i>afid</i> (which may be nil) to establish
identity. <i>Fssetroot</i> sets the root fid used by <i>fsopen</i>, <i>fsopenfd</i>,
<i>fsdirstat</i>, and <i>fsdirwstat</i>, which evaluate rooted path names.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
When a fid is no longer needed, it should be clunked by calling
<i>fsclose</i> and then considered freed. Similarly, when the connection
to the server is no longer needed, it should be closed by calling
<i>fsunmount</i>, which will take care of calling <i>fsclose</i> on the current
root fid. Once all fids have been clunked <i>and</i> the connection
has been closed (the order is not important), the allocated structures
will be freed and the file descriptor corresponding to the connection
will be closed (see <a href="../man2/close.html"><i>close</i>(2)</a>). Fids are not reference counted:
when <i>fsclose</i> is called, the clunk transaction and freeing of storage
happen immediately.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Fscreate</i> and <i>fsopen</i> establish new fids using the <i>walk</i>, <i>create</i>
and <i>open</i> transactions (see <i>walk</i>(9p) and <i>open</i>(9p)). The <i>path</i> argument
is evaluated relative to the <tt><font size=+1>CFsys</font></tt> root (see <i>fsroot</i> and <i>fssetroot</i>
above). The path is parsed as a slash-separated sequence of path
elements, as on Unix and Plan 9. Elements that are
empty or dot (<tt><font size=+1>.</font></tt>) are ignored.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Once opened, these fids can be read and written using <i>fspread</i>
and <i>fspwrite</i>, which execute <i>read</i> and <i>write</i> transactions (see <i>read</i>(9p)).
The library maintains an offset for each fid, analagous to the
offset maintained by the kernel for each open file descriptor.
<i>Fsread</i> and <i>fswrite</i> read and write from this offset, and
update it after successful calls. Calling <i>fspread</i> or <i>fspwrite</i>
with an <i>offset</i> of –1 is identical to calling <i>fsread</i> or <i>fswrite</i>.
<i>Fsreadn</i> calls <i>fsread</i> repeatedly to obtain exactly <i>n</i> bytes of data,
unless it encounters end-of-file or an error.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Reading an open a directory returns directory entries encoded
as described in <i>stat</i>(9p). <i>Fsdirread</i> calls <i>fsread</i> and then parses
the encoded entries into an array of <tt><font size=+1>Dir*</font></tt> data structures, storing
a pointer to the array in <tt><font size=+1>*d</font></tt> and returning the number of entries.
<i>Fsdirreadall</i> is similar but reads the entire directory. The
returned pointer should be freed with <i>free</i> (see <a href="../man3/malloc.html"><i>malloc</i>(3)</a>) when
no longer needed.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Fsdirfstat</i> and <i>fsdirfwstat</i> execute <i>stat</i> and <i>wstat</i> (see <i>stat</i>(9p))
transactions. The <tt><font size=+1>Dir</font></tt> structure returned by <i>fsdirfstat</i> should
be freed with <i>free</i> (see <a href="../man3/malloc.html"><i>malloc</i>(3)</a>) when no longer needed.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Fsdirstat</i> and <i>fsdirwstat</i> are similar to <i>fsdirfstat</i> and <i>fsdirfwstat</i>
but operate on paths relative to the file system root (see <i>fsopen</i>
and <i>fscreate</i> above).
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Fsopenfd</i> opens a file on the 9P server for reading or writing
but returns a Unix file descriptor instead of a fid structure.
The file descriptor is actually one end of a <a href="../man2/pipe.html"><i>pipe</i>(2)</a>. A proxy
process on the other end is ferrying data between the pipe and
the 9P fid. Because of the implementation as a pipe, the only
signal of a
read or write error is the closing of the pipe. The file descriptor
remains valid even after the <tt><font size=+1>CFsys</font></tt> is unmounted.<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/lib9pclient<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="../man4/intro.html"><i>intro</i>(4)</a>, <i>intro</i>(9p)<br>
</table>
<p><font size=+1><b>BUGS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
The implementation should use a special version string to distinguish
between servers that support <i>openfd</i>(9p) and servers that do not.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The interface does not provide access to the <i>walk</i>(9p) transaction,
or to <i>open</i> and <i>create</i> on already-established fids.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
There is no <i>fsseek</i>.<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>
|