1 058b0118 2005-01-03 devnull .TH 9PCLIENT 3
3 73a5509a 2006-07-23 devnull 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 058b0118 2005-01-03 devnull .SH SYNOPSIS
5 058b0118 2005-01-03 devnull .B #include <u.h>
7 058b0118 2005-01-03 devnull .B #include <libc.h>
9 058b0118 2005-01-03 devnull .B #include <fcall.h>
11 40a2ff6f 2006-01-30 devnull .B #include <thread.h>
13 058b0118 2005-01-03 devnull .B #include <9pclient.h>
14 c8b6342d 2005-01-13 devnull .ta +\w'\fLCFsys* 'u
17 058b0118 2005-01-03 devnull CFsys* fsmount(int fd, char *aname)
20 058b0118 2005-01-03 devnull CFsys* nsmount(char *name, char *aname)
23 058b0118 2005-01-03 devnull CFid* fsroot(CFsys *fsys)
26 058b0118 2005-01-03 devnull void fsunmount(CFsys *fsys)
29 058b0118 2005-01-03 devnull CFsys* fsinit(int fd)
32 d93fca6a 2005-02-11 devnull CFsys* nsinit(char *name)
35 058b0118 2005-01-03 devnull int fsversion(CFsys *fsys, int msize, char *version, int nversion)
38 e4d62adf 2005-01-18 devnull CFid* fsauth(CFsys *fsys, char *uname, char *aname)
41 e4d62adf 2005-01-18 devnull CFid* fsattach(CFsys *fsys, CFid *afid, char *uname, char *aname)
44 058b0118 2005-01-03 devnull void fssetroot(CFsys *fsys, CFid *fid)
47 058b0118 2005-01-03 devnull void fsclose(CFid *fid)
50 e4d62adf 2005-01-18 devnull CFid* fscreate(CFsys *fs, char *path, int mode, ulong perm)
53 73a5509a 2006-07-23 devnull int fsfcreate(CFid *fid, char *path, int mode, ulong perm)
56 5af8dd63 2006-03-19 devnull int fsremove(CFSys *fs, char *path)
59 5af8dd63 2006-03-19 devnull int fsfremove(CFid *fid)
62 5af8dd63 2006-03-19 devnull int fsaccess(CFsys *fs, char *path, int amode)
65 058b0118 2005-01-03 devnull CFid* fsopen(CFsys *fs, char *path, int mode)
68 73a5509a 2006-07-23 devnull int fsfopen(CFid *fid, char *path, int mode)
71 058b0118 2005-01-03 devnull long fspread(CFid *fid, void *buf, long n, vlong offset)
74 058b0118 2005-01-03 devnull long fspwrite(CFid *fid, void *buf, long n, vlong offset)
77 058b0118 2005-01-03 devnull long fsread(CFid *fid, void *buf, long n)
80 058b0118 2005-01-03 devnull long fsreadn(CFid *fid, void *buf, long n)
83 058b0118 2005-01-03 devnull long fswrite(CFid *fid, void *buf, long n)
86 5af8dd63 2006-03-19 devnull int fsprint(CFid *fid, char *fmt, ...)
89 5af8dd63 2006-03-19 devnull int fsvprint(CFid *fid, char *fmt, ...)
92 e4d62adf 2005-01-18 devnull vlong fsseek(CFid *Fid, vlong n, int type)
95 73a5509a 2006-07-23 devnull Qid fsqid(CFid *fid)
98 058b0118 2005-01-03 devnull long fsdirread(CFid *fid, Dir **d)
101 058b0118 2005-01-03 devnull long fsdirreadall(CFid *fid, Dir **d)
104 058b0118 2005-01-03 devnull Dir* fsdirstat(CFsys *fs, char *path)
107 058b0118 2005-01-03 devnull Dir* fsdirfstat(CFid *fid)
110 058b0118 2005-01-03 devnull int fsdirwstat(CFsys *fs, char *path, Dir *d)
113 058b0118 2005-01-03 devnull int fsdirfwstat(CFid *fid, Dir *d)
116 058b0118 2005-01-03 devnull int fsopenfd(CFsys *fs, char *path, int mode)
119 d93fca6a 2005-02-11 devnull CFsys* nsopen(char *name, char *aname, char *path, int mode)
122 73a5509a 2006-07-23 devnull extern int chatty9pclient;
125 73a5509a 2006-07-23 devnull extern int eofkill9pclient;
126 058b0118 2005-01-03 devnull .SH DESCRIPTION
128 058b0118 2005-01-03 devnull .I 9pclient
129 058b0118 2005-01-03 devnull library helps client programs interact with 9P servers.
132 058b0118 2005-01-03 devnull .B CFsys*
133 058b0118 2005-01-03 devnull represents a connection to a 9P server.
135 058b0118 2005-01-03 devnull .B CFid*
136 058b0118 2005-01-03 devnull represents an active fid on some connection;
138 058b0118 2005-01-03 devnull .IR intro (9p).
140 058b0118 2005-01-03 devnull A new connection to a 9P server is typically established by
141 058b0118 2005-01-03 devnull .I fsmount
143 058b0118 2005-01-03 devnull .IR nsmount .
144 058b0118 2005-01-03 devnull .I Fsmount
145 058b0118 2005-01-03 devnull initializes a new 9P conversation on the open file descriptor
146 058b0118 2005-01-03 devnull .IR fd ;
147 058b0118 2005-01-03 devnull .I nsmount
148 058b0118 2005-01-03 devnull connects to a service named
150 058b0118 2005-01-03 devnull in the current name space directory
152 d32deab1 2020-08-16 rsc .MR intro (4) ).
153 058b0118 2005-01-03 devnull Both attach to the root of the file system
154 058b0118 2005-01-03 devnull using the attach name
155 058b0118 2005-01-03 devnull .IR aname .
156 058b0118 2005-01-03 devnull .I Fsroot
157 058b0118 2005-01-03 devnull returns the
158 058b0118 2005-01-03 devnull .B CFid*
159 058b0118 2005-01-03 devnull corresponding to this root.
161 058b0118 2005-01-03 devnull .IR Fsinit ,
162 d93fca6a 2005-02-11 devnull .IR nsinit ,
163 058b0118 2005-01-03 devnull .IR fsversion ,
164 058b0118 2005-01-03 devnull .IR fsauth ,
165 058b0118 2005-01-03 devnull .IR fsattach ,
167 058b0118 2005-01-03 devnull .I fssetroot
168 058b0118 2005-01-03 devnull provide more detailed control over the file system connection
170 058b0118 2005-01-03 devnull .I fsmount
172 058b0118 2005-01-03 devnull .IR nsmount .
173 058b0118 2005-01-03 devnull .I Fsinit
174 058b0118 2005-01-03 devnull allocates a new
175 058b0118 2005-01-03 devnull .B CFsys*
176 058b0118 2005-01-03 devnull corresponding to a 9P conversation on the file descriptor
178 d93fca6a 2005-02-11 devnull and then calls
179 d93fca6a 2005-02-11 devnull .IR fsversion
180 d93fca6a 2005-02-11 devnull to initialize the connection.
181 d93fca6a 2005-02-11 devnull .I Nsinit
182 d93fca6a 2005-02-11 devnull does the same for name space services.
183 058b0118 2005-01-03 devnull .I Fsversion
184 058b0118 2005-01-03 devnull executes a
185 058b0118 2005-01-03 devnull .IR version (9p)
186 058b0118 2005-01-03 devnull transaction to establish
187 058b0118 2005-01-03 devnull maximum message size and 9P version.
188 058b0118 2005-01-03 devnull .I Fsauth
189 058b0118 2005-01-03 devnull executes an
190 058b0118 2005-01-03 devnull .IR auth (9p)
191 058b0118 2005-01-03 devnull transaction, returning the new auth fid.
192 058b0118 2005-01-03 devnull .RI ( Fsread
194 058b0118 2005-01-03 devnull .I fswrite
195 058b0118 2005-01-03 devnull can then be used to run the authentication protocol over the fid.)
196 058b0118 2005-01-03 devnull .I Fsattach
197 058b0118 2005-01-03 devnull executes an
198 058b0118 2005-01-03 devnull .IR attach (9p)
199 058b0118 2005-01-03 devnull transaction to connect to the root of a file tree served by the server.
200 058b0118 2005-01-03 devnull It presents
202 058b0118 2005-01-03 devnull (which may be nil)
203 058b0118 2005-01-03 devnull to establish identity.
204 058b0118 2005-01-03 devnull .I Fssetroot
205 058b0118 2005-01-03 devnull sets the root fid used by
206 058b0118 2005-01-03 devnull .IR fsopen ,
207 058b0118 2005-01-03 devnull .IR fsopenfd ,
208 058b0118 2005-01-03 devnull .IR fsdirstat ,
210 058b0118 2005-01-03 devnull .IR fsdirwstat ,
211 058b0118 2005-01-03 devnull which evaluate rooted path names.
213 058b0118 2005-01-03 devnull When a fid
214 058b0118 2005-01-03 devnull is no longer needed, it should be clunked by calling
215 058b0118 2005-01-03 devnull .I fsclose
216 058b0118 2005-01-03 devnull and then considered freed.
217 058b0118 2005-01-03 devnull Similarly, when the connection to the server is no longer needed,
218 058b0118 2005-01-03 devnull it should be closed by calling
219 058b0118 2005-01-03 devnull .IR fsunmount ,
220 058b0118 2005-01-03 devnull which will take care of calling
221 058b0118 2005-01-03 devnull .I fsclose
222 058b0118 2005-01-03 devnull on the current root fid.
223 058b0118 2005-01-03 devnull Once all fids have been clunked
225 058b0118 2005-01-03 devnull the connection has been closed
226 058b0118 2005-01-03 devnull (the order is not important),
227 058b0118 2005-01-03 devnull the allocated structures will be freed and the
228 058b0118 2005-01-03 devnull file descriptor corresponding to the connection
229 058b0118 2005-01-03 devnull will be closed
231 d32deab1 2020-08-16 rsc .MR close (2) ).
232 058b0118 2005-01-03 devnull Fids are not reference counted: when
233 058b0118 2005-01-03 devnull .I fsclose
234 058b0118 2005-01-03 devnull is called, the clunk transaction and freeing of storage
235 058b0118 2005-01-03 devnull happen immediately.
236 73a5509a 2006-07-23 devnull Despite its name,
237 73a5509a 2006-07-23 devnull .I fsclose
238 73a5509a 2006-07-23 devnull can be used to clunk fids that are not open for I/O.
240 058b0118 2005-01-03 devnull .I Fscreate
242 058b0118 2005-01-03 devnull .I fsopen
243 058b0118 2005-01-03 devnull establish new fids using the
244 058b0118 2005-01-03 devnull .IR walk ,
245 058b0118 2005-01-03 devnull .I create
248 058b0118 2005-01-03 devnull transactions
250 058b0118 2005-01-03 devnull .IR walk (9p)
252 058b0118 2005-01-03 devnull .IR open (9p)).
255 058b0118 2005-01-03 devnull argument is evaluated relative to the
256 058b0118 2005-01-03 devnull .B CFsys
259 058b0118 2005-01-03 devnull .I fsroot
261 058b0118 2005-01-03 devnull .I fssetroot
263 058b0118 2005-01-03 devnull The path is parsed as a slash-separated sequence of path elements,
264 058b0118 2005-01-03 devnull as on Unix and Plan 9.
265 058b0118 2005-01-03 devnull Elements that are empty or
267 c8b6342d 2005-01-13 devnull .RB ( . )
268 058b0118 2005-01-03 devnull are ignored.
270 73a5509a 2006-07-23 devnull Alternately,
271 73a5509a 2006-07-23 devnull .I fswalk
272 73a5509a 2006-07-23 devnull walks from a fid to a given name
273 73a5509a 2006-07-23 devnull to create a new fid.
274 73a5509a 2006-07-23 devnull The name may be nil, corresponding to a walk with no names.
275 73a5509a 2006-07-23 devnull Otherwise the name is taken as a slash-separated sequence
276 73a5509a 2006-07-23 devnull of path elements.
277 73a5509a 2006-07-23 devnull .I Fsfcreate
279 73a5509a 2006-07-23 devnull .I fsfopen
281 73a5509a 2006-07-23 devnull .I create
284 73a5509a 2006-07-23 devnull transactions using the passed fid argument,
285 73a5509a 2006-07-23 devnull which should have been obtained by calling
286 73a5509a 2006-07-23 devnull .IR fswalk .
288 73a5509a 2006-07-23 devnull Once opened, fids can be read and written using
289 058b0118 2005-01-03 devnull .I fspread
291 058b0118 2005-01-03 devnull .IR fspwrite ,
292 058b0118 2005-01-03 devnull which execute
295 058b0118 2005-01-03 devnull .I write
296 058b0118 2005-01-03 devnull transactions
298 058b0118 2005-01-03 devnull .IR read (9p)).
299 058b0118 2005-01-03 devnull The library maintains an offset for each fid,
300 058b0118 2005-01-03 devnull analagous to the offset maintained by the kernel for each open file descriptor.
301 058b0118 2005-01-03 devnull .I Fsread
303 058b0118 2005-01-03 devnull .I fswrite
304 058b0118 2005-01-03 devnull read and write from this offset, and update it after successful calls.
305 e4d62adf 2005-01-18 devnull .I Fsseek
306 e4d62adf 2005-01-18 devnull sets the offset; the
310 e4d62adf 2005-01-18 devnull arguments are used as in
311 d32deab1 2020-08-16 rsc .MR seek (3) .
313 058b0118 2005-01-03 devnull .I fspread
315 058b0118 2005-01-03 devnull .I fspwrite
317 058b0118 2005-01-03 devnull .I offset
319 058b0118 2005-01-03 devnull is identical to calling
320 058b0118 2005-01-03 devnull .I fsread
322 058b0118 2005-01-03 devnull .IR fswrite .
323 058b0118 2005-01-03 devnull .I Fsreadn
325 058b0118 2005-01-03 devnull .I fsread
326 058b0118 2005-01-03 devnull repeatedly to obtain exactly
328 058b0118 2005-01-03 devnull bytes of data, unless it encounters end-of-file or an error.
330 73a5509a 2006-07-23 devnull .IR Attach ,
331 73a5509a 2006-07-23 devnull .IR walk ,
332 73a5509a 2006-07-23 devnull .IR create ,
335 73a5509a 2006-07-23 devnull transactions include in their replies an updated qid for the
336 73a5509a 2006-07-23 devnull fid being manipulated.
337 73a5509a 2006-07-23 devnull .I Fsqid
338 73a5509a 2006-07-23 devnull returns the most recent qid returned by one of these transactions
339 73a5509a 2006-07-23 devnull for the given fid.
341 5af8dd63 2006-03-19 devnull .I Fsaccess
342 5af8dd63 2006-03-19 devnull behaves like Unix's
343 d32deab1 2020-08-16 rsc .MR access (2) .
344 5af8dd63 2006-03-19 devnull .I Fsremove
345 5af8dd63 2006-03-19 devnull removes the named path.
346 5af8dd63 2006-03-19 devnull .I Fsfremove
347 5af8dd63 2006-03-19 devnull removes the path corresponding to an open
348 5af8dd63 2006-03-19 devnull .BR CFid* .
350 058b0118 2005-01-03 devnull Reading an open a directory returns directory entries encoded as described in
351 058b0118 2005-01-03 devnull .IR stat (9p).
353 5af8dd63 2006-03-19 devnull .I Fsprint
355 5af8dd63 2006-03-19 devnull .I fsvprint
356 5af8dd63 2006-03-19 devnull are like
357 5af8dd63 2006-03-19 devnull .I fprint
359 5af8dd63 2006-03-19 devnull .I vfprint
361 d32deab1 2020-08-16 rsc .MR print (3) )
362 5af8dd63 2006-03-19 devnull but write to
363 5af8dd63 2006-03-19 devnull .BR CFid* s.
365 058b0118 2005-01-03 devnull .I Fsdirread
367 058b0118 2005-01-03 devnull .I fsread
368 058b0118 2005-01-03 devnull and then parses the encoded entries into an array of
370 058b0118 2005-01-03 devnull data structures,
371 058b0118 2005-01-03 devnull storing a pointer to the array in
373 058b0118 2005-01-03 devnull and returning the number of entries.
374 058b0118 2005-01-03 devnull .I Fsdirreadall
375 058b0118 2005-01-03 devnull is similar but reads the entire directory.
376 058b0118 2005-01-03 devnull The returned pointer should be freed with
379 d32deab1 2020-08-16 rsc .MR malloc (3) )
380 058b0118 2005-01-03 devnull when no longer needed.
382 058b0118 2005-01-03 devnull .I Fsdirfstat
384 058b0118 2005-01-03 devnull .I fsdirfwstat
388 058b0118 2005-01-03 devnull .I wstat
390 058b0118 2005-01-03 devnull .IR stat (9p))
391 058b0118 2005-01-03 devnull transactions.
394 058b0118 2005-01-03 devnull structure returned by
395 058b0118 2005-01-03 devnull .I fsdirfstat
396 058b0118 2005-01-03 devnull should be freed with
399 d32deab1 2020-08-16 rsc .MR malloc (3) )
400 058b0118 2005-01-03 devnull when no longer needed.
402 058b0118 2005-01-03 devnull .I Fsdirstat
404 058b0118 2005-01-03 devnull .I fsdirwstat
405 058b0118 2005-01-03 devnull are similar to
406 058b0118 2005-01-03 devnull .I fsdirfstat
408 058b0118 2005-01-03 devnull .I fsdirfwstat
409 058b0118 2005-01-03 devnull but operate on paths relative to the file system root
411 058b0118 2005-01-03 devnull .I fsopen
413 058b0118 2005-01-03 devnull .I fscreate
416 058b0118 2005-01-03 devnull .I Fsopenfd
417 058b0118 2005-01-03 devnull opens a file on the 9P server
418 058b0118 2005-01-03 devnull for reading or writing but returns a Unix file descriptor
419 058b0118 2005-01-03 devnull instead of a fid structure.
420 058b0118 2005-01-03 devnull The file descriptor is actually one end of a
421 d32deab1 2020-08-16 rsc .MR pipe (2) .
422 058b0118 2005-01-03 devnull A proxy process on the other end is ferrying data
423 058b0118 2005-01-03 devnull between the pipe and the 9P fid.
424 058b0118 2005-01-03 devnull Because of the implementation as a pipe,
425 058b0118 2005-01-03 devnull the only signal of a read or write error is the closing of the pipe.
426 058b0118 2005-01-03 devnull The file descriptor remains valid even after the
427 058b0118 2005-01-03 devnull .B CFsys
428 058b0118 2005-01-03 devnull is unmounted.
430 d93fca6a 2005-02-11 devnull .I Nsopen
431 d93fca6a 2005-02-11 devnull opens a single file on a name space server: it runs
432 d93fca6a 2005-02-11 devnull .IR nsmount ,
433 d93fca6a 2005-02-11 devnull .IR fsopen ,
434 d93fca6a 2005-02-11 devnull and then
435 d93fca6a 2005-02-11 devnull .IR fsunmount .
438 73a5509a 2006-07-23 devnull .B chatty9pclient
439 73a5509a 2006-07-23 devnull flag is set, the library prints all 9P messages
440 73a5509a 2006-07-23 devnull to standard error.
442 73a5509a 2006-07-23 devnull .B eofkill9pclient
443 73a5509a 2006-07-23 devnull flag is set, the library calls
444 73a5509a 2006-07-23 devnull .I threadexitsall
446 d32deab1 2020-08-16 rsc .MR thread (3) )
447 73a5509a 2006-07-23 devnull when it detects EOF on a 9P connection.
448 058b0118 2005-01-03 devnull .SH SOURCE
449 c3674de4 2005-01-11 devnull .B \*9/src/lib9pclient
450 058b0118 2005-01-03 devnull .SH SEE ALSO
451 d32deab1 2020-08-16 rsc .MR intro (4) ,
452 d93fca6a 2005-02-11 devnull .IR intro (9p),
453 d93fca6a 2005-02-11 devnull .I fsaopen
455 d93fca6a 2005-02-11 devnull .I nsaopen
457 d32deab1 2020-08-16 rsc .MR auth (3)
458 058b0118 2005-01-03 devnull .SH BUGS
459 058b0118 2005-01-03 devnull The implementation
460 058b0118 2005-01-03 devnull should use a special version string to distinguish between
461 058b0118 2005-01-03 devnull servers that support
462 058b0118 2005-01-03 devnull .IR openfd (9p)
463 058b0118 2005-01-03 devnull and servers that do not.
465 058b0118 2005-01-03 devnull The interface does not provide access to the
466 058b0118 2005-01-03 devnull .IR walk (9p)
467 058b0118 2005-01-03 devnull transaction, or to
470 058b0118 2005-01-03 devnull .I create
471 058b0118 2005-01-03 devnull on already-established fids.
