term% ls -F
term% cat index.txt
9PFID(2)                      System Calls Manual                     9PFID(2)

       Fid, Fidpool, allocfidpool, freefidpool, allocfid, closefid, lookupfid,
       removefid, Req, Reqpool, allocreqpool, freereqpool, allocreq, closereq,
       lookupreq, removereq - 9P fid, request tracking

       #include <u.h>
       #include <libc.h>
       #include <fcall.h>
       #include <thread.h>
       #include <9p.h>

       typedef struct Fid
           ulong fid;
           char  omode;  /* -1 if not open */
           char  *uid;
           Qid   qid;
           File  *file;
           void  *aux;
       } Fid;

       typedef struct Req
           ulong tag;
           Fcall ifcall;
           Fcall ofcall;
           Req   *oldreq;
           void  *aux;
           Fid   *fid;
           Fid   *afid;
           Fid   *newfid;
       } Req;

       Fidpool* allocfidpool(void (*destroy)(Fid*))
       void     freefidpool(Fidpool *p)
       Fid*     allocfid(Fidpool *p, ulong fid)
       Fid*     lookupfid(Fidpool *p, ulong fid)
       Fid*     removefid(Fidpool *p, ulong fid);
       void     closefid(Fid *f)

       Reqpool* allocreqpool(void (*destroy)(Req*))
       void     freereqpool(Reqpool *p)
       Req*     allocreq(Reqpool *p, ulong tag)
       Req*     lookupreq(Reqpool *p, ulong tag)
       Req*     removereq(Reqpool *p, ulong tag);
       void     closereq(Req *f)

       These  routines  provide management of Fid and Req structures from Fid‐
       pools and Reqpools.  They are primarily used  by  the  9P  server  loop
       described in 9p(2).

       Fid  structures  are  intended to represent active fids in a 9P connec‐
       tion, as Chan structures do in the Plan 9 kernel.  The fid  element  is
       the  integer  fid  used  in the 9P connection.  Omode is the mode under
       which the fid was opened, or -1 if this fid has not  been  opened  yet.
       Note that in addition to the values OREAD, OWRITE, and ORDWR, omode can
       contain the various flags permissible in an open call.  To  ignore  the
       flags,  use  omode&OMASK.   Omode  should not be changed by the client.
       The fid derives from a successful authentication by uid.  Qid  contains
       the  qid  returned  in  the  last successful walk or create transaction
       involving the fid.  In a file tree-based server, the Fid's file element
       points  at  a  File structure (see 9pfile(2)) corresponding to the fid.
       The aux member is intended for use by the client  to  hold  information
       specific  to  a  particular Fid.  With the exception of aux, these ele‐
       ments should be treated as read-only by the client.

       Allocfidpool creates a new Fidpool.  Freefidpool destroys such a  pool.
       Allocfid  returns  a  new  Fid whose fid number is fid.  There must not
       already be an extant Fid with that number in the pool.  Once a Fid  has
       been  allocated,  it  can  be  looked up by fid number using lookupfid.
       Fids are reference counted: both allocfid and lookupfid  increment  the
       reference  count  on the Fid structure before returning.  When a refer‐
       ence to a Fid is no longer needed, closefid should be  called  to  note
       the  destruction of the reference.  When the last reference to a Fid is
       removed, if destroy (supplied when creating the fid pool) is not  zero,
       it  is  called with the Fid as a parameter.  It should perform whatever
       cleanup is necessary regarding the aux element.  Removefid  is  equiva‐
       lent  to  lookupfid  but also removes the Fid from the pool.  Note that
       due to lingering references, the return of removefid may not mean  that
       destroy has been called.

       Allocreqpool, freereqpool, allocreq, lookupreq, closereq, and removereq
       are analogous but operate on Reqpools and Req structures.


       9p(2), 9pfile(2)