t9pclient.3 - plan9port - [fork] Plan 9 from user space
HTML git clone git://src.adamsgaard.dk/plan9port
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
t9pclient.3 (8672B)
---
1 .TH 9PCLIENT 3
2 .SH NAME
3 CFid, CFsys, fsinit, fsmount, fsroot, fssetroot, fsunmount, nsinit, nsmount, fsversion, fsauth, fsattach, fsclose, fscreate, fsfcreate, fsremove, fsfremove, fsaccess, fsdirread, fsdirreadall, fsdirstat, fsdirfstat, fsdirwstat, fsdirfwstat, fsopen, fsfopen, nsopen, fsopenfd, fspread, fspwrite, fsread, fsreadn, fsseek, fswrite, fsprint, fsvprint \- 9P client library
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .PP
7 .B #include <libc.h>
8 .PP
9 .B #include <fcall.h>
10 .PP
11 .B #include <thread.h>
12 .PP
13 .B #include <9pclient.h>
14 .ta +\w'\fLCFsys* 'u
15 .PP
16 .B
17 CFsys* fsmount(int fd, char *aname)
18 .PP
19 .B
20 CFsys* nsmount(char *name, char *aname)
21 .PP
22 .B
23 CFid* fsroot(CFsys *fsys)
24 .PP
25 .B
26 void fsunmount(CFsys *fsys)
27 .PP
28 .B
29 CFsys* fsinit(int fd)
30 .PP
31 .B
32 CFsys* nsinit(char *name)
33 .PP
34 .B
35 int fsversion(CFsys *fsys, int msize, char *version, int nversion)
36 .PP
37 .B
38 CFid* fsauth(CFsys *fsys, char *uname, char *aname)
39 .PP
40 .B
41 CFid* fsattach(CFsys *fsys, CFid *afid, char *uname, char *aname)
42 .PP
43 .B
44 void fssetroot(CFsys *fsys, CFid *fid)
45 .PP
46 .B
47 void fsclose(CFid *fid)
48 .PP
49 .B
50 CFid* fscreate(CFsys *fs, char *path, int mode, ulong perm)
51 .PP
52 .B
53 int fsfcreate(CFid *fid, char *path, int mode, ulong perm)
54 .PP
55 .B
56 int fsremove(CFSys *fs, char *path)
57 .PP
58 .B
59 int fsfremove(CFid *fid)
60 .PP
61 .B
62 int fsaccess(CFsys *fs, char *path, int amode)
63 .PP
64 .B
65 CFid* fsopen(CFsys *fs, char *path, int mode)
66 .PP
67 .B
68 int fsfopen(CFid *fid, char *path, int mode)
69 .PP
70 .B
71 long fspread(CFid *fid, void *buf, long n, vlong offset)
72 .PP
73 .B
74 long fspwrite(CFid *fid, void *buf, long n, vlong offset)
75 .PP
76 .B
77 long fsread(CFid *fid, void *buf, long n)
78 .PP
79 .B
80 long fsreadn(CFid *fid, void *buf, long n)
81 .PP
82 .B
83 long fswrite(CFid *fid, void *buf, long n)
84 .PP
85 .B
86 int fsprint(CFid *fid, char *fmt, ...)
87 .PP
88 .B
89 int fsvprint(CFid *fid, char *fmt, ...)
90 .PP
91 .B
92 vlong fsseek(CFid *Fid, vlong n, int type)
93 .PP
94 .B
95 Qid fsqid(CFid *fid)
96 .PP
97 .B
98 long fsdirread(CFid *fid, Dir **d)
99 .PP
100 .B
101 long fsdirreadall(CFid *fid, Dir **d)
102 .PP
103 .B
104 Dir* fsdirstat(CFsys *fs, char *path)
105 .PP
106 .B
107 Dir* fsdirfstat(CFid *fid)
108 .PP
109 .B
110 int fsdirwstat(CFsys *fs, char *path, Dir *d)
111 .PP
112 .B
113 int fsdirfwstat(CFid *fid, Dir *d)
114 .PP
115 .B
116 int fsopenfd(CFsys *fs, char *path, int mode)
117 .PP
118 .B
119 CFsys* nsopen(char *name, char *aname, char *path, int mode)
120 .PP
121 .B
122 extern int chatty9pclient;
123 .PP
124 .B
125 extern int eofkill9pclient;
126 .SH DESCRIPTION
127 The
128 .I 9pclient
129 library helps client programs interact with 9P servers.
130 .PP
131 A
132 .B CFsys*
133 represents a connection to a 9P server.
134 A
135 .B CFid*
136 represents an active fid on some connection;
137 see
138 .IR intro (9p).
139 .PP
140 A new connection to a 9P server is typically established by
141 .I fsmount
142 or
143 .IR nsmount .
144 .I Fsmount
145 initializes a new 9P conversation on the open file descriptor
146 .IR fd ;
147 .I nsmount
148 connects to a service named
149 .I name
150 in the current name space directory
151 (see
152 .MR intro (4) ).
153 Both attach to the root of the file system
154 using the attach name
155 .IR aname .
156 .I Fsroot
157 returns the
158 .B CFid*
159 corresponding to this root.
160 .PP
161 .IR Fsinit ,
162 .IR nsinit ,
163 .IR fsversion ,
164 .IR fsauth ,
165 .IR fsattach ,
166 and
167 .I fssetroot
168 provide more detailed control over the file system connection
169 than
170 .I fsmount
171 and
172 .IR nsmount .
173 .I Fsinit
174 allocates a new
175 .B CFsys*
176 corresponding to a 9P conversation on the file descriptor
177 .I fd
178 and then calls
179 .IR fsversion
180 to initialize the connection.
181 .I Nsinit
182 does the same for name space services.
183 .I Fsversion
184 executes a
185 .IR version (9p)
186 transaction to establish
187 maximum message size and 9P version.
188 .I Fsauth
189 executes an
190 .IR auth (9p)
191 transaction, returning the new auth fid.
192 .RI ( Fsread
193 and
194 .I fswrite
195 can then be used to run the authentication protocol over the fid.)
196 .I Fsattach
197 executes an
198 .IR attach (9p)
199 transaction to connect to the root of a file tree served by the server.
200 It presents
201 .I afid
202 (which may be nil)
203 to establish identity.
204 .I Fssetroot
205 sets the root fid used by
206 .IR fsopen ,
207 .IR fsopenfd ,
208 .IR fsdirstat ,
209 and
210 .IR fsdirwstat ,
211 which evaluate rooted path names.
212 .PP
213 When a fid
214 is no longer needed, it should be clunked by calling
215 .I fsclose
216 and then considered freed.
217 Similarly, when the connection to the server is no longer needed,
218 it should be closed by calling
219 .IR fsunmount ,
220 which will take care of calling
221 .I fsclose
222 on the current root fid.
223 Once all fids have been clunked
224 .I and
225 the connection has been closed
226 (the order is not important),
227 the allocated structures will be freed and the
228 file descriptor corresponding to the connection
229 will be closed
230 (see
231 .MR close (2) ).
232 Fids are not reference counted: when
233 .I fsclose
234 is called, the clunk transaction and freeing of storage
235 happen immediately.
236 Despite its name,
237 .I fsclose
238 can be used to clunk fids that are not open for I/O.
239 .PP
240 .I Fscreate
241 and
242 .I fsopen
243 establish new fids using the
244 .IR walk ,
245 .I create
246 and
247 .I open
248 transactions
249 (see
250 .IR walk (9p)
251 and
252 .IR open (9p)).
253 The
254 .I path
255 argument is evaluated relative to the
256 .B CFsys
257 root
258 (see
259 .I fsroot
260 and
261 .I fssetroot
262 above).
263 The path is parsed as a slash-separated sequence of path elements,
264 as on Unix and Plan 9.
265 Elements that are empty or
266 dot
267 .RB ( . )
268 are ignored.
269 .PP
270 Alternately,
271 .I fswalk
272 walks from a fid to a given name
273 to create a new fid.
274 The name may be nil, corresponding to a walk with no names.
275 Otherwise the name is taken as a slash-separated sequence
276 of path elements.
277 .I Fsfcreate
278 and
279 .I fsfopen
280 issue
281 .I create
282 and
283 .I open
284 transactions using the passed fid argument,
285 which should have been obtained by calling
286 .IR fswalk .
287 .PP
288 Once opened, fids can be read and written using
289 .I fspread
290 and
291 .IR fspwrite ,
292 which execute
293 .I read
294 and
295 .I write
296 transactions
297 (see
298 .IR read (9p)).
299 The library maintains an offset for each fid,
300 analagous to the offset maintained by the kernel for each open file descriptor.
301 .I Fsread
302 and
303 .I fswrite
304 read and write from this offset, and update it after successful calls.
305 .I Fsseek
306 sets the offset; the
307 .I n
308 and
309 .I type
310 arguments are used as in
311 .MR seek (3) .
312 Calling
313 .I fspread
314 or
315 .I fspwrite
316 with an
317 .I offset
318 of \-1
319 is identical to calling
320 .I fsread
321 or
322 .IR fswrite .
323 .I Fsreadn
324 calls
325 .I fsread
326 repeatedly to obtain exactly
327 .I n
328 bytes of data, unless it encounters end-of-file or an error.
329 .PP
330 .IR Attach ,
331 .IR walk ,
332 .IR create ,
333 and
334 .I open
335 transactions include in their replies an updated qid for the
336 fid being manipulated.
337 .I Fsqid
338 returns the most recent qid returned by one of these transactions
339 for the given fid.
340 .PP
341 .I Fsaccess
342 behaves like Unix's
343 .MR access (2) .
344 .I Fsremove
345 removes the named path.
346 .I Fsfremove
347 removes the path corresponding to an open
348 .BR CFid* .
349 .PP
350 Reading an open a directory returns directory entries encoded as described in
351 .IR stat (9p).
352 .PP
353 .I Fsprint
354 and
355 .I fsvprint
356 are like
357 .I fprint
358 and
359 .I vfprint
360 (see
361 .MR print (3) )
362 but write to
363 .BR CFid* s.
364 .PP
365 .I Fsdirread
366 calls
367 .I fsread
368 and then parses the encoded entries into an array of
369 .B Dir*
370 data structures,
371 storing a pointer to the array in
372 .BI *d
373 and returning the number of entries.
374 .I Fsdirreadall
375 is similar but reads the entire directory.
376 The returned pointer should be freed with
377 .I free
378 (see
379 .MR malloc (3) )
380 when no longer needed.
381 .PP
382 .I Fsdirfstat
383 and
384 .I fsdirfwstat
385 execute
386 .I stat
387 and
388 .I wstat
389 (see
390 .IR stat (9p))
391 transactions.
392 The
393 .B Dir
394 structure returned by
395 .I fsdirfstat
396 should be freed with
397 .I free
398 (see
399 .MR malloc (3) )
400 when no longer needed.
401 .PP
402 .I Fsdirstat
403 and
404 .I fsdirwstat
405 are similar to
406 .I fsdirfstat
407 and
408 .I fsdirfwstat
409 but operate on paths relative to the file system root
410 (see
411 .I fsopen
412 and
413 .I fscreate
414 above).
415 .PP
416 .I Fsopenfd
417 opens a file on the 9P server
418 for reading or writing but returns a Unix file descriptor
419 instead of a fid structure.
420 The file descriptor is actually one end of a
421 .MR pipe (2) .
422 A proxy process on the other end is ferrying data
423 between the pipe and the 9P fid.
424 Because of the implementation as a pipe,
425 the only signal of a read or write error is the closing of the pipe.
426 The file descriptor remains valid even after the
427 .B CFsys
428 is unmounted.
429 .PP
430 .I Nsopen
431 opens a single file on a name space server: it runs
432 .IR nsmount ,
433 .IR fsopen ,
434 and then
435 .IR fsunmount .
436 .PP
437 If the
438 .B chatty9pclient
439 flag is set, the library prints all 9P messages
440 to standard error.
441 If the
442 .B eofkill9pclient
443 flag is set, the library calls
444 .I threadexitsall
445 (see
446 .MR thread (3) )
447 when it detects EOF on a 9P connection.
448 .SH SOURCE
449 .B \*9/src/lib9pclient
450 .SH SEE ALSO
451 .MR intro (4) ,
452 .IR intro (9p),
453 .I fsaopen
454 and
455 .I nsaopen
456 in
457 .MR auth (3)
458 .SH BUGS
459 The implementation
460 should use a special version string to distinguish between
461 servers that support
462 .IR openfd (9p)
463 and servers that do not.
464 .PP
465 The interface does not provide access to the
466 .IR walk (9p)
467 transaction, or to
468 .I open
469 and
470 .I create
471 on already-established fids.