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);
69 void postmountsrv(Srv *s, char *name, char *mtpt, int flag)
70 void postsharesrv(Srv *s, char *name, char *mtpt, char *desc)
71 void threadpostmountsrv(Srv *s, char *name, char *mtpt, int flag)
72 void threadpostsharesrv(Srv *s, char *name, char *mtpt, char *desc)
73 void listensrv(Srv *s, char *addr)
74 void threadlistensrv(Srv *s, char *addr)
75 void respond(Req *r, char *error)
76 void responderror(Req*)
77 void readstr(Req *r, char *src)
78 void readbuf(Req *r, void *src, long nsrc)
79 typedef int Dirgen(int n, Dir *dir, void *aux)
80 void dirread9p(Req *r, Dirgen *gen, void *aux)
81 void walkandclone(Req *r, char *(*walk1)(Fid *old, char *name, void *v),
82 char *(*clone)(Fid *old, Fid *new, void *v), void *v)
88 void srvrelease(Srv *s)
89 void srvacquire(Srv *s)
97 void* emalloc9p(ulong n)
98 void* erealloc9p(void *v, ulong n)
99 char* estrdup9p(char *s)
109 serves a 9P session by reading requests from
111 dispatching them to the function pointers kept in
114 writing the responses to
119 .I threadpostmountsrv
124 structure members. See the description below.)
129 structures are allocated one-to-one with uncompleted
130 requests and active fids, and are described in
135 depends on whether there is a file tree
138 associated with the server, that is,
142 The differences are made explicit in the
143 discussion of the service loop below.
146 element is the client's, to do with as it pleases.
149 does not return until the 9P conversation is finished.
150 Since it is usually run in a separate process so that
151 the caller can exit, the service loop has little chance
152 to return gracefully on out of memory errors.
158 to obtain its memory.
159 The default implementations of these functions
165 but abort the program if they run out of memory.
166 If alternate behavior is desired, clients can link against
167 alternate implementations of these functions.
171 .I threadpostmountsrv
172 are wrappers that create a separate process in which to run
174 They do the following:
180 to be one end of a freshly allocated pipe,
183 initialized as the other end.
187 is non-nil, post the file descriptor
192 Fork a child process via
207 flags. This isolates the service loop from the callers
208 namespace and from notes posted to the callers note group
209 but shares data and bss segments.
211 The child process then waits for the parent to copy its
212 file descriptor table via
216 flag. This way, the service loop will share the original
217 file descriptor table with previously created child
218 processes of the caller.
220 The child process then calls
221 .IB close( s -> srvfd )
232 .BI amount( s -> srvfd,
239 The parent returns to the caller.
241 If any error occurs during
242 this process, the entire process is terminated by calling
250 but instead of mounting the service on a directory, it is
255 is the name of the share and
257 is the name of the service channel.
262 create a separate process to announce as
264 The process listens for incoming connections,
265 creating a new process to serve each.
266 Using these functions results in
268 and the service functions
269 being run in multiple processes simultaneously.
270 The library locks its own data structures as necessary;
271 the client may need to lock data it shares between
272 the multiple connections.
273 .SS Service functions
276 structure named after 9P transactions
277 are called to satisfy requests as they arrive.
278 If a function is provided, it
282 to be called when the request is satisfied.
283 The only parameter of each service function
288 The incoming request parameters are stored in
295 structures corresponding to the
302 structure corresponding to
303 .IB r -> ifcall.oldtag \fR.
304 The outgoing response data should be stored in
306 The one exception to this rule is that
311 .IB r -> ofcall.stat \fR:
312 the library will convert the structure into the machine-independent
319 .IB r -> ifcall . stat
321 When a request has been handled,
323 should be called with
326 If the request was satisfied successfully, the error
327 string should be a nil pointer.
328 Note that it is permissible for a function to return
329 without itself calling
331 as long as it has arranged for
333 to be called at some point in the future
334 by another proc sharing its address space,
335 but see the discussion of
342 as well as any pointers it once contained must
343 be considered freed and not referenced.
348 with the system error string
352 If the service loop detects an error in a request
353 (e.g., an attempt to reuse an extant fid, an open of
354 an already open fid, a read from a fid opened for write, etc.)
355 it will reply with an error without consulting
356 the service functions.
358 The service loop provided by
363 .IR threadpostmountsrv )
365 If it is expected that some requests might
366 block, arranging for alternate processes
367 to handle them is suggested (see
371 temporarily releases the calling process from the server
372 loop and if neccesary spawns a new process to handle 9p
373 requests. When released, the process can do blocking work
374 that would otherwise halt processing of 9p requests.
376 rejoins the calling process with the server loop after
379 The constraints on the service functions are as follows.
380 These constraints are checked while the server executes.
381 If a service function fails to do something it ought to have,
388 If authentication is desired,
391 function should record that
393 is the new authentication fid and
399 may be nil, in which case it will be treated as having
400 responded with the error
401 .RI `` "argv0: authentication not required" ,''
404 is the program name variable as set by
412 function should check the authentication state of
419 to the qid of the file system root.
421 may be nil only if file trees are in use;
422 in this case, the qid will be filled from the root
423 of the tree, and no authentication will be done.
426 If file trees are in use,
428 is handled internally, and
432 If file trees are not in use,
435 .IB r -> ifcall . wname
437 .IB r -> ifcall . nwname \fR,
441 .IB ofcall . nqid \fR,
442 and also copying any necessary
448 when the two are different.
453 appropriately, it can
455 with a nil error string even when 9P
458 in the case of a short walk);
459 the library detects error conditions and handles them appropriately.
461 Because implementing the full walk message is intricate and
462 prone to error, the helper routine
464 will handle the request given pointers to two functions
469 if non-nil, is called to signal the creation of
475 routine will copy or increment a reference count in
486 to the new path's qid.
487 Both should return nil
488 on success or an error message on error.
492 after handling the request.
494 .I Walk1\fR, \fPClone
495 If the client provides functions
498 .IB srv -> clone \fR,
499 the 9P service loop will call
501 with these functions to handle the request.
510 with the new qid on a successful walk.
513 If file trees are in use, the file
514 metadata will be consulted on open, create, remove, and wstat
515 to see if the requester has the appropriate permissions.
516 If not, an error will be sent back without consulting a service function.
518 If not using file trees or the user has the appropriate permissions,
521 .IB r -> ofcall . qid
522 already initialized to the one stored in the
524 structure (that is, the one returned in the previous walk).
525 If the qid changes, both should be updated.
530 function must fill in
534 .IB r -> ofcall . qid
536 When using file trees,
538 should allocate a new
544 may return nil (because, say, the file already exists).
549 behaves as though it were a function that always responded
550 with the error ``create prohibited''.
554 should mark the file as removed, whether
557 when using file trees, or by updating an internal data structure.
558 In general it is not a good idea to clean up the
560 information associated with the corresponding
562 at this time, to avoid memory errors if other
563 fids have references to that file.
564 Instead, it is suggested that
566 simply mark the file as removed (so that further
567 operations on it know to fail) and wait until the
568 file tree's destroy function is called to reclaim the
571 If not using file trees, it is prudent to take the
575 is not provided, all remove requests will draw
576 ``remove prohibited'' errors.
581 function must be provided; it fills
582 .IB r -> ofcall . data
584 .IB r -> ifcall . count
585 bytes of data from offset
586 .IB r -> ifcall . offset
589 .IB r -> ofcall . count
590 to the number of bytes being returned.
593 will handle reads of directories internally, only
596 for requests on files.
600 are useful for satisfying read requests on a string or buffer.
601 Consulting the request in
604 .IB r -> ofcall . data
606 .IB r -> ofcall . count \fR;
611 can be used to handle directory reads in servers
612 not using file trees.
615 function will be called as necessary to
618 with information for the
620 entry in the directory.
621 The string pointers placed in
623 should be fresh copies
626 they will be freed by
628 after each successful call to
631 should return zero if it successfully filled
633 minus one on end of directory.
638 function is similar but need not be provided.
639 If it is not, all writes will draw
640 ``write prohibited'' errors.
643 should attempt to write the
644 .IB r -> ifcall . count
646 .IB r -> ifcall . data
648 .IB r -> ifcall . offset
650 .IB r -> ofcall . count
651 to the number of bytes actually written.
652 Most programs consider it an error to
653 write less than the requested amount.
659 with the stat information for
663 will have been initialized with the stat info from
673 in changing the metadata for
677 When using file trees,
679 will take care to check that the request satisfies
680 the permissions outlined in
684 should take care to enforce permissions
688 Servers that always call
690 before returning from the service functions
695 is only necessary in programs
698 to be called asynchronously.
700 should cause the request
702 to be cancelled or hurried along.
705 is cancelled, this should be signalled by calling
714 with a nil error string.
718 before forcing a response to
720 In this case, the library will delay sending
723 message until the response to
733 are auxiliary functions, not called in direct response to 9P requests.
738 reference count drops to zero
740 it has been clunked and there are no outstanding
741 requests referring to it),
743 is called to allow the program to dispose
751 reference count drops to zero
753 it has been handled via
755 and other outstanding pointers to it have been closed),
757 is called to allow the program to dispose of the
762 This gets called (from the forked service process)
763 prior entering the 9P service loop.
766 Once the 9P service loop has finished
767 (end of file been reached on the service pipe
768 or a bad message has been read),
770 is called (if provided) to allow any final cleanup.
771 For example, it was used by the Palm Pilot synchronization
772 file system (never finished) to gracefully terminate the serial conversation once
773 the file system had been unmounted.
776 the service loop (which runs in a separate process
777 from its caller) terminates using
785 flag is at least one,
786 a transcript of the 9P session is printed
790 flag is greater than one,
791 additional unspecified debugging output is generated.
792 By convention, servers written using this library
803 .B /sys/src/lib9p/ramfs.c
804 are good examples of simple single-threaded file servers.
808 interface is appropriate for maintaining arbitrary file trees (as in
812 interface is best avoided when the
813 tree structure is easily generated as necessary;
814 this is true when the tree is highly structured (as in
818 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