Debian Codegraph @

fs/types.ha

raw
1 // SPDX-License-Identifier: MPL-2.0
2 // (c) Hare authors <https://harelang.org>
3
4 use encoding::utf8;
5 use errors;
6 use io;
7 use strings;
8 use time;
9
10 // An entry of a particular type was sought, but is something else in practice.
11 // For example, opening a file with [[iter]].
12 export type wrongtype = !void;
13
14 // Returned from [[rename]] if this rename is not possible due to technical
15 // constraints, such as if it would cause a file to move between filesystems. In
16 // this situation, other operations (such as copy & remove) may succeed if
17 // attempted.
18 export type cannotrename = !void;
19
20 // All possible fs error types.
21 export type error = !(
22 errors::noentry |
23 errors::noaccess |
24 errors::exists |
25 errors::busy |
26 errors::invalid |
27 errors::unsupported |
28 utf8::invalid |
29 wrongtype |
30 cannotrename |
31 io::error);
32
33 // Returns a human-friendly representation of an error.
34 export fn strerror(err: error) const str = {
35 match (err) {
36 case wrongtype =>
37 return "Wrong entry type for requested operation";
38 case cannotrename =>
39 return "Unable to perform rename operation (try move instead)";
40 case errors::noentry =>
41 return "File or directory not found";
42 case errors::noaccess =>
43 return "Permission denied";
44 case errors::exists =>
45 return "File or directory exists";
46 case errors::invalid =>
47 return "Invalid argument";
48 case errors::busy =>
49 return "Device is busy";
50 case errors::unsupported =>
51 return "Operation not supported";
52 case let err: utf8::invalid =>
53 return utf8::strerror(err);
54 case let err: io::error =>
55 return io::strerror(err);
56 };
57 };
58
59 // File mode information. These bits do not necessarily reflect the underlying
60 // operating system's mode representation, though they were chosen to be
61 // consistent with typical Unix file permissions. All implementations shall
62 // support at least USER_RW, DIR, and REG.
63 export type mode = enum uint {
64 // Read, write, and execute permissions for the file owner
65 USER_RWX = 0o700,
66 // Read and write permissions for the file owner
67 USER_RW = 0o600,
68 // Read and execute permissions for the file owner
69 USER_RX = 0o500,
70 // Read permissions for the file owner
71 USER_R = 0o400,
72 // Write permissions for the file owner
73 USER_W = 0o200,
74 // Execute permissions for the file owner
75 USER_X = 0o100,
76
77 // Read, write, and execute permissions for group members
78 GROUP_RWX = 0o070,
79 // Read and write permissions for group members
80 GROUP_RW = 0o060,
81 // Read and execute permissions for group members
82 GROUP_RX = 0o050,
83 // Read permissions for group members
84 GROUP_R = 0o040,
85 // Write permissions for group members
86 GROUP_W = 0o020,
87 // Execute permissions for group members
88 GROUP_X = 0o010,
89
90 // Read, write, and execute permissions for other users
91 OTHER_RWX = 0o007,
92 // Read and write permissions for other users
93 OTHER_RW = 0o006,
94 // Read and execute permissions for other users
95 OTHER_RX = 0o005,
96 // Read permissions for other users
97 OTHER_R = 0o004,
98 // Write permissions for other users
99 OTHER_W = 0o002,
100 // Execute permissions for other users
101 OTHER_X = 0o001,
102
103 // Entry has the set-uid bit set
104 SETUID = 0o4000,
105 // Entry has the set-gid bit set
106 SETGID = 0o2000,
107 // Entry has the sticky bit set
108 STICKY = 0o1000,
109
110 // Entry is of an unknown type
111 UNKNOWN = 0,
112 // Entry is a FIFO (named pipe)
113 FIFO = 0o010000,
114 // Entry is a directory
115 DIR = 0o040000,
116 // Entry is a character device
117 CHR = 0o020000,
118 // Entry is a block device
119 BLK = 0o060000,
120 // Entry is a regular file
121 REG = 0o100000,
122 // Entry is a symbolic link
123 LINK = 0o120000,
124 // Entry is a Unix socket
125 SOCK = 0o140000,
126 };
127
128 // A mask defining what items are populated in the stat structure.
129 export type stat_mask = enum uint {
130 UID = 1 << 0,
131 GID = 1 << 1,
132 SIZE = 1 << 2,
133 INODE = 1 << 3,
134 ATIME = 1 << 4,
135 MTIME = 1 << 5,
136 CTIME = 1 << 6,
137 };
138
139 // Information about a file or directory. The mask field defines what other
140 // fields are set; mode is always set.
141 export type filestat = struct {
142 mask: stat_mask,
143 mode: mode,
144 uid: uint,
145 gid: uint,
146 sz: size,
147 inode: u64,
148 atime: time::instant,
149 mtime: time::instant,
150 ctime: time::instant,
151 };
152
153 // An entry in a directory. This may be borrowed from the filesystem's internal
154 // state. If you want to keep this around beyond one call to [[next]], use
155 // [[dirent_dup]].
156 export type dirent = struct {
157 // The name of this entry. Not fully qualified: for example,
158 // "foo/bar/baz.txt" would store "baz.txt" here.
159 name: str,
160
161 // The type of this entry. The permission bits may be unset.
162 ftype: mode,
163 };
164
165 // Duplicates a [[dirent]] object. Call [[dirent_finish]] to get rid of it
166 // later.
167 export fn dirent_dup(e: *dirent) (dirent | nomem) = {
168 let new = *e;
169 new.name = strings::dup(e.name)?;
170 return new;
171 };
172
173 // Frees memory associated with a [[dirent]] object which was duplicated with
174 // [[dirent_dup]].
175 export fn dirent_finish(e: *dirent) void = free(e.name);
176
177 // Flags to use for opening a file. Not all operating systems support all flags;
178 // at a minimum, RDONLY, WRONLY, RDWR, CREATE, and TRUNC will be supported.
179 // Note that NOCTTY and CLOEXEC are on by default, and the CTTY/NOCLOEXEC flags
180 // respectively disable them.
181 export type flag = enum int {
182 RDONLY = 0,
183 WRONLY = 1,
184 RDWR = 2,
185 CREATE = 0o100,
186 EXCL = 0o200,
187 CTTY = 0o400,
188 TRUNC = 0o1000,
189 APPEND = 0o2000,
190 NONBLOCK = 0o4000,
191 DSYNC = 0o10000,
192 SYNC = 0o4010000,
193 RSYNC = 0o4010000,
194 DIRECTORY = 0o200000,
195 NOFOLLOW = 0o400000,
196 NOATIME = 0o1000000,
197 NOCLOEXEC = 0o2000000,
198 PATH = 0o10000000,
199 TMPFILE = 0o20200000,
200 };
201
202 export type closefunc = fn(fs: *fs) void;
203 export type removefunc = fn(fs: *fs, path: str) (void | error);
204 export type renamefunc = fn(fs: *fs, oldpath: str, newpath: str) (void | error);
205 export type iterfunc = fn(fs: *fs, path: str) (*iterator | error);
206 export type statfunc = fn(fs: *fs, path: str) (filestat | error);
207 export type fstatfunc = fn(fs: *fs, file: io::file) (filestat | error);
208 export type mkdirfunc = fn(fs: *fs, path: str, mode: mode) (void | error);
209 export type rmdirfunc = fn(fs: *fs, path: str) (void | error);
210 export type chmodfunc = fn(fs: *fs, path: str, mode: mode) (void | error);
211 export type fchmodfunc = fn(fd: io::file, mode: mode) (void | error);
212 export type chownfunc = fn(fs: *fs, path: str, uid: uint, gid: uint) (void | error);
213 export type fchownfunc = fn(fd: io::file, uid: uint, gid: uint) (void | error);
214 export type chtimesfunc = fn(fs: *fs, path: str, atime: (time::instant | void),
215 mtime: (time::instant | void)) (void | error);
216 export type fchtimesfunc = fn(fd: io::file, atime: (time::instant | void),
217 mtime: (time::instant | void)) (void | error);
218 export type resolvefunc = fn(fs: *fs, path: str) str;
219 export type readlinkfunc = fn(fs: *fs, path: str) (str | error);
220 export type linkfunc = fn(fs: *fs, old: str, new: str) (void | error);
221 export type symlinkfunc = fn(fs: *fs, target: str, path: str) (void | error);
222
223 export type openfunc = fn(
224 fs: *fs,
225 path: str,
226 flags: flag,
227 ) (io::handle | error);
228
229 export type openfilefunc = fn(
230 fs: *fs,
231 path: str,
232 flags: flag,
233 ) (io::file | error);
234
235 export type createfunc = fn(
236 fs: *fs,
237 path: str,
238 mode: mode,
239 flags: flag,
240 ) (io::handle | error);
241
242 export type createfilefunc = fn(
243 fs: *fs,
244 path: str,
245 mode: mode,
246 flags: flag,
247 ) (io::file | error);
248
249 // An abstract implementation of a filesystem, which provides common filesystem
250 // operations such as file creation and deletion, but which may be backed by any
251 // underlying storage system. See [[os::cwd]] for access to the host filesystem.
252 //
253 // To create a custom filesystem implementation, embed this type as the first
254 // member of a struct with user-specific data and fill out these fields as
255 // appropriate.
256 export type fs = struct {
257 // Frees resources associated with this filesystem.
258 close: nullable *closefunc,
259
260 // Opens a file.
261 open: nullable *openfunc,
262
263 // Opens a file as an [[io::file]].
264 openfile: nullable *openfilefunc,
265
266 // Creates a new file.
267 create: nullable *createfunc,
268
269 // Creates a new file as an [[io::file]].
270 createfile: nullable *createfilefunc,
271
272 // Removes a file.
273 remove: nullable *removefunc,
274
275 // Renames a file.
276 rename: nullable *renamefunc,
277
278 // Returns an iterator for a path, which yields the contents of a
279 // directory. Pass empty string to yield from the root.
280 //
281 // The iterator must return all entries without error. If an error would
282 // occur, it should be identified here and returned upfront.
283 iter: nullable *iterfunc,
284
285 // Obtains information about a file or directory. If the target is a
286 // symbolic link, information is returned about the link, not its
287 // target.
288 stat: nullable *statfunc,
289
290 // Obtains information about an [[io::file]].
291 fstat: nullable *fstatfunc,
292
293 // Returns the path referred to by a symbolic link. The caller will free
294 // the return value.
295 readlink: nullable *readlinkfunc,
296
297 // Creates a directory.
298 mkdir: nullable *mkdirfunc,
299
300 // Removes a directory. The target directory must be empty.
301 rmdir: nullable *rmdirfunc,
302
303 // Changes mode flags on a file or directory.
304 chmod: nullable *chmodfunc,
305
306 // Changes mode flags on a [[io::file]].
307 fchmod: nullable *fchmodfunc,
308
309 // Changes ownership of a file.
310 chown: nullable *chownfunc,
311
312 // Changes ownership of a [[io::file]].
313 fchown: nullable *fchownfunc,
314
315 // Changes access and modification time of a file.
316 chtimes: nullable *chtimesfunc,
317
318 // Changes access and modification time of an [[io::file]].
319 fchtimes: nullable *fchtimesfunc,
320
321 // Resolves a path to its absolute, normalized value. If the fs
322 // implementation does not provide this, [resolve] presumes that
323 // relative paths are rooted (i.e. "foo" == "/foo").
324 resolve: nullable *resolvefunc,
325
326 // Creates a new (hard) link.
327 link: nullable *linkfunc,
328
329 // Creates a new symbolic link.
330 symlink: nullable *symlinkfunc,
331 };
332
333 // A function which returns the next directory from an [[iterator]].
334 export type nextfunc = fn(iter: *iterator) (dirent | done | error);
335
336 // A function which frees state associated with an [[iterator]].
337 export type finishfunc = fn(iter: *iterator) void;
338
339 // A directory iterator. To implement a directory iterator for a filesystem,
340 // subtype this struct to store any necessary state and populate the pointers
341 // with your implementation.
342 export type iterator = struct {
343 // Returns the next member of the directory, or done if there are none
344 // remaining.
345 next: *nextfunc,
346 // Frees resources associated with the iterator.
347 finish: nullable *finishfunc,
348 };