lib/std/fs.rad 11.0 KiB 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
}