fs.cpp

#include "sys.h"
#include "handle.h"
#include <openkal/fs.h>
#include <openkal/memory.h>

namespace okl { extern char** g_envp; }

namespace {


// The directories this implementation supplies. A hosted system does not
// confine an ordinary program, so it supplies both the working directory and
// the whole file system; an implementation that confined a program would
// supply fewer, and the program could not tell the difference except by
// finding that a directory it wanted was absent.
//
// The working directory is reported under the name the environment knows it
// by, which is its absolute path rather than ".". A C library above openkal
// must both resolve an absolute path and report one, and a name of "." leaves
// it able to do only the first.
struct preopen { const char* name; kal_uintptr len; okl_uptr handle; };

char g_cwd[4096];

constexpr kal_uintptr kMaxGrants = 16;

// THE DIRECTORIES A STARTER GRANTED, WHEN THE PROGRAM WAS STARTED WITH GRANTS.
//
// They arrive as descriptors at 3 and upward, and their names in the variable
// `kal_process_spawn' writes (see `vector::build_env' in process.cpp):
//
//     KAL_PREOPENS=<pid>{;<fd>,<len>,<name>}
//
// The value is read only when `<pid>' is this process, so one inherited through
// a program that does not read it is not mistaken for a grant. A descriptor that
// is not a directory is reported as a preopen this program may not use, which is
// how an entry that could not be opened is reported anyway. Each descriptor is
// marked to close on replacement as it is taken over, so that a grant reaches
// the program it was made to and not that program's own children (SPEC.md
// clause 7.13). The names point into the environment, which lives as long as
// the program does.
//
// Answers false when there is no such value, which leaves the directories this
// implementation supplies by default.
bool granted(preopen* t, kal_uintptr* n) {
    constexpr char key[] = "KAL_PREOPENS=";
    constexpr okl_uptr key_len = sizeof key - 1;
    const char* v = nullptr;
    for (char** e = okl::g_envp; e && *e; ++e) {
        okl_uptr i = 0;
        while (i < key_len && (*e)[i] == key[i]) ++i;
        if (i == key_len) { v = *e + key_len; break; }
    }
    if (v == nullptr) return false;

    auto number = [&](okl_uptr& out) {
        if (*v < '0' || *v > '9') return false;
        out = 0;
        while (*v >= '0' && *v <= '9') out = out * 10 + static_cast<okl_uptr>(*v++ - '0');
        return true;
    };
    okl_uptr pid = 0;
    if (!number(pid) || static_cast<okl_long>(pid) != okl::sys(okl::nr_getpid)) return false;

    kal_uintptr k = 0;
    while (*v == ';' && k < kMaxGrants) {
        ++v;
        okl_uptr fd = 0, len = 0;
        if (!number(fd) || *v++ != ',' || !number(len) || *v++ != ',') return false;
        for (okl_uptr i = 0; i < len; ++i) if (v[i] == '\0') return false;

        okl::kstat st{};
        const bool dir = !okl::failed(okl::sys(okl::nr_fstat, static_cast<okl_long>(fd),
                                               reinterpret_cast<okl_long>(&st)))
                      && (st.mode & okl::s_ifmt) == okl::s_ifdir;
        if (dir) okl::sys(okl::nr_fcntl, static_cast<okl_long>(fd), okl::f_setfd, okl::fd_cloexec);
        t[k++] = { v, len, dir ? okl::pack(static_cast<int>(fd)) : 0u };
        v += len;
    }
    if (*v != '\0') return false;
    *n = k;
    return true;
}

// A DIRECTORY HANDLE NAMES A DIRECTORY; IT DOES NOT READ ONE (0.18.3).
//
// Every `kal_dir' is a base: names are resolved beneath it (`*at'), a program
// is started in it (`fchdir'), and it is described (`fstat', `fstatfs'). None
// of these reads the directory, and `O_PATH' is the open that asks for no
// access but naming. Reading happens only where entries are listed, and an
// enumeration already opens a descriptor of its own through the handle, with
// read access, at that moment.
//
// Until 0.18.2 the handles were opened for reading, and a directory the
// program may search but not read could not be a base at all. Measured on
// Android 14 under `run-as' (SELinux domain `runas_app', mcpp#857): the
// preopen of `/' failed with EACCES, so every name resolved beneath the root,
// and every program started by absolute name, failed before anything was
// started --- reported as "not found", because the base it would have been
// found in was never opened. The same program, its directory and its exec
// path all worked when each step was called directly.
constexpr okl_long dir_handle_flags = okl::o_path | okl::o_directory | okl::o_cloexec;

preopen* table(kal_uintptr* count) {
    static preopen t[kMaxGrants];
    static kal_uintptr n = 2;
    static bool opened = false;
    if (!opened) {
        opened = true;
        if (granted(t, &n)) { if (count) *count = n; return t; }
        n = 2;

        const okl_long n = okl::sys(okl::nr_getcwd, reinterpret_cast<okl_long>(g_cwd),
                                    static_cast<okl_long>(sizeof g_cwd));
        // getcwd reports the length including the terminator, and reports a
        // failure when the directory has been removed. A program whose working
        // directory no longer has a name still has the directory, so the
        // handle is opened either way and only the name falls back.
        okl_uptr cwd_len = 0;
        if (!okl::failed(n) && n > 1) cwd_len = static_cast<okl_uptr>(n) - 1;
        else { g_cwd[0] = '.'; g_cwd[1] = '\0'; cwd_len = 1; }

        const okl_long fd0 = okl::sys(okl::nr_openat, okl::at_fdcwd,
                                      reinterpret_cast<okl_long>("."), dir_handle_flags, 0);
        const okl_long fd1 = okl::sys(okl::nr_openat, okl::at_fdcwd,
                                      reinterpret_cast<okl_long>("/"), dir_handle_flags, 0);
        t[0] = { g_cwd, cwd_len, okl::failed(fd0) ? 0u : okl::pack(static_cast<int>(fd0)) };
        t[1] = { "/",   1,       okl::failed(fd1) ? 0u : okl::pack(static_cast<int>(fd1)) };
    }
    if (count) *count = n;
    return t;
}

int kind_of(okl_u32 mode) {
    switch (mode & okl::s_ifmt) {
        case okl::s_ifreg: return kal_node_file;
        case okl::s_ifdir: return kal_node_directory;
        case okl::s_iflnk: return kal_node_link;
        default:           return kal_node_other;
    }
}

// The properties of the volume a descriptor is on. kal_fs_props answers with
// this, and so does the one field of an enquiry that is a volume's property.
kal_uintptr volume_props(int fd) {
    // LOCKS AND CAPACITY ARE IN THE CONSERVATIVE SET, and that is a claim
    // about this kernel rather than about the volume: an open-file lock and
    // `fstatfs' are answered by the VFS for every format beneath it, including
    // the read-only ones --- a lock excludes writers a read-only volume does not
    // have, which is a true answer and not a useful one. A format that could not
    // would have to be excluded by name here, and this kernel has none.
    const kal_uintptr conservative =
        KAL_FS_PROP_MODIFIED_TIME | KAL_FS_PROP_ATOMIC_RENAME
        | KAL_FS_PROP_LOCKS | KAL_FS_PROP_CAPACITY;
    // A NAME HELD OPEN IS REMOVED AT ONCE (0.17, clause 7.14) on every format
    // whose names the VFS itself keeps: `unlink' drops the entry and the inode
    // lives on until its last descriptor closes. Not in the conservative set,
    // because a format the VFS does not keep may not: a network volume's client
    // renames a held file to a hidden name and removes it at the close, and a
    // user-space format may do the same, so the directory is not empty.
    const kal_uintptr local = conservative | KAL_FS_PROP_REMOVE_OPEN;
    if (fd < 0) return 0;

    okl::kstatfs sf{};
    const okl_long r = okl::sys(okl::nr_fstatfs, fd, reinterpret_cast<okl_long>(&sf));
    if (okl::failed(r)) return conservative;

    switch (sf.f_type) {
        // Formats with a case-sensitive namespace and nodes that name others.
        //
        // A rename that does not replace (0.17) is `renameat2' with
        // RENAME_NOREPLACE, which each of these formats implements except the
        // one whose support arrived late and is not known from its type; a
        // socket bound to a name (0.17, KAL_FS_PROP_LOCAL_ENDPOINT) is a node
        // every one of them stores.
        case okl::fs_ext234: case okl::fs_btrfs: case okl::fs_xfs:
        case okl::fs_f2fs:   case okl::fs_tmpfs: case okl::fs_overlay:
        case okl::fs_bcachefs:
            return local | KAL_FS_PROP_CASE_SENSITIVE
                 | KAL_FS_PROP_LINKS | KAL_FS_PROP_MAKE_LINKS
                 | KAL_FS_PROP_EXECUTABLE
                 | KAL_FS_PROP_RENAME_NO_REPLACE | KAL_FS_PROP_LOCAL_ENDPOINT;
        case okl::fs_zfs:
            return local | KAL_FS_PROP_CASE_SENSITIVE
                 | KAL_FS_PROP_LINKS | KAL_FS_PROP_MAKE_LINKS
                 | KAL_FS_PROP_EXECUTABLE | KAL_FS_PROP_LOCAL_ENDPOINT;

        // Read-only formats: the nodes are there and none can be made, and a
        // rename cannot be atomic because there is no rename.
        case okl::fs_squashfs: case okl::fs_erofs:
            return KAL_FS_PROP_MODIFIED_TIME | KAL_FS_PROP_CASE_SENSITIVE
                 | KAL_FS_PROP_LINKS | KAL_FS_PROP_LOCKS | KAL_FS_PROP_CAPACITY
                 | KAL_FS_PROP_EXECUTABLE;
        case okl::fs_iso9660:
            return KAL_FS_PROP_MODIFIED_TIME | KAL_FS_PROP_CASE_SENSITIVE
                 | KAL_FS_PROP_LOCKS | KAL_FS_PROP_CAPACITY;

        // The FAT family stores neither a case distinction nor a node that
        // names another. `symlink' on such a volume reports EPERM, and this is
        // where a caller learns that before it tries.
        case okl::fs_msdos: case okl::fs_exfat:
            return local;

        // A case-insensitive namespace, with nodes that name others.
        case okl::fs_ntfs: case okl::fs_ntfs3:
            return local | KAL_FS_PROP_LINKS | KAL_FS_PROP_MAKE_LINKS;
        // The same, on a format that stores a mode.
        case okl::fs_hfsplus:
            return local | KAL_FS_PROP_LINKS | KAL_FS_PROP_MAKE_LINKS
                 | KAL_FS_PROP_EXECUTABLE;

        default:
            return conservative;
    }
}

}  // namespace (reopened below)

namespace okl {
// The volume's properties, for the interfaces outside this file that ask one
// (openkal.net's rendezvous at a name).
kal_uintptr volume_props_of(int fd) { return volume_props(fd); }
}  // namespace okl

namespace {

// Writes no more of the structure than the caller says exists on its side, and
// reports which fields it filled.
//
// EVERY FIELD IS FILLED AND `wanted' IS IGNORED, WHICH IS THE ONE LINE THE
// SPECIFICATION SAYS THIS SHOULD BE. One `newfstatat' answers all of them on
// this kernel, so selecting would cost a branch and save nothing. An
// implementation whose environment answers them separately is the one `wanted'
// exists for.
//
// The exception is KAL_INFO_EXECUTABLE, which is a property of the volume as
// well as of the node: a format that stores no mode reports execute bits the
// mount chose, and reporting those would be answering for the volume. The
// volume is asked only when the caller wants the field, and only for a file.
void fill_info(const okl::kstat& st, kal_u32 wanted, kal_node_info* out,
               int volume_fd) {
    const kal_u32 self = out->self_size;
    kal_node_info v{};
    v.self_size   = self;
    v.present     = KAL_INFO_ALL & ~KAL_INFO_EXECUTABLE;
    v.size        = static_cast<kal_u64>(st.size);
    v.modified_ns = static_cast<kal_u64>(st.mtime_sec) * 1000000000u
                  + static_cast<kal_u64>(st.mtime_nsec);
    // The identity is the pair the kernel already keeps. It is opaque to a
    // caller, which may compare it and may not read it; using the device and
    // the inode is this kernel's answer and not the interface's shape.
    v.identity[0] = st.dev;
    v.identity[1] = st.ino;
    v.kind        = kind_of(st.mode);
    v.writable    = (st.mode & 0200u) != 0 ? 1 : 0;

    // A caller whose structure ends before the field is not given the position.
    const kal_u32 reaches = static_cast<kal_u32>(
        __builtin_offsetof(kal_node_info, executable) + sizeof v.executable);
    if ((wanted & KAL_INFO_EXECUTABLE) != 0 && self >= reaches
        && v.kind == kal_node_file
        && (volume_props(volume_fd) & KAL_FS_PROP_EXECUTABLE) != 0) {
        v.present   |= KAL_INFO_EXECUTABLE;
        v.executable = (st.mode & 0111u) != 0 ? 1 : 0;
    }

    const kal_u32 n = self < sizeof v ? self : (kal_u32)sizeof v;
    okl::copy(reinterpret_cast<char*>(out), reinterpret_cast<const char*>(&v), n);
}

// A node that refers to nothing, in the same shape.
void fill_absent(kal_node_info* out) {
    const kal_u32 self = out->self_size;
    kal_node_info v{};
    v.self_size = self;
    v.present   = KAL_INFO_KIND;
    v.kind      = kal_node_absent;
    const kal_u32 n = self < sizeof v ? self : (kal_u32)sizeof v;
    okl::copy(reinterpret_cast<char*>(out), reinterpret_cast<const char*>(&v), n);
}

// The caller must state how much of the structure exists on its side. A
// consumer that did not is a consumer whose structure this cannot be.
bool info_ok(const kal_node_info* out) {
    return out != nullptr && out->self_size >= sizeof(kal_u32) * 2;
}

// Copies a name into a caller's buffer and reports the length it HAS.
kal_uintptr put_name(const char* src, kal_uintptr n,
                     char* out, kal_uintptr cap, kal_uintptr* len) {
    if (out != nullptr && cap != 0) okl::copy(out, src, n < cap ? n : cap);
    if (len) *len = n;
    return n;
}

// Enumeration reads the kernel's own directory records. A C library's
// directory stream is not used, for the reason src/sys.h gives: the C library
// in a program above this one may be the one this implementation would be
// calling.
struct listing {
    int      fd;
    int      dir;      // the descriptor of the directory it was begun upon
    listing* next;
    int      busy;     // a context is inside kal_fs_list_next with it
    int      doomed;   // its directory was closed while it was busy
    okl_uptr used;
    okl_uptr pos;
    char     buf[8192];
};

// THE ENUMERATIONS NOT YET READ TO THE END, BECAUSE CLOSING THE DIRECTORY MUST
// END THEM. fs.h releases an iterator "by reading past the end or by closing
// the directory that produced it", and the descriptor a listing holds is its
// own, so closing the directory's descriptor does not reach it. Measured before
// this list existed: a C library above that opened a directory larger than its
// buffer, read one entry and closed it, 64 times, was left holding 64 more
// descriptors.
//
// The lock spins rather than suspends, because suspending would make openkal.fs
// depend upon openkal.task, as src/memory.cpp says of its own.
listing*     g_listings = nullptr;
volatile int g_listings_held = 0;

void listings_lock() {
    while (__atomic_exchange_n(&g_listings_held, 1, __ATOMIC_ACQUIRE)) okl::sys(okl::nr_sched_yield);
}
void listings_unlock() { __atomic_store_n(&g_listings_held, 0, __ATOMIC_RELEASE); }

void listing_release(listing* s) {
    okl::sys(okl::nr_close, s->fd);
    kal_free(s, sizeof(listing), alignof(listing));
}

// Ends every listing begun upon `dir'. What is ended is unlinked under the lock
// and released after it.
//
// A LISTING ANOTHER CONTEXT IS READING IS NOT RELEASED HERE. Clause 6.6 requires
// that concurrent operations upon one handle not damage this implementation's
// state, and releasing the buffer a getdents64 in another context is writing
// into would do exactly that. Such a listing is marked, and the context reading
// it releases it on the way out; it can no longer be found, so nothing reaches
// it after that.
void listings_end(int dir) {
    listing* done = nullptr;
    listings_lock();
    for (listing** p = &g_listings; *p != nullptr;) {
        listing* s = *p;
        if (s->dir != dir || s->doomed) { p = &s->next; continue; }
        if (s->busy) { s->doomed = 1; p = &s->next; continue; }
        *p = s->next; s->next = done; done = s;
    }
    listings_unlock();
    while (done != nullptr) { listing* s = done; done = s->next; listing_release(s); }
}

// Takes `s' for the calling context, or reports that it is not a listing of
// `dir' that is still open.
//
// THE WORD IS FOUND RATHER THAN BELIEVED. An iterator is the caller's copy of an
// address this implementation allocated, and closing its directory frees what
// it named --- so a caller that kept it, or that raced the close, holds an
// address that may by now be anything. Searching the open listings for it is
// what lets kal_fs_list_next refuse such a word without reading through it. The
// search is over enumerations not yet read to their end, which a program holds
// a handful of.
bool listing_take(listing* s, int dir) {
    for (;;) {
        listings_lock();
        listing* p = g_listings;
        while (p != nullptr && p != s) p = p->next;
        if (p == nullptr || p->dir != dir || p->doomed) { listings_unlock(); return false; }
        if (!p->busy) { p->busy = 1; listings_unlock(); return true; }
        // Two contexts reading one enumeration take turns; the order in which
        // they receive its entries is the unspecified order clause 6.6 permits.
        listings_unlock();
        okl::sys(okl::nr_sched_yield);
    }
}

// Gives `s' back, and releases it if it reached its end or its directory was
// closed while it was being read.
void listing_give(listing* s, bool ended) {
    listings_lock();
    s->busy = 0;
    const bool release = ended || s->doomed;
    if (release) {
        for (listing** p = &g_listings; *p != nullptr; p = &(*p)->next)
            if (*p == s) { *p = s->next; break; }
    }
    listings_unlock();
    if (release) listing_release(s);
}

}  // namespace

extern "C" {

kal_uintptr kal_fs_preopen_count(void) {
    kal_uintptr n = 0; table(&n); return n;
}

int kal_fs_preopen(kal_uintptr index, kal_dir* out,
                   char* name_out, kal_uintptr name_cap, kal_uintptr* name_len) {
    kal_uintptr n = 0;
    preopen* t = table(&n);
    if (index >= n || out == nullptr) return kal_err_invalid;
    if (t[index].handle == 0) return kal_err_permission;
    *out = kal_dir{ t[index].handle };
    put_name(t[index].name, t[index].len, name_out, name_cap, name_len);
    return kal_ok;
}

int kal_fs_open_dir(kal_dir base, const char* name, kal_uintptr len, kal_dir* out) {
    const int b = okl::unpack(base.h);
    if (b < 0 || out == nullptr || !okl::acceptable(name, len)) return kal_err_invalid;
    okl::terminated t(name, len); if (!t.ok) return kal_err_invalid;
    const okl_long fd = okl::sys(okl::nr_openat, b, reinterpret_cast<okl_long>(t.buf),
                                 dir_handle_flags, 0);
    if (okl::failed(fd)) return okl::translate(fd);
    *out = kal_dir{ okl::pack(static_cast<int>(fd)) };
    return kal_ok;
}

int kal_fs_open(kal_dir base, const char* name, kal_uintptr len,
                kal_uintptr flags, kal_file* out) {
    const int b = okl::unpack(base.h);
    if (b < 0 || out == nullptr || !okl::acceptable(name, len)) return kal_err_invalid;
    okl::terminated t(name, len); if (!t.ok) return kal_err_invalid;

    const bool r = (flags & KAL_OPEN_READ)  != 0;
    const bool w = (flags & KAL_OPEN_WRITE) != 0;
    okl_long f = w ? (r ? okl::o_rdwr : okl::o_wronly) : okl::o_rdonly;
    f |= okl::o_cloexec;
    if (flags & KAL_OPEN_CREATE)    f |= okl::o_creat;
    if (flags & KAL_OPEN_EXCLUSIVE) f |= okl::o_excl;
    if (flags & KAL_OPEN_TRUNCATE)  f |= okl::o_trunc;
    if (flags & KAL_OPEN_APPEND)    f |= okl::o_append;

    const okl_long fd = okl::sys(okl::nr_openat, b, reinterpret_cast<okl_long>(t.buf), f, 0666);
    if (okl::failed(fd)) return okl::translate(fd);
    *out = kal_file{ okl::pack(static_cast<int>(fd)) };
    return kal_ok;
}

void kal_fs_close_dir(kal_dir d) {
    const int fd = okl::unpack(d.h);
    if (fd < 0) return;
    // Before the close, because after it the number may already name another
    // directory whose enumerations are not this one's.
    listings_end(fd);
    okl::retire(d.h); okl::sys(okl::nr_close, fd);
}

void kal_fs_close_file(kal_file f) {
    const int fd = okl::unpack(f.h);
    if (fd >= 0) { okl::retire(f.h); okl::sys(okl::nr_close, fd); }
}

// A file's stream is the file. The descriptor is what openkal.stream's handle
// holds on this implementation, so no conversion is required and none is
// performed: the two interfaces agree because both are descriptor-shaped here,
// which is a property of this implementation and not of the specification.
kal_stream kal_fs_stream(kal_file f) {
    const int fd = okl::unpack(f.h);
    return kal_stream{ fd < 0 ? 0u : static_cast<kal_uintptr>(fd) };
}

// The greatest length of a name this implementation accepts.
kal_uintptr kal_fs_max_name(void) { return okl::max_name; }

int kal_fs_seek(kal_file f, kal_i64 offset, int whence, kal_u64* result) {
    const int fd = okl::unpack(f.h);
    if (fd < 0) return kal_err_invalid;
    int w = 0;
    if (whence == KAL_SEEK_CURRENT) w = 1;
    else if (whence == KAL_SEEK_END) w = 2;
    const okl_long r = okl::sys(okl::nr_lseek, fd, static_cast<okl_long>(offset), w);
    if (okl::failed(r)) return okl::translate(r);
    if (result) *result = static_cast<kal_u64>(r);
    return kal_ok;
}

int kal_fs_truncate(kal_file f, kal_u64 size) {
    const int fd = okl::unpack(f.h);
    if (fd < 0) return kal_err_invalid;
    const okl_long r = okl::sys(okl::nr_ftruncate, fd, static_cast<okl_long>(size));
    return okl::failed(r) ? okl::translate(r) : kal_ok;
}

int kal_fs_info(kal_dir base, const char* name, kal_uintptr len,
                kal_uintptr flags, kal_u32 wanted, kal_node_info* out) {
    const int b = okl::unpack(base.h);
    if (b < 0 || !info_ok(out) || !okl::acceptable(name, len)) return kal_err_invalid;
    okl::terminated t(name, len); if (!t.ok) return kal_err_invalid;
    okl::kstat st{};
    // RESOLVES BY DEFAULT, SO THAT ASKING AND OPENING ANSWER THE SAME QUESTION.
    //
    // This implementation asked with AT_SYMLINK_NOFOLLOW always while
    // `kal_fs_open' resolved, so a name referring to a node whose content is
    // another name was reported as that node while opening it reached a file.
    // A C library above reported a link where the host reports a regular file,
    // and one symbolic link made a whole tree uncopyable.
    const okl_long at = (flags & KAL_FS_NO_RESOLVE) ? okl::at_symlink_nofollow : 0;
    const okl_long r = okl::sys(okl::nr_newfstatat, b, reinterpret_cast<okl_long>(t.buf),
                                reinterpret_cast<okl_long>(&st), at);
    if (okl::failed(r)) {
        // Clause 7.7: enquiry about a name that does not exist is answered,
        // not refused. A component of the name that is not a directory is the
        // same answer, because the name still refers to nothing --- and so is a
        // node whose content names something absent, when the enquiry resolves.
        if (r == -okl::e_noent || r == -okl::e_notdir || r == -okl::e_loop) {
            fill_absent(out);
            return kal_ok;
        }
        return okl::translate(r);
    }
    fill_info(st, wanted, out, b);
    return kal_ok;
}

int kal_fs_file_info(kal_file f, kal_u32 wanted, kal_node_info* out) {
    const int fd = okl::unpack(f.h);
    if (fd < 0 || !info_ok(out)) return kal_err_invalid;
    okl::kstat st{};
    const okl_long r = okl::sys(okl::nr_fstat, fd, reinterpret_cast<okl_long>(&st));
    if (okl::failed(r)) return okl::translate(r);
    fill_info(st, wanted, out, fd);
    return kal_ok;
}

int kal_fs_set_modified(kal_file f, kal_u64 modified_ns) {
    const int fd = okl::unpack(f.h);
    if (fd < 0) return kal_err_invalid;
    // The kernel's operation takes two times and this interface names one, so
    // the other is given the value that means "leave it alone". Setting the
    // access time to the value openkal did not ask about would be an effect the
    // caller did not request and could not have predicted.
    constexpr okl_i64 utime_omit = 0x3ffffffe;
    okl::ktimespec times[2];
    times[0].sec = 0;  times[0].nsec = utime_omit;
    times[1].sec = static_cast<okl_i64>(modified_ns / 1000000000u);
    times[1].nsec = static_cast<okl_i64>(modified_ns % 1000000000u);
    // A null name and a descriptor is this kernel's spelling of "the open file
    // itself" rather than "a name beneath it".
    const okl_long r = okl::sys(okl::nr_utimensat, fd, 0,
                                reinterpret_cast<okl_long>(times), 0);
    return okl::failed(r) ? okl::translate(r) : kal_ok;
}

// The same, upon a NAME. Version 0.10.
//
// ADDED BECAUSE THE FORM ABOVE CANNOT REACH A DIRECTORY, AND A CONSUMER
// PAID FOR THAT. `kal_fs_set_modified' takes a `kal_file'; a directory is opened
// as a `kal_dir'; there was no third thing. openkal-musl reached a lock
// directory's timestamp by opening the directory for READING and setting the
// time on that, which worked here and was outside anything the interface said.
// This is the stated route.
int kal_fs_set_modified_at(kal_dir base, const char* name, kal_uintptr len,
                           kal_u64 modified_ns) {
    const int b = okl::unpack(base.h);
    if (b < 0 || !okl::acceptable(name, len)) return kal_err_invalid;
    okl::terminated t(name, len); if (!t.ok) return kal_err_invalid;

    constexpr okl_i64 utime_omit = 0x3ffffffe;
    okl::ktimespec times[2];
    times[0].sec = 0;  times[0].nsec = utime_omit;
    times[1].sec  = static_cast<okl_i64>(modified_ns / 1000000000u);
    times[1].nsec = static_cast<okl_i64>(modified_ns % 1000000000u);

    // Resolves, because opening resolves and this is stated to agree with it.
    const okl_long r = okl::sys(okl::nr_utimensat, b,
                                reinterpret_cast<okl_long>(t.buf),
                                reinterpret_cast<okl_long>(times), 0);
    return okl::failed(r) ? okl::translate(r) : kal_ok;
}

// Whether a node may be started, version 0.13. This kernel stores the property
// as three bits, one per class of caller; the interface states one property,
// so a class that may read the node may start it, and clearing clears all
// three. Nothing else about the mode changes.
int kal_fs_set_executable_at(kal_dir base, const char* name, kal_uintptr len,
                             int executable) {
    const int b = okl::unpack(base.h);
    if (b < 0 || !okl::acceptable(name, len)) return kal_err_invalid;
    okl::terminated t(name, len); if (!t.ok) return kal_err_invalid;
    if ((volume_props(b) & KAL_FS_PROP_EXECUTABLE) == 0) return kal_err_not_supported;

    okl::kstat st{};
    okl_long r = okl::sys(okl::nr_newfstatat, b, reinterpret_cast<okl_long>(t.buf),
                          reinterpret_cast<okl_long>(&st), 0);
    if (okl::failed(r)) return okl::translate(r);
    const int k = kind_of(st.mode);
    if (k == kal_node_directory) return kal_err_is_directory;
    if (k != kal_node_file) return kal_err_invalid;

    const unsigned mode = static_cast<unsigned>(st.mode) & 07777u;
    const unsigned next = executable != 0 ? (mode | ((mode & 0444u) >> 2))
                                          : (mode & ~0111u);
    if (next == mode) return kal_ok;
    // Resolves, as the enquiry above did, so the node changed is the node read.
    r = okl::sys(okl::nr_fchmodat, b, reinterpret_cast<okl_long>(t.buf),
                 static_cast<okl_long>(next));
    return okl::failed(r) ? okl::translate(r) : kal_ok;
}

int kal_fs_mkdir(kal_dir base, const char* name, kal_uintptr len) {
    const int b = okl::unpack(base.h);
    if (b < 0 || !okl::acceptable(name, len)) return kal_err_invalid;
    okl::terminated t(name, len); if (!t.ok) return kal_err_invalid;
    const okl_long r = okl::sys(okl::nr_mkdirat, b, reinterpret_cast<okl_long>(t.buf), 0777);
    return okl::failed(r) ? okl::translate(r) : kal_ok;
}

int kal_fs_remove(kal_dir base, const char* name, kal_uintptr len) {
    const int b = okl::unpack(base.h);
    if (b < 0 || !okl::acceptable(name, len)) return kal_err_invalid;
    okl::terminated t(name, len); if (!t.ok) return kal_err_invalid;
    okl_long r = okl::sys(okl::nr_unlinkat, b, reinterpret_cast<okl_long>(t.buf), 0);
    if (!okl::failed(r)) return kal_ok;
    // One operation removes a name, and the kernel distinguishes two kinds of
    // name where this interface does not.
    if (r == -okl::e_isdir || r == -okl::e_perm) {
        const okl_long d = okl::sys(okl::nr_unlinkat, b, reinterpret_cast<okl_long>(t.buf),
                                    okl::at_removedir);
        if (!okl::failed(d)) return kal_ok;
        r = d;
    }
    return okl::translate(r);
}

int kal_fs_rename(kal_dir from, const char* a, kal_uintptr alen,
                  kal_dir to,   const char* b, kal_uintptr blen) {
    const int f = okl::unpack(from.h), t2 = okl::unpack(to.h);
    if (f < 0 || t2 < 0 || !okl::acceptable(a, alen) || !okl::acceptable(b, blen)) return kal_err_invalid;
    okl::terminated ta(a, alen), tb(b, blen);
    if (!ta.ok || !tb.ok) return kal_err_invalid;
    const okl_long r = okl::sys(okl::nr_renameat, f, reinterpret_cast<okl_long>(ta.buf),
                                t2, reinterpret_cast<okl_long>(tb.buf));
    return okl::failed(r) ? okl::translate(r) : kal_ok;
}

// A RENAME THAT DOES NOT REPLACE (0.17) is the kernel's own: `renameat2' with
// RENAME_NOREPLACE tests and renames in one act. A format that does not
// implement the flag answers EINVAL, and a kernel before 3.15 ENOSYS; both are
// a volume that cannot, which `kal_fs_props' answers before the call for the
// formats this file knows.
int kal_fs_rename_flags(kal_dir from, const char* a, kal_uintptr alen,
                        kal_dir to,   const char* b, kal_uintptr blen,
                        kal_uintptr flags) {
    if ((flags & ~static_cast<kal_uintptr>(KAL_RENAME_NO_REPLACE)) != 0) return kal_err_invalid;
    if (flags == 0) return kal_fs_rename(from, a, alen, to, b, blen);
    const int f = okl::unpack(from.h), t2 = okl::unpack(to.h);
    if (f < 0 || t2 < 0 || !okl::acceptable(a, alen) || !okl::acceptable(b, blen)) return kal_err_invalid;
    if ((volume_props(t2) & KAL_FS_PROP_RENAME_NO_REPLACE) == 0) return kal_err_not_supported;
    okl::terminated ta(a, alen), tb(b, blen);
    if (!ta.ok || !tb.ok) return kal_err_invalid;
    const okl_long r = okl::sys(okl::nr_renameat2, f, reinterpret_cast<okl_long>(ta.buf),
                                t2, reinterpret_cast<okl_long>(tb.buf), 1 /* RENAME_NOREPLACE */);
    if (r == -okl::e_inval || r == -okl::e_nosys) return kal_err_not_supported;
    return okl::failed(r) ? okl::translate(r) : kal_ok;
}

// Enumeration holds a descriptor of its own, obtained by opening the directory
// through itself. A duplicate would share the file offset with the handle the
// caller holds, so two enumerations of one directory would consume each
// other's entries.
int kal_fs_list_begin(kal_dir d, kal_uintptr* iter) {
    const int fd = okl::unpack(d.h);
    if (fd < 0 || iter == nullptr) return kal_err_invalid;
    const okl_long own = okl::sys(okl::nr_openat, fd, reinterpret_cast<okl_long>("."),
                                  okl::o_rdonly | okl::o_directory | okl::o_cloexec, 0);
    if (okl::failed(own)) return okl::translate(own);
    auto* s = static_cast<listing*>(kal_alloc(sizeof(listing), alignof(listing)));
    if (s == nullptr) { okl::sys(okl::nr_close, own); return kal_err_no_memory; }
    s->fd = static_cast<int>(own); s->dir = fd; s->busy = 0; s->doomed = 0;
    s->used = 0; s->pos = 0;
    listings_lock(); s->next = g_listings; g_listings = s; listings_unlock();
    *iter = reinterpret_cast<kal_uintptr>(s);
    return kal_ok;
}

int kal_fs_list_next(kal_dir d, kal_uintptr* iter,
                     char* name_out, kal_uintptr name_cap,
                     kal_uintptr* name_len, int* kind) {
    // A CLOSED DIRECTORY IS A RELEASED HANDLE (clause 6.7), and closing it
    // released the iterator too, which fs.h states. Both are refused here
    // without the iterator being read through.
    const int fd = okl::unpack(d.h);
    if (fd < 0 || iter == nullptr || *iter == 0) return kal_err_invalid;
    auto* s = reinterpret_cast<listing*>(*iter);
    if (!listing_take(s, fd)) return kal_err_invalid;
    for (;;) {
        if (s->pos >= s->used) {
            const okl_long r = okl::sys(okl::nr_getdents64, s->fd,
                                        reinterpret_cast<okl_long>(s->buf),
                                        static_cast<okl_long>(sizeof s->buf));
            if (okl::interrupted(r)) continue;
            if (okl::failed(r) || r == 0) {
                listing_give(s, true);
                *iter = 0;
                if (name_len) *name_len = 0;
                return okl::failed(r) ? okl::translate(r) : kal_ok;
            }
            s->used = static_cast<okl_uptr>(r);
            s->pos  = 0;
        }
        auto* e = reinterpret_cast<okl::kdirent64*>(s->buf + s->pos);
        s->pos += e->reclen;
        // The two entries that name the directory and its parent are omitted.
        // They exist to support ascent, which this interface does not offer.
        if (e->name[0] == '.' && (e->name[1] == '\0'
            || (e->name[1] == '.' && e->name[2] == '\0'))) continue;
        put_name(e->name, okl::length(e->name), name_out, name_cap, name_len);
        if (kind) *kind = e->type == okl::dt_dir ? kal_node_directory
                        : e->type == okl::dt_reg ? kal_node_file
                        : e->type == okl::dt_lnk ? kal_node_link : kal_node_other;
        listing_give(s, false);
        return kal_ok;
    }
}

// The properties of the volume a directory is on.
//
// AN ENQUIRY TAKING THE RESOURCE, BECAUSE EVERY POSITION IS A PROPERTY OF THE
// FORMAT. Version 0.6 answered with one word per implementation and claimed
// case sensitivity in it unconditionally --- which is false on any machine that
// has a FAT volume mounted, and this implementation offers the whole filesystem
// as a preopen, so such a volume is reachable through it. It also never claimed
// links, while every operation here met them.
//
// What is claimed for a format this implementation does not recognise is the
// set that cannot be wrong: the kernel reports a modification time for every
// filesystem it mounts, and `renameat' within one directory is atomic by POSIX.
// Case sensitivity and links are claimed only where the format is known to have
// them.
kal_uintptr kal_fs_props(kal_dir d) {
    return volume_props(okl::unpack(d.h));
}

// --- exclusion upon a range of a file --------------------------------------
//
// THE OPEN-FILE FORM, AND THE DIFFERENCE IS THE WHOLE REASON THIS IS
// WORTH SPECIFYING.
//
// This kernel's oldest record lock is held by the PROCESS and is released as
// soon as that process closes ANY descriptor for the node --- so a library that
// opened one file twice destroyed its own lock, and two parts of one program
// could not exclude each other at all. openkal states that the holder is the
// `kal_file', which is exactly what `F_OFD_*' describes: the lock belongs to the
// open file description and ends when the last descriptor for it closes, and
// when the program ends however it ends.
//
// Releasing on death is the half a caller cannot build for itself. Exclusion
// it can: `KAL_OPEN_EXCLUSIVE' and a name beside the file. What nothing above
// this line can do is release that name when its holder dies, so a program that
// ended abnormally while holding one would be locked out of its own file for
// ever.
static int lock_range(kal_file f, kal_u64 start, kal_u64 len,
                      short type, bool wait) {
    const int fd = okl::unpack(f.h);
    if (fd < 0) return kal_err_invalid;

    okl::kflock fl{};
    fl.l_type   = type;
    fl.l_whence = okl::seek_set;
    fl.l_start  = static_cast<okl_i64>(start);
    // openkal spells "to the end, however far that comes to be" as zero, and so
    // does this kernel. The two agree, so nothing is translated.
    fl.l_len    = static_cast<okl_i64>(len);

    const okl_long cmd = wait ? okl::f_ofd_setlkw : okl::f_ofd_setlk;
    okl_long r;
    do {
        r = okl::sys(okl::nr_fcntl, fd, cmd, reinterpret_cast<okl_long>(&fl));
    } while (okl::interrupted(r));
    if (!okl::failed(r)) return kal_ok;

    // TWO VALUES MEAN ONE THING HERE, AND openkal NAMES ONE OF THEM.
    //
    // The standard this call comes from says a range another holder has is
    // reported as EITHER of two values, and leaves the choice to the system ---
    // so a caller must accept both and an implementation of openkal must not
    // pass that choice on. openkal says `kal_err_again', which is the answer a
    // caller polls upon; the other value translates to `permission', which a
    // caller reads as "asking again will not help" and acts upon by stopping.
    //
    // Narrowed to the attempt that does NOT wait, because that is the only
    // one for which the two values carry this meaning. A permission failure on
    // any other path keeps its own answer.
    if (!wait && (-r == okl::e_acces || -r == okl::e_again)) return kal_err_again;
    return okl::translate(r);
}

int kal_fs_lock(kal_file f, kal_u64 start, kal_u64 len, kal_uintptr mode) {
    const bool shared    = (mode & KAL_LOCK_SHARED)    != 0;
    const bool exclusive = (mode & KAL_LOCK_EXCLUSIVE) != 0;
    // One of the two, and not both and not neither: a caller that asked for
    // both asked for something no environment has, and one that asked for
    // neither did not say what it wanted.
    if (shared == exclusive) return kal_err_invalid;
    return lock_range(f, start, len,
                      shared ? okl::lock_read : okl::lock_write,
                      (mode & KAL_LOCK_WAIT) != 0);
}

int kal_fs_unlock(kal_file f, kal_u64 start, kal_u64 len) {
    // Never waits: releasing is not a request another holder can block.
    return lock_range(f, start, len, okl::lock_unlock, false);
}

// --- how much the volume holds ----------------------------------------------
int kal_fs_capacity(kal_dir d, kal_u64* total, kal_u64* available) {
    const int fd = okl::unpack(d.h);
    if (fd < 0) return kal_err_invalid;

    okl::kstatfs sf{};
    const okl_long r = okl::sys(okl::nr_fstatfs, fd, reinterpret_cast<okl_long>(&sf));
    if (okl::failed(r)) return okl::translate(r);

    // In bytes, because that is what the interface says and what a caller of it
    // wants; this kernel reports blocks and the size of one.
    const kal_u64 unit = static_cast<kal_u64>(sf.f_bsize);
    // `f_bavail' AND NOT `f_bfree'. The second counts blocks the volume has,
    // including those only a privileged writer may reach; the first counts the
    // ones THIS program could actually use, which is the question asked.
    if (total)     *total     = static_cast<kal_u64>(sf.f_blocks) * unit;
    if (available) *available = static_cast<kal_u64>(sf.f_bavail) * unit;
    return kal_ok;
}

// Nodes whose content is another name.
int kal_fs_link_create(kal_dir base, const char* name, kal_uintptr len,
                       const char* target, kal_uintptr target_len,
                       kal_uintptr flags) {
    // The target is not a name this interface resolves: it is content, stored
    // and interpreted by whoever follows it later. It is therefore not passed
    // through `acceptable', which would refuse a target that ascends --- and a
    // target that ascends is the ordinary case for a relative one.
    (void)flags;   // this kernel does not distinguish a link to a directory
    const int b = okl::unpack(base.h);
    if (b < 0 || !okl::acceptable(name, len) || target == nullptr) return kal_err_invalid;
    okl::terminated n(name, len);        if (!n.ok) return kal_err_invalid;
    okl::terminated tgt(target, target_len); if (!tgt.ok) return kal_err_invalid;
    const okl_long r = okl::sys(okl::nr_symlinkat, reinterpret_cast<okl_long>(tgt.buf),
                                b, reinterpret_cast<okl_long>(n.buf));
    return okl::failed(r) ? okl::translate(r) : kal_ok;
}

kal_intptr kal_fs_link_read(kal_dir base, const char* name, kal_uintptr len,
                            char* out, kal_uintptr cap) {
    const int b = okl::unpack(base.h);
    if (b < 0 || !okl::acceptable(name, len)) return -kal_err_invalid;
    okl::terminated t(name, len); if (!t.ok) return -kal_err_invalid;

    // The kernel truncates into the buffer it is given and does not report the
    // length the content has, so a caller asking for the length --- a capacity
    // of zero --- is served from a buffer of this implementation's own.
    char own[okl::max_name + 1];
    char* dst = (out != nullptr && cap != 0) ? out : own;
    okl_uptr room = (out != nullptr && cap != 0) ? cap : sizeof own;
    okl_long r = okl::sys(okl::nr_readlinkat, b, reinterpret_cast<okl_long>(t.buf),
                          reinterpret_cast<okl_long>(dst), static_cast<okl_long>(room));
    if (okl::failed(r)) return -okl::translate(r);

    // A result equal to the room given may have been truncated. Asking again
    // with room of this implementation's own is what turns "at least this" into
    // "this", and it is the only way this kernel offers.
    if (static_cast<okl_uptr>(r) == room && room < sizeof own) {
        const okl_long full = okl::sys(okl::nr_readlinkat, b,
                                       reinterpret_cast<okl_long>(t.buf),
                                       reinterpret_cast<okl_long>(own),
                                       static_cast<okl_long>(sizeof own));
        if (!okl::failed(full)) r = full;
    }
    return static_cast<kal_intptr>(r);
}

}