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