14 srv \- 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);
62 void postmountsrv(Srv *s, char *name, char *mtpt, int flag)
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
104 structure members. See the description below.)
109 structures are allocated one-to-one with uncompleted
110 requests and active fids, and are described in
115 depends on whether there is a file tree
118 associated with the server, that is,
122 The differences are made explicit in the
123 discussion of the service loop below.
126 element is the client's, to do with as it pleases.
129 does not return until the 9P conversation is finished.
130 Since it is usually run in a separate process so that
131 the caller can exit, the service loop has little chance
132 to return gracefully on out of memory errors.
138 to obtain its memory.
139 The default implementations of these functions
145 but abort the program if they run out of memory.
146 If alternate behavior is desired, clients can link against
147 alternate implementations of these functions.
151 .I threadpostmountsrv
152 are wrappers that create a separate process in which to run
154 They do the following:
158 is zero (the common case),
163 to be one end of a freshly allocated pipe,
166 initialized as the other end.
171 .BI postfd( s -> srvfd ,
178 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
220 .SS Service functions
223 structure named after 9P transactions
224 are called to satisfy requests as they arrive.
225 If a function is provided, it
229 to be called when the request is satisfied.
230 The only parameter of each service function
235 The incoming request parameters are stored in
242 structures corresponding to the
249 structure corresponding to
250 .IB r -> ifcall.oldtag \fR.
251 The outgoing response data should be stored in
253 The one exception to this rule is that
258 .IB r -> ofcall.stat \fR:
259 the library will convert the structure into the machine-independent
266 .IB r -> ifcall . stat
268 When a request has been handled,
270 should be called with
273 If the request was satisfied successfully, the error
274 string should be a nil pointer.
275 Note that it is permissible for a function to return
276 without itself calling
278 as long as it has arranged for
280 to be called at some point in the future
281 by another proc sharing its address space,
282 but see the discussion of
289 as well as any pointers it once contained must
290 be considered freed and not referenced.
292 If the service loop detects an error in a request
293 (e.g., an attempt to reuse an extant fid, an open of
294 an already open fid, a read from a fid opened for write, etc.)
295 it will reply with an error without consulting
296 the service functions.
298 The service loop provided by
303 .IR threadpostmountsrv )
305 If it is expected that some requests might
306 block, arranging for alternate processes
307 to handle them is suggested.
309 The constraints on the service functions are as follows.
310 These constraints are checked while the server executes.
311 If a service function fails to do something it ought to have,
318 If authentication is desired,
321 function should record that
323 is the new authentication fid and
329 may be nil, in which case it will be treated as having
330 responded with the error
331 .RI `` "argv0: authentication not required" ,''
334 is the program name variable as set by
342 function should check the authentication state of
349 to the qid of the file system root.
351 may be nil only if file trees are in use;
352 in this case, the qid will be filled from the root
353 of the tree, and no authentication will be done.
356 If file trees are in use,
358 is handled internally, and
362 If file trees are not in use,
365 .IB r -> ifcall . wname
367 .IB r -> ifcall . nwname \fR,
371 .IB ofcall . nqid \fR,
372 and also copying any necessary
378 when the two are different.
383 appropriately, it can
385 with a nil error string even when 9P
388 in the case of a short walk);
389 the library detects error conditions and handles them appropriately.
391 Because implementing the full walk message is intricate and
392 prone to error, the helper routine
394 will handle the request given pointers to two functions
399 if non-nil, is called to signal the creation of
405 routine will copy or increment a reference count in
416 to the new path's qid.
417 Both should return nil
418 on success or an error message on error.
422 after handling the request.
424 .I Walk1\fR, \fPClone
425 If the client provides functions
428 .IB srv -> clone \fR,
429 the 9P service loop will call
431 with these functions to handle the request.
440 with the new qid on a successful walk.
443 If file trees are in use, the file
444 metadata will be consulted on open, create, remove, and wstat
445 to see if the requester has the appropriate permissions.
446 If not, an error will be sent back without consulting a service function.
448 If not using file trees or the user has the appropriate permissions,
451 .IB r -> ofcall . qid
452 already initialized to the one stored in the
454 structure (that is, the one returned in the previous walk).
455 If the qid changes, both should be updated.
460 function must fill in
464 .IB r -> ofcall . qid
466 When using file trees,
468 should allocate a new
474 may return nil (because, say, the file already exists).
479 behaves as though it were a function that always responded
480 with the error ``create prohibited''.
484 should mark the file as removed, whether
487 when using file trees, or by updating an internal data structure.
488 In general it is not a good idea to clean up the
490 information associated with the corresponding
492 at this time, to avoid memory errors if other
493 fids have references to that file.
494 Instead, it is suggested that
496 simply mark the file as removed (so that further
497 operations on it know to fail) and wait until the
498 file tree's destroy function is called to reclaim the
501 If not using file trees, it is prudent to take the
505 is not provided, all remove requests will draw
506 ``remove prohibited'' errors.
511 function must be provided; it fills
512 .IB r -> ofcall . data
514 .IB r -> ifcall . count
515 bytes of data from offset
516 .IB r -> ifcall . offset
519 .IB r -> ofcall . count
520 to the number of bytes being returned.
523 will handle reads of directories internally, only
526 for requests on files.
530 are useful for satisfying read requests on a string or buffer.
531 Consulting the request in
534 .IB r -> ofcall . data
536 .IB r -> ofcall . count \fR;
541 can be used to handle directory reads in servers
542 not using file trees.
545 function will be called as necessary to
548 with information for the
550 entry in the directory.
551 The string pointers placed in
553 should be fresh copies
556 they will be freed by
558 after each successful call to
561 should return zero if it successfully filled
563 minus one on end of directory.
568 function is similar but need not be provided.
569 If it is not, all writes will draw
570 ``write prohibited'' errors.
573 should attempt to write the
574 .IB r -> ifcall . count
576 .IB r -> ifcall . data
578 .IB r -> ifcall . offset
580 .IB r -> ofcall . count
581 to the number of bytes actually written.
582 Most programs consider it an error to
583 write less than the requested amount.
589 with the stat information for
593 will have been initialized with the stat info from
603 in changing the metadata for
607 When using file trees,
609 will take care to check that the request satisfies
610 the permissions outlined in
614 should take care to enforce permissions
618 Single-threaded servers, which always call
620 before returning from the service functions,
625 is only necessary in multithreaded programs,
628 to be called asynchronously.
630 should cause the request
632 to be cancelled or hurried along.
635 is cancelled, this should be signalled by calling
644 with a nil error string.
648 before forcing a response to
650 In this case, the library will delay sending
653 message until the response to
662 are auxiliary functions, not called in direct response to 9P requests.
667 reference count drops to zero
669 it has been clunked and there are no outstanding
670 requests referring to it),
672 is called to allow the program to dispose
680 reference count drops to zero
682 it has been handled via
684 and other outstanding pointers to it have been closed),
686 is called to allow the program to dispose of the
691 Once the 9P service loop has finished
692 (end of file been reached on the service pipe
693 or a bad message has been read),
695 is called (if provided) to allow any final cleanup.
696 For example, it was used by the Palm Pilot synchronization
697 file system (never finished) to gracefully terminate the serial conversation once
698 the file system had been unmounted.
701 the service loop (which runs in a separate process
702 from its caller) terminates using
710 flag is at least one,
711 a transcript of the 9P session is printed
715 flag is greater than one,
716 additional unspecified debugging output is generated.
717 By convention, servers written using this library
728 .B /sys/src/lib9p/ramfs.c
729 are good examples of simple single-threaded file servers.
735 are good examples of multithreaded file servers.
739 interface is appropriate for maintaining arbitrary file trees (as in
743 interface is best avoided when the
744 tree structure is easily generated as necessary;
745 this is true when the tree is highly structured (as in
749 or is maintained elsewhere.
758 The switch to 9P2000 was taken as an opportunity to tidy
759 much of the interface; we promise to avoid such gratuitous change
