14 walkandclone \- 9P file service
27 .ta \w'\fL1234'u +\w'\fLTree* 'u
31 void (*attach)(Req *r);
34 void (*create)(Req *r);
36 void (*write)(Req *r);
37 void (*remove)(Req *r);
38 void (*flush)(Req *r);
40 void (*wstat)(Req *r);
43 char* (*walk1)(Fid *fid, char *name, Qid *qid);
44 char* (*clone)(Fid *oldfid, Fid *newfid);
46 void (*destroyfid)(Fid *fid);
47 void (*destroyreq)(Req *r);
48 void (*start)(Srv *s);
63 void threadpostmountsrv(Srv *s, char *name, char *mtpt, int flag)
64 int postfd(char *srvname, int fd)
65 void respond(Req *r, char *error)
66 ulong readstr(Req *r, char *src)
67 ulong readbuf(Req *r, void *src, ulong nsrc)
68 typedef int Dirgen(int n, Dir *dir, void *aux)
69 void dirread9p(Req *r, Dirgen *gen, void *aux)
70 void walkandclone(Req *r, char *(*walk1)(Fid *old, char *name, void *v),
71 char *(*clone)(Fid *old, Fid *new, void *v), void *v)
77 void* emalloc9p(ulong n)
78 void* erealloc9p(void *v, ulong n)
79 char* estrdup9p(char *s)
89 serves a 9P session by reading requests from
91 dispatching them to the function pointers kept in
94 writing the responses to
102 structure members. See the description below.)
107 structures are allocated one-to-one with uncompleted
108 requests and active fids, and are described in
113 depends on whether there is a file tree
116 associated with the server, that is,
120 The differences are made explicit in the
121 discussion of the service loop below.
124 element is the client's, to do with as it pleases.
127 does not return until the 9P conversation is finished.
128 Since it is usually run in a separate process so that
129 the caller can exit, the service loop has little chance
130 to return gracefully on out of memory errors.
136 to obtain its memory.
137 The default implementations of these functions
143 but abort the program if they run out of memory.
144 If alternate behavior is desired, clients can link against
145 alternate implementations of these functions.
147 .I threadpostmountsrv
148 is a wrapper that creates a separate process in which to run
150 It does the following:
154 is zero (the common case),
159 to be one end of a freshly allocated pipe,
162 initialized as the other end.
167 .BI postfd( s -> srvfd ,
174 Fork a child process via
189 .IB close( s -> srvfd )
200 .BI amount( s -> srvfd,
207 The parent returns to the caller.
209 If any error occurs during
210 this process, the entire process is terminated by calling
212 .SS Service functions
215 structure named after 9P transactions
216 are called to satisfy requests as they arrive.
217 If a function is provided, it
221 to be called when the request is satisfied.
222 The only parameter of each service function
227 The incoming request parameters are stored in
234 structures corresponding to the
241 structure corresponding to
242 .IB r -> ifcall.oldtag \fR.
243 The outgoing response data should be stored in
245 The one exception to this rule is that
250 .IB r -> ofcall.stat \fR:
251 the library will convert the structure into the machine-independent
258 .IB r -> ifcall . stat
260 When a request has been handled,
262 should be called with
265 If the request was satisfied successfully, the error
266 string should be a nil pointer.
267 Note that it is permissible for a function to return
268 without itself calling
270 as long as it has arranged for
272 to be called at some point in the future
273 by another proc sharing its address space,
274 but see the discussion of
281 as well as any pointers it once contained must
282 be considered freed and not referenced.
284 If the service loop detects an error in a request
285 (e.g., an attempt to reuse an extant fid, an open of
286 an already open fid, a read from a fid opened for write, etc.)
287 it will reply with an error without consulting
288 the service functions.
290 The service loop provided by
293 .I threadpostmountsrv )
295 If it is expected that some requests might
296 block, arranging for alternate processes
297 to handle them is suggested.
299 The constraints on the service functions are as follows.
300 These constraints are checked while the server executes.
301 If a service function fails to do something it ought to have,
308 If authentication is desired,
311 function should record that
313 is the new authentication fid and
319 may be nil, in which case it will be treated as having
320 responded with the error
321 .RI `` "argv0: authentication not required" ,''
324 is the program name variable as set by
332 function should check the authentication state of
339 to the qid of the file system root.
341 may be nil only if file trees are in use;
342 in this case, the qid will be filled from the root
343 of the tree, and no authentication will be done.
346 If file trees are in use,
348 is handled internally, and
352 If file trees are not in use,
355 .IB r -> ifcall . wname
357 .IB r -> ifcall . nwname \fR,
361 .IB ofcall . nqid \fR,
362 and also copying any necessary
368 when the two are different.
373 appropriately, it can
375 with a nil error string even when 9P
378 in the case of a short walk);
379 the library detects error conditions and handles them appropriately.
381 Because implementing the full walk message is intricate and
382 prone to error, the helper routine
384 will handle the request given pointers to two functions
389 if non-nil, is called to signal the creation of
395 routine will copy or increment a reference count in
406 to the new path's qid.
407 Both should return nil
408 on success or an error message on error.
412 after handling the request.
414 .I Walk1\fR, \fPClone
415 If the client provides functions
418 .IB srv -> clone \fR,
419 the 9P service loop will call
421 with these functions to handle the request.
430 with the new qid on a successful walk.
433 If file trees are in use, the file
434 metadata will be consulted on open, create, remove, and wstat
435 to see if the requester has the appropriate permissions.
436 If not, an error will be sent back without consulting a service function.
438 If not using file trees or the user has the appropriate permissions,
441 .IB r -> ofcall . qid
442 already initialized to the one stored in the
444 structure (that is, the one returned in the previous walk).
445 If the qid changes, both should be updated.
450 function must fill in
454 .IB r -> ofcall . qid
456 When using file trees,
458 should allocate a new
464 may return nil (because, say, the file already exists).
469 behaves as though it were a function that always responded
470 with the error ``create prohibited''.
474 should mark the file as removed, whether
477 when using file trees, or by updating an internal data structure.
478 In general it is not a good idea to clean up the
480 information associated with the corresponding
482 at this time, to avoid memory errors if other
483 fids have references to that file.
484 Instead, it is suggested that
486 simply mark the file as removed (so that further
487 operations on it know to fail) and wait until the
488 file tree's destroy function is called to reclaim the
491 If not using file trees, it is prudent to take the
495 is not provided, all remove requests will draw
496 ``remove prohibited'' errors.
501 function must be provided; it fills
502 .IB r -> ofcall . data
504 .IB r -> ifcall . count
505 bytes of data from offset
506 .IB r -> ifcall . offset
509 .IB r -> ofcall . count
510 to the number of bytes being returned.
513 will handle reads of directories internally, only
516 for requests on files.
520 are useful for satisfying read requests on a string or buffer.
521 Consulting the request in
524 .IB r -> ofcall . data
526 .IB r -> ofcall . count \fR;
531 can be used to handle directory reads in servers
532 not using file trees.
535 function will be called as necessary to
538 with information for the
540 entry in the directory.
541 The string pointers placed in
543 should be fresh copies
546 they will be freed by
548 after each successful call to
551 should return zero if it successfully filled
553 minus one on end of directory.
558 function is similar but need not be provided.
559 If it is not, all writes will draw
560 ``write prohibited'' errors.
563 should attempt to write the
564 .IB r -> ifcall . count
566 .IB r -> ifcall . data
568 .IB r -> ifcall . offset
570 .IB r -> ofcall . count
571 to the number of bytes actually written.
572 Most programs consider it an error to
573 write less than the requested amount.
579 with the stat information for
583 will have been initialized with the stat info from
593 in changing the metadata for
597 When using file trees,
599 will take care to check that the request satisfies
600 the permissions outlined in
604 should take care to enforce permissions
608 Servers that always call
610 before returning from the service functions
615 is only necessary in programs that
618 to be called asynchronously.
620 should cause the request
622 to be cancelled or hurried along.
625 is cancelled, this should be signalled by calling
634 with a nil error string.
638 before forcing a response to
640 In this case, the library will delay sending
643 message until the response to
653 are auxiliary functions, not called in direct response to 9P requests.
658 reference count drops to zero
660 it has been clunked and there are no outstanding
661 requests referring to it),
663 is called to allow the program to dispose
671 reference count drops to zero
673 it has been handled via
675 and other outstanding pointers to it have been closed),
677 is called to allow the program to dispose of the
682 Before the 9P service loop begins, the service proc calls
684 so that the server can run any initialization that must be
685 done from inside the service proc.
688 Once the 9P service loop has finished
689 (end of file been reached on the service pipe
690 or a bad message has been read),
692 is called (if provided) to allow any final cleanup.
693 For example, it was used by the Palm Pilot synchronization
694 file system (never finished) to gracefully terminate the serial conversation once
695 the file system had been unmounted.
698 the service loop (which runs in a separate process
699 from its caller) terminates using
707 flag is at least one,
708 a transcript of the 9P session is printed
712 flag is greater than one,
713 additional unspecified debugging output is generated.
714 By convention, servers written using this library
720 .B \*9/src/lib9p/ramfs.c
721 is an example of a simple single-threaded file server.
733 interface is appropriate for maintaining arbitrary file trees (as in
737 interface is best avoided when the
738 tree structure is easily generated as necessary;
739 this is true when the tree is highly structured (as in
743 or is maintained elsewhere.
