diff options
Diffstat (limited to 'man/man3/9p.3')
| -rw-r--r-- | man/man3/9p.3 | 760 |
1 files changed, 760 insertions, 0 deletions
diff --git a/man/man3/9p.3 b/man/man3/9p.3 new file mode 100644 index 00000000..48d029ef --- /dev/null +++ b/man/man3/9p.3 @@ -0,0 +1,760 @@ +.TH 9P 3 +.SH NAME +Srv, +dirread9p, +emalloc9p, +erealloc9p, +estrdup9p, +postfd, +postmountsrv, +readbuf, +readstr, +respond, +threadpostmountsrv, +srv \- 9P file service +.SH SYNOPSIS +.ft L +.nf +#include <u.h> +#include <libc.h> +#include <fcall.h> +#include <thread.h> +#include <9p.h> +.fi +.PP +.ft L +.nf +.ta \w'\fL1234'u +\w'\fLTree* 'u +typedef struct Srv { + Tree* tree; + + void (*attach)(Req *r); + void (*auth)(Req *r); + void (*open)(Req *r); + void (*create)(Req *r); + void (*read)(Req *r); + void (*write)(Req *r); + void (*remove)(Req *r); + void (*flush)(Req *r); + void (*stat)(Req *r); + void (*wstat)(Req *r); + void (*walk)(Req *r); + + char* (*walk1)(Fid *fid, char *name, Qid *qid); + char* (*clone)(Fid *oldfid, Fid *newfid); + + void (*destroyfid)(Fid *fid); + void (*destroyreq)(Req *r); + void (*end)(Srv *s); + void* aux; + + int infd; + int outfd; + int srvfd; + int nopipe; +} Srv; +.fi +.PP +.nf +.ft L +.ta \w'\fLvoid* 'u +int srv(Srv *s) +void postmountsrv(Srv *s, char *name, char *mtpt, int flag) +void threadpostmountsrv(Srv *s, char *name, char *mtpt, int flag) +int postfd(char *srvname, int fd) +void respond(Req *r, char *error) +ulong readstr(Req *r, char *src) +ulong readbuf(Req *r, void *src, ulong nsrc) +typedef int Dirgen(int n, Dir *dir, void *aux) +void dirread9p(Req *r, Dirgen *gen, void *aux) +void walkandclone(Req *r, char *(*walk1)(Fid *old, char *name, void *v), + char *(*clone)(Fid *old, Fid *new, void *v), void *v) +.fi +.PP +.nf +.ft L +.ta \w'\fLvoid* 'u +void* emalloc9p(ulong n) +void* erealloc9p(void *v, ulong n) +char* estrdup9p(char *s) +.fi +.PP +.nf +.ft L +extern int chatty9p; +.fi +.SH DESCRIPTION +The function +.I srv +serves a 9P session by reading requests from +.BR s->infd , +dispatching them to the function pointers kept in +.BR Srv , +and +writing the responses to +.BR s->outfd . +(Typically, +.I postmountsrv +or +.I threadpostmountsrv +initializes the +.B infd +and +.B outfd +structure members. See the description below.) +.PP +.B Req +and +.B Fid +structures are allocated one-to-one with uncompleted +requests and active fids, and are described in +.IR 9pfid (2). +.PP +The behavior of +.I srv +depends on whether there is a file tree +(see +.IR 9pfile (2)) +associated with the server, that is, +whether the +.B tree +element is nonzero. +The differences are made explicit in the +discussion of the service loop below. +The +.B aux +element is the client's, to do with as it pleases. +.PP +.I Srv +does not return until the 9P conversation is finished. +Since it is usually run in a separate process so that +the caller can exit, the service loop has little chance +to return gracefully on out of memory errors. +It calls +.IR emalloc9p , +.IR erealloc9p , +and +.I estrdup9p +to obtain its memory. +The default implementations of these functions +act as +.IR malloc , +.IR realloc , +and +.I strdup +but abort the program if they run out of memory. +If alternate behavior is desired, clients can link against +alternate implementations of these functions. +.PP +.I Postmountsrv +and +.I threadpostmountsrv +are wrappers that create a separate process in which to run +.IR srv . +They do the following: +.IP +If +.IB s -> nopipe +is zero (the common case), +initialize +.IB s -> infd +and +.IB s -> outfd +to be one end of a freshly allocated pipe, +with +.IB s -> srvfd +initialized as the other end. +.IP +If +.B name +is non-nil, call +.BI postfd( s -> srvfd , +.IB name ) +to post +.IB s -> srvfd +as +.BI /srv/ name . +.IP +Fork a child process via +.I rfork +(see +.IR fork (2)) +or +.I procrfork +(see +.IR thread (2)), +using the +.BR RFFDG , +.RR RFNOTEG , +.BR RFNAMEG , +and +.BR RFMEM +flags. +The child process +calls +.IB close( s -> srvfd ) +and then +.IB srv( s ) \fR; +it will exit once +.I srv +returns. +.IP +If +.I mtpt +is non-nil, +call +.BI amount( s -> srvfd, +.IB mtpt , +.IB flag , +\fB"")\fR; +otherwise, close +.IB s -> srvfd \fR. +.IP +The parent returns to the caller. +.LP +If any error occurs during +this process, the entire process is terminated by calling +.I sysfatal +(see +.IR perror (2)). +.SS Service functions +The functions in a +.B Srv +structure named after 9P transactions +are called to satisfy requests as they arrive. +If a function is provided, it +.I must +arrange for +.I respond +to be called when the request is satisfied. +The only parameter of each service function +is a +.B Req* +parameter (say +.IR r ). +The incoming request parameters are stored in +.IB r -> ifcall \fR; +.IB r -> fid +and +.IB r -> newfid +are pointers to +.B Fid +structures corresponding to the +numeric fids in +.IB r -> ifcall \fR; +similarly, +.IB r -> oldreq +is the +.B Req +structure corresponding to +.IB r -> ifcall.oldtag \fR. +The outgoing response data should be stored in +.IB r -> ofcall \fR. +The one exception to this rule is that +.I stat +should fill in +.IB r -> d +rather than +.IB r -> ofcall.stat \fR: +the library will convert the structure into the machine-independent +wire representation. +Similarly, +.I wstat +may consult +.IB r -> d +rather than decoding +.IB r -> ifcall . stat +itself. +When a request has been handled, +.I respond +should be called with +.I r +and an error string. +If the request was satisfied successfully, the error +string should be a nil pointer. +Note that it is permissible for a function to return +without itself calling +.IR respond , +as long as it has arranged for +.I respond +to be called at some point in the future +by another proc sharing its address space, +but see the discussion of +.I flush +below. +Once +.I respond +has been called, the +.B Req* +as well as any pointers it once contained must +be considered freed and not referenced. +.PP +If the service loop detects an error in a request +(e.g., an attempt to reuse an extant fid, an open of +an already open fid, a read from a fid opened for write, etc.) +it will reply with an error without consulting +the service functions. +.PP +The service loop provided by +.I srv +(and indirectly by +.I postmountsrv +and +.IR threadpostmountsrv ) +is single-threaded. +If it is expected that some requests might +block, arranging for alternate processes +to handle them is suggested. +.PP +The constraints on the service functions are as follows. +These constraints are checked while the server executes. +If a service function fails to do something it ought to have, +.I srv +will call +.I endsrv +and then abort. +.TP +.I Auth +If authentication is desired, +the +.I auth +function should record that +.I afid +is the new authentication fid and +set +.I afid->qid +and +.IR ofcall.qid . +.I Auth +may be nil, in which case it will be treated as having +responded with the error +.RI `` "argv0: authentication not required" ,'' +where +.I argv0 +is the program name variable as set by +.I ARGBEGIN +(see +.IR arg (2)). +.TP +.I Attach +The +.I attach +function should check the authentication state of +.I afid +if desired, +and set +.IB r -> fid -> qid +and +.I ofcall.qid +to the qid of the file system root. +.I Attach +may be nil only if file trees are in use; +in this case, the qid will be filled from the root +of the tree, and no authentication will be done. +.TP +.I Walk +If file trees are in use, +.I walk +is handled internally, and +.IB srv -> walk +is never called. +.IP +If file trees are not in use, +.I walk +should consult +.IB r -> ifcall . wname +and +.IB r -> ifcall . nwname \fR, +filling in +.IB ofcall . qid +and +.IB ofcall . nqid \fR, +and also copying any necessary +.I aux +state from +.IB r -> fid +to +.IB r -> newfid +when the two are different. +As long as +.I walk +sets +.IB ofcall . nqid +appropriately, it can +.I respond +with a nil error string even when 9P +demands an error +.RI ( e.g. , +in the case of a short walk); +the library detects error conditions and handles them appropriately. +.IP +Because implementing the full walk message is intricate and +prone to error, the helper routine +.I walkandclone +will handle the request given pointers to two functions +.I walk1 +and (optionally) +.I clone . +.IR Clone , +if non-nil, is called to signal the creation of +.I newfid +from +.IR oldfid . +Typically a +.I clone +routine will copy or increment a reference count in +.IR oldfid 's +.I aux +element. +.I Walk1 +should walk +.I fid +to +.IR name , +initializing +.IB fid -> qid +to the new path's qid. +Both should return nil +on success or an error message on error. +.I Walkandclone +will call +.I respond +after handling the request. +.TP +.I Walk1\fR, \fPClone +If the client provides functions +.IB srv -> walk1 +and (optionally) +.IB srv -> clone \fR, +the 9P service loop will call +.I walkandclone +with these functions to handle the request. +Unlike the +.I walk1 +above, +.IB srv -> walk1 +must fill in both +.IB fid -> qid +and +.BI * qid +with the new qid on a successful walk. +.TP +.I Open +If file trees are in use, the file +metadata will be consulted on open, create, remove, and wstat +to see if the requester has the appropriate permissions. +If not, an error will be sent back without consulting a service function. +.PP +If not using file trees or the user has the appropriate permissions, +.I open +is called with +.IB r -> ofcall . qid +already initialized to the one stored in the +.B Fid +structure (that is, the one returned in the previous walk). +If the qid changes, both should be updated. +.TP +.I Create +The +.I create +function must fill in +both +.IB r -> fid -> qid +and +.IB r -> ofcall . qid +on success. +When using file trees, +.I create +should allocate a new +.B File +with +.IR createfile ; +note that +.I createfile +may return nil (because, say, the file already exists). +If the +.I create +function is nil, +.I srv +behaves as though it were a function that always responded +with the error ``create prohibited''. +.TP +.I Remove +.I Remove +should mark the file as removed, whether +by calling +.I removefile +when using file trees, or by updating an internal data structure. +In general it is not a good idea to clean up the +.I aux +information associated with the corresponding +.B File +at this time, to avoid memory errors if other +fids have references to that file. +Instead, it is suggested that +.I remove +simply mark the file as removed (so that further +operations on it know to fail) and wait until the +file tree's destroy function is called to reclaim the +.I aux +pointer. +If not using file trees, it is prudent to take the +analogous measures. +If +.I remove +is not provided, all remove requests will draw +``remove prohibited'' errors. +.TP +.I Read +The +.I read +function must be provided; it fills +.IB r -> ofcall . data +with at most +.IB r -> ifcall . count +bytes of data from offset +.IB r -> ifcall . offset +of the file. +It also sets +.IB r -> ofcall . count +to the number of bytes being returned. +If using file trees, +.I srv +will handle reads of directories internally, only +calling +.I read +for requests on files. +.I Readstr +and +.I readbuf +are useful for satisfying read requests on a string or buffer. +Consulting the request in +.IB r -> ifcall \fR, +they fill +.IB r -> ofcall . data +and set +.IB r -> ofcall . count \fR; +they do not call +.IB respond . +Similarly, +.I dirread9p +can be used to handle directory reads in servers +not using file trees. +The passed +.I gen +function will be called as necessary to +fill +.I dir +with information for the +.IR n th +entry in the directory. +The string pointers placed in +.I dir +should be fresh copies +made with +.IR estrdup9p ; +they will be freed by +.I dirread9p +after each successful call to +.IR gen . +.I Gen +should return zero if it successfully filled +.IR dir , +minus one on end of directory. +.TP +.I Write +The +.I write +function is similar but need not be provided. +If it is not, all writes will draw +``write prohibited'' errors. +Otherwise, +.I write +should attempt to write the +.IB r -> ifcall . count +bytes of +.IB r -> ifcall . data +to offset +.IB r -> ifcall . offset +of the file, setting +.IB r -> ofcall . count +to the number of bytes actually written. +Most programs consider it an error to +write less than the requested amount. +.TP +.I Stat +.I Stat +should fill +.IB r -> d +with the stat information for +.IB r -> fid \fR. +If using file trees, +.IB r -> d +will have been initialized with the stat info from +the tree, and +.I stat +itself may be nil. +.TP +.I Wstat +The +.I wstat +consults +.IB r -> d +in changing the metadata for +.IB r -> fid +as described in +.IR stat (5). +When using file trees, +.I srv +will take care to check that the request satisfies +the permissions outlined in +.IR stat (5). +Otherwise +.I wstat +should take care to enforce permissions +where appropriate. +.TP +.I Flush +Single-threaded servers, which always call +.I respond +before returning from the service functions, +need not provide a +.I flush +implementation: +.I flush +is only necessary in multithreaded programs, +which arrange for +.I respond +to be called asynchronously. +.I Flush +should cause the request +.IB r -> oldreq +to be cancelled or hurried along. +If +.I oldreq +is cancelled, this should be signalled by calling +.I respond +on +.I oldreq +with error string +.RB ` interrupted '. +.I Flush +must respond to +.I r +with a nil error string. +.I Flush +may respond to +.I r +before forcing a response to +.IB r -> oldreq \fR. +In this case, the library will delay sending +the +.I Rflush +message until the response to +.IB r -> oldreq +has been sent. +.PD +.PP +.IR Destroyfid , +.IR destroyreq , +and +.I end +are auxiliary functions, not called in direct response to 9P requests. +.TP +.I Destroyfid +When a +.BR Fid 's +reference count drops to zero +.RI ( i.e., +it has been clunked and there are no outstanding +requests referring to it), +.I destroyfid +is called to allow the program to dispose +of the +.IB fid -> aux +pointer. +.TP +.I Destroyreq +Similarly, when a +.BR Req 's +reference count drops to zero +.RI ( i.e. , +it has been handled via +.I respond +and other outstanding pointers to it have been closed), +.I destroyreq +is called to allow the program to dispose of the +.IB r -> aux +pointer. +.TP +.I End +Once the 9P service loop has finished +(end of file been reached on the service pipe +or a bad message has been read), +.I end +is called (if provided) to allow any final cleanup. +For example, it was used by the Palm Pilot synchronization +file system (never finished) to gracefully terminate the serial conversation once +the file system had been unmounted. +After calling +.IR end , +the service loop (which runs in a separate process +from its caller) terminates using +.I _exits +(see +.IR exits (2)). +.PD +.PP +If the +.B chatty9p +flag is at least one, +a transcript of the 9P session is printed +on standard error. +If the +.B chatty9p +flag is greater than one, +additional unspecified debugging output is generated. +By convention, servers written using this library +accept the +.B -D +option to increment +.BR chatty9p . +.SH EXAMPLES +.IR Archfs (4), +.IR cdfs (4), +.IR nntpfs (4), +.IR snap (4), +and +.B /sys/src/lib9p/ramfs.c +are good examples of simple single-threaded file servers. +.IR Webfs (4) +and +.I sshnet +(see +.IR ssh (1)) +are good examples of multithreaded file servers. +.PP +In general, the +.B File +interface is appropriate for maintaining arbitrary file trees (as in +.IR ramfs ). +The +.B File +interface is best avoided when the +tree structure is easily generated as necessary; +this is true when the tree is highly structured (as in +.I cdfs +and +.IR nntpfs ) +or is maintained elsewhere. +.SH SOURCE +.B /sys/src/lib9p +.SH SEE ALSO +.IR 9pfid (2), +.IR 9pfile (2), +.IR srv (3), +.IR intro (5) +.SH BUGS +The switch to 9P2000 was taken as an opportunity to tidy +much of the interface; we promise to avoid such gratuitous change +in the future. |