1 058b0118 2005-01-03 devnull .TH 9PCLIENT 3
3 058b0118 2005-01-03 devnull 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
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 058b0118 2005-01-03 devnull .B #include <9pclient.h>
13 058b0118 2005-01-03 devnull .ta +'\fLCFsys* 'u
15 058b0118 2005-01-03 devnull CFsys* fsmount(int fd, char *aname)
18 058b0118 2005-01-03 devnull CFsys* nsmount(char *name, char *aname)
21 058b0118 2005-01-03 devnull CFid* fsroot(CFsys *fsys)
24 058b0118 2005-01-03 devnull void fsunmount(CFsys *fsys)
27 058b0118 2005-01-03 devnull CFsys* fsinit(int fd)
30 058b0118 2005-01-03 devnull int fsversion(CFsys *fsys, int msize, char *version, int nversion)
33 058b0118 2005-01-03 devnull CFid *fsauth(CFsys *fsys, char *uname, char *aname)
36 058b0118 2005-01-03 devnull CFid *fsattach(CFsys *fsys, CFid *afid, char *uname, char *aname)
39 058b0118 2005-01-03 devnull void fssetroot(CFsys *fsys, CFid *fid)
42 058b0118 2005-01-03 devnull void fsclose(CFid *fid)
45 058b0118 2005-01-03 devnull CFid *fscreate(CFsys *fs, char *path, int mode, ulong perm)
48 058b0118 2005-01-03 devnull CFid* fsopen(CFsys *fs, char *path, int mode)
51 058b0118 2005-01-03 devnull long fspread(CFid *fid, void *buf, long n, vlong offset)
54 058b0118 2005-01-03 devnull long fspwrite(CFid *fid, void *buf, long n, vlong offset)
57 058b0118 2005-01-03 devnull long fsread(CFid *fid, void *buf, long n)
60 058b0118 2005-01-03 devnull long fsreadn(CFid *fid, void *buf, long n)
63 058b0118 2005-01-03 devnull long fswrite(CFid *fid, void *buf, long n)
66 058b0118 2005-01-03 devnull long fsdirread(CFid *fid, Dir **d)
69 058b0118 2005-01-03 devnull long fsdirreadall(CFid *fid, Dir **d)
72 058b0118 2005-01-03 devnull Dir* fsdirstat(CFsys *fs, char *path)
75 058b0118 2005-01-03 devnull Dir* fsdirfstat(CFid *fid)
78 058b0118 2005-01-03 devnull int fsdirwstat(CFsys *fs, char *path, Dir *d)
81 058b0118 2005-01-03 devnull int fsdirfwstat(CFid *fid, Dir *d)
84 058b0118 2005-01-03 devnull int fsopenfd(CFsys *fs, char *path, int mode)
85 058b0118 2005-01-03 devnull .SH DESCRIPTION
87 058b0118 2005-01-03 devnull .I 9pclient
88 058b0118 2005-01-03 devnull library helps client programs interact with 9P servers.
91 058b0118 2005-01-03 devnull .B CFsys*
92 058b0118 2005-01-03 devnull represents a connection to a 9P server.
95 058b0118 2005-01-03 devnull represents an active fid on some connection;
97 058b0118 2005-01-03 devnull .IR intro (9p).
99 058b0118 2005-01-03 devnull A new connection to a 9P server is typically established by
100 058b0118 2005-01-03 devnull .I fsmount
102 058b0118 2005-01-03 devnull .IR nsmount .
103 058b0118 2005-01-03 devnull .I Fsmount
104 058b0118 2005-01-03 devnull initializes a new 9P conversation on the open file descriptor
105 058b0118 2005-01-03 devnull .IR fd ;
106 058b0118 2005-01-03 devnull .I nsmount
107 058b0118 2005-01-03 devnull connects to a service named
109 058b0118 2005-01-03 devnull in the current name space directory
111 058b0118 2005-01-03 devnull .IR intro (4)).
112 058b0118 2005-01-03 devnull Both attach to the root of the file system
113 058b0118 2005-01-03 devnull using the attach name
114 058b0118 2005-01-03 devnull .IR aname .
115 058b0118 2005-01-03 devnull .I Fsroot
116 058b0118 2005-01-03 devnull returns the
117 058b0118 2005-01-03 devnull .B CFid*
118 058b0118 2005-01-03 devnull corresponding to this root.
120 058b0118 2005-01-03 devnull .IR Fsinit ,
121 058b0118 2005-01-03 devnull .IR fsversion ,
122 058b0118 2005-01-03 devnull .IR fsauth ,
123 058b0118 2005-01-03 devnull .IR fsattach ,
125 058b0118 2005-01-03 devnull .I fssetroot
126 058b0118 2005-01-03 devnull provide more detailed control over the file system connection
128 058b0118 2005-01-03 devnull .I fsmount
130 058b0118 2005-01-03 devnull .IR nsmount .
131 058b0118 2005-01-03 devnull .I Fsinit
132 058b0118 2005-01-03 devnull allocates a new
133 058b0118 2005-01-03 devnull .B CFsys*
134 058b0118 2005-01-03 devnull corresponding to a 9P conversation on the file descriptor
135 058b0118 2005-01-03 devnull .IR fd .
136 058b0118 2005-01-03 devnull .I Fsversion
137 058b0118 2005-01-03 devnull executes a
138 058b0118 2005-01-03 devnull .IR version (9p)
139 058b0118 2005-01-03 devnull transaction to establish
140 058b0118 2005-01-03 devnull maximum message size and 9P version.
141 058b0118 2005-01-03 devnull .I Fsauth
142 058b0118 2005-01-03 devnull executes an
143 058b0118 2005-01-03 devnull .IR auth (9p)
144 058b0118 2005-01-03 devnull transaction, returning the new auth fid.
145 058b0118 2005-01-03 devnull .RI ( Fsread
147 058b0118 2005-01-03 devnull .I fswrite
148 058b0118 2005-01-03 devnull can then be used to run the authentication protocol over the fid.)
149 058b0118 2005-01-03 devnull .I Fsattach
150 058b0118 2005-01-03 devnull executes an
151 058b0118 2005-01-03 devnull .IR attach (9p)
152 058b0118 2005-01-03 devnull transaction to connect to the root of a file tree served by the server.
153 058b0118 2005-01-03 devnull It presents
155 058b0118 2005-01-03 devnull (which may be nil)
156 058b0118 2005-01-03 devnull to establish identity.
157 058b0118 2005-01-03 devnull .I Fssetroot
158 058b0118 2005-01-03 devnull sets the root fid used by
159 058b0118 2005-01-03 devnull .IR fsopen ,
160 058b0118 2005-01-03 devnull .IR fsopenfd ,
161 058b0118 2005-01-03 devnull .IR fsdirstat ,
163 058b0118 2005-01-03 devnull .IR fsdirwstat ,
164 058b0118 2005-01-03 devnull which evaluate rooted path names.
166 058b0118 2005-01-03 devnull When a fid
167 058b0118 2005-01-03 devnull is no longer needed, it should be clunked by calling
168 058b0118 2005-01-03 devnull .I fsclose
169 058b0118 2005-01-03 devnull and then considered freed.
170 058b0118 2005-01-03 devnull Similarly, when the connection to the server is no longer needed,
171 058b0118 2005-01-03 devnull it should be closed by calling
172 058b0118 2005-01-03 devnull .IR fsunmount ,
173 058b0118 2005-01-03 devnull which will take care of calling
174 058b0118 2005-01-03 devnull .I fsclose
175 058b0118 2005-01-03 devnull on the current root fid.
176 058b0118 2005-01-03 devnull Once all fids have been clunked
178 058b0118 2005-01-03 devnull the connection has been closed
179 058b0118 2005-01-03 devnull (the order is not important),
180 058b0118 2005-01-03 devnull the allocated structures will be freed and the
181 058b0118 2005-01-03 devnull file descriptor corresponding to the connection
182 058b0118 2005-01-03 devnull will be closed
184 058b0118 2005-01-03 devnull .IR close (2)).
185 058b0118 2005-01-03 devnull Fids are not reference counted: when
186 058b0118 2005-01-03 devnull .I fsclose
187 058b0118 2005-01-03 devnull is called, the clunk transaction and freeing of storage
188 058b0118 2005-01-03 devnull happen immediately.
190 058b0118 2005-01-03 devnull .I Fscreate
192 058b0118 2005-01-03 devnull .I fsopen
193 058b0118 2005-01-03 devnull establish new fids using the
194 058b0118 2005-01-03 devnull .IR walk ,
195 058b0118 2005-01-03 devnull .I create
198 058b0118 2005-01-03 devnull transactions
200 058b0118 2005-01-03 devnull .IR walk (9p)
202 058b0118 2005-01-03 devnull .IR open (9p)).
205 058b0118 2005-01-03 devnull argument is evaluated relative to the
206 058b0118 2005-01-03 devnull .B CFsys
209 058b0118 2005-01-03 devnull .I fsroot
211 058b0118 2005-01-03 devnull .I fssetroot
213 058b0118 2005-01-03 devnull The path is parsed as a slash-separated sequence of path elements,
214 058b0118 2005-01-03 devnull as on Unix and Plan 9.
215 058b0118 2005-01-03 devnull Elements that are empty or
217 058b0118 2005-01-03 devnull .B ( . )
218 058b0118 2005-01-03 devnull are ignored.
220 058b0118 2005-01-03 devnull Once opened, these fids can be read and written using
221 058b0118 2005-01-03 devnull .I fspread
223 058b0118 2005-01-03 devnull .IR fspwrite ,
224 058b0118 2005-01-03 devnull which execute
227 058b0118 2005-01-03 devnull .I write
228 058b0118 2005-01-03 devnull transactions
230 058b0118 2005-01-03 devnull .IR read (9p)).
231 058b0118 2005-01-03 devnull The library maintains an offset for each fid,
232 058b0118 2005-01-03 devnull analagous to the offset maintained by the kernel for each open file descriptor.
233 058b0118 2005-01-03 devnull .I Fsread
235 058b0118 2005-01-03 devnull .I fswrite
236 058b0118 2005-01-03 devnull read and write from this offset, and update it after successful calls.
238 058b0118 2005-01-03 devnull .I fspread
240 058b0118 2005-01-03 devnull .I fspwrite
242 058b0118 2005-01-03 devnull .I offset
244 058b0118 2005-01-03 devnull is identical to calling
245 058b0118 2005-01-03 devnull .I fsread
247 058b0118 2005-01-03 devnull .IR fswrite .
248 058b0118 2005-01-03 devnull .I Fsreadn
250 058b0118 2005-01-03 devnull .I fsread
251 058b0118 2005-01-03 devnull repeatedly to obtain exactly
253 058b0118 2005-01-03 devnull bytes of data, unless it encounters end-of-file or an error.
255 058b0118 2005-01-03 devnull Reading an open a directory returns directory entries encoded as described in
256 058b0118 2005-01-03 devnull .IR stat (9p).
257 058b0118 2005-01-03 devnull .I Fsdirread
259 058b0118 2005-01-03 devnull .I fsread
260 058b0118 2005-01-03 devnull and then parses the encoded entries into an array of
262 058b0118 2005-01-03 devnull data structures,
263 058b0118 2005-01-03 devnull storing a pointer to the array in
265 058b0118 2005-01-03 devnull and returning the number of entries.
266 058b0118 2005-01-03 devnull .I Fsdirreadall
267 058b0118 2005-01-03 devnull is similar but reads the entire directory.
268 058b0118 2005-01-03 devnull The returned pointer should be freed with
271 058b0118 2005-01-03 devnull .IR malloc (3))
272 058b0118 2005-01-03 devnull when no longer needed.
274 058b0118 2005-01-03 devnull .I Fsdirfstat
276 058b0118 2005-01-03 devnull .I fsdirfwstat
280 058b0118 2005-01-03 devnull .I wstat
282 058b0118 2005-01-03 devnull .IR stat (9p))
283 058b0118 2005-01-03 devnull transactions.
286 058b0118 2005-01-03 devnull structure returned by
287 058b0118 2005-01-03 devnull .I fsdirfstat
288 058b0118 2005-01-03 devnull should be freed with
291 058b0118 2005-01-03 devnull .IR malloc (3))
292 058b0118 2005-01-03 devnull when no longer needed.
294 058b0118 2005-01-03 devnull .I Fsdirstat
296 058b0118 2005-01-03 devnull .I fsdirwstat
297 058b0118 2005-01-03 devnull are similar to
298 058b0118 2005-01-03 devnull .I fsdirfstat
300 058b0118 2005-01-03 devnull .I fsdirfwstat
301 058b0118 2005-01-03 devnull but operate on paths relative to the file system root
303 058b0118 2005-01-03 devnull .I fsopen
305 058b0118 2005-01-03 devnull .I fscreate
308 058b0118 2005-01-03 devnull .I Fsopenfd
309 058b0118 2005-01-03 devnull opens a file on the 9P server
310 058b0118 2005-01-03 devnull for reading or writing but returns a Unix file descriptor
311 058b0118 2005-01-03 devnull instead of a fid structure.
312 058b0118 2005-01-03 devnull The file descriptor is actually one end of a
313 058b0118 2005-01-03 devnull .IR pipe (2).
314 058b0118 2005-01-03 devnull A proxy process on the other end is ferrying data
315 058b0118 2005-01-03 devnull between the pipe and the 9P fid.
316 058b0118 2005-01-03 devnull Because of the implementation as a pipe,
317 058b0118 2005-01-03 devnull the only signal of a read or write error is the closing of the pipe.
318 058b0118 2005-01-03 devnull The file descriptor remains valid even after the
319 058b0118 2005-01-03 devnull .B CFsys
320 058b0118 2005-01-03 devnull is unmounted.
321 058b0118 2005-01-03 devnull .SH SOURCE
322 c3674de4 2005-01-11 devnull .B \*9/src/lib9pclient
323 058b0118 2005-01-03 devnull .SH SEE ALSO
324 058b0118 2005-01-03 devnull .IR intro (4),
325 058b0118 2005-01-03 devnull .IR intro (9p)
326 058b0118 2005-01-03 devnull .SH BUGS
327 058b0118 2005-01-03 devnull The implementation
328 058b0118 2005-01-03 devnull should use a special version string to distinguish between
329 058b0118 2005-01-03 devnull servers that support
330 058b0118 2005-01-03 devnull .IR openfd (9p)
331 058b0118 2005-01-03 devnull and servers that do not.
333 058b0118 2005-01-03 devnull The interface does not provide access to the
334 058b0118 2005-01-03 devnull .IR walk (9p)
335 058b0118 2005-01-03 devnull transaction, or to
338 058b0118 2005-01-03 devnull .I create
339 058b0118 2005-01-03 devnull on already-established fids.
341 058b0118 2005-01-03 devnull There is no
342 058b0118 2005-01-03 devnull .IR fsseek .