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 Qid
          {
              uvlong path;
              ulong  vers;
              uchar  type;
          } Qid;

          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;
              Srv   *srv;
              ...
          } 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)

     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
          number in the pool.  Once a Fid has been allocated, it can
          be looked up by fid number using lookupfid. Fids are refer-
          ence counted: both allocfid and lookupfid increment the
          reference count on the Fid structure before returning.  When
          a reference 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
          equivalent 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)