Blame


1 058b0118 2005-01-03 devnull .TH 9PCLIENT 3
2 058b0118 2005-01-03 devnull .SH NAME
3 83c4506a 2005-02-11 devnull CFid, CFsys, fsinit, fsmount, fsroot, fssetroot, fsunmount, nsinit, nsmount, fsversion, fsauth, fsattach, fsclose, fscreate, fsdirread, fsdirreadall, fsdirstat, fsdirfstat, fsdirwstat, fsdirfwstat, fsopen, nsopen, fsopenfd, fspread, fspwrite, fsread, fsreadn, fsseek, fswrite \- 9P client library
4 058b0118 2005-01-03 devnull .SH SYNOPSIS
5 058b0118 2005-01-03 devnull .B #include <u.h>
6 058b0118 2005-01-03 devnull .PP
7 058b0118 2005-01-03 devnull .B #include <libc.h>
8 058b0118 2005-01-03 devnull .PP
9 058b0118 2005-01-03 devnull .B #include <fcall.h>
10 058b0118 2005-01-03 devnull .PP
11 058b0118 2005-01-03 devnull .B #include <9pclient.h>
12 c8b6342d 2005-01-13 devnull .ta +\w'\fLCFsys* 'u
13 058b0118 2005-01-03 devnull .PP
14 058b0118 2005-01-03 devnull .B
15 058b0118 2005-01-03 devnull CFsys* fsmount(int fd, char *aname)
16 058b0118 2005-01-03 devnull .PP
17 058b0118 2005-01-03 devnull .B
18 058b0118 2005-01-03 devnull CFsys* nsmount(char *name, char *aname)
19 058b0118 2005-01-03 devnull .PP
20 058b0118 2005-01-03 devnull .B
21 058b0118 2005-01-03 devnull CFid* fsroot(CFsys *fsys)
22 058b0118 2005-01-03 devnull .PP
23 058b0118 2005-01-03 devnull .B
24 058b0118 2005-01-03 devnull void fsunmount(CFsys *fsys)
25 058b0118 2005-01-03 devnull .PP
26 058b0118 2005-01-03 devnull .B
27 058b0118 2005-01-03 devnull CFsys* fsinit(int fd)
28 058b0118 2005-01-03 devnull .PP
29 058b0118 2005-01-03 devnull .B
30 d93fca6a 2005-02-11 devnull CFsys* nsinit(char *name)
31 d93fca6a 2005-02-11 devnull .PP
32 d93fca6a 2005-02-11 devnull .B
33 058b0118 2005-01-03 devnull int fsversion(CFsys *fsys, int msize, char *version, int nversion)
34 058b0118 2005-01-03 devnull .PP
35 058b0118 2005-01-03 devnull .B
36 e4d62adf 2005-01-18 devnull CFid* fsauth(CFsys *fsys, char *uname, char *aname)
37 058b0118 2005-01-03 devnull .PP
38 058b0118 2005-01-03 devnull .B
39 e4d62adf 2005-01-18 devnull CFid* fsattach(CFsys *fsys, CFid *afid, char *uname, char *aname)
40 058b0118 2005-01-03 devnull .PP
41 058b0118 2005-01-03 devnull .B
42 058b0118 2005-01-03 devnull void fssetroot(CFsys *fsys, CFid *fid)
43 058b0118 2005-01-03 devnull .PP
44 058b0118 2005-01-03 devnull .B
45 058b0118 2005-01-03 devnull void fsclose(CFid *fid)
46 058b0118 2005-01-03 devnull .PP
47 058b0118 2005-01-03 devnull .B
48 e4d62adf 2005-01-18 devnull CFid* fscreate(CFsys *fs, char *path, int mode, ulong perm)
49 058b0118 2005-01-03 devnull .PP
50 058b0118 2005-01-03 devnull .B
51 058b0118 2005-01-03 devnull CFid* fsopen(CFsys *fs, char *path, int mode)
52 058b0118 2005-01-03 devnull .PP
53 058b0118 2005-01-03 devnull .B
54 058b0118 2005-01-03 devnull long fspread(CFid *fid, void *buf, long n, vlong offset)
55 058b0118 2005-01-03 devnull .PP
56 058b0118 2005-01-03 devnull .B
57 058b0118 2005-01-03 devnull long fspwrite(CFid *fid, void *buf, long n, vlong offset)
58 058b0118 2005-01-03 devnull .PP
59 058b0118 2005-01-03 devnull .B
60 058b0118 2005-01-03 devnull long fsread(CFid *fid, void *buf, long n)
61 058b0118 2005-01-03 devnull .PP
62 058b0118 2005-01-03 devnull .B
63 058b0118 2005-01-03 devnull long fsreadn(CFid *fid, void *buf, long n)
64 058b0118 2005-01-03 devnull .PP
65 058b0118 2005-01-03 devnull .B
66 058b0118 2005-01-03 devnull long fswrite(CFid *fid, void *buf, long n)
67 058b0118 2005-01-03 devnull .PP
68 058b0118 2005-01-03 devnull .B
69 e4d62adf 2005-01-18 devnull vlong fsseek(CFid *Fid, vlong n, int type)
70 e4d62adf 2005-01-18 devnull .PP
71 e4d62adf 2005-01-18 devnull .B
72 058b0118 2005-01-03 devnull long fsdirread(CFid *fid, Dir **d)
73 058b0118 2005-01-03 devnull .PP
74 058b0118 2005-01-03 devnull .B
75 058b0118 2005-01-03 devnull long fsdirreadall(CFid *fid, Dir **d)
76 058b0118 2005-01-03 devnull .PP
77 058b0118 2005-01-03 devnull .B
78 058b0118 2005-01-03 devnull Dir* fsdirstat(CFsys *fs, char *path)
79 058b0118 2005-01-03 devnull .PP
80 058b0118 2005-01-03 devnull .B
81 058b0118 2005-01-03 devnull Dir* fsdirfstat(CFid *fid)
82 058b0118 2005-01-03 devnull .PP
83 058b0118 2005-01-03 devnull .B
84 058b0118 2005-01-03 devnull int fsdirwstat(CFsys *fs, char *path, Dir *d)
85 058b0118 2005-01-03 devnull .PP
86 058b0118 2005-01-03 devnull .B
87 058b0118 2005-01-03 devnull int fsdirfwstat(CFid *fid, Dir *d)
88 058b0118 2005-01-03 devnull .PP
89 058b0118 2005-01-03 devnull .B
90 058b0118 2005-01-03 devnull int fsopenfd(CFsys *fs, char *path, int mode)
91 d93fca6a 2005-02-11 devnull .PP
92 d93fca6a 2005-02-11 devnull .B
93 d93fca6a 2005-02-11 devnull CFsys* nsopen(char *name, char *aname, char *path, int mode)
94 058b0118 2005-01-03 devnull .SH DESCRIPTION
95 058b0118 2005-01-03 devnull The
96 058b0118 2005-01-03 devnull .I 9pclient
97 058b0118 2005-01-03 devnull library helps client programs interact with 9P servers.
98 058b0118 2005-01-03 devnull .PP
99 058b0118 2005-01-03 devnull A
100 058b0118 2005-01-03 devnull .B CFsys*
101 058b0118 2005-01-03 devnull represents a connection to a 9P server.
102 058b0118 2005-01-03 devnull A
103 058b0118 2005-01-03 devnull .B CFid*
104 058b0118 2005-01-03 devnull represents an active fid on some connection;
105 058b0118 2005-01-03 devnull see
106 058b0118 2005-01-03 devnull .IR intro (9p).
107 058b0118 2005-01-03 devnull .PP
108 058b0118 2005-01-03 devnull A new connection to a 9P server is typically established by
109 058b0118 2005-01-03 devnull .I fsmount
110 058b0118 2005-01-03 devnull or
111 058b0118 2005-01-03 devnull .IR nsmount .
112 058b0118 2005-01-03 devnull .I Fsmount
113 058b0118 2005-01-03 devnull initializes a new 9P conversation on the open file descriptor
114 058b0118 2005-01-03 devnull .IR fd ;
115 058b0118 2005-01-03 devnull .I nsmount
116 058b0118 2005-01-03 devnull connects to a service named
117 058b0118 2005-01-03 devnull .I name
118 058b0118 2005-01-03 devnull in the current name space directory
119 058b0118 2005-01-03 devnull (see
120 058b0118 2005-01-03 devnull .IR intro (4)).
121 058b0118 2005-01-03 devnull Both attach to the root of the file system
122 058b0118 2005-01-03 devnull using the attach name
123 058b0118 2005-01-03 devnull .IR aname .
124 058b0118 2005-01-03 devnull .I Fsroot
125 058b0118 2005-01-03 devnull returns the
126 058b0118 2005-01-03 devnull .B CFid*
127 058b0118 2005-01-03 devnull corresponding to this root.
128 058b0118 2005-01-03 devnull .PP
129 058b0118 2005-01-03 devnull .IR Fsinit ,
130 d93fca6a 2005-02-11 devnull .IR nsinit ,
131 058b0118 2005-01-03 devnull .IR fsversion ,
132 058b0118 2005-01-03 devnull .IR fsauth ,
133 058b0118 2005-01-03 devnull .IR fsattach ,
134 058b0118 2005-01-03 devnull and
135 058b0118 2005-01-03 devnull .I fssetroot
136 058b0118 2005-01-03 devnull provide more detailed control over the file system connection
137 058b0118 2005-01-03 devnull than
138 058b0118 2005-01-03 devnull .I fsmount
139 058b0118 2005-01-03 devnull and
140 058b0118 2005-01-03 devnull .IR nsmount .
141 058b0118 2005-01-03 devnull .I Fsinit
142 058b0118 2005-01-03 devnull allocates a new
143 058b0118 2005-01-03 devnull .B CFsys*
144 058b0118 2005-01-03 devnull corresponding to a 9P conversation on the file descriptor
145 d93fca6a 2005-02-11 devnull .I fd
146 d93fca6a 2005-02-11 devnull and then calls
147 d93fca6a 2005-02-11 devnull .IR fsversion
148 d93fca6a 2005-02-11 devnull to initialize the connection.
149 d93fca6a 2005-02-11 devnull .I Nsinit
150 d93fca6a 2005-02-11 devnull does the same for name space services.
151 058b0118 2005-01-03 devnull .I Fsversion
152 058b0118 2005-01-03 devnull executes a
153 058b0118 2005-01-03 devnull .IR version (9p)
154 058b0118 2005-01-03 devnull transaction to establish
155 058b0118 2005-01-03 devnull maximum message size and 9P version.
156 058b0118 2005-01-03 devnull .I Fsauth
157 058b0118 2005-01-03 devnull executes an
158 058b0118 2005-01-03 devnull .IR auth (9p)
159 058b0118 2005-01-03 devnull transaction, returning the new auth fid.
160 058b0118 2005-01-03 devnull .RI ( Fsread
161 058b0118 2005-01-03 devnull and
162 058b0118 2005-01-03 devnull .I fswrite
163 058b0118 2005-01-03 devnull can then be used to run the authentication protocol over the fid.)
164 058b0118 2005-01-03 devnull .I Fsattach
165 058b0118 2005-01-03 devnull executes an
166 058b0118 2005-01-03 devnull .IR attach (9p)
167 058b0118 2005-01-03 devnull transaction to connect to the root of a file tree served by the server.
168 058b0118 2005-01-03 devnull It presents
169 058b0118 2005-01-03 devnull .I afid
170 058b0118 2005-01-03 devnull (which may be nil)
171 058b0118 2005-01-03 devnull to establish identity.
172 058b0118 2005-01-03 devnull .I Fssetroot
173 058b0118 2005-01-03 devnull sets the root fid used by
174 058b0118 2005-01-03 devnull .IR fsopen ,
175 058b0118 2005-01-03 devnull .IR fsopenfd ,
176 058b0118 2005-01-03 devnull .IR fsdirstat ,
177 058b0118 2005-01-03 devnull and
178 058b0118 2005-01-03 devnull .IR fsdirwstat ,
179 058b0118 2005-01-03 devnull which evaluate rooted path names.
180 058b0118 2005-01-03 devnull .PP
181 058b0118 2005-01-03 devnull When a fid
182 058b0118 2005-01-03 devnull is no longer needed, it should be clunked by calling
183 058b0118 2005-01-03 devnull .I fsclose
184 058b0118 2005-01-03 devnull and then considered freed.
185 058b0118 2005-01-03 devnull Similarly, when the connection to the server is no longer needed,
186 058b0118 2005-01-03 devnull it should be closed by calling
187 058b0118 2005-01-03 devnull .IR fsunmount ,
188 058b0118 2005-01-03 devnull which will take care of calling
189 058b0118 2005-01-03 devnull .I fsclose
190 058b0118 2005-01-03 devnull on the current root fid.
191 058b0118 2005-01-03 devnull Once all fids have been clunked
192 058b0118 2005-01-03 devnull .I and
193 058b0118 2005-01-03 devnull the connection has been closed
194 058b0118 2005-01-03 devnull (the order is not important),
195 058b0118 2005-01-03 devnull the allocated structures will be freed and the
196 058b0118 2005-01-03 devnull file descriptor corresponding to the connection
197 058b0118 2005-01-03 devnull will be closed
198 058b0118 2005-01-03 devnull (see
199 058b0118 2005-01-03 devnull .IR close (2)).
200 058b0118 2005-01-03 devnull Fids are not reference counted: when
201 058b0118 2005-01-03 devnull .I fsclose
202 058b0118 2005-01-03 devnull is called, the clunk transaction and freeing of storage
203 058b0118 2005-01-03 devnull happen immediately.
204 058b0118 2005-01-03 devnull .PP
205 058b0118 2005-01-03 devnull .I Fscreate
206 058b0118 2005-01-03 devnull and
207 058b0118 2005-01-03 devnull .I fsopen
208 058b0118 2005-01-03 devnull establish new fids using the
209 058b0118 2005-01-03 devnull .IR walk ,
210 058b0118 2005-01-03 devnull .I create
211 058b0118 2005-01-03 devnull and
212 058b0118 2005-01-03 devnull .I open
213 058b0118 2005-01-03 devnull transactions
214 058b0118 2005-01-03 devnull (see
215 058b0118 2005-01-03 devnull .IR walk (9p)
216 058b0118 2005-01-03 devnull and
217 058b0118 2005-01-03 devnull .IR open (9p)).
218 058b0118 2005-01-03 devnull The
219 058b0118 2005-01-03 devnull .I path
220 058b0118 2005-01-03 devnull argument is evaluated relative to the
221 058b0118 2005-01-03 devnull .B CFsys
222 058b0118 2005-01-03 devnull root
223 058b0118 2005-01-03 devnull (see
224 058b0118 2005-01-03 devnull .I fsroot
225 058b0118 2005-01-03 devnull and
226 058b0118 2005-01-03 devnull .I fssetroot
227 058b0118 2005-01-03 devnull above).
228 058b0118 2005-01-03 devnull The path is parsed as a slash-separated sequence of path elements,
229 058b0118 2005-01-03 devnull as on Unix and Plan 9.
230 058b0118 2005-01-03 devnull Elements that are empty or
231 058b0118 2005-01-03 devnull dot
232 c8b6342d 2005-01-13 devnull .RB ( . )
233 058b0118 2005-01-03 devnull are ignored.
234 058b0118 2005-01-03 devnull .PP
235 058b0118 2005-01-03 devnull Once opened, these fids can be read and written using
236 058b0118 2005-01-03 devnull .I fspread
237 058b0118 2005-01-03 devnull and
238 058b0118 2005-01-03 devnull .IR fspwrite ,
239 058b0118 2005-01-03 devnull which execute
240 058b0118 2005-01-03 devnull .I read
241 058b0118 2005-01-03 devnull and
242 058b0118 2005-01-03 devnull .I write
243 058b0118 2005-01-03 devnull transactions
244 058b0118 2005-01-03 devnull (see
245 058b0118 2005-01-03 devnull .IR read (9p)).
246 058b0118 2005-01-03 devnull The library maintains an offset for each fid,
247 058b0118 2005-01-03 devnull analagous to the offset maintained by the kernel for each open file descriptor.
248 058b0118 2005-01-03 devnull .I Fsread
249 058b0118 2005-01-03 devnull and
250 058b0118 2005-01-03 devnull .I fswrite
251 058b0118 2005-01-03 devnull read and write from this offset, and update it after successful calls.
252 e4d62adf 2005-01-18 devnull .I Fsseek
253 e4d62adf 2005-01-18 devnull sets the offset; the
254 e4d62adf 2005-01-18 devnull .I n
255 e4d62adf 2005-01-18 devnull and
256 e4d62adf 2005-01-18 devnull .I type
257 e4d62adf 2005-01-18 devnull arguments are used as in
258 e4d62adf 2005-01-18 devnull .IR seek (3).
259 058b0118 2005-01-03 devnull Calling
260 058b0118 2005-01-03 devnull .I fspread
261 058b0118 2005-01-03 devnull or
262 058b0118 2005-01-03 devnull .I fspwrite
263 058b0118 2005-01-03 devnull with an
264 058b0118 2005-01-03 devnull .I offset
265 058b0118 2005-01-03 devnull of \-1
266 058b0118 2005-01-03 devnull is identical to calling
267 058b0118 2005-01-03 devnull .I fsread
268 058b0118 2005-01-03 devnull or
269 058b0118 2005-01-03 devnull .IR fswrite .
270 058b0118 2005-01-03 devnull .I Fsreadn
271 058b0118 2005-01-03 devnull calls
272 058b0118 2005-01-03 devnull .I fsread
273 058b0118 2005-01-03 devnull repeatedly to obtain exactly
274 058b0118 2005-01-03 devnull .I n
275 058b0118 2005-01-03 devnull bytes of data, unless it encounters end-of-file or an error.
276 058b0118 2005-01-03 devnull .PP
277 058b0118 2005-01-03 devnull Reading an open a directory returns directory entries encoded as described in
278 058b0118 2005-01-03 devnull .IR stat (9p).
279 058b0118 2005-01-03 devnull .I Fsdirread
280 058b0118 2005-01-03 devnull calls
281 058b0118 2005-01-03 devnull .I fsread
282 058b0118 2005-01-03 devnull and then parses the encoded entries into an array of
283 058b0118 2005-01-03 devnull .B Dir*
284 058b0118 2005-01-03 devnull data structures,
285 058b0118 2005-01-03 devnull storing a pointer to the array in
286 058b0118 2005-01-03 devnull .BI *d
287 058b0118 2005-01-03 devnull and returning the number of entries.
288 058b0118 2005-01-03 devnull .I Fsdirreadall
289 058b0118 2005-01-03 devnull is similar but reads the entire directory.
290 058b0118 2005-01-03 devnull The returned pointer should be freed with
291 058b0118 2005-01-03 devnull .I free
292 058b0118 2005-01-03 devnull (see
293 058b0118 2005-01-03 devnull .IR malloc (3))
294 058b0118 2005-01-03 devnull when no longer needed.
295 058b0118 2005-01-03 devnull .PP
296 058b0118 2005-01-03 devnull .I Fsdirfstat
297 058b0118 2005-01-03 devnull and
298 058b0118 2005-01-03 devnull .I fsdirfwstat
299 058b0118 2005-01-03 devnull execute
300 058b0118 2005-01-03 devnull .I stat
301 058b0118 2005-01-03 devnull and
302 058b0118 2005-01-03 devnull .I wstat
303 058b0118 2005-01-03 devnull (see
304 058b0118 2005-01-03 devnull .IR stat (9p))
305 058b0118 2005-01-03 devnull transactions.
306 058b0118 2005-01-03 devnull The
307 058b0118 2005-01-03 devnull .B Dir
308 058b0118 2005-01-03 devnull structure returned by
309 058b0118 2005-01-03 devnull .I fsdirfstat
310 058b0118 2005-01-03 devnull should be freed with
311 058b0118 2005-01-03 devnull .I free
312 058b0118 2005-01-03 devnull (see
313 058b0118 2005-01-03 devnull .IR malloc (3))
314 058b0118 2005-01-03 devnull when no longer needed.
315 058b0118 2005-01-03 devnull .PP
316 058b0118 2005-01-03 devnull .I Fsdirstat
317 058b0118 2005-01-03 devnull and
318 058b0118 2005-01-03 devnull .I fsdirwstat
319 058b0118 2005-01-03 devnull are similar to
320 058b0118 2005-01-03 devnull .I fsdirfstat
321 058b0118 2005-01-03 devnull and
322 058b0118 2005-01-03 devnull .I fsdirfwstat
323 058b0118 2005-01-03 devnull but operate on paths relative to the file system root
324 058b0118 2005-01-03 devnull (see
325 058b0118 2005-01-03 devnull .I fsopen
326 058b0118 2005-01-03 devnull and
327 058b0118 2005-01-03 devnull .I fscreate
328 058b0118 2005-01-03 devnull above).
329 058b0118 2005-01-03 devnull .PP
330 058b0118 2005-01-03 devnull .I Fsopenfd
331 058b0118 2005-01-03 devnull opens a file on the 9P server
332 058b0118 2005-01-03 devnull for reading or writing but returns a Unix file descriptor
333 058b0118 2005-01-03 devnull instead of a fid structure.
334 058b0118 2005-01-03 devnull The file descriptor is actually one end of a
335 058b0118 2005-01-03 devnull .IR pipe (2).
336 058b0118 2005-01-03 devnull A proxy process on the other end is ferrying data
337 058b0118 2005-01-03 devnull between the pipe and the 9P fid.
338 058b0118 2005-01-03 devnull Because of the implementation as a pipe,
339 058b0118 2005-01-03 devnull the only signal of a read or write error is the closing of the pipe.
340 058b0118 2005-01-03 devnull The file descriptor remains valid even after the
341 058b0118 2005-01-03 devnull .B CFsys
342 058b0118 2005-01-03 devnull is unmounted.
343 d93fca6a 2005-02-11 devnull .PP
344 d93fca6a 2005-02-11 devnull .I Nsopen
345 d93fca6a 2005-02-11 devnull opens a single file on a name space server: it runs
346 d93fca6a 2005-02-11 devnull .IR nsmount ,
347 d93fca6a 2005-02-11 devnull .IR fsopen ,
348 d93fca6a 2005-02-11 devnull and then
349 d93fca6a 2005-02-11 devnull .IR fsunmount .
350 058b0118 2005-01-03 devnull .SH SOURCE
351 c3674de4 2005-01-11 devnull .B \*9/src/lib9pclient
352 058b0118 2005-01-03 devnull .SH SEE ALSO
353 058b0118 2005-01-03 devnull .IR intro (4),
354 d93fca6a 2005-02-11 devnull .IR intro (9p),
355 d93fca6a 2005-02-11 devnull .I fsaopen
356 d93fca6a 2005-02-11 devnull and
357 d93fca6a 2005-02-11 devnull .I nsaopen
358 d93fca6a 2005-02-11 devnull in
359 d93fca6a 2005-02-11 devnull .IR auth (3)
360 058b0118 2005-01-03 devnull .SH BUGS
361 058b0118 2005-01-03 devnull The implementation
362 058b0118 2005-01-03 devnull should use a special version string to distinguish between
363 058b0118 2005-01-03 devnull servers that support
364 058b0118 2005-01-03 devnull .IR openfd (9p)
365 058b0118 2005-01-03 devnull and servers that do not.
366 058b0118 2005-01-03 devnull .PP
367 058b0118 2005-01-03 devnull The interface does not provide access to the
368 058b0118 2005-01-03 devnull .IR walk (9p)
369 058b0118 2005-01-03 devnull transaction, or to
370 058b0118 2005-01-03 devnull .I open
371 058b0118 2005-01-03 devnull and
372 058b0118 2005-01-03 devnull .I create
373 058b0118 2005-01-03 devnull on already-established fids.