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 threadpostmountsrv(Srv *s, char *name, char *mtpt, int flag)
67 void listensrv(Srv *s, char *addr)
68 void threadlistensrv(Srv *s, char *addr)
69 int postfd(char *srvname, int fd)
70 void respond(Req *r, char *error)
71 void responderror(Req*)
72 void readstr(Req *r, char *src)
73 void readbuf(Req *r, void *src, long nsrc)
74 typedef int Dirgen(int n, Dir *dir, void *aux)
75 void dirread9p(Req *r, Dirgen *gen, void *aux)
76 void walkandclone(Req *r, char *(*walk1)(Fid *old, char *name, void *v),
77 char *(*clone)(Fid *old, Fid *new, void *v), void *v)
83 void* emalloc9p(ulong n)
84 void* erealloc9p(void *v, ulong n)
85 char* estrdup9p(char *s)
95 serves a 9P session by reading requests from
97 dispatching them to the function pointers kept in
100 writing the responses to
105 .I threadpostmountsrv
110 structure members. See the description below.)
115 structures are allocated one-to-one with uncompleted
116 requests and active fids, and are described in
121 depends on whether there is a file tree
124 associated with the server, that is,
128 The differences are made explicit in the
129 discussion of the service loop below.
132 element is the client's, to do with as it pleases.
135 does not return until the 9P conversation is finished.
136 Since it is usually run in a separate process so that
137 the caller can exit, the service loop has little chance
138 to return gracefully on out of memory errors.
144 to obtain its memory.
145 The default implementations of these functions
151 but abort the program if they run out of memory.
152 If alternate behavior is desired, clients can link against
153 alternate implementations of these functions.
157 .I threadpostmountsrv
158 are wrappers that create a separate process in which to run
160 They do the following:
164 is zero (the common case),
169 to be one end of a freshly allocated pipe,
172 initialized as the other end.
177 .BI postfd( s -> srvfd ,
184 Fork a child process via
201 .IB close( s -> srvfd )
212 .BI amount( s -> srvfd,
219 The parent returns to the caller.
221 If any error occurs during
222 this process, the entire process is terminated by calling
230 create a separate process to announce as
232 The process listens for incoming connections,
233 creating a new process to serve each.
234 Using these functions results in
236 and the service functions
237 being run in multiple processes simultaneously.
238 The library locks its own data structures as necessary;
239 the client may need to lock data it shares between
240 the multiple connections.
241 .SS Service functions
244 structure named after 9P transactions
245 are called to satisfy requests as they arrive.
246 If a function is provided, it
250 to be called when the request is satisfied.
251 The only parameter of each service function
256 The incoming request parameters are stored in
263 structures corresponding to the
270 structure corresponding to
271 .IB r -> ifcall.oldtag \fR.
272 The outgoing response data should be stored in
274 The one exception to this rule is that
279 .IB r -> ofcall.stat \fR:
280 the library will convert the structure into the machine-independent
287 .IB r -> ifcall . stat
289 When a request has been handled,
291 should be called with
294 If the request was satisfied successfully, the error
295 string should be a nil pointer.
296 Note that it is permissible for a function to return
297 without itself calling
299 as long as it has arranged for
301 to be called at some point in the future
302 by another proc sharing its address space,
303 but see the discussion of
310 as well as any pointers it once contained must
311 be considered freed and not referenced.
316 with the system error string
320 If the service loop detects an error in a request
321 (e.g., an attempt to reuse an extant fid, an open of
322 an already open fid, a read from a fid opened for write, etc.)
323 it will reply with an error without consulting
324 the service functions.
326 The service loop provided by
331 .IR threadpostmountsrv )
333 If it is expected that some requests might
334 block, arranging for alternate processes
335 to handle them is suggested.
337 The constraints on the service functions are as follows.
338 These constraints are checked while the server executes.
339 If a service function fails to do something it ought to have,
346 If authentication is desired,
349 function should record that
351 is the new authentication fid and
357 may be nil, in which case it will be treated as having
358 responded with the error
359 .RI `` "argv0: authentication not required" ,''
362 is the program name variable as set by
370 function should check the authentication state of
377 to the qid of the file system root.
379 may be nil only if file trees are in use;
380 in this case, the qid will be filled from the root
381 of the tree, and no authentication will be done.
384 If file trees are in use,
386 is handled internally, and
390 If file trees are not in use,
393 .IB r -> ifcall . wname
395 .IB r -> ifcall . nwname \fR,
399 .IB ofcall . nqid \fR,
400 and also copying any necessary
406 when the two are different.
411 appropriately, it can
413 with a nil error string even when 9P
416 in the case of a short walk);
417 the library detects error conditions and handles them appropriately.
419 Because implementing the full walk message is intricate and
420 prone to error, the helper routine
422 will handle the request given pointers to two functions
427 if non-nil, is called to signal the creation of
433 routine will copy or increment a reference count in
444 to the new path's qid.
445 Both should return nil
446 on success or an error message on error.
450 after handling the request.
452 .I Walk1\fR, \fPClone
453 If the client provides functions
456 .IB srv -> clone \fR,
457 the 9P service loop will call
459 with these functions to handle the request.
468 with the new qid on a successful walk.
471 If file trees are in use, the file
472 metadata will be consulted on open, create, remove, and wstat
473 to see if the requester has the appropriate permissions.
474 If not, an error will be sent back without consulting a service function.
476 If not using file trees or the user has the appropriate permissions,
479 .IB r -> ofcall . qid
480 already initialized to the one stored in the
482 structure (that is, the one returned in the previous walk).
483 If the qid changes, both should be updated.
488 function must fill in
492 .IB r -> ofcall . qid
494 When using file trees,
496 should allocate a new
502 may return nil (because, say, the file already exists).
507 behaves as though it were a function that always responded
508 with the error ``create prohibited''.
512 should mark the file as removed, whether
515 when using file trees, or by updating an internal data structure.
516 In general it is not a good idea to clean up the
518 information associated with the corresponding
520 at this time, to avoid memory errors if other
521 fids have references to that file.
522 Instead, it is suggested that
524 simply mark the file as removed (so that further
525 operations on it know to fail) and wait until the
526 file tree's destroy function is called to reclaim the
529 If not using file trees, it is prudent to take the
533 is not provided, all remove requests will draw
534 ``remove prohibited'' errors.
539 function must be provided; it fills
540 .IB r -> ofcall . data
542 .IB r -> ifcall . count
543 bytes of data from offset
544 .IB r -> ifcall . offset
547 .IB r -> ofcall . count
548 to the number of bytes being returned.
551 will handle reads of directories internally, only
554 for requests on files.
558 are useful for satisfying read requests on a string or buffer.
559 Consulting the request in
562 .IB r -> ofcall . data
564 .IB r -> ofcall . count \fR;
569 can be used to handle directory reads in servers
570 not using file trees.
573 function will be called as necessary to
576 with information for the
578 entry in the directory.
579 The string pointers placed in
581 should be fresh copies
584 they will be freed by
586 after each successful call to
589 should return zero if it successfully filled
591 minus one on end of directory.
596 function is similar but need not be provided.
597 If it is not, all writes will draw
598 ``write prohibited'' errors.
601 should attempt to write the
602 .IB r -> ifcall . count
604 .IB r -> ifcall . data
606 .IB r -> ifcall . offset
608 .IB r -> ofcall . count
609 to the number of bytes actually written.
610 Most programs consider it an error to
611 write less than the requested amount.
617 with the stat information for
621 will have been initialized with the stat info from
631 in changing the metadata for
635 When using file trees,
637 will take care to check that the request satisfies
638 the permissions outlined in
642 should take care to enforce permissions
646 Servers that always call
648 before returning from the service functions
653 is only necessary in programs
656 to be called asynchronously.
658 should cause the request
660 to be cancelled or hurried along.
663 is cancelled, this should be signalled by calling
672 with a nil error string.
676 before forcing a response to
678 In this case, the library will delay sending
681 message until the response to
690 are auxiliary functions, not called in direct response to 9P requests.
695 reference count drops to zero
697 it has been clunked and there are no outstanding
698 requests referring to it),
700 is called to allow the program to dispose
708 reference count drops to zero
710 it has been handled via
712 and other outstanding pointers to it have been closed),
714 is called to allow the program to dispose of the
719 Once the 9P service loop has finished
720 (end of file been reached on the service pipe
721 or a bad message has been read),
723 is called (if provided) to allow any final cleanup.
724 For example, it was used by the Palm Pilot synchronization
725 file system (never finished) to gracefully terminate the serial conversation once
726 the file system had been unmounted.
729 the service loop (which runs in a separate process
730 from its caller) terminates using
738 flag is at least one,
739 a transcript of the 9P session is printed
743 flag is greater than one,
744 additional unspecified debugging output is generated.
745 By convention, servers written using this library
756 .B /sys/src/lib9p/ramfs.c
757 are good examples of simple single-threaded file servers.
763 are good examples of multithreaded file servers.
767 interface is appropriate for maintaining arbitrary file trees (as in
771 interface is best avoided when the
772 tree structure is easily generated as necessary;
773 this is true when the tree is highly structured (as in
777 or is maintained elsewhere.
786 The switch to 9P2000 was taken as an opportunity to tidy
787 much of the interface; we promise to avoid such gratuitous change