Debian Codegraph @

fs/fs.ha

raw
1 // SPDX-License-Identifier: MPL-2.0
2 // (c) Hare authors <https://harelang.org>
3
4 use errors;
5 use io;
6 use path;
7 use time;
8
9 // Closes a filesystem. The fs cannot be used after this function is called.
10 export fn close(fs: *fs) void = {
11 match (fs.close) {
12 case null => void;
13 case let f: *closefunc =>
14 f(fs);
15 };
16 };
17
18 // Opens a file.
19 //
20 // [[flag::CREATE]] isn't very useful with this function, since the new file's
21 // mode is set to zero. For this use-case, use [[create]] instead.
22 export fn open(
23 fs: *fs,
24 path: str,
25 flags: flag = flag::RDONLY,
26 ) (io::handle | error) = {
27 match (fs.open) {
28 case null =>
29 return errors::unsupported;
30 case let f: *openfunc =>
31 return f(fs, path, flags);
32 };
33 };
34
35 // Opens a file, as an [[io::file]]. This file will be backed by an open file
36 // handle on the host operating system, which may not be possible with all
37 // filesystem implementations (such cases will return [[io::unsupported]]).
38 //
39 // [[flag::CREATE]] isn't very useful with this function, since the new file's
40 // mode is set to zero. For this use-case, use [[create_file]] instead.
41 export fn open_file(
42 fs: *fs,
43 path: str,
44 flags: flag = flag::RDONLY,
45 ) (io::file | error) = {
46 match (fs.openfile) {
47 case null =>
48 return errors::unsupported;
49 case let f: *openfilefunc =>
50 return f(fs, path, flags);
51 };
52 };
53
54 // Creates a new file with the given mode if it doesn't already exist, and opens
55 // it for writing.
56 export fn create(
57 fs: *fs,
58 path: str,
59 mode: mode,
60 flags: flag = flag::WRONLY | flag::TRUNC,
61 ) (io::handle | error) = {
62 match (fs.create) {
63 case null =>
64 return errors::unsupported;
65 case let f: *createfunc =>
66 return f(fs, path, mode, flags);
67 };
68 };
69
70 // Creates a new file with the given mode if it doesn't already exist, and opens
71 // it as an [[io::file]] for writing. This file will be backed by an open file
72 // handle on the host operating system, which may not be possible with all
73 // filesystem implementations (such cases will return [[io::unsupported]]).
74 export fn create_file(
75 fs: *fs,
76 path: str,
77 mode: mode,
78 flags: flag = flag::WRONLY | flag::TRUNC,
79 ) (io::file | error) = {
80 match (fs.createfile) {
81 case null =>
82 return errors::unsupported;
83 case let f: *createfilefunc =>
84 return f(fs, path, mode, flags);
85 };
86 };
87
88 // Removes a file.
89 export fn remove(fs: *fs, path: str) (void | error) = {
90 match (fs.remove) {
91 case null =>
92 return errors::unsupported;
93 case let f: *removefunc =>
94 return f(fs, path);
95 };
96 };
97
98 // Renames a file. This generally only works if the source and destination path
99 // are both on the same filesystem. See [[move]] for an implementation which
100 // falls back on a "copy & remove" procedure in this situation.
101 export fn rename(fs: *fs, oldpath: str, newpath: str) (void | error) = {
102 match (fs.rename) {
103 case null =>
104 return errors::unsupported;
105 case let f: *renamefunc =>
106 return f(fs, oldpath, newpath);
107 };
108 };
109
110 // Moves a file. This will use [[rename]] if possible, and will fall back to
111 // copy and remove if necessary.
112 export fn move(fs: *fs, oldpath: str, newpath: str) (void | error) = {
113 match (rename(fs, oldpath, newpath)) {
114 case let err: error =>
115 match (err) {
116 case (cannotrename | errors::unsupported) => void; // Fallback
117 case =>
118 return err;
119 };
120 case void =>
121 return; // Success
122 };
123 // TODO:
124 // - Move non-regular files
125 let st = stat(fs, oldpath)?;
126 assert(isfile(st.mode), "TODO: move non-regular files");
127 st.mode &= 0o7777;
128 let old = open(fs, oldpath)?;
129 let new = match (create(fs, newpath, st.mode)) {
130 case let h: io::handle =>
131 yield h;
132 case let err: error =>
133 _ = io::close(old);
134 return err;
135 };
136 match (io::copy(new, old)) {
137 case let err: io::error =>
138 _ = io::close(new);
139 _ = io::close(old);
140 remove(fs, newpath)?;
141 return err;
142 case size => void;
143 };
144 io::close(new)?;
145 io::close(old)?;
146 remove(fs, oldpath)?;
147 };
148
149 // Creates an [[iterator]] for a given directory to read its contents. The order
150 // in which entries are returned is undefined. The user should call [[next]] to
151 // enumerate entries, and [[finish]] when done iterating.
152 export fn iter(fs: *fs, path: str) (*iterator | error) = {
153 match (fs.iter) {
154 case null =>
155 return errors::unsupported;
156 case let f: *iterfunc =>
157 return f(fs, path);
158 };
159 };
160
161 // Frees state associated with an [[iterator]].
162 export fn finish(iter: *iterator) void = {
163 match (iter.finish) {
164 case null => void;
165 case let f: *finishfunc =>
166 return f(iter);
167 };
168 };
169
170 // Obtains information about a file or directory. If the target is a symlink,
171 // information is returned about the link, not its target.
172 export fn stat(fs: *fs, path: str) (filestat | error) = {
173 match (fs.stat) {
174 case null =>
175 return errors::unsupported;
176 case let f: *statfunc =>
177 return f(fs, path);
178 };
179 };
180
181 // Obtains information about an [[io::file]].
182 export fn fstat(fs: *fs, fd: io::file) (filestat | error) = {
183 match (fs.fstat) {
184 case null =>
185 return errors::unsupported;
186 case let f: *fstatfunc =>
187 return f(fs, fd);
188 };
189 };
190
191 // Returns true if a node exists at the given path, or false if not.
192 //
193 // Note that testing for file existence before using the file can often lead to
194 // race conditions. If possible, prefer to simply attempt to use the file (e.g.
195 // via "open"), and handle the resulting error should the file not exist.
196 export fn exists(fs: *fs, path: str) bool = {
197 match (stat(fs, path)) {
198 case filestat =>
199 return true;
200 case error =>
201 return false;
202 };
203 };
204
205 // Returns the path referred to by a symbolic link. The return value is
206 // statically allocated and will be overwritten on subsequent calls.
207 export fn readlink(fs: *fs, path: str) (str | error) = {
208 match (fs.readlink) {
209 case null =>
210 return errors::unsupported;
211 case let f: *readlinkfunc =>
212 return f(fs, path);
213 };
214 };
215
216 // Creates a directory.
217 export fn mkdir(fs: *fs, path: str, mode: mode) (void | error) = {
218 match (fs.mkdir) {
219 case null =>
220 return errors::unsupported;
221 case let f: *mkdirfunc =>
222 return f(fs, path, mode);
223 };
224 };
225
226 // Makes a directory, and all non-extant directories in its path.
227 export fn mkdirs(fs: *fs, path: str, mode: mode) (void | error) = {
228 let parent = path::dirname(path);
229 if (path != parent) {
230 match (mkdirs(fs, parent, mode)) {
231 case errors::exists => void;
232 case void => void;
233 case let err: error =>
234 return err;
235 };
236 };
237 match (mkdir(fs, path, mode)) {
238 case errors::exists => void;
239 case void => void;
240 case let err: error =>
241 return err;
242 };
243 };
244
245 // Removes a directory. The target directory must be empty; see [[rmdirall]] to
246 // remove its contents as well.
247 export fn rmdir(fs: *fs, path: str) (void | error) = {
248 if (path == "") {
249 return errors::invalid;
250 };
251 match (fs.rmdir) {
252 case null =>
253 return errors::unsupported;
254 case let f: *rmdirfunc =>
255 return f(fs, path);
256 };
257 };
258
259 // Changes mode flags on a file or directory.
260 export fn chmod(fs: *fs, path: str, mode: mode) (void | error) = {
261 match (fs.chmod) {
262 case null =>
263 return errors::unsupported;
264 case let f: *chmodfunc =>
265 return f(fs, path, mode);
266 };
267 };
268
269 // Changes mode flags on a [[io::file]].
270 export fn fchmod(fs: *fs, fd: io::file, mode: mode) (void | error) = {
271 match (fs.fchmod) {
272 case null =>
273 return errors::unsupported;
274 case let f: *fchmodfunc =>
275 return f(fd, mode);
276 };
277 };
278
279 // Changes ownership of a file.
280 export fn chown(fs: *fs, path: str, uid: uint, gid: uint) (void | error) = {
281 match (fs.chown) {
282 case null =>
283 return errors::unsupported;
284 case let f: *chownfunc =>
285 return f(fs, path, uid, gid);
286 };
287 };
288
289 // Changes ownership of a [[io::file]].
290 export fn fchown(fs: *fs, fd: io::file, uid: uint, gid: uint) (void | error) = {
291 match (fs.fchown) {
292 case null =>
293 return errors::unsupported;
294 case let f: *fchownfunc =>
295 return f(fd, uid, gid);
296 };
297 };
298
299 // Changes the access and modification time of a file. A void value will leave
300 // the corresponding time unchanged.
301 export fn chtimes(
302 fs: *fs,
303 path: str,
304 atime: (time::instant | void),
305 mtime: (time::instant | void)
306 ) (void | error) = {
307 match (fs.chtimes) {
308 case null =>
309 return errors::unsupported;
310 case let f: *chtimesfunc =>
311 return f(fs, path, atime, mtime);
312 };
313 };
314
315 // Changes the access and modification time of an [[io::file]]. A void value
316 // will leave the corresponding time unchanged.
317 export fn fchtimes(
318 fs: *fs,
319 fd: io::file,
320 atime: (time::instant | void),
321 mtime: (time::instant | void)
322 ) (void | error) = {
323 match (fs.fchtimes) {
324 case null =>
325 return errors::unsupported;
326 case let f: *fchtimesfunc =>
327 return f(fd, atime, mtime);
328 };
329 };
330
331 // Resolves a path to its absolute, normalized value. Relative paths will be
332 // rooted (if supported by the fs implementation), and "." and ".." components
333 // will be reduced. This function does not follow symlinks; see [[realpath]] if
334 // you need this behavior. The return value is statically allocated; use
335 // [[strings::dup]] to extend its lifetime.
336 export fn resolve(fs: *fs, path: str) str = {
337 match (fs.resolve) {
338 case null => void;
339 case let f: *resolvefunc =>
340 return f(fs, path);
341 };
342 static let buf = path::buffer { ... };
343 path::set(&buf, path)!;
344 return path::string(&buf);
345 };
346
347 // Creates a new (hard) link at 'new' for the file at 'old'.
348 export fn link(fs: *fs, old: str, new: str) (void | error) = {
349 match (fs.link) {
350 case null =>
351 return errors::unsupported;
352 case let f: *linkfunc =>
353 return f(fs, old, new);
354 };
355 };
356
357 // Creates a new symbolic link at 'path' which points to 'target'.
358 export fn symlink(fs: *fs, target: str, path: str) (void | error) = {
359 match (fs.symlink) {
360 case null =>
361 return errors::unsupported;
362 case let f: *symlinkfunc =>
363 return f(fs, target, path);
364 };
365 };
366
367 // Returns the next directory entry from an iterator, or done if none remain.
368 // '.' and '..' are skipped. It is a programming error to call this again after
369 // it has returned void. Calling this again after an error is safe. The list is
370 // not guaranteed to be complete when an error has been returned. The file stat
371 // returned may only have the type bits set on the file mode; callers should
372 // call [[stat]] to obtain the detailed file mode.
373 export fn next(iter: *iterator) (dirent | done | error) = iter.next(iter);