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