@ai-ecoverse/slicc-kernel 1.110.8 → 1.111.0

package/README.md

@@ -317,7 +317,7 @@ On top of preview1 a WASI program gets:
 - **Job control:** `^Z`, `SIGTSTP`, `SIGTTIN` and `SIGTTOU` stop a WASIX program at once, unless it has a handler for them. A stopped program that is busy computing is stopped for job control (`jobs` shows it, `fg`, `bg` and `SIGCONT` work), but its worker keeps a core busy until its next system call, since a worker's running code cannot be frozen from outside. Agents should `kill` such a job rather than leave it stopped. An Emscripten program stops at its next kernel call as well, and at its next write, read or sleep that its glue answers without the kernel (a write to its own `/dev/null`, as in `yes > /dev/null`), so a stopped one keeps no core busy unless it computes without any of these calls. A stopped program doesn't move on while stopped: a `sleep` (or a blocked read) that would end meanwhile ends after `SIGCONT`. A call that the stop interrupted runs again after `SIGCONT`, as on Linux. One with a timeout (`select`, `poll`, `ppoll`, `pselect`, `nanosleep`, a timed semaphore wait) waits only for the time that's left, counted from when the kernel first got the call, so it still ends at its deadline. `epoll_wait` and `epoll_pwait` aren't run again: they fail with `EINTR`, even without a handler (signal(7)). A signal for such a program is also delivered at those glue-answered calls, so a handler runs in a loop that only writes to `/dev/null`. For the same reason, a signal with a handler or a terminating default (`^C`, `SIGTERM`) reaches a program that is busy computing only at its next system call, so a CPU-bound loop may not end on `^C`; `kill -9` always ends it. A pending signal is delivered at the program's next WASI or WASIX call, including the calls its worker answers without the kernel (`random_get`, `args_get`, …), except the exempt ones: `clock_time_get` (a tight loop of it measured up to 30% slower), `proc_exit`, `proc_exit2`, `thread_exit`, `thread_spawn_v2` and `wasi.thread-spawn` (wasi-threads), the calls that install handlers (`callback_signal`, `slicc.sigaction_set`), and calls made while Asyncify unwinds or rewinds the stack for `fork` or `longjmp`. A signal that arrives while a thread computes is thus delivered at its next call; when that call is a wait (`poll_oneoff` with a timeout or a descriptor, so `nanosleep` and `poll`/`select` too, `sigmask_poll`, or a futex wait), the handler has run during the call, so the wait ends at once: `EINTR` for a libc of -22 or later (an older one sees its clocks fire, as for any interruption), and a futex wait returns woken. A thread blocked in the kernel or waiting on a lock (`pthread_cond_wait`, a futex) is woken by a signal for it (a futex wait checks for signals every 50 ms, so each waiting thread wakes briefly that often), and `pthread_kill` runs the handler on the thread it names. A sleep, or a clock in `poll_oneoff`, never ends before the time asked (it can end later, never earlier). A signal that ends a sleep or a `poll`/`select` with a timeout makes the call fail with `EINTR` in a program whose libc says it is wasix-sysroot 2025.9.30-22 or later (its `slicc.libc` custom section). Older libcs turn that answer into `ENOTSUP` from `nanosleep` (up to -18), so for a program without the section the wait ends as if it had timed out, unless it imports `fd_fdflags_set` (then `EINTR`, as before).
 - **Blocked signals** (`sigprocmask`, `pthread_sigmask`, `sigpending`): a program whose libc imports `slicc.sigmask_set(how, set_lo, set_hi, old_ptr)` and `slicc.sigpending_get(ptr)` (wasix-sysroot 2025.9.30-28 and later) has a blocked mask per thread. `how` is musl's `SIG_BLOCK` 0, `SIG_UNBLOCK` 1 or `SIG_SETMASK` 2, the set is the 64-bit `sigset_t` (bit `sig - 1`), and the old mask is written as a u64 at `old_ptr`; any other `how` is `EINVAL`. `SIGKILL` and `SIGSTOP` cannot be blocked. A blocked signal is not delivered, does not interrupt a sleep or a blocked call, and its default action (terminate or stop) waits: it stays pending, `sigpending` shows it (the thread's pending signals and the process's), and it is delivered when it is unblocked, before `sigmask_set` returns. A signal ignored with `SIG_IGN` is discarded even while blocked. A forked child (with the mask of the thread that forked), the program an `exec` starts and a spawned child keep the mask, all 64 bits of it, and so does a new thread; `/proc/<pid>/status` shows the main thread's as `SigBlk`. The mask is kept in a word of the worker's shared header, so changing it costs no kernel call. A program without the import (an older libc) has no mask and gets every signal at once, as before, and one it starts by `exec` with a mask set starts with none. A signal for the whole process goes to the main thread, unless the main thread blocks it and another thread does not. Then, as on Linux, it goes to that thread: its handler runs there, or with no handler its default action ends (or stops) the whole process at once. So the "signal thread" pattern works: block in main, unblock in a worker (#520). It waits on the main thread only when every thread blocks it. A signal sent to one thread (`pthread_kill`) that it blocks waits for that thread, and if it has no handler, the thread's unblock ends the whole process by the signal, whatever the other threads block. `slicc.sigmask_poll(set_lo, set_hi, in_ptr, out_ptr, nsubscriptions, nevents_ptr)` is `pselect`, `ppoll` and `sigsuspend`: it swaps the thread's mask to the given set for the call and puts the old one back before it returns. It delivers a pending signal the new mask unblocks, without polling, or polls as `poll_oneoff` does, under the new mask, so a signal it unblocks interrupts the wait with no window between the swap and the wait; with no subscriptions it waits until a signal is delivered. An interrupted call returns `EINTR` with no events, after the handler has run. `slicc.sigmask_epoll_wait(set_lo, set_hi, epfd, events_ptr, maxevents, timeout_ns, nevents_ptr)` is `epoll_pwait` (#771). It swaps the thread's mask to the given set in the same way. A pending signal the new mask unblocks runs its handler and makes the call return `EINTR` with no events, without waiting. Otherwise the call waits exactly as `wasix_32v1.epoll_wait` with the same arguments does (the same event layout and errors; a `timeout_ns` of all bits set is forever, 0 doesn't wait), under the new mask, so a signal it unblocks ends the wait with `EINTR` after the handler. The old mask is back before the call returns, on every path, and `*nevents_ptr` is always written. A kernel without it answers `ENOSYS`, and the libc keeps its non-atomic swap around `epoll_wait`. For both masked waits, a signal that came while the program computed and was delivered as the call began (its handler ran under the old mask, as on Linux, where it would have run before the call) ends the call with `EINTR` only if the new mask leaves it unblocked; when the new mask blocks every signal delivered then, the call waits as if none had come (#799). `slicc.sigwait(set_lo, set_hi, timeout_ns, sig_ptr)` is `sigwait`, `sigwaitinfo` and `sigtimedwait` (#520). If a signal of the set is pending for the thread, or else for the process, it takes it: the lowest-numbered first, with no handler run. It writes the number as a `u32` at `sig_ptr` and returns 0. Otherwise it waits until one is pending. `timeout_ns` of all bits set is forever and 0 doesn't wait; when the time runs out it answers `EAGAIN` (`*sig_ptr = 0`). A signal outside the set that the thread has unblocked and handles runs its handler and ends the call with `EINTR` (also one that came while the program computed and was delivered as the call began, as for the other waits), and so does a job-control stop, once continued. While a thread waits, the kernel counts it as able to take the signals of its set: a process-directed signal that every thread blocks goes to it (the main thread first, if it is the one waiting), so the signal-thread pattern works with `sigwait` too. Only kernel signals 1 to 31 can be waited for. A kernel without it answers `ENOSYS`. `slicc.sigaction_inherited(ign_ptr)` (#820) writes, as a little-endian `u64` at `ign_ptr`, the signals the program arrived with set to `SIG_IGN`, inherited across `exec` or spawn (bit `sig - 1`; never `SIGKILL` or `SIGSTOP`; kernel signals are 1 to 31, so the high word is 0), and returns 0. A libc calls it once before constructors and `main` and seeds its `sigaction` table with `SIG_IGN` for each bit, so `sigaction(sig, NULL, &old)` reads an inherited ignore back (wasix-sysroot 2025.9.30-32 and later); a kernel without it answers `ENOSYS`, and the libc keeps its defaults. Handlers are never inherited. **SIGCHLD:** with `SIGCHLD` set to `SIG_IGN` (by the program, or inherited), or with `SA_NOCLDWAIT` in the flags `slicc.sigaction_set` gets for `SIGCHLD`, an exited child is reaped at once and never stays a zombie: `waitpid` for it is `ECHILD`, and `wait` blocks until every child has exited, then fails with `ECHILD`, as on Linux. `SIGCHLD` is still sent. An explicit `SIG_DFL` turns it back off. A child that a process waits on for `exec`, or that `kernel.run` and the run calls collect, is never reaped that way.
 - **Pipes** have no file type for WASI and WASIX programs' `fstat` (`st_mode` type 0), because WASI has no FIFO file type. A socket type, as kernels 1.47.3 to 1.48.1 gave them, made Ruby treat a `popen` pipe as a socket (`close_write` then never ends the child's input). The kernel's `slicc_fs.fd_mode` answers `S_IFIFO | 0600` (Linux numbering) for a pipe, and wasix-sysroot 2025.9.30-21 and later take the type from it, so programs built on it see a FIFO (`S_ISFIFO`); older libcs keep only the permission bits. Until then Python's asyncio refuses a pipe for a subprocess (`Pipe transport is only for pipes, sockets and character devices`). They are read and written as pipes; socket calls on them fail with `ENOTSOCK`, and `isatty()` is false. Emscripten programs, bash included, see a FIFO. The same holds for any kernel descriptor that is neither seekable nor a terminal or device, such as captured output.
-- **Sockets**: the WASIX socket calls (`sock_open`, `sock_pair` for an `AF_UNIX` stream pair, `bind`, `listen`, `connect`, `accept`, options, local and peer names) are the kernel's loopback sockets, and preview1's `sock_recv` / `sock_send` / `sock_shutdown` work on them and on inherited ones. Writing to a socket whose peer is gone fails with `EPIPE`, through `fd_write` as through `sock_send`, as if `MSG_NOSIGNAL` were set. A write to a pipe, FIFO or terminal whose reader is gone follows the program's `SIGPIPE` disposition, as the kernel knows it (#810): at the default it ends the program with status 141; ignored (also an ignore inherited across `exec` and spawn, as bash's `trap '' PIPE` passes on), the write fails with `EPIPE`; with a handler, the handler runs on the thread that wrote and then the write fails with `EPIPE` (#820); blocked, `SIGPIPE` stays pending and the write fails with `EPIPE`. An Emscripten program's write to a pipe, and its `send` without `MSG_NOSIGNAL`, follow the same rules, except that the kernel doesn't see an Emscripten program's signal mask, so a blocked `SIGPIPE` there still ends it. A WASI program asking `sigaction` about an inherited ignore still sees the default, since its libc keeps its own table. HTTP and HTTPS leave through the realm proxy that `https_proxy` names, as for any other program; `resolve` answers `/etc/hosts` names and literal addresses, and the [uplink](#uplink)'s names. `sock_open(SOCK_DGRAM)` on `AF_INET`/`AF_INET6` gives a [datagram socket](#datagram-sockets-udp); `sock_send_to` and `sock_recv_from` carry its addresses, and `RECV_DATA_TRUNCATED` is set in `ro_flags` when a datagram did not fit.
+- **Sockets**: the WASIX socket calls (`sock_open`, `sock_pair` for an `AF_UNIX` stream or datagram pair, `bind`, `listen`, `connect`, `accept`, options, local and peer names) are the kernel's loopback sockets, and preview1's `sock_recv` / `sock_send` / `sock_shutdown` work on them and on inherited ones. Writing to a socket whose peer is gone fails with `EPIPE`, through `fd_write` as through `sock_send`, as if `MSG_NOSIGNAL` were set. A write to a pipe, FIFO or terminal whose reader is gone follows the program's `SIGPIPE` disposition, as the kernel knows it (#810): at the default it ends the program with status 141; ignored (also an ignore inherited across `exec` and spawn, as bash's `trap '' PIPE` passes on), the write fails with `EPIPE`; with a handler, the handler runs on the thread that wrote and then the write fails with `EPIPE` (#820); blocked, `SIGPIPE` stays pending and the write fails with `EPIPE`. An Emscripten program's write to a pipe, and its `send` without `MSG_NOSIGNAL`, follow the same rules, except that the kernel doesn't see an Emscripten program's signal mask, so a blocked `SIGPIPE` there still ends it. A WASI program asking `sigaction` about an inherited ignore still sees the default, since its libc keeps its own table. HTTP and HTTPS leave through the realm proxy that `https_proxy` names, as for any other program; `resolve` answers `/etc/hosts` names and literal addresses, and the [uplink](#uplink)'s names. `sock_open(SOCK_DGRAM)` on `AF_INET`/`AF_INET6` gives a [datagram socket](#datagram-sockets-udp); `sock_send_to` and `sock_recv_from` carry its addresses, and `RECV_DATA_TRUNCATED` is set in `ro_flags` when a datagram did not fit.
 - **Diagnostics**: a trap ends the program with 134 and its message on stderr; with `SLICC_WASM_BACKTRACE=1` the wasm frames follow, named from the module's name section, or from a sidecar for a module shipped without one (`<module>.names` beside it, or the same path in a `<package>-names` package). `SLICC_WASI_STATS=1` makes a program print its calls, counted and timed, as it ends.
 
 ### Program imports
@@ -398,7 +398,7 @@ await kernel.run(['curl', '-sS', 'https://registry.npmjs.org/@ai-ecoverse/wasm-b
 
 #### Datagram sockets (UDP)
 
-WASIX programs get `AF_INET`/`AF_INET6` `SOCK_DGRAM` sockets (`AF_UNIX` datagrams are `EPROTONOSUPPORT`). They are kernel descriptors like stream sockets: they survive `dup`, `fork` and `exec`, and work with `select`, `poll`, WASIX epoll and `fstat` (`SOCK_DGRAM`).
+WASIX programs get `AF_INET`/`AF_INET6` `SOCK_DGRAM` sockets, and `AF_UNIX` ones (see below). They are kernel descriptors like stream sockets: they survive `dup`, `fork` and `exec`, and work with `select`, `poll`, WASIX epoll and `fstat` (`SOCK_DGRAM`).
 - **Addresses:** `bind` follows the stream rules: loopback or `0.0.0.0`/`::`, port `0` for an ephemeral port, the kernel's reserved ports refused (`EADDRINUSE`), any other address `EADDRNOTAVAIL`. The first send binds an unbound socket. UDP and TCP ports are separate.
 - **Where a datagram goes** is decided as for a TCP `connect`, by the same route table: loopback (`127.0.0.0/8`, `::1`, `0.0.0.0`) is delivered inside the kernel, an address the uplink routes goes through `uplink.udp` when `traits.udp` is set, and everything else is `ENETUNREACH`: `host.slicc.internal`, link-local (`169.254.0.0/16`, so the metadata service too), reserved, multicast and broadcast (`224.0.0.0/4`, `240.0.0.0/4`, `255.255.255.255`, `ff00::/8`), with or without an uplink; an unspecified destination (`0.0.0.0`, `::`) is the kernel's loopback, as for TCP. Such a datagram never reaches the uplink.
 - **One datagram per call:** `recv`/`read` returns one datagram, and a buffer that is too short gets its first bytes and loses the rest. `MSG_PEEK` leaves it queued. A datagram is at most 65 507 bytes (65 527 to an IPv6 address); a larger send is `EMSGSIZE`. A send with no address on an unconnected socket is `EDESTADDRREQ`.
@@ -417,6 +417,14 @@ WASIX programs get `AF_INET`/`AF_INET6` `SOCK_DGRAM` sockets (`AF_UNIX` datagram
 - **The host machine** is `host.slicc.internal` (`SLICC_HOST_LOOPBACK`), as `host.docker.internal` is in Docker, while `localhost` and `127.0.0.1` stay the kernel's own loopback. The proxy forwards `http(s)://host.slicc.internal:<port>/…` to the transport as `http(s)://127.0.0.1:<port>/…`, so it reaches the real machine's loopback through the local proxy or Node's `fetch` (through the page's own `fetch`, a request needs CORS from that server and Chrome's Local Network Access permission); other loopback addresses are still refused. This is HTTP and HTTPS through the proxy only: `/etc/hosts` and WASIX name resolution give the name `10.0.2.2`, QEMU's address for its host, so a program that connects a socket to it directly fails with `ENETUNREACH` instead of reaching the kernel's loopback.
 - **Without a transport**, every request is answered `502` with `slicc-kernel: no network transport (createKernel({ network: { transport } }))`.
 
+**`AF_UNIX` datagram sockets** ([#891](https://github.com/ai-ecoverse/slicc-kernel/issues/891)), for syslog-style logging and `sd_notify`-style readiness:
+- **Binding:** `bind` to a path creates a socket file, with the same owner and permission checks as a stream socket. The directory must be writable. The file stays after `close`, until something unlinks it. An abstract name (`\0…`) binds without a file.
+- **Sending:** `sendto(path)` needs write permission on the socket file. One send is one message. `recvfrom` returns it whole (or truncated, with `MSG_TRUNC`, to the buffer), with the sender's bound path as the address, or an empty path for an unbound or socketpair sender.
+- **Connecting:** `connect(path)` sets the default destination for `send`/`write`. A receiver that is connected to another socket refuses everyone else's datagrams with `EPERM`. `socketpair(AF_UNIX, SOCK_DGRAM)` gives two connected, unnamed sockets.
+- **Errors:** a missing path is `ENOENT`, a file no datagram socket is bound to is `ECONNREFUSED`, a stream socket's path is `EPROTOTYPE` (both ways), and a taken path is `EADDRINUSE`.
+- **Flow control:** a receiver queue holds 512 messages or 256 KiB. A full one blocks a sender, or fails a non-blocking send with `EAGAIN`, as on Linux.
+- **Not supported:** passing descriptors or credentials (`SCM_RIGHTS`, `SCM_CREDENTIALS`) over datagrams, and `AF_UNIX` datagrams for Emscripten and JS programs.
+
 ### Node name
 
 The kernel has one node name, `slicc` unless `createKernel({ hostname })` (or `createNodeKernel`) names another; it must be a valid host name, and not `localhost`, a `*.localhost` name, `host.slicc.internal`, `wasmer.sh` or an IPv4 address, or `createKernel` rejects. `no_proxy` lists it (and `emscripten`), so HTTP clients reach the kernel's own servers by it directly.