1
0

9p 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760
  1. .TH 9P 2
  2. .SH NAME
  3. Srv,
  4. dirread9p,
  5. emalloc9p,
  6. erealloc9p,
  7. estrdup9p,
  8. postfd,
  9. postmountsrv,
  10. readbuf,
  11. readstr,
  12. respond,
  13. threadpostmountsrv,
  14. srv \- 9P file service
  15. .SH SYNOPSIS
  16. .ft L
  17. .nf
  18. #include <u.h>
  19. #include <libc.h>
  20. #include <fcall.h>
  21. #include <thread.h>
  22. #include <9p.h>
  23. .fi
  24. .PP
  25. .ft L
  26. .nf
  27. .ta \w'\fL1234'u +\w'\fLTree* 'u
  28. typedef struct Srv {
  29. Tree* tree;
  30. void (*attach)(Req *r);
  31. void (*auth)(Req *r);
  32. void (*open)(Req *r);
  33. void (*create)(Req *r);
  34. void (*read)(Req *r);
  35. void (*write)(Req *r);
  36. void (*remove)(Req *r);
  37. void (*flush)(Req *r);
  38. void (*stat)(Req *r);
  39. void (*wstat)(Req *r);
  40. void (*walk)(Req *r);
  41. char* (*walk1)(Fid *fid, char *name, Qid *qid);
  42. char* (*clone)(Fid *oldfid, Fid *newfid);
  43. void (*destroyfid)(Fid *fid);
  44. void (*destroyreq)(Req *r);
  45. void (*end)(Srv *s);
  46. void* aux;
  47. int infd;
  48. int outfd;
  49. int srvfd;
  50. int nopipe;
  51. } Srv;
  52. .fi
  53. .PP
  54. .nf
  55. .ft L
  56. .ta \w'\fLvoid* 'u
  57. int srv(Srv *s)
  58. void postmountsrv(Srv *s, char *name, char *mtpt, int flag)
  59. void threadpostmountsrv(Srv *s, char *name, char *mtpt, int flag)
  60. int postfd(char *srvname, int fd)
  61. void respond(Req *r, char *error)
  62. ulong readstr(Req *r, char *src)
  63. ulong readbuf(Req *r, void *src, ulong nsrc)
  64. typedef int Dirgen(int n, Dir *dir, void *aux)
  65. void dirread9p(Req *r, Dirgen *gen, void *aux)
  66. void walkandclone(Req *r, char *(*walk1)(Fid *old, char *name, void *v),
  67. char *(*clone)(Fid *old, Fid *new, void *v), void *v)
  68. .fi
  69. .PP
  70. .nf
  71. .ft L
  72. .ta \w'\fLvoid* 'u
  73. void* emalloc9p(ulong n)
  74. void* erealloc9p(void *v, ulong n)
  75. char* estrdup9p(char *s)
  76. .fi
  77. .PP
  78. .nf
  79. .ft L
  80. extern int chatty9p;
  81. .fi
  82. .SH DESCRIPTION
  83. The function
  84. .I srv
  85. serves a 9P session by reading requests from
  86. .BR s->infd ,
  87. dispatching them to the function pointers kept in
  88. .BR Srv ,
  89. and
  90. writing the responses to
  91. .BR s->outfd .
  92. (Typically,
  93. .I postmountsrv
  94. or
  95. .I threadpostmountsrv
  96. initializes the
  97. .B infd
  98. and
  99. .B outfd
  100. structure members. See the description below.)
  101. .PP
  102. .B Req
  103. and
  104. .B Fid
  105. structures are allocated one-to-one with uncompleted
  106. requests and active fids, and are described in
  107. .IR 9pfid (2).
  108. .PP
  109. The behavior of
  110. .I srv
  111. depends on whether there is a file tree
  112. (see
  113. .IR 9pfile (2))
  114. associated with the server, that is,
  115. whether the
  116. .B tree
  117. element is nonzero.
  118. The differences are made explicit in the
  119. discussion of the service loop below.
  120. The
  121. .B aux
  122. element is the client's, to do with as it pleases.
  123. .PP
  124. .I Srv
  125. does not return until the 9P conversation is finished.
  126. Since it is usually run in a separate process so that
  127. the caller can exit, the service loop has little chance
  128. to return gracefully on out of memory errors.
  129. It calls
  130. .IR emalloc9p ,
  131. .IR erealloc9p ,
  132. and
  133. .I estrdup9p
  134. to obtain its memory.
  135. The default implementations of these functions
  136. act as
  137. .IR malloc ,
  138. .IR realloc ,
  139. and
  140. .I strdup
  141. but abort the program if they run out of memory.
  142. If alternate behavior is desired, clients can link against
  143. alternate implementations of these functions.
  144. .PP
  145. .I Postmountsrv
  146. and
  147. .I threadpostmountsrv
  148. are wrappers that create a separate process in which to run
  149. .IR srv .
  150. They do the following:
  151. .IP
  152. If
  153. .IB s -> nopipe
  154. is zero (the common case),
  155. initialize
  156. .IB s -> infd
  157. and
  158. .IB s -> outfd
  159. to be one end of a freshly allocated pipe,
  160. with
  161. .IB s -> srvfd
  162. initialized as the other end.
  163. .IP
  164. If
  165. .B name
  166. is non-nil, call
  167. .BI postfd( s -> srvfd ,
  168. .IB name )
  169. to post
  170. .IB s -> srvfd
  171. as
  172. .BI /srv/ name .
  173. .IP
  174. Fork a child process via
  175. .I rfork
  176. (see
  177. .IR fork (2))
  178. or
  179. .I procrfork
  180. (see
  181. .IR thread (2)),
  182. using the
  183. .BR RFFDG ,
  184. .RR RFNOTEG ,
  185. .BR RFNAMEG ,
  186. and
  187. .BR RFMEM
  188. flags.
  189. The child process
  190. calls
  191. .IB close( s -> srvfd )
  192. and then
  193. .IB srv( s ) \fR;
  194. it will exit once
  195. .I srv
  196. returns.
  197. .IP
  198. If
  199. .I mtpt
  200. is non-nil,
  201. call
  202. .BI amount( s -> srvfd,
  203. .IB mtpt ,
  204. .IB flag ,
  205. \fB"")\fR;
  206. otherwise, close
  207. .IB s -> srvfd \fR.
  208. .IP
  209. The parent returns to the caller.
  210. .LP
  211. If any error occurs during
  212. this process, the entire process is terminated by calling
  213. .I sysfatal
  214. (see
  215. .IR perror (2)).
  216. .SS Service functions
  217. The functions in a
  218. .B Srv
  219. structure named after 9P transactions
  220. are called to satisfy requests as they arrive.
  221. If a function is provided, it
  222. .I must
  223. arrange for
  224. .I respond
  225. to be called when the request is satisfied.
  226. The only parameter of each service function
  227. is a
  228. .B Req*
  229. parameter (say
  230. .IR r ).
  231. The incoming request parameters are stored in
  232. .IB r -> ifcall \fR;
  233. .IB r -> fid
  234. and
  235. .IB r -> newfid
  236. are pointers to
  237. .B Fid
  238. structures corresponding to the
  239. numeric fids in
  240. .IB r -> ifcall \fR;
  241. similarly,
  242. .IB r -> oldreq
  243. is the
  244. .B Req
  245. structure corresponding to
  246. .IB r -> ifcall.oldtag \fR.
  247. The outgoing response data should be stored in
  248. .IB r -> ofcall \fR.
  249. The one exception to this rule is that
  250. .I stat
  251. should fill in
  252. .IB r -> d
  253. rather than
  254. .IB r -> ofcall.stat \fR:
  255. the library will convert the structure into the machine-independent
  256. wire representation.
  257. Similarly,
  258. .I wstat
  259. may consult
  260. .IB r -> d
  261. rather than decoding
  262. .IB r -> ifcall . stat
  263. itself.
  264. When a request has been handled,
  265. .I respond
  266. should be called with
  267. .I r
  268. and an error string.
  269. If the request was satisfied successfully, the error
  270. string should be a nil pointer.
  271. Note that it is permissible for a function to return
  272. without itself calling
  273. .IR respond ,
  274. as long as it has arranged for
  275. .I respond
  276. to be called at some point in the future
  277. by another proc sharing its address space,
  278. but see the discussion of
  279. .I flush
  280. below.
  281. Once
  282. .I respond
  283. has been called, the
  284. .B Req*
  285. as well as any pointers it once contained must
  286. be considered freed and not referenced.
  287. .PP
  288. If the service loop detects an error in a request
  289. (e.g., an attempt to reuse an extant fid, an open of
  290. an already open fid, a read from a fid opened for write, etc.)
  291. it will reply with an error without consulting
  292. the service functions.
  293. .PP
  294. The service loop provided by
  295. .I srv
  296. (and indirectly by
  297. .I postmountsrv
  298. and
  299. .IR threadpostmountsrv )
  300. is single-threaded.
  301. If it is expected that some requests might
  302. block, arranging for alternate processes
  303. to handle them is suggested.
  304. .PP
  305. The constraints on the service functions are as follows.
  306. These constraints are checked while the server executes.
  307. If a service function fails to do something it ought to have,
  308. .I srv
  309. will call
  310. .I endsrv
  311. and then abort.
  312. .TP
  313. .I Auth
  314. If authentication is desired,
  315. the
  316. .I auth
  317. function should record that
  318. .I afid
  319. is the new authentication fid and
  320. set
  321. .I afid->qid
  322. and
  323. .IR ofcall.qid .
  324. .I Auth
  325. may be nil, in which case it will be treated as having
  326. responded with the error
  327. .RI `` "argv0: authentication not required" ,''
  328. where
  329. .I argv0
  330. is the program name variable as set by
  331. .I ARGBEGIN
  332. (see
  333. .IR arg (2)).
  334. .TP
  335. .I Attach
  336. The
  337. .I attach
  338. function should check the authentication state of
  339. .I afid
  340. if desired,
  341. and set
  342. .IB r -> fid -> qid
  343. and
  344. .I ofcall.qid
  345. to the qid of the file system root.
  346. .I Attach
  347. may be nil only if file trees are in use;
  348. in this case, the qid will be filled from the root
  349. of the tree, and no authentication will be done.
  350. .TP
  351. .I Walk
  352. If file trees are in use,
  353. .I walk
  354. is handled internally, and
  355. .IB srv -> walk
  356. is never called.
  357. .IP
  358. If file trees are not in use,
  359. .I walk
  360. should consult
  361. .IB r -> ifcall . wname
  362. and
  363. .IB r -> ifcall . nwname \fR,
  364. filling in
  365. .IB ofcall . qid
  366. and
  367. .IB ofcall . nqid \fR,
  368. and also copying any necessary
  369. .I aux
  370. state from
  371. .IB r -> fid
  372. to
  373. .IB r -> newfid
  374. when the two are different.
  375. As long as
  376. .I walk
  377. sets
  378. .IB ofcall . nqid
  379. appropriately, it can
  380. .I respond
  381. with a nil error string even when 9P
  382. demands an error
  383. .RI ( e.g. ,
  384. in the case of a short walk);
  385. the library detects error conditions and handles them appropriately.
  386. .IP
  387. Because implementing the full walk message is intricate and
  388. prone to error, the helper routine
  389. .I walkandclone
  390. will handle the request given pointers to two functions
  391. .I walk1
  392. and (optionally)
  393. .I clone .
  394. .IR Clone ,
  395. if non-nil, is called to signal the creation of
  396. .I newfid
  397. from
  398. .IR oldfid .
  399. Typically a
  400. .I clone
  401. routine will copy or increment a reference count in
  402. .IR oldfid 's
  403. .I aux
  404. element.
  405. .I Walk1
  406. should walk
  407. .I fid
  408. to
  409. .IR name ,
  410. initializing
  411. .IB fid -> qid
  412. to the new path's qid.
  413. Both should return nil
  414. on success or an error message on error.
  415. .I Walkandclone
  416. will call
  417. .I respond
  418. after handling the request.
  419. .TP
  420. .I Walk1\fR, \fPClone
  421. If the client provides functions
  422. .IB srv -> walk1
  423. and (optionally)
  424. .IB srv -> clone \fR,
  425. the 9P service loop will call
  426. .I walkandclone
  427. with these functions to handle the request.
  428. Unlike the
  429. .I walk1
  430. above,
  431. .IB srv -> walk1
  432. must fill in both
  433. .IB fid -> qid
  434. and
  435. .BI * qid
  436. with the new qid on a successful walk.
  437. .TP
  438. .I Open
  439. If file trees are in use, the file
  440. metadata will be consulted on open, create, remove, and wstat
  441. to see if the requester has the appropriate permissions.
  442. If not, an error will be sent back without consulting a service function.
  443. .PP
  444. If not using file trees or the user has the appropriate permissions,
  445. .I open
  446. is called with
  447. .IB r -> ofcall . qid
  448. already initialized to the one stored in the
  449. .B Fid
  450. structure (that is, the one returned in the previous walk).
  451. If the qid changes, both should be updated.
  452. .TP
  453. .I Create
  454. The
  455. .I create
  456. function must fill in
  457. both
  458. .IB r -> fid -> qid
  459. and
  460. .IB r -> ofcall . qid
  461. on success.
  462. When using file trees,
  463. .I create
  464. should allocate a new
  465. .B File
  466. with
  467. .IR createfile ;
  468. note that
  469. .I createfile
  470. may return nil (because, say, the file already exists).
  471. If the
  472. .I create
  473. function is nil,
  474. .I srv
  475. behaves as though it were a function that always responded
  476. with the error ``create prohibited''.
  477. .TP
  478. .I Remove
  479. .I Remove
  480. should mark the file as removed, whether
  481. by calling
  482. .I removefile
  483. when using file trees, or by updating an internal data structure.
  484. In general it is not a good idea to clean up the
  485. .I aux
  486. information associated with the corresponding
  487. .B File
  488. at this time, to avoid memory errors if other
  489. fids have references to that file.
  490. Instead, it is suggested that
  491. .I remove
  492. simply mark the file as removed (so that further
  493. operations on it know to fail) and wait until the
  494. file tree's destroy function is called to reclaim the
  495. .I aux
  496. pointer.
  497. If not using file trees, it is prudent to take the
  498. analogous measures.
  499. If
  500. .I remove
  501. is not provided, all remove requests will draw
  502. ``remove prohibited'' errors.
  503. .TP
  504. .I Read
  505. The
  506. .I read
  507. function must be provided; it fills
  508. .IB r -> ofcall . data
  509. with at most
  510. .IB r -> ifcall . count
  511. bytes of data from offset
  512. .IB r -> ifcall . offset
  513. of the file.
  514. It also sets
  515. .IB r -> ofcall . count
  516. to the number of bytes being returned.
  517. If using file trees,
  518. .I srv
  519. will handle reads of directories internally, only
  520. calling
  521. .I read
  522. for requests on files.
  523. .I Readstr
  524. and
  525. .I readbuf
  526. are useful for satisfying read requests on a string or buffer.
  527. Consulting the request in
  528. .IB r -> ifcall \fR,
  529. they fill
  530. .IB r -> ofcall . data
  531. and set
  532. .IB r -> ofcall . count \fR;
  533. they do not call
  534. .IB respond .
  535. Similarly,
  536. .I dirread9p
  537. can be used to handle directory reads in servers
  538. not using file trees.
  539. The passed
  540. .I gen
  541. function will be called as necessary to
  542. fill
  543. .I dir
  544. with information for the
  545. .IR n th
  546. entry in the directory.
  547. The string pointers placed in
  548. .I dir
  549. should be fresh copies
  550. made with
  551. .IR estrdup9p ;
  552. they will be freed by
  553. .I dirread9p
  554. after each successful call to
  555. .IR gen .
  556. .I Gen
  557. should return zero if it successfully filled
  558. .IR dir ,
  559. minus one on end of directory.
  560. .TP
  561. .I Write
  562. The
  563. .I write
  564. function is similar but need not be provided.
  565. If it is not, all writes will draw
  566. ``write prohibited'' errors.
  567. Otherwise,
  568. .I write
  569. should attempt to write the
  570. .IB r -> ifcall . count
  571. bytes of
  572. .IB r -> ifcall . data
  573. to offset
  574. .IB r -> ifcall . offset
  575. of the file, setting
  576. .IB r -> ofcall . count
  577. to the number of bytes actually written.
  578. Most programs consider it an error to
  579. write less than the requested amount.
  580. .TP
  581. .I Stat
  582. .I Stat
  583. should fill
  584. .IB r -> d
  585. with the stat information for
  586. .IB r -> fid \fR.
  587. If using file trees,
  588. .IB r -> d
  589. will have been initialized with the stat info from
  590. the tree, and
  591. .I stat
  592. itself may be nil.
  593. .TP
  594. .I Wstat
  595. The
  596. .I wstat
  597. consults
  598. .IB r -> d
  599. in changing the metadata for
  600. .IB r -> fid
  601. as described in
  602. .IR stat (5).
  603. When using file trees,
  604. .I srv
  605. will take care to check that the request satisfies
  606. the permissions outlined in
  607. .IR stat (5).
  608. Otherwise
  609. .I wstat
  610. should take care to enforce permissions
  611. where appropriate.
  612. .TP
  613. .I Flush
  614. Single-threaded servers, which always call
  615. .I respond
  616. before returning from the service functions,
  617. need not provide a
  618. .I flush
  619. implementation:
  620. .I flush
  621. is only necessary in multithreaded programs,
  622. which arrange for
  623. .I respond
  624. to be called asynchronously.
  625. .I Flush
  626. should cause the request
  627. .IB r -> oldreq
  628. to be cancelled or hurried along.
  629. If
  630. .I oldreq
  631. is cancelled, this should be signalled by calling
  632. .I respond
  633. on
  634. .I oldreq
  635. with error string
  636. .RB ` interrupted '.
  637. .I Flush
  638. must respond to
  639. .I r
  640. with a nil error string.
  641. .I Flush
  642. may respond to
  643. .I r
  644. before forcing a response to
  645. .IB r -> oldreq \fR.
  646. In this case, the library will delay sending
  647. the
  648. .I Rflush
  649. message until the response to
  650. .IB r -> oldreq
  651. has been sent.
  652. .PD
  653. .PP
  654. .IR Destroyfid ,
  655. .IR destroyreq ,
  656. and
  657. .I end
  658. are auxiliary functions, not called in direct response to 9P requests.
  659. .TP
  660. .I Destroyfid
  661. When a
  662. .BR Fid 's
  663. reference count drops to zero
  664. .RI ( i.e.,
  665. it has been clunked and there are no outstanding
  666. requests referring to it),
  667. .I destroyfid
  668. is called to allow the program to dispose
  669. of the
  670. .IB fid -> aux
  671. pointer.
  672. .TP
  673. .I Destroyreq
  674. Similarly, when a
  675. .BR Req 's
  676. reference count drops to zero
  677. .RI ( i.e. ,
  678. it has been handled via
  679. .I respond
  680. and other outstanding pointers to it have been closed),
  681. .I destroyreq
  682. is called to allow the program to dispose of the
  683. .IB r -> aux
  684. pointer.
  685. .TP
  686. .I End
  687. Once the 9P service loop has finished
  688. (end of file been reached on the service pipe
  689. or a bad message has been read),
  690. .I end
  691. is called (if provided) to allow any final cleanup.
  692. For example, it was used by the Palm Pilot synchronization
  693. file system (never finished) to gracefully terminate the serial conversation once
  694. the file system had been unmounted.
  695. After calling
  696. .IR end ,
  697. the service loop (which runs in a separate process
  698. from its caller) terminates using
  699. .I _exits
  700. (see
  701. .IR exits (2)).
  702. .PD
  703. .PP
  704. If the
  705. .B chatty9p
  706. flag is at least one,
  707. a transcript of the 9P session is printed
  708. on standard error.
  709. If the
  710. .B chatty9p
  711. flag is greater than one,
  712. additional unspecified debugging output is generated.
  713. By convention, servers written using this library
  714. accept the
  715. .B -D
  716. option to increment
  717. .BR chatty9p .
  718. .SH EXAMPLES
  719. .IR Archfs (4),
  720. .IR cdfs (4),
  721. .IR nntpfs (4),
  722. .IR snap (4),
  723. and
  724. .B /sys/src/lib9p/ramfs.c
  725. are good examples of simple single-threaded file servers.
  726. .IR Webfs (4)
  727. and
  728. .I sshnet
  729. (see
  730. .IR ssh (1))
  731. are good examples of multithreaded file servers.
  732. .PP
  733. In general, the
  734. .B File
  735. interface is appropriate for maintaining arbitrary file trees (as in
  736. .IR ramfs ).
  737. The
  738. .B File
  739. interface is best avoided when the
  740. tree structure is easily generated as necessary;
  741. this is true when the tree is highly structured (as in
  742. .I cdfs
  743. and
  744. .IR nntpfs )
  745. or is maintained elsewhere.
  746. .SH SOURCE
  747. .B /sys/src/lib9p
  748. .SH SEE ALSO
  749. .IR 9pfid (2),
  750. .IR 9pfile (2),
  751. .IR srv (3),
  752. .IR intro (5)
  753. .SH BUGS
  754. The switch to 9P2000 was taken as an opportunity to tidy
  755. much of the interface; we promise to avoid such gratuitous change
  756. in the future.