Blob


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