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