1 058b0118 2005-01-03 devnull .TH 9PCLIENT 3
3 5af8dd63 2006-03-19 devnull CFid, CFsys, fsinit, fsmount, fsroot, fssetroot, fsunmount, nsinit, nsmount, fsversion, fsauth, fsattach, fsclose, fscreate, fsremove, fsfremove, fsaccess, fsdirread, fsdirreadall, fsdirstat, fsdirfstat, fsdirwstat, fsdirfwstat, fsopen, 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 5af8dd63 2006-03-19 devnull int fsremove(CFSys *fs, char *path)
56 5af8dd63 2006-03-19 devnull int fsfremove(CFid *fid)
59 5af8dd63 2006-03-19 devnull int fsaccess(CFsys *fs, char *path, int amode)
62 058b0118 2005-01-03 devnull CFid* fsopen(CFsys *fs, char *path, int mode)
65 058b0118 2005-01-03 devnull long fspread(CFid *fid, void *buf, long n, vlong offset)
68 058b0118 2005-01-03 devnull long fspwrite(CFid *fid, void *buf, long n, vlong offset)
71 058b0118 2005-01-03 devnull long fsread(CFid *fid, void *buf, long n)
74 058b0118 2005-01-03 devnull long fsreadn(CFid *fid, void *buf, long n)
77 058b0118 2005-01-03 devnull long fswrite(CFid *fid, void *buf, long n)
80 5af8dd63 2006-03-19 devnull int fsprint(CFid *fid, char *fmt, ...)
83 5af8dd63 2006-03-19 devnull int fsvprint(CFid *fid, char *fmt, ...)
86 e4d62adf 2005-01-18 devnull vlong fsseek(CFid *Fid, vlong n, int type)
89 058b0118 2005-01-03 devnull long fsdirread(CFid *fid, Dir **d)
92 058b0118 2005-01-03 devnull long fsdirreadall(CFid *fid, Dir **d)
95 058b0118 2005-01-03 devnull Dir* fsdirstat(CFsys *fs, char *path)
98 058b0118 2005-01-03 devnull Dir* fsdirfstat(CFid *fid)
101 058b0118 2005-01-03 devnull int fsdirwstat(CFsys *fs, char *path, Dir *d)
104 058b0118 2005-01-03 devnull int fsdirfwstat(CFid *fid, Dir *d)
107 058b0118 2005-01-03 devnull int fsopenfd(CFsys *fs, char *path, int mode)
110 d93fca6a 2005-02-11 devnull CFsys* nsopen(char *name, char *aname, char *path, int mode)
111 058b0118 2005-01-03 devnull .SH DESCRIPTION
113 058b0118 2005-01-03 devnull .I 9pclient
114 058b0118 2005-01-03 devnull library helps client programs interact with 9P servers.
117 058b0118 2005-01-03 devnull .B CFsys*
118 058b0118 2005-01-03 devnull represents a connection to a 9P server.
120 058b0118 2005-01-03 devnull .B CFid*
121 058b0118 2005-01-03 devnull represents an active fid on some connection;
123 058b0118 2005-01-03 devnull .IR intro (9p).
125 058b0118 2005-01-03 devnull A new connection to a 9P server is typically established by
126 058b0118 2005-01-03 devnull .I fsmount
128 058b0118 2005-01-03 devnull .IR nsmount .
129 058b0118 2005-01-03 devnull .I Fsmount
130 058b0118 2005-01-03 devnull initializes a new 9P conversation on the open file descriptor
131 058b0118 2005-01-03 devnull .IR fd ;
132 058b0118 2005-01-03 devnull .I nsmount
133 058b0118 2005-01-03 devnull connects to a service named
135 058b0118 2005-01-03 devnull in the current name space directory
137 058b0118 2005-01-03 devnull .IR intro (4)).
138 058b0118 2005-01-03 devnull Both attach to the root of the file system
139 058b0118 2005-01-03 devnull using the attach name
140 058b0118 2005-01-03 devnull .IR aname .
141 058b0118 2005-01-03 devnull .I Fsroot
142 058b0118 2005-01-03 devnull returns the
143 058b0118 2005-01-03 devnull .B CFid*
144 058b0118 2005-01-03 devnull corresponding to this root.
146 058b0118 2005-01-03 devnull .IR Fsinit ,
147 d93fca6a 2005-02-11 devnull .IR nsinit ,
148 058b0118 2005-01-03 devnull .IR fsversion ,
149 058b0118 2005-01-03 devnull .IR fsauth ,
150 058b0118 2005-01-03 devnull .IR fsattach ,
152 058b0118 2005-01-03 devnull .I fssetroot
153 058b0118 2005-01-03 devnull provide more detailed control over the file system connection
155 058b0118 2005-01-03 devnull .I fsmount
157 058b0118 2005-01-03 devnull .IR nsmount .
158 058b0118 2005-01-03 devnull .I Fsinit
159 058b0118 2005-01-03 devnull allocates a new
160 058b0118 2005-01-03 devnull .B CFsys*
161 058b0118 2005-01-03 devnull corresponding to a 9P conversation on the file descriptor
163 d93fca6a 2005-02-11 devnull and then calls
164 d93fca6a 2005-02-11 devnull .IR fsversion
165 d93fca6a 2005-02-11 devnull to initialize the connection.
166 d93fca6a 2005-02-11 devnull .I Nsinit
167 d93fca6a 2005-02-11 devnull does the same for name space services.
168 058b0118 2005-01-03 devnull .I Fsversion
169 058b0118 2005-01-03 devnull executes a
170 058b0118 2005-01-03 devnull .IR version (9p)
171 058b0118 2005-01-03 devnull transaction to establish
172 058b0118 2005-01-03 devnull maximum message size and 9P version.
173 058b0118 2005-01-03 devnull .I Fsauth
174 058b0118 2005-01-03 devnull executes an
175 058b0118 2005-01-03 devnull .IR auth (9p)
176 058b0118 2005-01-03 devnull transaction, returning the new auth fid.
177 058b0118 2005-01-03 devnull .RI ( Fsread
179 058b0118 2005-01-03 devnull .I fswrite
180 058b0118 2005-01-03 devnull can then be used to run the authentication protocol over the fid.)
181 058b0118 2005-01-03 devnull .I Fsattach
182 058b0118 2005-01-03 devnull executes an
183 058b0118 2005-01-03 devnull .IR attach (9p)
184 058b0118 2005-01-03 devnull transaction to connect to the root of a file tree served by the server.
185 058b0118 2005-01-03 devnull It presents
187 058b0118 2005-01-03 devnull (which may be nil)
188 058b0118 2005-01-03 devnull to establish identity.
189 058b0118 2005-01-03 devnull .I Fssetroot
190 058b0118 2005-01-03 devnull sets the root fid used by
191 058b0118 2005-01-03 devnull .IR fsopen ,
192 058b0118 2005-01-03 devnull .IR fsopenfd ,
193 058b0118 2005-01-03 devnull .IR fsdirstat ,
195 058b0118 2005-01-03 devnull .IR fsdirwstat ,
196 058b0118 2005-01-03 devnull which evaluate rooted path names.
198 058b0118 2005-01-03 devnull When a fid
199 058b0118 2005-01-03 devnull is no longer needed, it should be clunked by calling
200 058b0118 2005-01-03 devnull .I fsclose
201 058b0118 2005-01-03 devnull and then considered freed.
202 058b0118 2005-01-03 devnull Similarly, when the connection to the server is no longer needed,
203 058b0118 2005-01-03 devnull it should be closed by calling
204 058b0118 2005-01-03 devnull .IR fsunmount ,
205 058b0118 2005-01-03 devnull which will take care of calling
206 058b0118 2005-01-03 devnull .I fsclose
207 058b0118 2005-01-03 devnull on the current root fid.
208 058b0118 2005-01-03 devnull Once all fids have been clunked
210 058b0118 2005-01-03 devnull the connection has been closed
211 058b0118 2005-01-03 devnull (the order is not important),
212 058b0118 2005-01-03 devnull the allocated structures will be freed and the
213 058b0118 2005-01-03 devnull file descriptor corresponding to the connection
214 058b0118 2005-01-03 devnull will be closed
216 058b0118 2005-01-03 devnull .IR close (2)).
217 058b0118 2005-01-03 devnull Fids are not reference counted: when
218 058b0118 2005-01-03 devnull .I fsclose
219 058b0118 2005-01-03 devnull is called, the clunk transaction and freeing of storage
220 058b0118 2005-01-03 devnull happen immediately.
222 058b0118 2005-01-03 devnull .I Fscreate
224 058b0118 2005-01-03 devnull .I fsopen
225 058b0118 2005-01-03 devnull establish new fids using the
226 058b0118 2005-01-03 devnull .IR walk ,
227 058b0118 2005-01-03 devnull .I create
230 058b0118 2005-01-03 devnull transactions
232 058b0118 2005-01-03 devnull .IR walk (9p)
234 058b0118 2005-01-03 devnull .IR open (9p)).
237 058b0118 2005-01-03 devnull argument is evaluated relative to the
238 058b0118 2005-01-03 devnull .B CFsys
241 058b0118 2005-01-03 devnull .I fsroot
243 058b0118 2005-01-03 devnull .I fssetroot
245 058b0118 2005-01-03 devnull The path is parsed as a slash-separated sequence of path elements,
246 058b0118 2005-01-03 devnull as on Unix and Plan 9.
247 058b0118 2005-01-03 devnull Elements that are empty or
249 c8b6342d 2005-01-13 devnull .RB ( . )
250 058b0118 2005-01-03 devnull are ignored.
252 058b0118 2005-01-03 devnull Once opened, these fids can be read and written using
253 058b0118 2005-01-03 devnull .I fspread
255 058b0118 2005-01-03 devnull .IR fspwrite ,
256 058b0118 2005-01-03 devnull which execute
259 058b0118 2005-01-03 devnull .I write
260 058b0118 2005-01-03 devnull transactions
262 058b0118 2005-01-03 devnull .IR read (9p)).
263 058b0118 2005-01-03 devnull The library maintains an offset for each fid,
264 058b0118 2005-01-03 devnull analagous to the offset maintained by the kernel for each open file descriptor.
265 058b0118 2005-01-03 devnull .I Fsread
267 058b0118 2005-01-03 devnull .I fswrite
268 058b0118 2005-01-03 devnull read and write from this offset, and update it after successful calls.
269 e4d62adf 2005-01-18 devnull .I Fsseek
270 e4d62adf 2005-01-18 devnull sets the offset; the
274 e4d62adf 2005-01-18 devnull arguments are used as in
275 e4d62adf 2005-01-18 devnull .IR seek (3).
277 058b0118 2005-01-03 devnull .I fspread
279 058b0118 2005-01-03 devnull .I fspwrite
281 058b0118 2005-01-03 devnull .I offset
283 058b0118 2005-01-03 devnull is identical to calling
284 058b0118 2005-01-03 devnull .I fsread
286 058b0118 2005-01-03 devnull .IR fswrite .
287 058b0118 2005-01-03 devnull .I Fsreadn
289 058b0118 2005-01-03 devnull .I fsread
290 058b0118 2005-01-03 devnull repeatedly to obtain exactly
292 058b0118 2005-01-03 devnull bytes of data, unless it encounters end-of-file or an error.
294 5af8dd63 2006-03-19 devnull .I Fsaccess
295 5af8dd63 2006-03-19 devnull behaves like Unix's
296 5af8dd63 2006-03-19 devnull .IR access (2).
297 5af8dd63 2006-03-19 devnull .I Fsremove
298 5af8dd63 2006-03-19 devnull removes the named path.
299 5af8dd63 2006-03-19 devnull .I Fsfremove
300 5af8dd63 2006-03-19 devnull removes the path corresponding to an open
301 5af8dd63 2006-03-19 devnull .BR CFid* .
303 058b0118 2005-01-03 devnull Reading an open a directory returns directory entries encoded as described in
304 058b0118 2005-01-03 devnull .IR stat (9p).
306 5af8dd63 2006-03-19 devnull .I Fsprint
308 5af8dd63 2006-03-19 devnull .I fsvprint
309 5af8dd63 2006-03-19 devnull are like
310 5af8dd63 2006-03-19 devnull .I fprint
312 5af8dd63 2006-03-19 devnull .I vfprint
314 5af8dd63 2006-03-19 devnull .IR print (3))
315 5af8dd63 2006-03-19 devnull but write to
316 5af8dd63 2006-03-19 devnull .BR CFid* s.
318 058b0118 2005-01-03 devnull .I Fsdirread
320 058b0118 2005-01-03 devnull .I fsread
321 058b0118 2005-01-03 devnull and then parses the encoded entries into an array of
323 058b0118 2005-01-03 devnull data structures,
324 058b0118 2005-01-03 devnull storing a pointer to the array in
326 058b0118 2005-01-03 devnull and returning the number of entries.
327 058b0118 2005-01-03 devnull .I Fsdirreadall
328 058b0118 2005-01-03 devnull is similar but reads the entire directory.
329 058b0118 2005-01-03 devnull The returned pointer should be freed with
332 058b0118 2005-01-03 devnull .IR malloc (3))
333 058b0118 2005-01-03 devnull when no longer needed.
335 058b0118 2005-01-03 devnull .I Fsdirfstat
337 058b0118 2005-01-03 devnull .I fsdirfwstat
341 058b0118 2005-01-03 devnull .I wstat
343 058b0118 2005-01-03 devnull .IR stat (9p))
344 058b0118 2005-01-03 devnull transactions.
347 058b0118 2005-01-03 devnull structure returned by
348 058b0118 2005-01-03 devnull .I fsdirfstat
349 058b0118 2005-01-03 devnull should be freed with
352 058b0118 2005-01-03 devnull .IR malloc (3))
353 058b0118 2005-01-03 devnull when no longer needed.
355 058b0118 2005-01-03 devnull .I Fsdirstat
357 058b0118 2005-01-03 devnull .I fsdirwstat
358 058b0118 2005-01-03 devnull are similar to
359 058b0118 2005-01-03 devnull .I fsdirfstat
361 058b0118 2005-01-03 devnull .I fsdirfwstat
362 058b0118 2005-01-03 devnull but operate on paths relative to the file system root
364 058b0118 2005-01-03 devnull .I fsopen
366 058b0118 2005-01-03 devnull .I fscreate
369 058b0118 2005-01-03 devnull .I Fsopenfd
370 058b0118 2005-01-03 devnull opens a file on the 9P server
371 058b0118 2005-01-03 devnull for reading or writing but returns a Unix file descriptor
372 058b0118 2005-01-03 devnull instead of a fid structure.
373 058b0118 2005-01-03 devnull The file descriptor is actually one end of a
374 058b0118 2005-01-03 devnull .IR pipe (2).
375 058b0118 2005-01-03 devnull A proxy process on the other end is ferrying data
376 058b0118 2005-01-03 devnull between the pipe and the 9P fid.
377 058b0118 2005-01-03 devnull Because of the implementation as a pipe,
378 058b0118 2005-01-03 devnull the only signal of a read or write error is the closing of the pipe.
379 058b0118 2005-01-03 devnull The file descriptor remains valid even after the
380 058b0118 2005-01-03 devnull .B CFsys
381 058b0118 2005-01-03 devnull is unmounted.
383 d93fca6a 2005-02-11 devnull .I Nsopen
384 d93fca6a 2005-02-11 devnull opens a single file on a name space server: it runs
385 d93fca6a 2005-02-11 devnull .IR nsmount ,
386 d93fca6a 2005-02-11 devnull .IR fsopen ,
387 d93fca6a 2005-02-11 devnull and then
388 d93fca6a 2005-02-11 devnull .IR fsunmount .
389 058b0118 2005-01-03 devnull .SH SOURCE
390 c3674de4 2005-01-11 devnull .B \*9/src/lib9pclient
391 058b0118 2005-01-03 devnull .SH SEE ALSO
392 058b0118 2005-01-03 devnull .IR intro (4),
393 d93fca6a 2005-02-11 devnull .IR intro (9p),
394 d93fca6a 2005-02-11 devnull .I fsaopen
396 d93fca6a 2005-02-11 devnull .I nsaopen
398 d93fca6a 2005-02-11 devnull .IR auth (3)
399 058b0118 2005-01-03 devnull .SH BUGS
400 058b0118 2005-01-03 devnull The implementation
401 058b0118 2005-01-03 devnull should use a special version string to distinguish between
402 058b0118 2005-01-03 devnull servers that support
403 058b0118 2005-01-03 devnull .IR openfd (9p)
404 058b0118 2005-01-03 devnull and servers that do not.
406 058b0118 2005-01-03 devnull The interface does not provide access to the
407 058b0118 2005-01-03 devnull .IR walk (9p)
408 058b0118 2005-01-03 devnull transaction, or to
411 058b0118 2005-01-03 devnull .I create
412 058b0118 2005-01-03 devnull on already-established fids.