9PFID(2)                                                 9PFID(2)

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

     SYNOPSIS
          #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)

     9PFID(2)                                                 9PFID(2)

     DESCRIPTION
          These routines provide management of Fid and Req structures
          from Fidpools 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
          connection, 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 elements 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 num-
          ber 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.

     SOURCE
          /sys/src/lib9p

     SEE ALSO
          9p(2), 9pfile(2)