15 walkandclone \- 9P file service
28 .ta \w'\fL1234'u +\w'\fLTree* 'u
32 void (*attach)(Req *r);
35 void (*create)(Req *r);
37 void (*write)(Req *r);
38 void (*remove)(Req *r);
39 void (*flush)(Req *r);
41 void (*wstat)(Req *r);
44 char* (*walk1)(Fid *fid, char *name, Qid *qid);
45 char* (*clone)(Fid *oldfid, Fid *newfid);
47 void (*destroyfid)(Fid *fid);
48 void (*destroyreq)(Req *r);
49 void (*start)(Srv *s);
64 void postmountsrv(Srv *s, char *name, char *mtpt, int flag)
65 void threadpostmountsrv(Srv *s, char *name, char *mtpt, int flag)
66 int postfd(char *srvname, int fd)
67 void respond(Req *r, char *error)
68 ulong readstr(Req *r, char *src)
69 ulong readbuf(Req *r, void *src, ulong nsrc)
70 typedef int Dirgen(int n, Dir *dir, void *aux)
71 void dirread9p(Req *r, Dirgen *gen, void *aux)
72 void walkandclone(Req *r, char *(*walk1)(Fid *old, char *name, void *v),
73 char *(*clone)(Fid *old, Fid *new, void *v), void *v)
79 void* emalloc9p(ulong n)
80 void* erealloc9p(void *v, ulong n)
81 char* estrdup9p(char *s)
91 serves a 9P session by reading requests from
93 dispatching them to the function pointers kept in
96 writing the responses to
101 .I threadpostmountsrv
106 structure members. See the description below.)
111 structures are allocated one-to-one with uncompleted
112 requests and active fids, and are described in
117 depends on whether there is a file tree
120 associated with the server, that is,
124 The differences are made explicit in the
125 discussion of the service loop below.
128 element is the client's, to do with as it pleases.
131 does not return until the 9P conversation is finished.
132 Since it is usually run in a separate process so that
133 the caller can exit, the service loop has little chance
134 to return gracefully on out of memory errors.
140 to obtain its memory.
141 The default implementations of these functions
147 but abort the program if they run out of memory.
148 If alternate behavior is desired, clients can link against
149 alternate implementations of these functions.
153 .I threadpostmountsrv
154 are wrappers that create a separate process in which to run
156 They do the following:
160 is zero (the common case),
165 to be one end of a freshly allocated pipe,
168 initialized as the other end.
173 .BI postfd( s -> srvfd ,
180 Fork a child process via
195 .IB close( s -> srvfd )
206 .BI amount( s -> srvfd,
213 The parent returns to the caller.
215 If any error occurs during
216 this process, the entire process is terminated by calling
218 .SS Service functions
221 structure named after 9P transactions
222 are called to satisfy requests as they arrive.
223 If a function is provided, it
227 to be called when the request is satisfied.
228 The only parameter of each service function
233 The incoming request parameters are stored in
240 structures corresponding to the
247 structure corresponding to
248 .IB r -> ifcall.oldtag \fR.
249 The outgoing response data should be stored in
251 The one exception to this rule is that
256 .IB r -> ofcall.stat \fR:
257 the library will convert the structure into the machine-independent
264 .IB r -> ifcall . stat
266 When a request has been handled,
268 should be called with
271 If the request was satisfied successfully, the error
272 string should be a nil pointer.
273 Note that it is permissible for a function to return
274 without itself calling
276 as long as it has arranged for
278 to be called at some point in the future
279 by another proc sharing its address space,
280 but see the discussion of
287 as well as any pointers it once contained must
288 be considered freed and not referenced.
290 If the service loop detects an error in a request
291 (e.g., an attempt to reuse an extant fid, an open of
292 an already open fid, a read from a fid opened for write, etc.)
293 it will reply with an error without consulting
294 the service functions.
296 The service loop provided by
301 .IR threadpostmountsrv )
303 If it is expected that some requests might
304 block, arranging for alternate processes
305 to handle them is suggested.
307 The constraints on the service functions are as follows.
308 These constraints are checked while the server executes.
309 If a service function fails to do something it ought to have,
316 If authentication is desired,
319 function should record that
321 is the new authentication fid and
327 may be nil, in which case it will be treated as having
328 responded with the error
329 .RI `` "argv0: authentication not required" ,''
332 is the program name variable as set by
340 function should check the authentication state of
347 to the qid of the file system root.
349 may be nil only if file trees are in use;
350 in this case, the qid will be filled from the root
351 of the tree, and no authentication will be done.
354 If file trees are in use,
356 is handled internally, and
360 If file trees are not in use,
363 .IB r -> ifcall . wname
365 .IB r -> ifcall . nwname \fR,
369 .IB ofcall . nqid \fR,
370 and also copying any necessary
376 when the two are different.
381 appropriately, it can
383 with a nil error string even when 9P
386 in the case of a short walk);
387 the library detects error conditions and handles them appropriately.
389 Because implementing the full walk message is intricate and
390 prone to error, the helper routine
392 will handle the request given pointers to two functions
397 if non-nil, is called to signal the creation of
403 routine will copy or increment a reference count in
414 to the new path's qid.
415 Both should return nil
416 on success or an error message on error.
420 after handling the request.
422 .I Walk1\fR, \fPClone
423 If the client provides functions
426 .IB srv -> clone \fR,
427 the 9P service loop will call
429 with these functions to handle the request.
438 with the new qid on a successful walk.
441 If file trees are in use, the file
442 metadata will be consulted on open, create, remove, and wstat
443 to see if the requester has the appropriate permissions.
444 If not, an error will be sent back without consulting a service function.
446 If not using file trees or the user has the appropriate permissions,
449 .IB r -> ofcall . qid
450 already initialized to the one stored in the
452 structure (that is, the one returned in the previous walk).
453 If the qid changes, both should be updated.
458 function must fill in
462 .IB r -> ofcall . qid
464 When using file trees,
466 should allocate a new
472 may return nil (because, say, the file already exists).
477 behaves as though it were a function that always responded
478 with the error ``create prohibited''.
482 should mark the file as removed, whether
485 when using file trees, or by updating an internal data structure.
486 In general it is not a good idea to clean up the
488 information associated with the corresponding
490 at this time, to avoid memory errors if other
491 fids have references to that file.
492 Instead, it is suggested that
494 simply mark the file as removed (so that further
495 operations on it know to fail) and wait until the
496 file tree's destroy function is called to reclaim the
499 If not using file trees, it is prudent to take the
503 is not provided, all remove requests will draw
504 ``remove prohibited'' errors.
509 function must be provided; it fills
510 .IB r -> ofcall . data
512 .IB r -> ifcall . count
513 bytes of data from offset
514 .IB r -> ifcall . offset
517 .IB r -> ofcall . count
518 to the number of bytes being returned.
521 will handle reads of directories internally, only
524 for requests on files.
528 are useful for satisfying read requests on a string or buffer.
529 Consulting the request in
532 .IB r -> ofcall . data
534 .IB r -> ofcall . count \fR;
539 can be used to handle directory reads in servers
540 not using file trees.
543 function will be called as necessary to
546 with information for the
548 entry in the directory.
549 The string pointers placed in
551 should be fresh copies
554 they will be freed by
556 after each successful call to
559 should return zero if it successfully filled
561 minus one on end of directory.
566 function is similar but need not be provided.
567 If it is not, all writes will draw
568 ``write prohibited'' errors.
571 should attempt to write the
572 .IB r -> ifcall . count
574 .IB r -> ifcall . data
576 .IB r -> ifcall . offset
578 .IB r -> ofcall . count
579 to the number of bytes actually written.
580 Most programs consider it an error to
581 write less than the requested amount.
587 with the stat information for
591 will have been initialized with the stat info from
601 in changing the metadata for
605 When using file trees,
607 will take care to check that the request satisfies
608 the permissions outlined in
612 should take care to enforce permissions
616 Single-threaded servers, which always call
618 before returning from the service functions,
623 is only necessary in multithreaded programs,
626 to be called asynchronously.
628 should cause the request
630 to be cancelled or hurried along.
633 is cancelled, this should be signalled by calling
642 with a nil error string.
646 before forcing a response to
648 In this case, the library will delay sending
651 message until the response to
661 are auxiliary functions, not called in direct response to 9P requests.
666 reference count drops to zero
668 it has been clunked and there are no outstanding
669 requests referring to it),
671 is called to allow the program to dispose
679 reference count drops to zero
681 it has been handled via
683 and other outstanding pointers to it have been closed),
685 is called to allow the program to dispose of the
690 Before the 9P service loop begins, the service proc calls
692 so that the server can run any initialization that must be
693 done from inside the service proc.
696 Once the 9P service loop has finished
697 (end of file been reached on the service pipe
698 or a bad message has been read),
700 is called (if provided) to allow any final cleanup.
701 For example, it was used by the Palm Pilot synchronization
702 file system (never finished) to gracefully terminate the serial conversation once
703 the file system had been unmounted.
706 the service loop (which runs in a separate process
707 from its caller) terminates using
715 flag is at least one,
716 a transcript of the 9P session is printed
720 flag is greater than one,
721 additional unspecified debugging output is generated.
722 By convention, servers written using this library
728 .B \*9/src/lib9p/ramfs.c
729 is an example of a simple single-threaded file server.
741 interface is appropriate for maintaining arbitrary file trees (as in
745 interface is best avoided when the
746 tree structure is easily generated as necessary;
747 this is true when the tree is highly structured (as in
751 or is maintained elsewhere.
