sys/man/2/9pfid

   1 .TH 9PFID 2
   2 .SH NAME
   3 Fid, Fidpool, allocfidpool, freefidpool, allocfid, closefid, lookupfid, removefid,
   4 Req, Reqpool, allocreqpool, freereqpool, allocreq, closereq, lookupreq, removereq \- 9P fid, request tracking
   5 .SH SYNOPSIS
   6 .ft L
   7 .nf
   8 #include <u.h>
   9 #include <libc.h>
  10 #include <fcall.h>
  11 #include <thread.h>
  12 #include <9p.h>
  13 .fi
  14 .PP
  15 .ft L
  16 .nf
  17 .ta \w'\fL    'u +\w'\fLulong 'u
  18 typedef struct Fid
  19 {
  20         ulong   fid;
  21         char    omode;  /* -1 if not open */
  22         char    *uid;
  23         Qid     qid;
  24         File    *file;
  25         void    *aux;
  26         \fI...\fP
  27 } Fid;
  28 .fi
  29 .PP
  30 .ft L
  31 .nf
  32 .ta \w'\fL    'u +\w'\fLulong 'u
  33 typedef struct Req
  34 {
  35         ulong   tag;
  36         Fcall   ifcall;
  37         Fcall   ofcall;
  38         Req     *oldreq;
  39         void    *aux;
  40         Fid     *fid;
  41         Fid     *afid;
  42         Fid     *newfid;
  43         \fI...\fP
  44 } Req;
  45 .fi
  46 .PP
  47 .ft L
  48 .nf
  49 .ta \w'\fLFidpool* 'u
  50 Fidpool*        allocfidpool(void (*destroy)(Fid*))
  51 void    freefidpool(Fidpool *p)
  52 Fid*    allocfid(Fidpool *p, ulong fid)
  53 Fid*    lookupfid(Fidpool *p, ulong fid)
  54 Fid*    removefid(Fidpool *p, ulong fid);
  55 void    closefid(Fid *f)
  56 .fi
  57 .PP
  58 .ft L
  59 .nf
  60 .ta \w'\fLReqpool* 'u
  61 Reqpool*        allocreqpool(void (*destroy)(Req*))
  62 void    freereqpool(Reqpool *p)
  63 Req*    allocreq(Reqpool *p, ulong tag)
  64 Req*    lookupreq(Reqpool *p, ulong tag)
  65 Req*    removereq(Reqpool *p, ulong tag);
  66 void    closereq(Req *f)
  67 .fi
  68 .SH DESCRIPTION
  69 These routines provide management of
  70 .B Fid
  71 and
  72 .B Req
  73 structures from
  74 .BR Fidpool s
  75 and
  76 .BR Reqpool s.
  77 They are primarily used by the 9P server loop
  78 described in
  79 .IR 9p (2).
  80 .PP
  81 .B Fid
  82 structures are intended to represent
  83 active fids in a 9P connection, as
  84 .B Chan
  85 structures do in the Plan 9 kernel.
  86 The
  87 .B fid
  88 element is the integer fid used in the 9P
  89 connection.
  90 .B Omode
  91 is the mode under which the fid was opened, or
  92 .B -1
  93 if this fid has not been opened yet.
  94 Note that in addition to the values
  95 .BR OREAD ,
  96 .BR OWRITE ,
  97 and
  98 .BR ORDWR ,
  99 .B omode
 100 can contain the various flags permissible in
 101 an open call.
 102 To ignore the flags, use
 103 .BR omode&OMASK .
 104 .B Omode
 105 should not be changed by the client.
 106 The fid derives from a successful authentication by
 107 .BR uid .
 108 .B Qid
 109 contains the qid returned in the last successful
 110 .B walk
 111 or
 112 .B create
 113 transaction involving the fid.
 114 In a file tree-based server, the
 115 .BR Fid 's
 116 .B file
 117 element points at a
 118 .B File
 119 structure
 120 (see
 121 .IR 9pfile (2))
 122 corresponding to the fid.
 123 The
 124 .B aux
 125 member is intended for use by the
 126 client to hold information specific to a particular
 127 .BR Fid .
 128 With the exception of
 129 .BR aux ,
 130 these elements should be treated
 131 as read-only by the client.
 132 .PP
 133 .I Allocfidpool
 134 creates a new
 135 .BR Fidpool .
 136 .I Freefidpool
 137 destroys such a pool.
 138 .I Allocfid
 139 returns a new
 140 .B Fid
 141 whose fid number is
 142 .IR fid .
 143 There must not already be an extant
 144 .B Fid
 145 with that number in the pool.
 146 Once a
 147 .B Fid
 148 has been allocated, it can be looked up by
 149 fid number using
 150 .IR lookupfid .
 151 .BR Fid s
 152 are reference counted: both
 153 .I allocfid
 154 and
 155 .I lookupfid
 156 increment the reference count on the
 157 .B Fid
 158 structure before
 159 returning.
 160 When a reference to a
 161 .B Fid
 162 is no longer needed,
 163 .I closefid
 164 should be called to note the destruction of the reference.
 165 When the last reference to a
 166 .B Fid
 167 is removed, if
 168 .I destroy
 169 (supplied when creating the fid pool)
 170 is not zero, it is called with the
 171 .B Fid
 172 as a parameter.
 173 It should perform whatever cleanup is necessary
 174 regarding the
 175 .B aux
 176 element.
 177 .I Removefid
 178 is equivalent to
 179 .I lookupfid
 180 but also removes the
 181 .B Fid
 182 from the pool.
 183 Note that due to lingering references,
 184 the return of
 185 .I removefid
 186 may not mean that
 187 .I destroy
 188 has been called.
 189 .PP
 190 .IR Allocreqpool ,
 191 .IR freereqpool ,
 192 .IR allocreq ,
 193 .IR lookupreq ,
 194 .IR closereq ,
 195 and
 196 .I removereq
 197 are analogous but
 198 operate on
 199 .BR Reqpool s
 200 and
 201 .B Req
 202 structures.
 203 .SH SOURCE
 204 .B /sys/src/lib9p
 205 .SH SEE ALSO
 206 .IR 9p (2),
 207 .IR 9pfile (2)