9p-file.3 (4411B)
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.