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