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