1 .TH 9P-FILE 3
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, char *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 (9p).
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 .MR lock (3) )
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 (9p))
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 \*9/src/lib9p/file.c
220 .SH SEE ALSO
221 .MR 9p (3)
222 .SH BUGS
223 The reference counting is cumbersome.