From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man3/9p.html | 434 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 434 insertions(+) create mode 100644 man/man3/9p.html (limited to 'man/man3/9p.html') diff --git a/man/man3/9p.html b/man/man3/9p.html new file mode 100644 index 00000000..9896b0b7 --- /dev/null +++ b/man/man3/9p.html @@ -0,0 +1,434 @@ + +9p(3) - Plan 9 from User Space + + + + +
+
+
9P(3)9P(3) +
+
+

NAME
+ +
+ + Srv, dirread9p, emalloc9p, erealloc9p, estrdup9p, postfd, postmountsrv, + readbuf, readstr, respond, srv, threadpostmountsrv, walkandclone + – 9P file service
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <fcall.h>
+ #include <thread.h>
+ #include <9p.h>
+ +
+ + 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;
+ +
+ + 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)
+ +
+ + +
+ +
+ void* emalloc9p(ulong n)
+ void* erealloc9p(void *v, ulong n)
+ char* estrdup9p(char *s)
+ +
+ + extern int chatty9p;
+ +
+

DESCRIPTION
+ +
+ + The function srv serves a 9P session by reading requests from + s−>infd, dispatching them to the function pointers kept in Srv, + and writing the responses to s−>outfd. (Typically, postmountsrv + or threadpostmountsrv initializes the infd and outfd structure + members. See the description below.) +
+ + Req and Fid structures are allocated one-to-one with uncompleted + requests and active fids, and are described in 9p-fid(3). +
+ + The behavior of srv depends on whether there is a file tree (see + 9p-file(3)) associated with the server, that is, whether the tree + element is nonzero. The differences are made explicit in the discussion + of the service loop below. The aux element is the client’s, to + do with as it pleases. +
+ + 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 emalloc9p, erealloc9p, and estrdup9p + to obtain its memory. The default implementations of these + functions act as malloc, realloc, and 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. + +
+ + Postmountsrv and threadpostmountsrv are wrappers that create a + separate process in which to run srv. They do the following:
+ +
+ + If s−>nopipe is zero (the common case), initialize s−>infd and s−>outfd + to be one end of a freshly allocated pipe, with s−>srvfd initialized + as the other end.
+ If name is non-nil, call postfd(s−>srvfd, name) to post s−>srvfd + as /srv/name.
+ Fork a child process via rfork(3) or procrfork (see thread(3)), + using the RFFDG, RFNAMEG, and RFMEM flags. The child process calls + close(s->srvfd) and then srv(s); it will exit once srv returns.
+ If mtpt is non-nil, call amount(s−>srvfd, mtpt, flag, ""); otherwise, + close s−>srvfd.
+ The parent returns to the caller. +
+ + +
+ If any error occurs during this process, the entire process is + terminated by calling sysfatal(3).
+

Service functions
+ The functions in a Srv structure named after 9P transactions are + called to satisfy requests as they arrive. If a function is provided, + it must arrange for respond to be called when the request is satisfied. + The only parameter of each service function is a Req* parameter + (say r). The incoming request parameters are + stored in r−>ifcall; r−>fid and r−>newfid are pointers to Fid structures + corresponding to the numeric fids in r−>ifcall; similarly, r−>oldreq + is the Req structure corresponding to r−>ifcall.oldtag. The outgoing + response data should be stored in r−>ofcall. The one exception + to this rule is that stat should fill in + r−>d rather than r−>ofcall.stat: the library will convert the structure + into the machine-independent wire representation. Similarly, wstat + may consult r−>d rather than decoding r−>ifcall.stat itself. When + a request has been handled, respond should be called with 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 + respond, as long as it has arranged for respond to be called at + some point in the future by another proc sharing its address space, + but see the discussion of flush below. Once respond has been + called, the Req* as well as any pointers it once contained must + be considered freed and not referenced. +
+ + 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. +
+ + The service loop provided by srv (and indirectly by postmountsrv + and threadpostmountsrv) is single-threaded. If it is expected + that some requests might block, arranging for alternate processes + to handle them is suggested. +
+ + 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, srv will call + endsrv and then abort.
+ Auth   If authentication is desired, the auth function should record + that afid is the new authentication fid and set afid->qid and ofcall.qid. + Auth may be nil, in which case it will be treated as having responded + with the error “argv0: authentication not required,” where argv0 + is the program name variable as set by + +
+ + ARGBEGIN (see arg(3)).
+ +
+ AttachThe attach function should check the authentication state + of afid if desired, and set r−>fid−>qid and ofcall.qid to the qid + of the file system root. 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. + Walk   If file trees are in use, walk is handled internally, and + srv−>walk is never called.
+ +
+ + If file trees are not in use, walk should consult r−>ifcall.wname + and r−>ifcall.nwname, filling in ofcall.qid and ofcall.nqid, and + also copying any necessary aux state from r−>fid to r−>newfid when + the two are different. As long as walk sets ofcall.nqid appropriately, + it can respond with a nil error string + even when 9P demands an error (e.g., in the case of a short walk); + the library detects error conditions and handles them appropriately.
+ Because implementing the full walk message is intricate and prone + to error, the helper routine walkandclone will handle the request + given pointers to two functions walk1 and (optionally) clone . + Clone, if non-nil, is called to signal the creation of newfid + from oldfid. Typically a clone routine will copy or increment + a reference count in oldfid’s aux element. Walk1 should walk fid + to name, initializing fid−>qid to the new path’s qid. Both should + return nil on success or an error message on error. Walkandclone + will call respond after handling the request.
+ +
+ Walk1, Clone
+ +
+ + If the client provides functions srv−>walk1 and (optionally) srv−>clone, + the 9P service loop will call walkandclone with these functions + to handle the request. Unlike the walk1 above, srv−>walk1 must + fill in both fid−>qid and *qid with the new qid on a successful + walk.
+ +
+ 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. +
+ + If not using file trees or the user has the appropriate permissions, + open is called with r−>ofcall.qid already initialized to the one + stored in the Fid structure (that is, the one returned in the + previous walk). If the qid changes, both should be updated.
+ CreateThe create function must fill in both r−>fid−>qid and r−>ofcall.qid + on success. When using file trees, create should allocate a new + File with createfile; note that createfile may return nil (because, + say, the file already exists). If the create function is nil, + srv behaves as though it were a function that always + +
+ + responded with the error “create prohibited”.
+ +
+ Remove
+ +
+ + Remove +
+ +
+ + should mark the file as removed, whether by calling removefile + when using file trees, or by updating an internal data structure. + In general it is not a good idea to clean up the aux information + associated with the corresponding File at this time, to avoid + memory errors if other fids have references to that + file. Instead, it is suggested that 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 aux pointer. If not using file trees, it is prudent to take + the analogous measures. If remove is not provided, all remove + requests will draw “remove prohibited” errors.
+ +
+ Read   The read function must be provided; it fills r−>ofcall.data + with at most r−>ifcall.count bytes of data from offset r−>ifcall.offset + of the file. It also sets r−>ofcall.count to the number of bytes + being returned. If using file trees, srv will handle reads of + directories internally, only calling read for requests on + +
+ + files. Readstr and readbuf are useful for satisfying read requests + on a string or buffer. Consulting the request in r−>ifcall, they + fill r−>ofcall.data and set r−>ofcall.count; they do not call respond. + Similarly, dirread9p can be used to handle directory reads in + servers not using file trees. The passed gen + function will be called as necessary to fill dir with information + for the nth entry in the directory. The string pointers placed + in dir should be fresh copies made with estrdup9p; they will be + freed by dirread9p after each successful call to gen. Gen should + return zero if it successfully filled dir, minus one on end of + directory.
+ +
+ WriteThe write function is similar but need not be provided. If + it is not, all writes will draw “write prohibited” errors. Otherwise, + write should attempt to write the r−>ifcall.count bytes of r−>ifcall.data + to offset r−>ifcall.offset of the file, setting r−>ofcall.count + to the number of bytes actually written. Most + +
+ + programs consider it an error to write less than the requested + amount.
+ +
+ Stat   Stat should fill r−>d with the stat information for r−>fid. + If using file trees, r−>d will have been initialized with the stat + info from the tree, and stat itself may be nil.
+ WstatThe wstat consults r−>d in changing the metadata for r−>fid + as described in stat(9p). When using file trees, srv will take + care to check that the request satisfies the permissions outlined + in stat(9p). Otherwise wstat should take care to enforce permissions + where appropriate.
+ Flush   Single-threaded servers, which always call respond before + returning from the service functions, need not provide a flush + implementation: flush is only necessary in multithreaded programs, + which arrange for respond to be called asynchronously. Flush should + cause the request r−>oldreq to be cancelled or + +
+ + hurried along. If oldreq is cancelled, this should be signalled + by calling respond on oldreq with error string ‘interrupted’. + Flush must respond to r with a nil error string. Flush may respond + to r before forcing a response to r−>oldreq. In this case, the + library will delay sending the Rflush message until the + response to r−>oldreq has been sent. +
+ + +
+ Destroyfid, destroyreq, and end are auxiliary functions, not called + in direct response to 9P requests.
+ Destroyfid
+ +
+ + When a Fid’s reference count drops to zero (i.e., it has been + clunked and there are no outstanding requests referring to it), + destroyfid is called to allow the program to dispose of the fid−>aux + pointer.
+ +
+ Destroyreq
+ +
+ + Similarly, when a Req’s reference count drops to zero (i.e., it + has been handled via respond and other outstanding pointers to + it have been closed), destroyreq is called to allow the program + to dispose of the r−>aux pointer.
+ +
+ End    Once the 9P service loop has finished (end of file been reached + on the service pipe or a bad message has been read), 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 end, the service + loop (which runs in a separate process from its caller) terminates + using _exits (see exits(3)). +
+ + +
+ If the chatty9p flag is at least one, a transcript of the 9P session + is printed on standard error. If the chatty9p flag is greater + than one, additional unspecified debugging output is generated. + By convention, servers written using this library accept the −D + option to increment chatty9p. + +

+

EXAMPLES
+ +
+ + /usr/local/plan9/src/lib9p/ramfs.c is an example of a simple single-threaded + file server. On Plan 9, see archfs, cdfs, nntpfs, webfs, and sshnet + for more examples. +
+ + In general, the File interface is appropriate for maintaining + arbitrary file trees (as in ramfs). The 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 cdfs and + nntpfs) or is maintained elsewhere.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9p
+ +
+

SEE ALSO
+ +
+ + 9p-fid(3), 9p-file(3), intro(9p)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + -- cgit v1.2.3