30 authwrite \- 9P file service
43 .ta \w'\fL1234'u +\w'\fLTree* 'u
47 void (*attach)(Req *r);
50 void (*create)(Req *r);
52 void (*write)(Req *r);
53 void (*remove)(Req *r);
54 void (*flush)(Req *r);
56 void (*wstat)(Req *r);
59 char* (*walk1)(Fid *fid, char *name, Qid *qid);
60 char* (*clone)(Fid *oldfid, Fid *newfid);
62 void (*destroyfid)(Fid *fid);
63 void (*destroyreq)(Req *r);
64 void (*start)(Srv *s);
71 void (*forker)(void (*fn)(void*), void *arg, int flags);
79 int postsrv(Srv *s, char *name);
80 void postmountsrv(Srv *s, char *name, char *mtpt, int flag)
81 void postsharesrv(Srv *s, char *name, char *mtpt, char *desc)
82 void listensrv(Srv *s, char *addr)
83 void threadsrv(Srv *s)
84 int threadpostsrv(Srv *s, char *name);
85 void threadpostmountsrv(Srv *s, char *name, char *mtpt, int flag)
86 void threadpostsharesrv(Srv *s, char *name, char *mtpt, char *desc)
87 void threadlistensrv(Srv *s, char *addr)
88 void srvforker(void (*fn)(void*), void *arg, int flags)
89 void threadsrvforker(void (*fn)(void*), void *arg, int flags)
90 void respond(Req *r, char *error)
91 void responderror(Req*)
92 void readstr(Req *r, char *src)
93 void readbuf(Req *r, void *src, long nsrc)
94 typedef int Dirgen(int n, Dir *dir, void *aux)
95 void dirread9p(Req *r, Dirgen *gen, void *aux)
96 void walkandclone(Req *r, char *(*walk1)(Fid *old, char *name, void *v),
97 char *(*clone)(Fid *old, Fid *new, void *v), void *v)
103 void srvrelease(Srv *s)
104 void srvacquire(Srv *s)
112 void* emalloc9p(ulong n)
113 void* erealloc9p(void *v, ulong n)
114 char* estrdup9p(char *s)
126 int authattach(Req *r);
127 void authread(Req *r);
128 void authwrite(Req *r);
135 serve a 9P session by reading requests from
137 dispatching them to the function pointers kept in
140 writing the responses to
145 .I threadpostmountsrv
150 structure members. See the description below.)
155 structures are allocated one-to-one with uncompleted
156 requests and active fids, and are described in
161 depends on whether there is a file tree
164 associated with the server, that is,
168 The differences are made explicit in the
169 discussion of the service loop below.
172 element is the client's, to do with as it pleases.
175 does not return until the 9P conversation is finished.
176 Since it is usually run in a separate process so that
177 the caller can exit, the service loop has little chance
178 to return gracefully on out of memory errors.
184 to obtain its memory.
185 The default implementations of these functions
191 but abort the program if they run out of memory.
192 If alternate behavior is desired, clients can link against
193 alternate implementations of these functions.
199 handle the creation of new processes on a connection which use
212 are wrappers that create a separate process in which to run
214 They do the following:
220 to be one end of a freshly allocated pipe.
224 is non-nil, post the other end file descriptor under the name
233 unless already initialized to a non-nil value.
235 Fork a child process via
244 flags. This isolates the service loop from the callers
245 namespace and from notes posted to the callers note group
246 but shares data and bss segments.
248 The child process then waits for the parent to copy its
249 file descriptor table via
253 flag. This way, the service loop will share the original
254 file descriptor table with previously created child
255 processes of the caller.
257 The child process then closes the other end file descriptor
261 The parent process returns from the function with the
262 mountable file descriptor
268 return a file descriptor of
270 with error string set.
287 otherwise, close the file descriptor.
288 If any error occurs during
289 this process, the entire process is terminated by calling
297 but instead of mounting the service on a directory, it is
302 is the name of the share and
304 is the name of the service channel.
309 create a separate process to announce as
311 The process listens for incoming connections,
312 creating a new process to serve each.
313 Using these functions results in
315 and the service functions
316 being run in multiple processes simultaneously.
317 The library locks its own data structures as necessary;
318 the client may need to lock data it shares between
319 the multiple connections.
320 .SS Service functions
323 structure named after 9P transactions
324 are called to satisfy requests as they arrive.
325 If a function is provided, it
329 to be called when the request is satisfied.
330 The only parameter of each service function
335 The incoming request parameters are stored in
342 structures corresponding to the
349 structure corresponding to
350 .IB r -> ifcall.oldtag \fR.
351 The outgoing response data should be stored in
353 The one exception to this rule is that
358 .IB r -> ofcall.stat \fR:
359 the library will convert the structure into the machine-independent
366 .IB r -> ifcall . stat
368 When a request has been handled,
370 should be called with
373 If the request was satisfied successfully, the error
374 string should be a nil pointer.
375 Note that it is permissible for a function to return
376 without itself calling
378 as long as it has arranged for
380 to be called at some point in the future
381 by another proc sharing its address space,
382 but see the discussion of
389 as well as any pointers it once contained must
390 be considered freed and not referenced.
395 with the system error string
399 If the service loop detects an error in a request
400 (e.g., an attempt to reuse an extant fid, an open of
401 an already open fid, a read from a fid opened for write, etc.)
402 it will reply with an error without consulting
403 the service functions.
405 The service loop provided by
410 .IR threadpostmountsrv )
412 If it is expected that some requests might
413 block, arranging for alternate processes
414 to handle them is suggested (see
418 temporarily releases the calling process from the server
419 loop and if neccesary spawns a new process to handle 9p
420 requests. When released, the process can do blocking work
421 that would otherwise halt processing of 9p requests.
423 rejoins the calling process with the server loop after
426 The constraints on the service functions are as follows.
427 These constraints are checked while the server executes.
428 If a service function fails to do something it ought to have,
435 If authentication is desired,
438 function should record that
440 is the new authentication fid and
446 may be nil, in which case it will be treated as having
447 responded with the error
448 .RI `` "argv0: authentication not required" ,''
451 is the program name variable as set by
459 function should check the authentication state of
466 to the qid of the file system root.
468 may be nil only if file trees are in use;
469 in this case, the qid will be filled from the root
470 of the tree, and no authentication will be done.
473 If file trees are in use,
475 is handled internally, and
479 If file trees are not in use,
482 .IB r -> ifcall . wname
484 .IB r -> ifcall . nwname \fR,
488 .IB ofcall . nqid \fR,
489 and also copying any necessary
495 when the two are different.
500 appropriately, it can
502 with a nil error string even when 9P
505 in the case of a short walk);
506 the library detects error conditions and handles them appropriately.
508 Because implementing the full walk message is intricate and
509 prone to error, the helper routine
511 will handle the request given pointers to two functions
516 if non-nil, is called to signal the creation of
522 routine will copy or increment a reference count in
533 to the new path's qid.
534 Both should return nil
535 on success or an error message on error.
539 after handling the request.
541 .I Walk1\fR, \fPClone
542 If the client provides functions
545 .IB srv -> clone \fR,
546 the 9P service loop will call
548 with these functions to handle the request.
557 with the new qid on a successful walk.
560 If file trees are in use, the file
561 metadata will be consulted on open, create, remove, and wstat
562 to see if the requester has the appropriate permissions.
563 If not, an error will be sent back without consulting a service function.
565 If not using file trees or the user has the appropriate permissions,
568 .IB r -> ofcall . qid
569 already initialized to the one stored in the
571 structure (that is, the one returned in the previous walk).
572 If the qid changes, both should be updated.
577 function must fill in
581 .IB r -> ofcall . qid
583 When using file trees,
585 should allocate a new
591 may return nil (because, say, the file already exists).
596 behaves as though it were a function that always responded
597 with the error ``create prohibited''.
601 should mark the file as removed, whether
604 when using file trees, or by updating an internal data structure.
605 In general it is not a good idea to clean up the
607 information associated with the corresponding
609 at this time, to avoid memory errors if other
610 fids have references to that file.
611 Instead, it is suggested that
613 simply mark the file as removed (so that further
614 operations on it know to fail) and wait until the
615 file tree's destroy function is called to reclaim the
618 If not using file trees, it is prudent to take the
622 is not provided, all remove requests will draw
623 ``remove prohibited'' errors.
628 function must be provided; it fills
629 .IB r -> ofcall . data
631 .IB r -> ifcall . count
632 bytes of data from offset
633 .IB r -> ifcall . offset
636 .IB r -> ofcall . count
637 to the number of bytes being returned.
640 will handle reads of directories internally, only
643 for requests on files.
647 are useful for satisfying read requests on a string or buffer.
648 Consulting the request in
651 .IB r -> ofcall . data
653 .IB r -> ofcall . count \fR;
658 can be used to handle directory reads in servers
659 not using file trees.
662 function will be called as necessary to
665 with information for the
667 entry in the directory.
668 The string pointers placed in
670 should be fresh copies
673 they will be freed by
675 after each successful call to
678 should return zero if it successfully filled
680 minus one on end of directory.
685 function is similar but need not be provided.
686 If it is not, all writes will draw
687 ``write prohibited'' errors.
690 should attempt to write the
691 .IB r -> ifcall . count
693 .IB r -> ifcall . data
695 .IB r -> ifcall . offset
697 .IB r -> ofcall . count
698 to the number of bytes actually written.
699 Most programs consider it an error to
700 write less than the requested amount.
706 with the stat information for
710 will have been initialized with the stat info from
720 in changing the metadata for
724 When using file trees,
726 will take care to check that the request satisfies
727 the permissions outlined in
731 should take care to enforce permissions
735 Servers that always call
737 before returning from the service functions
742 is only necessary in programs
745 to be called asynchronously.
747 should cause the request
749 to be cancelled or hurried along.
752 is cancelled, this should be signalled by calling
761 with a nil error string.
765 before forcing a response to
767 In this case, the library will delay sending
770 message until the response to
780 are auxiliary functions, not called in direct response to 9P requests.
785 reference count drops to zero
787 it has been clunked and there are no outstanding
788 requests referring to it),
790 is called to allow the program to dispose
798 reference count drops to zero
800 it has been handled via
802 and other outstanding pointers to it have been closed),
804 is called to allow the program to dispose of the
809 This gets called (from the forked service process)
810 prior entering the 9P service loop.
813 Once the 9P service loop has finished
814 (end of file been reached on the service pipe
815 or a bad message has been read),
817 is called (if provided) to allow any final cleanup.
818 For example, it was used by the Palm Pilot synchronization
819 file system (never finished) to gracefully terminate the serial conversation once
820 the file system had been unmounted.
823 the service loop (which runs in a separate process
824 from its caller) terminates using
835 are functions to assist in the creation of authenticated
844 It can be used as the
846 service function address.
848 will return 0 if the session has properly
849 authenticated or will return -1 and
852 with an apropiate error.
856 can be called from the
860 service functions respectfully to handle
866 flag is at least one,
867 a transcript of the 9P session is printed
871 flag is greater than one,
872 additional unspecified debugging output is generated.
873 By convention, servers written using this library
884 .B /sys/src/lib9p/ramfs.c
885 are good examples of simple single-threaded file servers.
889 interface is appropriate for maintaining arbitrary file trees (as in
893 interface is best avoided when the
894 tree structure is easily generated as necessary;
895 this is true when the tree is highly structured (as in
899 or is maintained elsewhere.
910 The switch to 9P2000 was taken as an opportunity to tidy
911 much of the interface; we promise to avoid such gratuitous change