| 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 |
}; |