.githooks/
compiler/
kernel/
lib/
examples/
std/
arch/
bits/
char/
collections/
fs/
hash/
lang/
mem/
sys/
arch.rad
68 B
bits.rad
1.6 KiB
char.rad
1.5 KiB
collections.rad
39 B
fmt.rad
11.6 KiB
fs.rad
11.0 KiB
hash.rad
41 B
intrinsics.rad
467 B
io.rad
1.7 KiB
lang.rad
335 B
mem.rad
12.0 KiB
mem.ras
919 B
process.rad
6.2 KiB
std.manifest
4.9 KiB
std.rad
349 B
sys.rad
1.0 KiB
testing.rad
2.4 KiB
tests.rad
26.6 KiB
vec.rad
3.2 KiB
scripts/
seed/
sublime/
test/
vim/
.gitignore
333 B
.gitsigners
224 B
AGENTS.md
8.3 KiB
CONTRIBUTING
2.1 KiB
LICENSE
1.1 KiB
Makefile
2.5 KiB
README
3.4 KiB
STYLE
3.2 KiB
std.lib
2.1 KiB
std.lib.test
1.1 KiB
lib/std/fs.rad
raw
| 1 | //! Host-neutral file system access. |
| 2 | //! |
| 3 | //! Paths are byte strings without a terminating zero byte. Relative paths |
| 4 | //! resolve against the host's current directory. File operations throw |
| 5 | //! [`sys::Error`]. Allocated reads can also throw [`alloc::AllocError`]. |
| 6 | |
| 7 | @test mod tests; |
| 8 | |
| 9 | use std::lang::alloc; |
| 10 | use std::mem; |
| 11 | use std::mem::heap; |
| 12 | use std::sys; |
| 13 | use std::sys::host; |
| 14 | |
| 15 | /// Maximum storage for one directory listing during tree removal. |
| 16 | constant TREE_LIST_BYTES: u32 = 65536; |
| 17 | |
| 18 | /// Kind of a file system entry. |
| 19 | export union Kind: Copy { |
| 20 | /// Regular file. |
| 21 | File, |
| 22 | /// Directory. |
| 23 | Directory, |
| 24 | /// Any other entry. |
| 25 | Other, |
| 26 | } |
| 27 | |
| 28 | /// Size and kind of a file system entry. |
| 29 | export record Stat: Copy { |
| 30 | /// Size in bytes. Zero for directories. |
| 31 | size: u64, |
| 32 | /// Kind of the entry. |
| 33 | kind: Kind, |
| 34 | } |
| 35 | |
| 36 | /// Check a nonempty relative path with nonempty, normal components. |
| 37 | /// Components use `/` separators. Zero bytes and `.` or `..` components |
| 38 | /// are invalid. The check is lexical. |
| 39 | export fn isNormalRelativePath(path: &[u8]) -> bool { |
| 40 | if path.len == 0 or path[path.len - 1] == '/' { |
| 41 | return false; |
| 42 | } |
| 43 | let mut start: u32 = 0; |
| 44 | for byte, i in path { |
| 45 | if byte == 0 { |
| 46 | return false; |
| 47 | } |
| 48 | if byte == '/' { |
| 49 | let part = &path[start .. i]; |
| 50 | if part.len == 0 or mem::eq(part, ".") or mem::eq(part, "..") { |
| 51 | return false; |
| 52 | } |
| 53 | set start = i + 1; |
| 54 | } |
| 55 | } |
| 56 | let part = &path[start ..]; |
| 57 | return not mem::eq(part, ".") and not mem::eq(part, ".."); |
| 58 | } |
| 59 | |
| 60 | /// Open the file at `path` for reading and return its descriptor. The host |
| 61 | /// open mode is 0 to read and 1 to create or truncate for writing. |
| 62 | export fn openRead(path: &[u8]) -> i64 throws (sys::Error) { |
| 63 | return try host::callPath(host::OPEN, path, 0, 0); |
| 64 | } |
| 65 | |
| 66 | /// Close a descriptor. Closing a standard descriptor is `Invalid`. |
| 67 | export fn close(fd: i64) throws (sys::Error) { |
| 68 | try host::call(host::CLOSE, fd, 0, 0, 0); |
| 69 | } |
| 70 | |
| 71 | /// Read from `fd` until end of file. Throws `TooLarge` when the data does not |
| 72 | /// fit in `buf`. |
| 73 | fn readAll(fd: i64, buf: &mut [u8]) -> u32 throws (sys::Error) { |
| 74 | let mut total: u32 = 0; |
| 75 | while total < buf.len { |
| 76 | let n = try host::read(fd, &mut buf[total ..]); |
| 77 | if n == 0 { |
| 78 | return total; |
| 79 | } |
| 80 | set total += n; |
| 81 | } |
| 82 | // The buffer is full. Any further byte does not fit. |
| 83 | let mut probe: [u8; 1] = [0; 1]; |
| 84 | if try host::read(fd, &mut probe[..]) <> 0 { |
| 85 | throw sys::Error::TooLarge; |
| 86 | } |
| 87 | return total; |
| 88 | } |
| 89 | |
| 90 | /// Read the file at `path` into `buf` and return the number of bytes read. |
| 91 | /// Throws `TooLarge` when the file does not fit. |
| 92 | export fn readFile(path: &[u8], buf: &mut [u8]) -> u32 throws (sys::Error) { |
| 93 | let fd = try openRead(path); |
| 94 | let n = try readAll(fd, buf) catch err { |
| 95 | try close(fd) catch {}; |
| 96 | throw err; |
| 97 | }; |
| 98 | try close(fd); |
| 99 | return n; |
| 100 | } |
| 101 | |
| 102 | /// Read a regular file into storage owned by `arena`. |
| 103 | /// The result has the recorded file size. A size that exceeds the remaining |
| 104 | /// arena space throws `TooLarge`. Other allocation failures throw `AllocError`. |
| 105 | /// The read must return the recorded number of bytes. |
| 106 | export fn readFileAlloc(path: *[u8], arena: &heap::Heap) -> *[u8] |
| 107 | throws (sys::Error, alloc::AllocError) |
| 108 | { |
| 109 | let info = try stat(path) else throw sys::Error::NotFound; |
| 110 | if info.kind <> Kind::File { |
| 111 | throw sys::Error::Invalid; |
| 112 | } |
| 113 | if info.size > heap::remaining(arena) as u64 { |
| 114 | throw sys::Error::TooLarge; |
| 115 | } |
| 116 | let size = info.size as u32; |
| 117 | let mut bytes: *mut [u8] = &mut []; |
| 118 | let fd = try openRead(path); |
| 119 | try readAllInto(fd, &mut bytes, size, arena) catch err as sys::Error { |
| 120 | try close(fd) catch {}; |
| 121 | throw err; |
| 122 | } catch err as alloc::AllocError { |
| 123 | try close(fd) catch {}; |
| 124 | throw err; |
| 125 | }; |
| 126 | try close(fd); |
| 127 | if bytes.len <> size { |
| 128 | throw sys::Error::Invalid; |
| 129 | } |
| 130 | return &bytes[..]; |
| 131 | } |
| 132 | |
| 133 | /// Append the data of `fd` up to end of file to `bytes`, in storage from |
| 134 | /// `arena`. Throws `TooLarge` when more than `limit` bytes remain. |
| 135 | fn readAllInto(fd: i64, bytes: &mut *mut [u8], limit: u32, arena: &heap::Heap) |
| 136 | throws (sys::Error, alloc::AllocError) |
| 137 | { |
| 138 | let mut remaining = limit; |
| 139 | while remaining > 0 { |
| 140 | let n = try host::readInto(fd, bytes, remaining, arena); |
| 141 | if n == 0 { |
| 142 | return; |
| 143 | } |
| 144 | set remaining -= n; |
| 145 | } |
| 146 | // The limit is reached. Any further byte does not fit. |
| 147 | let mut probe: [u8; 1] = [0; 1]; |
| 148 | if try host::read(fd, &mut probe[..]) <> 0 { |
| 149 | throw sys::Error::TooLarge; |
| 150 | } |
| 151 | } |
| 152 | |
| 153 | /// A file open for writing. Failures are remembered rather than reported by |
| 154 | /// each write. Call [`Writer::close`] exactly once: it releases the descriptor |
| 155 | /// and reports every failure of the writer. |
| 156 | export record Writer: Copy { |
| 157 | /// Host descriptor. |
| 158 | fd: i64, |
| 159 | /// First write failure. Later writes do nothing once it is set. |
| 160 | failure: ?sys::Error, |
| 161 | } |
| 162 | |
| 163 | /// Create the file at `path`, or truncate it when it exists, and open it for |
| 164 | /// writing. |
| 165 | export fn create(path: &[u8]) -> Writer throws (sys::Error) { |
| 166 | return Writer { fd: try host::callPath(host::OPEN, path, 1, 0), failure: nil }; |
| 167 | } |
| 168 | |
| 169 | /// Write all of `data` to the file. After a failure this does nothing; the |
| 170 | /// first failure is reported by `close`. |
| 171 | export fn (w: &mut Writer) write(data: &[u8]) { |
| 172 | let mut written: u32 = 0; |
| 173 | while w.failure == nil and written < data.len { |
| 174 | let n = try host::write(w.fd, &data[written ..]) catch err { |
| 175 | set w.failure = err; |
| 176 | return; |
| 177 | }; |
| 178 | if n == 0 { |
| 179 | set w.failure = sys::Error::Io; |
| 180 | return; |
| 181 | } |
| 182 | set written += n; |
| 183 | } |
| 184 | } |
| 185 | |
| 186 | /// Close the file. Always releases the descriptor. Throws the first write |
| 187 | /// failure if there was one, otherwise the failure to close, from which |
| 188 | /// buffered data may be lost. |
| 189 | export fn (w: &mut Writer) close() throws (sys::Error) { |
| 190 | let mut error = w.failure; |
| 191 | try close(w.fd) catch err { |
| 192 | if error == nil { |
| 193 | set error = err; |
| 194 | } |
| 195 | }; |
| 196 | if let first = error { |
| 197 | throw first; |
| 198 | } |
| 199 | } |
| 200 | |
| 201 | /// Write the parts in order to the file at `path`. Creates the file, or |
| 202 | /// truncates it when it exists. |
| 203 | export fn writeFileParts(path: &[u8], parts: &[*[u8]]) throws (sys::Error) { |
| 204 | let mut out = try create(path); |
| 205 | for part in parts { |
| 206 | out.write(part); |
| 207 | } |
| 208 | try out.close(); |
| 209 | } |
| 210 | |
| 211 | /// Write `data` to the file at `path`. Creates the file, or truncates it when |
| 212 | /// it exists. |
| 213 | export fn writeFile(path: &[u8], data: &[u8]) throws (sys::Error) { |
| 214 | let mut out = try create(path); |
| 215 | out.write(data); |
| 216 | try out.close(); |
| 217 | } |
| 218 | |
| 219 | /// Look up the entry at `path`. Returns `nil` when it does not exist. |
| 220 | export fn stat(path: &[u8]) -> ?Stat throws (sys::Error) { |
| 221 | let mut out: [u8; 16] = [0; 16]; |
| 222 | try host::callPath(host::STAT, path, host::addr(&out[..]), 0) catch err { |
| 223 | if err == sys::Error::NotFound { |
| 224 | return nil; |
| 225 | } |
| 226 | throw err; |
| 227 | }; |
| 228 | // The host `Stat` record is a 64-bit size, a 32-bit kind (1 file, 2 |
| 229 | // directory) and padding. |
| 230 | let code = mem::readLe(&out[..], 8, 4); |
| 231 | let mut kind = Kind::Other; |
| 232 | if code == 1 { |
| 233 | set kind = Kind::File; |
| 234 | } else if code == 2 { |
| 235 | set kind = Kind::Directory; |
| 236 | } |
| 237 | return Stat { size: mem::readLe(&out[..], 0, 8), kind }; |
| 238 | } |
| 239 | |
| 240 | /// Create the directory at `path`. Throws `Exists` when the path is taken. |
| 241 | export fn makeDir(path: &[u8]) throws (sys::Error) { |
| 242 | try host::callPath(host::MAKE_DIR, path, 0, 0); |
| 243 | } |
| 244 | |
| 245 | /// Create one directory or require the existing entry to be a directory. |
| 246 | fn requireDirectory(path: &[u8]) throws (sys::Error) { |
| 247 | try makeDir(path) catch error { |
| 248 | if error <> sys::Error::Exists { |
| 249 | throw error; |
| 250 | } |
| 251 | let info = try stat(path) else throw sys::Error::NotFound; |
| 252 | if info.kind <> Kind::Directory { |
| 253 | throw sys::Error::Invalid; |
| 254 | } |
| 255 | }; |
| 256 | } |
| 257 | |
| 258 | /// Create a directory and all missing parent directories. |
| 259 | /// Existing directories are accepted. An empty path requires no directories. |
| 260 | export fn createDirAll(path: &[u8]) throws (sys::Error) { |
| 261 | for byte, i in path { |
| 262 | if byte == '/' and i > 0 { |
| 263 | try requireDirectory(&path[.. i]); |
| 264 | } |
| 265 | } |
| 266 | if path.len > 0 { |
| 267 | try requireDirectory(path); |
| 268 | } |
| 269 | } |
| 270 | |
| 271 | /// Remove the file or empty directory at `path`. |
| 272 | export fn remove(path: &[u8]) throws (sys::Error) { |
| 273 | try host::callPath(host::REMOVE, path, 0, 0); |
| 274 | } |
| 275 | |
| 276 | /// Remove a file or directory tree. A missing path is already removed. |
| 277 | /// Symbolic links are removed as links. `arena` must be made with `heap::over`. |
| 278 | /// Each active directory uses at most `TREE_LIST_BYTES` of listing storage. |
| 279 | export fn removeTree(root: *[u8], arena: &heap::Heap) throws (sys::Error) { |
| 280 | try remove(root) catch error { |
| 281 | if error == sys::Error::NotFound { |
| 282 | return; |
| 283 | } |
| 284 | if error <> sys::Error::NotEmpty { |
| 285 | throw error; |
| 286 | } |
| 287 | let listing = try listDirAlloc(root, TREE_LIST_BYTES, arena) catch err as sys::Error { |
| 288 | throw err; |
| 289 | } catch err as alloc::AllocError { |
| 290 | throw sys::Error::TooLarge; |
| 291 | }; |
| 292 | let mut names = mem::split(listing, 0); |
| 293 | while let name = names.next() { |
| 294 | if not isNormalRelativePath(name) or mem::find(name, "/") <> nil { |
| 295 | throw sys::Error::Invalid; |
| 296 | } |
| 297 | let saved = heap::mark(arena); |
| 298 | let path = try alloc::concatBytes(arena, &[root, "/", name]) catch { |
| 299 | throw sys::Error::TooLarge; |
| 300 | }; |
| 301 | try removeTree(&path[..], arena); |
| 302 | // Child paths and listings are no longer live after removal. |
| 303 | unsafe { |
| 304 | heap::rewind(arena, saved); |
| 305 | } |
| 306 | } |
| 307 | try remove(root); |
| 308 | }; |
| 309 | } |
| 310 | |
| 311 | /// Rename `from` to `to`. An existing file at `to` is replaced. |
| 312 | export fn rename(from: &[u8], to: &[u8]) throws (sys::Error) { |
| 313 | try host::callPath(host::RENAME, from, host::addr(to), to.len as i64); |
| 314 | } |
| 315 | |
| 316 | /// Atomically swap two existing directory entries on the same filesystem. |
| 317 | export fn exchange(left: &[u8], right: &[u8]) throws (sys::Error) { |
| 318 | try host::callPath(host::EXCHANGE, left, host::addr(right), right.len as i64); |
| 319 | } |
| 320 | |
| 321 | /// List the directory at `path` into `buf`. Returns the names, each followed |
| 322 | /// by a zero byte, in host order, which `mem::split(names, 0)` iterates. Throws |
| 323 | /// `TooLarge` when they do not fit. |
| 324 | export fn listDir(path: &[u8], buf: *mut [u8]) -> *[u8] throws (sys::Error) { |
| 325 | let n = try host::callPath(host::LIST_DIR, path, host::addr(buf), buf.len as i64); |
| 326 | return &buf[.. n as u32]; |
| 327 | } |
| 328 | |
| 329 | /// List the directory at `path` as [`listDir`] does, into at most `capacity` |
| 330 | /// bytes of storage from `arena` that is not filled first. Throws `TooLarge` |
| 331 | /// when the names do not fit. |
| 332 | export fn listDirAlloc(path: &[u8], capacity: u32, arena: &heap::Heap) -> *[u8] |
| 333 | throws (sys::Error, alloc::AllocError) |
| 334 | { |
| 335 | let mut bytes: *mut [u8] = &mut []; |
| 336 | let args: [i64; 4] = [host::addr(path), path.len as i64, 0, 0]; |
| 337 | try host::callInto(host::LIST_DIR, args, 2, &mut bytes, capacity, arena); |
| 338 | return &bytes[..]; |
| 339 | } |