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