9pfid 3.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207
  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)