21 srv \- 9P file service
34 .ta \w'\fL1234'u +\w'\fLTree* 'u
38 void (*attach)(Req *r);
41 void (*create)(Req *r);
43 void (*write)(Req *r);
44 void (*remove)(Req *r);
45 void (*flush)(Req *r);
47 void (*wstat)(Req *r);
50 char* (*walk1)(Fid *fid, char *name, Qid *qid);
51 char* (*clone)(Fid *oldfid, Fid *newfid);
53 void (*destroyfid)(Fid *fid);
54 void (*destroyreq)(Req *r);
55 void (*start)(Srv *s);
70 void postmountsrv(Srv *s, char *name, char *mtpt, int flag)
71 void postsharesrv(Srv *s, char *name, char *mtpt, char *desc)
72 void threadpostmountsrv(Srv *s, char *name, char *mtpt, int flag)
73 void threadpostsharesrv(Srv *s, char *name, char *mtpt, char *desc)
74 void listensrv(Srv *s, char *addr)
75 void threadlistensrv(Srv *s, char *addr)
76 int postfd(char *srvname, int fd)
77 void respond(Req *r, char *error)
78 void responderror(Req*)
79 void readstr(Req *r, char *src)
80 void readbuf(Req *r, void *src, long nsrc)
81 typedef int Dirgen(int n, Dir *dir, void *aux)
82 void dirread9p(Req *r, Dirgen *gen, void *aux)
83 void walkandclone(Req *r, char *(*walk1)(Fid *old, char *name, void *v),
84 char *(*clone)(Fid *old, Fid *new, void *v), void *v)
90 void srvrelease(Srv *s)
91 void srvacquire(Srv *s)
99 void* emalloc9p(ulong n)
100 void* erealloc9p(void *v, ulong n)
101 char* estrdup9p(char *s)
111 serves a 9P session by reading requests from
113 dispatching them to the function pointers kept in
116 writing the responses to
121 .I threadpostmountsrv
126 structure members. See the description below.)
131 structures are allocated one-to-one with uncompleted
132 requests and active fids, and are described in
137 depends on whether there is a file tree
140 associated with the server, that is,
144 The differences are made explicit in the
145 discussion of the service loop below.
148 element is the client's, to do with as it pleases.
151 does not return until the 9P conversation is finished.
152 Since it is usually run in a separate process so that
153 the caller can exit, the service loop has little chance
154 to return gracefully on out of memory errors.
160 to obtain its memory.
161 The default implementations of these functions
167 but abort the program if they run out of memory.
168 If alternate behavior is desired, clients can link against
169 alternate implementations of these functions.
173 .I threadpostmountsrv
174 are wrappers that create a separate process in which to run
176 They do the following:
180 is zero (the common case),
185 to be one end of a freshly allocated pipe,
188 initialized as the other end.
193 .BI postfd( s -> srvfd ,
200 Fork a child process via
217 .IB close( s -> srvfd )
228 .BI amount( s -> srvfd,
235 The parent returns to the caller.
237 If any error occurs during
238 this process, the entire process is terminated by calling
246 but instead of mounting the service on a directory, it is
251 is the name of the share and
253 is the name of the service channel.
258 create a separate process to announce as
260 The process listens for incoming connections,
261 creating a new process to serve each.
262 Using these functions results in
264 and the service functions
265 being run in multiple processes simultaneously.
266 The library locks its own data structures as necessary;
267 the client may need to lock data it shares between
268 the multiple connections.
269 .SS Service functions
272 structure named after 9P transactions
273 are called to satisfy requests as they arrive.
274 If a function is provided, it
278 to be called when the request is satisfied.
279 The only parameter of each service function
284 The incoming request parameters are stored in
291 structures corresponding to the
298 structure corresponding to
299 .IB r -> ifcall.oldtag \fR.
300 The outgoing response data should be stored in
302 The one exception to this rule is that
307 .IB r -> ofcall.stat \fR:
308 the library will convert the structure into the machine-independent
315 .IB r -> ifcall . stat
317 When a request has been handled,
319 should be called with
322 If the request was satisfied successfully, the error
323 string should be a nil pointer.
324 Note that it is permissible for a function to return
325 without itself calling
327 as long as it has arranged for
329 to be called at some point in the future
330 by another proc sharing its address space,
331 but see the discussion of
338 as well as any pointers it once contained must
339 be considered freed and not referenced.
344 with the system error string
348 If the service loop detects an error in a request
349 (e.g., an attempt to reuse an extant fid, an open of
350 an already open fid, a read from a fid opened for write, etc.)
351 it will reply with an error without consulting
352 the service functions.
354 The service loop provided by
359 .IR threadpostmountsrv )
361 If it is expected that some requests might
362 block, arranging for alternate processes
363 to handle them is suggested.
366 detaches the calling process from the server loop and
367 if neccesary spawns a new process to handle 9p requests.
368 When released, the process is free to do blocking work
369 or even exit because it now running in parallel to the
372 joins the calling (released) process with the server loop.
374 The constraints on the service functions are as follows.
375 These constraints are checked while the server executes.
376 If a service function fails to do something it ought to have,
383 If authentication is desired,
386 function should record that
388 is the new authentication fid and
394 may be nil, in which case it will be treated as having
395 responded with the error
396 .RI `` "argv0: authentication not required" ,''
399 is the program name variable as set by
407 function should check the authentication state of
414 to the qid of the file system root.
416 may be nil only if file trees are in use;
417 in this case, the qid will be filled from the root
418 of the tree, and no authentication will be done.
421 If file trees are in use,
423 is handled internally, and
427 If file trees are not in use,
430 .IB r -> ifcall . wname
432 .IB r -> ifcall . nwname \fR,
436 .IB ofcall . nqid \fR,
437 and also copying any necessary
443 when the two are different.
448 appropriately, it can
450 with a nil error string even when 9P
453 in the case of a short walk);
454 the library detects error conditions and handles them appropriately.
456 Because implementing the full walk message is intricate and
457 prone to error, the helper routine
459 will handle the request given pointers to two functions
464 if non-nil, is called to signal the creation of
470 routine will copy or increment a reference count in
481 to the new path's qid.
482 Both should return nil
483 on success or an error message on error.
487 after handling the request.
489 .I Walk1\fR, \fPClone
490 If the client provides functions
493 .IB srv -> clone \fR,
494 the 9P service loop will call
496 with these functions to handle the request.
505 with the new qid on a successful walk.
508 If file trees are in use, the file
509 metadata will be consulted on open, create, remove, and wstat
510 to see if the requester has the appropriate permissions.
511 If not, an error will be sent back without consulting a service function.
513 If not using file trees or the user has the appropriate permissions,
516 .IB r -> ofcall . qid
517 already initialized to the one stored in the
519 structure (that is, the one returned in the previous walk).
520 If the qid changes, both should be updated.
525 function must fill in
529 .IB r -> ofcall . qid
531 When using file trees,
533 should allocate a new
539 may return nil (because, say, the file already exists).
544 behaves as though it were a function that always responded
545 with the error ``create prohibited''.
549 should mark the file as removed, whether
552 when using file trees, or by updating an internal data structure.
553 In general it is not a good idea to clean up the
555 information associated with the corresponding
557 at this time, to avoid memory errors if other
558 fids have references to that file.
559 Instead, it is suggested that
561 simply mark the file as removed (so that further
562 operations on it know to fail) and wait until the
563 file tree's destroy function is called to reclaim the
566 If not using file trees, it is prudent to take the
570 is not provided, all remove requests will draw
571 ``remove prohibited'' errors.
576 function must be provided; it fills
577 .IB r -> ofcall . data
579 .IB r -> ifcall . count
580 bytes of data from offset
581 .IB r -> ifcall . offset
584 .IB r -> ofcall . count
585 to the number of bytes being returned.
588 will handle reads of directories internally, only
591 for requests on files.
595 are useful for satisfying read requests on a string or buffer.
596 Consulting the request in
599 .IB r -> ofcall . data
601 .IB r -> ofcall . count \fR;
606 can be used to handle directory reads in servers
607 not using file trees.
610 function will be called as necessary to
613 with information for the
615 entry in the directory.
616 The string pointers placed in
618 should be fresh copies
621 they will be freed by
623 after each successful call to
626 should return zero if it successfully filled
628 minus one on end of directory.
633 function is similar but need not be provided.
634 If it is not, all writes will draw
635 ``write prohibited'' errors.
638 should attempt to write the
639 .IB r -> ifcall . count
641 .IB r -> ifcall . data
643 .IB r -> ifcall . offset
645 .IB r -> ofcall . count
646 to the number of bytes actually written.
647 Most programs consider it an error to
648 write less than the requested amount.
654 with the stat information for
658 will have been initialized with the stat info from
668 in changing the metadata for
672 When using file trees,
674 will take care to check that the request satisfies
675 the permissions outlined in
679 should take care to enforce permissions
683 Servers that always call
685 before returning from the service functions
690 is only necessary in programs
693 to be called asynchronously.
695 should cause the request
697 to be cancelled or hurried along.
700 is cancelled, this should be signalled by calling
709 with a nil error string.
713 before forcing a response to
715 In this case, the library will delay sending
718 message until the response to
728 are auxiliary functions, not called in direct response to 9P requests.
733 reference count drops to zero
735 it has been clunked and there are no outstanding
736 requests referring to it),
738 is called to allow the program to dispose
746 reference count drops to zero
748 it has been handled via
750 and other outstanding pointers to it have been closed),
752 is called to allow the program to dispose of the
757 This gets called (from the forked service process)
758 prior entering the 9P service loop.
761 Once the 9P service loop has finished
762 (end of file been reached on the service pipe
763 or a bad message has been read),
765 is called (if provided) to allow any final cleanup.
766 For example, it was used by the Palm Pilot synchronization
767 file system (never finished) to gracefully terminate the serial conversation once
768 the file system had been unmounted.
771 the service loop (which runs in a separate process
772 from its caller) terminates using
780 flag is at least one,
781 a transcript of the 9P session is printed
785 flag is greater than one,
786 additional unspecified debugging output is generated.
787 By convention, servers written using this library
798 .B /sys/src/lib9p/ramfs.c
799 are good examples of simple single-threaded file servers.
805 are good examples of multithreaded file servers.
809 interface is appropriate for maintaining arbitrary file trees (as in
813 interface is best avoided when the
814 tree structure is easily generated as necessary;
815 this is true when the tree is highly structured (as in
819 or is maintained elsewhere.
829 The switch to 9P2000 was taken as an opportunity to tidy
830 much of the interface; we promise to avoid such gratuitous change