17 srv \- 9P file service
30 .ta \w'\fL1234'u +\w'\fLTree* 'u
34 void (*attach)(Req *r);
37 void (*create)(Req *r);
39 void (*write)(Req *r);
40 void (*remove)(Req *r);
41 void (*flush)(Req *r);
43 void (*wstat)(Req *r);
46 char* (*walk1)(Fid *fid, char *name, Qid *qid);
47 char* (*clone)(Fid *oldfid, Fid *newfid);
49 void (*destroyfid)(Fid *fid);
50 void (*destroyreq)(Req *r);
65 void postmountsrv(Srv *s, char *name, char *mtpt, int flag)
66 void postsharesrv(Srv *s, char *name, char *mtpt, char *desc)
67 void threadpostmountsrv(Srv *s, char *name, char *mtpt, int flag)
68 void threadpostsharesrv(Srv *s, char *name, char *mtpt, char *desc)
69 void listensrv(Srv *s, char *addr)
70 void threadlistensrv(Srv *s, char *addr)
71 int postfd(char *srvname, int fd)
72 void respond(Req *r, char *error)
73 void responderror(Req*)
74 void readstr(Req *r, char *src)
75 void readbuf(Req *r, void *src, long nsrc)
76 typedef int Dirgen(int n, Dir *dir, void *aux)
77 void dirread9p(Req *r, Dirgen *gen, void *aux)
78 void walkandclone(Req *r, char *(*walk1)(Fid *old, char *name, void *v),
79 char *(*clone)(Fid *old, Fid *new, void *v), void *v)
85 void srvrelease(Srv *s)
86 void srvacquire(Srv *s)
94 void* emalloc9p(ulong n)
95 void* erealloc9p(void *v, ulong n)
96 char* estrdup9p(char *s)
106 serves a 9P session by reading requests from
108 dispatching them to the function pointers kept in
111 writing the responses to
116 .I threadpostmountsrv
121 structure members. See the description below.)
126 structures are allocated one-to-one with uncompleted
127 requests and active fids, and are described in
132 depends on whether there is a file tree
135 associated with the server, that is,
139 The differences are made explicit in the
140 discussion of the service loop below.
143 element is the client's, to do with as it pleases.
146 does not return until the 9P conversation is finished.
147 Since it is usually run in a separate process so that
148 the caller can exit, the service loop has little chance
149 to return gracefully on out of memory errors.
155 to obtain its memory.
156 The default implementations of these functions
162 but abort the program if they run out of memory.
163 If alternate behavior is desired, clients can link against
164 alternate implementations of these functions.
168 .I threadpostmountsrv
169 are wrappers that create a separate process in which to run
171 They do the following:
175 is zero (the common case),
180 to be one end of a freshly allocated pipe,
183 initialized as the other end.
188 .BI postfd( s -> srvfd ,
195 Fork a child process via
212 .IB close( s -> srvfd )
223 .BI amount( s -> srvfd,
230 The parent returns to the caller.
232 If any error occurs during
233 this process, the entire process is terminated by calling
241 but instead of mounting the service on a directory, it is
246 is the name of the share and
248 is the name of the service channel.
253 create a separate process to announce as
255 The process listens for incoming connections,
256 creating a new process to serve each.
257 Using these functions results in
259 and the service functions
260 being run in multiple processes simultaneously.
261 The library locks its own data structures as necessary;
262 the client may need to lock data it shares between
263 the multiple connections.
264 .SS Service functions
267 structure named after 9P transactions
268 are called to satisfy requests as they arrive.
269 If a function is provided, it
273 to be called when the request is satisfied.
274 The only parameter of each service function
279 The incoming request parameters are stored in
286 structures corresponding to the
293 structure corresponding to
294 .IB r -> ifcall.oldtag \fR.
295 The outgoing response data should be stored in
297 The one exception to this rule is that
302 .IB r -> ofcall.stat \fR:
303 the library will convert the structure into the machine-independent
310 .IB r -> ifcall . stat
312 When a request has been handled,
314 should be called with
317 If the request was satisfied successfully, the error
318 string should be a nil pointer.
319 Note that it is permissible for a function to return
320 without itself calling
322 as long as it has arranged for
324 to be called at some point in the future
325 by another proc sharing its address space,
326 but see the discussion of
333 as well as any pointers it once contained must
334 be considered freed and not referenced.
339 with the system error string
343 If the service loop detects an error in a request
344 (e.g., an attempt to reuse an extant fid, an open of
345 an already open fid, a read from a fid opened for write, etc.)
346 it will reply with an error without consulting
347 the service functions.
349 The service loop provided by
354 .IR threadpostmountsrv )
356 If it is expected that some requests might
357 block, arranging for alternate processes
358 to handle them is suggested.
361 detaches the calling process from the server loop and
362 if neccesary spawns a new process to handle 9p requests.
363 When released, the process is free to do blocking work
364 or even exit because it now running in parallel to the
367 joins the calling (released) process with the server loop.
369 The constraints on the service functions are as follows.
370 These constraints are checked while the server executes.
371 If a service function fails to do something it ought to have,
378 If authentication is desired,
381 function should record that
383 is the new authentication fid and
389 may be nil, in which case it will be treated as having
390 responded with the error
391 .RI `` "argv0: authentication not required" ,''
394 is the program name variable as set by
402 function should check the authentication state of
409 to the qid of the file system root.
411 may be nil only if file trees are in use;
412 in this case, the qid will be filled from the root
413 of the tree, and no authentication will be done.
416 If file trees are in use,
418 is handled internally, and
422 If file trees are not in use,
425 .IB r -> ifcall . wname
427 .IB r -> ifcall . nwname \fR,
431 .IB ofcall . nqid \fR,
432 and also copying any necessary
438 when the two are different.
443 appropriately, it can
445 with a nil error string even when 9P
448 in the case of a short walk);
449 the library detects error conditions and handles them appropriately.
451 Because implementing the full walk message is intricate and
452 prone to error, the helper routine
454 will handle the request given pointers to two functions
459 if non-nil, is called to signal the creation of
465 routine will copy or increment a reference count in
476 to the new path's qid.
477 Both should return nil
478 on success or an error message on error.
482 after handling the request.
484 .I Walk1\fR, \fPClone
485 If the client provides functions
488 .IB srv -> clone \fR,
489 the 9P service loop will call
491 with these functions to handle the request.
500 with the new qid on a successful walk.
503 If file trees are in use, the file
504 metadata will be consulted on open, create, remove, and wstat
505 to see if the requester has the appropriate permissions.
506 If not, an error will be sent back without consulting a service function.
508 If not using file trees or the user has the appropriate permissions,
511 .IB r -> ofcall . qid
512 already initialized to the one stored in the
514 structure (that is, the one returned in the previous walk).
515 If the qid changes, both should be updated.
520 function must fill in
524 .IB r -> ofcall . qid
526 When using file trees,
528 should allocate a new
534 may return nil (because, say, the file already exists).
539 behaves as though it were a function that always responded
540 with the error ``create prohibited''.
544 should mark the file as removed, whether
547 when using file trees, or by updating an internal data structure.
548 In general it is not a good idea to clean up the
550 information associated with the corresponding
552 at this time, to avoid memory errors if other
553 fids have references to that file.
554 Instead, it is suggested that
556 simply mark the file as removed (so that further
557 operations on it know to fail) and wait until the
558 file tree's destroy function is called to reclaim the
561 If not using file trees, it is prudent to take the
565 is not provided, all remove requests will draw
566 ``remove prohibited'' errors.
571 function must be provided; it fills
572 .IB r -> ofcall . data
574 .IB r -> ifcall . count
575 bytes of data from offset
576 .IB r -> ifcall . offset
579 .IB r -> ofcall . count
580 to the number of bytes being returned.
583 will handle reads of directories internally, only
586 for requests on files.
590 are useful for satisfying read requests on a string or buffer.
591 Consulting the request in
594 .IB r -> ofcall . data
596 .IB r -> ofcall . count \fR;
601 can be used to handle directory reads in servers
602 not using file trees.
605 function will be called as necessary to
608 with information for the
610 entry in the directory.
611 The string pointers placed in
613 should be fresh copies
616 they will be freed by
618 after each successful call to
621 should return zero if it successfully filled
623 minus one on end of directory.
628 function is similar but need not be provided.
629 If it is not, all writes will draw
630 ``write prohibited'' errors.
633 should attempt to write the
634 .IB r -> ifcall . count
636 .IB r -> ifcall . data
638 .IB r -> ifcall . offset
640 .IB r -> ofcall . count
641 to the number of bytes actually written.
642 Most programs consider it an error to
643 write less than the requested amount.
649 with the stat information for
653 will have been initialized with the stat info from
663 in changing the metadata for
667 When using file trees,
669 will take care to check that the request satisfies
670 the permissions outlined in
674 should take care to enforce permissions
678 Servers that always call
680 before returning from the service functions
685 is only necessary in programs
688 to be called asynchronously.
690 should cause the request
692 to be cancelled or hurried along.
695 is cancelled, this should be signalled by calling
704 with a nil error string.
708 before forcing a response to
710 In this case, the library will delay sending
713 message until the response to
722 are auxiliary functions, not called in direct response to 9P requests.
727 reference count drops to zero
729 it has been clunked and there are no outstanding
730 requests referring to it),
732 is called to allow the program to dispose
740 reference count drops to zero
742 it has been handled via
744 and other outstanding pointers to it have been closed),
746 is called to allow the program to dispose of the
751 Once the 9P service loop has finished
752 (end of file been reached on the service pipe
753 or a bad message has been read),
755 is called (if provided) to allow any final cleanup.
756 For example, it was used by the Palm Pilot synchronization
757 file system (never finished) to gracefully terminate the serial conversation once
758 the file system had been unmounted.
761 the service loop (which runs in a separate process
762 from its caller) terminates using
770 flag is at least one,
771 a transcript of the 9P session is printed
775 flag is greater than one,
776 additional unspecified debugging output is generated.
777 By convention, servers written using this library
788 .B /sys/src/lib9p/ramfs.c
789 are good examples of simple single-threaded file servers.
795 are good examples of multithreaded file servers.
799 interface is appropriate for maintaining arbitrary file trees (as in
803 interface is best avoided when the
804 tree structure is easily generated as necessary;
805 this is true when the tree is highly structured (as in
809 or is maintained elsewhere.
819 The switch to 9P2000 was taken as an opportunity to tidy
820 much of the interface; we promise to avoid such gratuitous change