9p 15 KB

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