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