9pfile 4.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223
  1. .TH 9PFILE 2
  2. .SH NAME
  3. Tree, alloctree, freetree,
  4. File, createfile, closefile, removefile, walkfile,
  5. opendirfile, readdirfile, closedirfile, hasperm \- in-memory file hierarchy
  6. .SH SYNOPSIS
  7. .ft L
  8. .nf
  9. #include <u.h>
  10. #include <libc.h>
  11. #include <fcall.h>
  12. #include <thread.h>
  13. #include <9p.h>
  14. .fi
  15. .PP
  16. .ft L
  17. .nf
  18. .ta \w'\fLFile 'u
  19. typedef struct File
  20. {
  21. Ref;
  22. Dir;
  23. void *aux;
  24. \fI...\fP
  25. } File;
  26. .fi
  27. .PP
  28. .ft L
  29. .nf
  30. .ta \w'\fLTree 'u
  31. typedef struct Tree
  32. {
  33. File *root;
  34. \fI...\fP
  35. } Tree;
  36. .fi
  37. .PP
  38. .ft L
  39. .nf
  40. .ta \w'\fLReaddir* 'u +4n +4n
  41. Tree* alloctree(char *uid, char *gid, ulong mode,
  42. void (*destroy)(File*))
  43. void freetree(Tree *tree)
  44. File* createfile(File *dir, char *name, char *uid,
  45. ulong mode, void *aux)
  46. int removefile(File *file)
  47. void closefile(File *file)
  48. File* walkfile(File *dir, char *path)
  49. Readdir* opendirfile(File *dir)
  50. long readdirfile(Readdir *rdir, uchar *buf, long n)
  51. void closedirfile(Readdir *rdir)
  52. int hasperm(File *file, char *uid, int p)
  53. .fi
  54. .SH DESCRIPTION
  55. .BR File s
  56. and
  57. .BR Tree s
  58. provide an in-memory file hierarchy
  59. intended for use in 9P file servers.
  60. .PP
  61. .I Alloctree
  62. creates a new tree of files, and
  63. .I freetree
  64. destroys it.
  65. The root of the tree
  66. (also the
  67. .B root
  68. element in the structure)
  69. will have mode
  70. .I mode
  71. and be owned by user
  72. .I uid
  73. and group
  74. .IR gid .
  75. .I Destroy
  76. is used when freeing
  77. .B File
  78. structures and is described later.
  79. .PP
  80. .BR File s
  81. (including directories)
  82. other than the root are created using
  83. .IR createfile ,
  84. which attempts to create a file named
  85. .I name
  86. in the directory
  87. .IR dir .
  88. If created, the file will have owner
  89. .I uid
  90. and have a group inherited from
  91. the directory.
  92. .I Mode
  93. and the permissions of
  94. .I dir
  95. are used to calculate the permission bits for
  96. the file as described in
  97. .IR open (5).
  98. It is permissible for
  99. .I name
  100. to be a slash-separated path rather than a single element.
  101. .PP
  102. .I Removefile
  103. removes a file from the file tree.
  104. The file will not be freed until the last
  105. reference to it has been removed.
  106. Directories may only be removed when empty.
  107. .I Removefile
  108. returns zero on success, \-1 on error.
  109. It is correct to consider
  110. .I removefile
  111. to be
  112. .I closefile
  113. with the side effect of removing the file
  114. when possible.
  115. .PP
  116. .I Walkfile
  117. evaluates
  118. .I path
  119. relative to the directory
  120. .IR dir ,
  121. returning the resulting file,
  122. or zero if the named file or any intermediate element
  123. does not exist.
  124. .PP
  125. The
  126. .B File
  127. structure's
  128. .B aux
  129. pointer may be used by the client
  130. for
  131. .RB per- File
  132. storage.
  133. .BR File s
  134. are reference-counted: if not zero,
  135. .I destroy
  136. (specified in the call to
  137. .IR alloctree )
  138. will be called for each file when its
  139. last reference is removed or when the tree is freed.
  140. .I Destroy
  141. should take care of any necessary cleanup related to
  142. .BR aux .
  143. When creating new file references by copying pointers,
  144. call
  145. .I incref
  146. (see
  147. .IR lock (2))
  148. to update the reference count.
  149. To note the removal of a reference to a file, call
  150. .IR closefile .
  151. .I Createfile
  152. and
  153. .I walkfile
  154. return new references.
  155. .IR Removefile ,
  156. .IR closefile ,
  157. and
  158. .I walkfile
  159. (but not
  160. .IR createfile )
  161. consume the passed reference.
  162. .PP
  163. Directories may be read, yielding a directory entry structure
  164. (see
  165. .IR stat (5))
  166. for each file in the directory.
  167. In order to allow concurrent reading of directories,
  168. clients must obtain a
  169. .B Readdir
  170. structure by calling
  171. .I opendirfile
  172. on a directory.
  173. Subsequent calls to
  174. .I readdirfile
  175. will each yield an integral number of machine-independent
  176. stat buffers, until end of directory.
  177. When finished, call
  178. .I closedirfile
  179. to free the
  180. .BR Readdir .
  181. .PP
  182. .I Hasperm
  183. does simplistic permission checking; it assumes only
  184. one-user groups named by uid and returns non-zero if
  185. .I uid
  186. has permission
  187. .I p
  188. (a bitwise-or of
  189. .BR AREAD ,
  190. .BR AWRITE
  191. and
  192. .BR AEXEC )
  193. according to
  194. .IB file ->mode \fR.
  195. 9P servers written using
  196. .B File
  197. trees will do standard permission checks automatically;
  198. .I hasperm
  199. may be called explicitly to do additional checks.
  200. A 9P server may link against a different
  201. .I hasperm
  202. implementation to provide more complex groups.
  203. .SH EXAMPLE
  204. The following code correctly handles references
  205. when elementwise walking a path and creating a file.
  206. .IP
  207. .EX
  208. f = tree->root;
  209. incref(f);
  210. for(i=0; i<n && f!=nil; i++)
  211. f = walkfile(f, elem[i]);
  212. if(f == nil)
  213. return nil;
  214. nf = createfile(f, "foo", "nls", 0666, nil);
  215. closefile(f);
  216. return nf;
  217. .EE
  218. .SH SOURCE
  219. .B /sys/src/lib9p/file.c
  220. .SH SEE ALSO
  221. .IR 9p (2)
  222. .SH BUGS
  223. The reference counting is cumbersome.