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)