cranelift/docs/WASI-some-possible-changes.md

# Possible changes

The following are a list of relatively straightforward changes
to WASI core that should be considered.

## Split file/networking/random/clock from args/environ/exit.

Currently everything is mixed together in one big "core" module. But we can
split them out to allow minimal configurations that don't support this style
of files and networking.

## Move higher-level and unused errno codes out of the core API.

The core API currently defines errno codes such as `EDOM` which are
not used for anything. POSIX requires them to be defined, however
that can be done in the higher-level libraries, rather than in the
WASI core API itself.

## Detecting EOF from read/recv explicitly.

POSIX's `read` returns 0 if and only if it reaches the end of a file or stream.

Say you have a read buffer of 1024 bytes, and are reading a file that happens
to be 7 bytes long. The first `read` call will return 7, but unless you happen
to know how big the file is supposed to be, you can't distinguish between
that being all there is, and `read` getting interrupted and returning less
data than you requested.

Many applications today do an extra `read` when they encounter the end of a
file, to ensure that they get a `read` that returns 0 bytes read, to confirm
that they've reached the end of the file. If `read` instead had a way to
indicate that it had reached the end, this extra call wouldn't be necessary.

And, `read` on a socket is almost equivalent to `recv` with no flags -- except for
one surprising special case: on a datagram socket, if there's a zero-length
datagram, `read` can't consume it, while `recv` can. This is because `read` can't
indicate that it successfully read 0 bytes, because it has overloaded the meaning
of 0 to indicate eof-of-file.

So, it would be tidier from multiple perspectives if `read` could indicate
that it had reached the end of a file or stream, independently of how many
bytes it has read.

## Merging read and recv

These are very similar, and differ only in subtle ways. It'd make the API
easier to understand if they were unified.

## Trap instead of returning EFAULT

POSIX system calls return EFAULT when given invalid pointers, however from an
application perspective, it'd be more natural for them to just segfault.

## More detailed capability error reporting

Replace `__WASI_ENOTCAPABLE` with error codes that indicate *which* capabilities
were required but not present.

## Split `__wasi_path_open` into `__wasi_path_open_file` and `__wasi_path_open_directory`?

We could also split `__WASI_RIGHT_PATH_OPEN` into file vs directory,
(obviating `__WASI_O_DIRECTORY`).

## Fix the y2556 bug

In some places, timestamps are measured in nanoseconds since the UNIX epoch,
so our calculations indicate a 64-bit counter will overflow on
Sunday, July 21, 2554, at 11:34:33 pm UTC.

These timestamps aren't used in that many places, so it wouldn't cost that
much to widen these timestamps. We can either just extend the current type to
128 bits (two i64's in wasm) or move to a `timespec`-like `tv_sec`/`tv_nsec`
pair.

## Remove `fd_allocate`?

Darwin doesn't implement `fd_allocate`, despite it being a in POSIX
since 2001. So we don't currently know any way to implement `fd_allocate`
on Darwin that's safe from race conditions. Should we remove it from the API?

## Redesign `fstflags_t`

The relationship between `*_SET_*TIM` and `*_SET_*TIM_NOW` is non-obvious.
We should look at this again.

## readdir

Truncating entries that don't fit into a buffer may be error-prone. Should
we redesign how directory reading works?

## symlinks

Symlinks are fairly UNIX-specific. Should we remove `__wasi_path_symlink`
and `__wasi_path_readlink`?

Also, symlink resolution doesn't benefit from libpreopen-style path
translation. Should we move symlink resolution into the libpreopen layer
and do it entirely in "userspace"?

## Remove the `path_len` argument from `__wasi_fd_prestat_dir_name`

The buffer should be sized to the length returned from `__wasi_fd_prestat_get`,
so it's not necessary to pass the length back into the runtime.

## Add a `__wasi_path_filestat_set_size` function?

Along with libc/libpreopen support, this would enable implementing the
POSIX `truncate` function.

## errno values returned by `path_open`

We should specify the errno value returned when `path_open` is told
to open a directory and `__WASI_LOOKUP_SYMLINK_FOLLOW` isn't set, and
the path refers to a symbolic link.