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 (see
367 temporarily releases the calling process from the server
368 loop and if neccesary spawns a new process to handle 9p
369 requests. When released, the process can do blocking work
370 that would otherwise halt processing of 9p requests.
372 rejoins the calling process with the server loop after
375 The constraints on the service functions are as follows.
376 These constraints are checked while the server executes.
377 If a service function fails to do something it ought to have,
384 If authentication is desired,
387 function should record that
389 is the new authentication fid and
395 may be nil, in which case it will be treated as having
396 responded with the error
397 .RI `` "argv0: authentication not required" ,''
400 is the program name variable as set by
408 function should check the authentication state of
415 to the qid of the file system root.
417 may be nil only if file trees are in use;
418 in this case, the qid will be filled from the root
419 of the tree, and no authentication will be done.
422 If file trees are in use,
424 is handled internally, and
428 If file trees are not in use,
431 .IB r -> ifcall . wname
433 .IB r -> ifcall . nwname \fR,
437 .IB ofcall . nqid \fR,
438 and also copying any necessary
444 when the two are different.
449 appropriately, it can
451 with a nil error string even when 9P
454 in the case of a short walk);
455 the library detects error conditions and handles them appropriately.
457 Because implementing the full walk message is intricate and
458 prone to error, the helper routine
460 will handle the request given pointers to two functions
465 if non-nil, is called to signal the creation of
471 routine will copy or increment a reference count in
482 to the new path's qid.
483 Both should return nil
484 on success or an error message on error.
488 after handling the request.
490 .I Walk1\fR, \fPClone
491 If the client provides functions
494 .IB srv -> clone \fR,
495 the 9P service loop will call
497 with these functions to handle the request.
506 with the new qid on a successful walk.
509 If file trees are in use, the file
510 metadata will be consulted on open, create, remove, and wstat
511 to see if the requester has the appropriate permissions.
512 If not, an error will be sent back without consulting a service function.
514 If not using file trees or the user has the appropriate permissions,
517 .IB r -> ofcall . qid
518 already initialized to the one stored in the
520 structure (that is, the one returned in the previous walk).
521 If the qid changes, both should be updated.
526 function must fill in
530 .IB r -> ofcall . qid
532 When using file trees,
534 should allocate a new
540 may return nil (because, say, the file already exists).
545 behaves as though it were a function that always responded
546 with the error ``create prohibited''.
550 should mark the file as removed, whether
553 when using file trees, or by updating an internal data structure.
554 In general it is not a good idea to clean up the
556 information associated with the corresponding
558 at this time, to avoid memory errors if other
559 fids have references to that file.
560 Instead, it is suggested that
562 simply mark the file as removed (so that further
563 operations on it know to fail) and wait until the
564 file tree's destroy function is called to reclaim the
567 If not using file trees, it is prudent to take the
571 is not provided, all remove requests will draw
572 ``remove prohibited'' errors.
577 function must be provided; it fills
578 .IB r -> ofcall . data
580 .IB r -> ifcall . count
581 bytes of data from offset
582 .IB r -> ifcall . offset
585 .IB r -> ofcall . count
586 to the number of bytes being returned.
589 will handle reads of directories internally, only
592 for requests on files.
596 are useful for satisfying read requests on a string or buffer.
597 Consulting the request in
600 .IB r -> ofcall . data
602 .IB r -> ofcall . count \fR;
607 can be used to handle directory reads in servers
608 not using file trees.
611 function will be called as necessary to
614 with information for the
616 entry in the directory.
617 The string pointers placed in
619 should be fresh copies
622 they will be freed by
624 after each successful call to
627 should return zero if it successfully filled
629 minus one on end of directory.
634 function is similar but need not be provided.
635 If it is not, all writes will draw
636 ``write prohibited'' errors.
639 should attempt to write the
640 .IB r -> ifcall . count
642 .IB r -> ifcall . data
644 .IB r -> ifcall . offset
646 .IB r -> ofcall . count
647 to the number of bytes actually written.
648 Most programs consider it an error to
649 write less than the requested amount.
655 with the stat information for
659 will have been initialized with the stat info from
669 in changing the metadata for
673 When using file trees,
675 will take care to check that the request satisfies
676 the permissions outlined in
680 should take care to enforce permissions
684 Servers that always call
686 before returning from the service functions
691 is only necessary in programs
694 to be called asynchronously.
696 should cause the request
698 to be cancelled or hurried along.
701 is cancelled, this should be signalled by calling
710 with a nil error string.
714 before forcing a response to
716 In this case, the library will delay sending
719 message until the response to
729 are auxiliary functions, not called in direct response to 9P requests.
734 reference count drops to zero
736 it has been clunked and there are no outstanding
737 requests referring to it),
739 is called to allow the program to dispose
747 reference count drops to zero
749 it has been handled via
751 and other outstanding pointers to it have been closed),
753 is called to allow the program to dispose of the
758 This gets called (from the forked service process)
759 prior entering the 9P service loop.
762 Once the 9P service loop has finished
763 (end of file been reached on the service pipe
764 or a bad message has been read),
766 is called (if provided) to allow any final cleanup.
767 For example, it was used by the Palm Pilot synchronization
768 file system (never finished) to gracefully terminate the serial conversation once
769 the file system had been unmounted.
772 the service loop (which runs in a separate process
773 from its caller) terminates using
781 flag is at least one,
782 a transcript of the 9P session is printed
786 flag is greater than one,
787 additional unspecified debugging output is generated.
788 By convention, servers written using this library
799 .B /sys/src/lib9p/ramfs.c
800 are good examples of simple single-threaded file servers.
804 interface is appropriate for maintaining arbitrary file trees (as in
808 interface is best avoided when the
809 tree structure is easily generated as necessary;
810 this is true when the tree is highly structured (as in
814 or is maintained elsewhere.
825 The switch to 9P2000 was taken as an opportunity to tidy
826 much of the interface; we promise to avoid such gratuitous change