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  (*start)(Srv *s);
              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)

     9P(3)                                                       9P(3)

          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 uncom-
          pleted 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 follow-
          ing:

               If s->nopipe is zero (the common case), initialize
               s->infd and s->outfd to be one end of a freshly allo-
               cated 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

     9P(3)                                                       9P(3)

               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 func-
          tion 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 outgo-
          ing 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 func-
          tion 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 func-
          tions.

          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 end and then abort.

     9P(3)                                                       9P(3)

          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)).

          Attach
               The 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 neces-
               sary aux state from r->fid to r->newfid when the two
               are different.  As long as walk sets ofcall.nqid appro-
               priately, 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 ref-
               erence 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 suc-
               cessful 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,

     9P(3)                                                       9P(3)

               an error will be sent back without consulting a service
               function.

          If not using file trees or the user has the appropriate per-
          missions, open is called with r->ofcall.qid already initial-
          ized 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.

          Create
               The 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 updat-
               ing 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 mem-
               ory 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 func-
               tion 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.  Con-
               sulting 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 han-
               dle 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.

     9P(3)                                                       9P(3)

          Write
               The 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 ini-
               tialized with the stat info from the tree, and stat
               itself may be nil.

          Wstat
               The 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 appropri-
               ate.

          Flush
               Servers that always call respond before returning from
               the service functions need not provide a flush imple-
               mentation: flush is only necessary in programs that
               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 forc-
               ing 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, start, and end are auxiliary func-
          tions, 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 out-
               standing pointers to it have been closed), destroyreq
               is called to allow the program to dispose of the r->aux
               pointer.

     9P(3)                                                       9P(3)

          Start
               Before the 9P service loop begins, the service proc
               calls start so that the server can run any initializa-
               tion that must be done from inside the service proc.

          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 grace-
               fully terminate the serial conversation once the file
               system had been unmounted.  After calling end, the ser-
               vice 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
          /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 maintain-
          ing 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 struc-
          tured (as in cdfs and nntpfs) or is maintained elsewhere.

     SOURCE
          /src/lib9p

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