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);
63 void postmountsrv(Srv *s, char *name, char *mtpt, int flag)
64 void threadpostmountsrv(Srv *s, char *name, char *mtpt, int flag)
65 int postfd(char *srvname, int fd)
66 void respond(Req *r, char *error)
67 ulong readstr(Req *r, char *src)
68 ulong readbuf(Req *r, void *src, ulong nsrc)
69 typedef int Dirgen(int n, Dir *dir, void *aux)
70 void dirread9p(Req *r, Dirgen *gen, void *aux)
71 void walkandclone(Req *r, char *(*walk1)(Fid *old, char *name, void *v),
72 char *(*clone)(Fid *old, Fid *new, void *v), void *v)
78 void* emalloc9p(ulong n)
79 void* erealloc9p(void *v, ulong n)
80 char* estrdup9p(char *s)
90 serves a 9P session by reading requests from
92 dispatching them to the function pointers kept in
95 writing the responses to
100 .I threadpostmountsrv
105 structure members. See the description below.)
110 structures are allocated one-to-one with uncompleted
111 requests and active fids, and are described in
116 depends on whether there is a file tree
119 associated with the server, that is,
123 The differences are made explicit in the
124 discussion of the service loop below.
127 element is the client's, to do with as it pleases.
130 does not return until the 9P conversation is finished.
131 Since it is usually run in a separate process so that
132 the caller can exit, the service loop has little chance
133 to return gracefully on out of memory errors.
139 to obtain its memory.
140 The default implementations of these functions
146 but abort the program if they run out of memory.
147 If alternate behavior is desired, clients can link against
148 alternate implementations of these functions.
152 .I threadpostmountsrv
153 are wrappers that create a separate process in which to run
155 They do the following:
159 is zero (the common case),
164 to be one end of a freshly allocated pipe,
167 initialized as the other end.
172 .BI postfd( s -> srvfd ,
179 Fork a child process via
194 .IB close( s -> srvfd )
205 .BI amount( s -> srvfd,
212 The parent returns to the caller.
214 If any error occurs during
215 this process, the entire process is terminated by calling
217 .SS Service functions
220 structure named after 9P transactions
221 are called to satisfy requests as they arrive.
222 If a function is provided, it
226 to be called when the request is satisfied.
227 The only parameter of each service function
232 The incoming request parameters are stored in
239 structures corresponding to the
246 structure corresponding to
247 .IB r -> ifcall.oldtag \fR.
248 The outgoing response data should be stored in
250 The one exception to this rule is that
255 .IB r -> ofcall.stat \fR:
256 the library will convert the structure into the machine-independent
263 .IB r -> ifcall . stat
265 When a request has been handled,
267 should be called with
270 If the request was satisfied successfully, the error
271 string should be a nil pointer.
272 Note that it is permissible for a function to return
273 without itself calling
275 as long as it has arranged for
277 to be called at some point in the future
278 by another proc sharing its address space,
279 but see the discussion of
286 as well as any pointers it once contained must
287 be considered freed and not referenced.
289 If the service loop detects an error in a request
290 (e.g., an attempt to reuse an extant fid, an open of
291 an already open fid, a read from a fid opened for write, etc.)
292 it will reply with an error without consulting
293 the service functions.
295 The service loop provided by
300 .IR threadpostmountsrv )
302 If it is expected that some requests might
303 block, arranging for alternate processes
304 to handle them is suggested.
306 The constraints on the service functions are as follows.
307 These constraints are checked while the server executes.
308 If a service function fails to do something it ought to have,
315 If authentication is desired,
318 function should record that
320 is the new authentication fid and
326 may be nil, in which case it will be treated as having
327 responded with the error
328 .RI `` "argv0: authentication not required" ,''
331 is the program name variable as set by
339 function should check the authentication state of
346 to the qid of the file system root.
348 may be nil only if file trees are in use;
349 in this case, the qid will be filled from the root
350 of the tree, and no authentication will be done.
353 If file trees are in use,
355 is handled internally, and
359 If file trees are not in use,
362 .IB r -> ifcall . wname
364 .IB r -> ifcall . nwname \fR,
368 .IB ofcall . nqid \fR,
369 and also copying any necessary
375 when the two are different.
380 appropriately, it can
382 with a nil error string even when 9P
385 in the case of a short walk);
386 the library detects error conditions and handles them appropriately.
388 Because implementing the full walk message is intricate and
389 prone to error, the helper routine
391 will handle the request given pointers to two functions
396 if non-nil, is called to signal the creation of
402 routine will copy or increment a reference count in
413 to the new path's qid.
414 Both should return nil
415 on success or an error message on error.
419 after handling the request.
421 .I Walk1\fR, \fPClone
422 If the client provides functions
425 .IB srv -> clone \fR,
426 the 9P service loop will call
428 with these functions to handle the request.
437 with the new qid on a successful walk.
440 If file trees are in use, the file
441 metadata will be consulted on open, create, remove, and wstat
442 to see if the requester has the appropriate permissions.
443 If not, an error will be sent back without consulting a service function.
445 If not using file trees or the user has the appropriate permissions,
448 .IB r -> ofcall . qid
449 already initialized to the one stored in the
451 structure (that is, the one returned in the previous walk).
452 If the qid changes, both should be updated.
457 function must fill in
461 .IB r -> ofcall . qid
463 When using file trees,
465 should allocate a new
471 may return nil (because, say, the file already exists).
476 behaves as though it were a function that always responded
477 with the error ``create prohibited''.
481 should mark the file as removed, whether
484 when using file trees, or by updating an internal data structure.
485 In general it is not a good idea to clean up the
487 information associated with the corresponding
489 at this time, to avoid memory errors if other
490 fids have references to that file.
491 Instead, it is suggested that
493 simply mark the file as removed (so that further
494 operations on it know to fail) and wait until the
495 file tree's destroy function is called to reclaim the
498 If not using file trees, it is prudent to take the
502 is not provided, all remove requests will draw
503 ``remove prohibited'' errors.
508 function must be provided; it fills
509 .IB r -> ofcall . data
511 .IB r -> ifcall . count
512 bytes of data from offset
513 .IB r -> ifcall . offset
516 .IB r -> ofcall . count
517 to the number of bytes being returned.
520 will handle reads of directories internally, only
523 for requests on files.
527 are useful for satisfying read requests on a string or buffer.
528 Consulting the request in
531 .IB r -> ofcall . data
533 .IB r -> ofcall . count \fR;
538 can be used to handle directory reads in servers
539 not using file trees.
542 function will be called as necessary to
545 with information for the
547 entry in the directory.
548 The string pointers placed in
550 should be fresh copies
553 they will be freed by
555 after each successful call to
558 should return zero if it successfully filled
560 minus one on end of directory.
565 function is similar but need not be provided.
566 If it is not, all writes will draw
567 ``write prohibited'' errors.
570 should attempt to write the
571 .IB r -> ifcall . count
573 .IB r -> ifcall . data
575 .IB r -> ifcall . offset
577 .IB r -> ofcall . count
578 to the number of bytes actually written.
579 Most programs consider it an error to
580 write less than the requested amount.
586 with the stat information for
590 will have been initialized with the stat info from
600 in changing the metadata for
604 When using file trees,
606 will take care to check that the request satisfies
607 the permissions outlined in
611 should take care to enforce permissions
615 Single-threaded servers, which always call
617 before returning from the service functions,
622 is only necessary in multithreaded programs,
625 to be called asynchronously.
627 should cause the request
629 to be cancelled or hurried along.
632 is cancelled, this should be signalled by calling
641 with a nil error string.
645 before forcing a response to
647 In this case, the library will delay sending
650 message until the response to
659 are auxiliary functions, not called in direct response to 9P requests.
664 reference count drops to zero
666 it has been clunked and there are no outstanding
667 requests referring to it),
669 is called to allow the program to dispose
677 reference count drops to zero
679 it has been handled via
681 and other outstanding pointers to it have been closed),
683 is called to allow the program to dispose of the
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 /usr/local/plan9/src/lib9p/ramfs.c
721 is an example of simple single-threaded file servers.
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.
745 .B /usr/local/plan9/src/lib9p
