Improve cancellations, randomness, and time

- Exhaustively document cancellation points
- Rename SIGCANCEL to SIGTHR just like BSDs
- Further improve POSIX thread cancellations
- Ensure asynchronous cancellations work correctly
- Elevate the quality of getrandom() and getentropy()
- Make futexes cancel correctly on OpenBSD 6.x and 7.x
- Add reboot.com and shutdown.com to examples directory
- Remove underscore prefix from awesome timespec_*() APIs
- Create assertions that help verify our cancellation points
- Remove bad timespec APIs (cmp generalizes eq/ne/gt/gte/lt/lte)

libc/stdio/dirstream.c

@@ -255,6 +255,8 @@ static textwindows dontinline struct dirent *readdir_nt(DIR *dir) {
  *
  * @returns newly allocated DIR object, or NULL w/ errno
  * @errors ENOENT, ENOTDIR, EACCES, EMFILE, ENFILE, ENOMEM
+ * @raise ECANCELED if thread was cancelled in masked mode
+ * @raise EINTR if we needed to block and a signal was delivered instead
  * @cancellationpoint
  * @see glob()
  */

libc/stdio/getentropy.c

@@ -17,20 +17,41 @@
 │ PERFORMANCE OF THIS SOFTWARE.                                                │
 ╚─────────────────────────────────────────────────────────────────────────────*/
 #include "libc/calls/blockcancel.internal.h"
+#include "libc/calls/blocksigs.internal.h"
+#include "libc/calls/syscall_support-sysv.internal.h"
+#include "libc/dce.h"
+#include "libc/intrin/asan.internal.h"
+#include "libc/intrin/strace.internal.h"
 #include "libc/stdio/rand.h"
 #include "libc/sysv/errfuns.h"
 
+int sys_getentropy(void *, size_t) asm("sys_getrandom");
+
 /**
  * Returns random seeding bytes, the XNU/OpenBSD way.
  *
  * @return 0 on success, or -1 w/ errno
- * @raise EIO if more than 256 bytes are requested
+ * @raise EFAULT if the `n` bytes at `p` aren't valid memory
+ * @raise EIO is returned if more than 256 bytes are requested
  * @see getrandom()
  */
-int getentropy(void *buf, size_t size) {
-  if (size > 256) return eio();
-  BLOCK_CANCELLATIONS;
-  if (getrandom(buf, size, 0) != size) notpossible;
-  ALLOW_CANCELLATIONS;
-  return 0;
+int getentropy(void *p, size_t n) {
+  int rc;
+  if (n > 256) {
+    rc = eio();
+  } else if ((!p && n) || (IsAsan() && !__asan_is_valid(p, n))) {
+    rc = efault();
+  } else if (IsXnu() || IsOpenbsd()) {
+    if (sys_getentropy(p, n)) notpossible;
+    rc = 0;
+  } else {
+    BLOCK_SIGNALS;
+    BLOCK_CANCELLATIONS;
+    if (__getrandom(p, n, 0) != n) notpossible;
+    ALLOW_CANCELLATIONS;
+    ALLOW_SIGNALS;
+    rc = 0;
+  }
+  STRACE("getentropy(%p, %'zu) → %'ld% m", p, n, rc);
+  return rc;
 }

libc/stdio/getrandom.c

@@ -16,15 +16,24 @@
 │ TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR             │
 │ PERFORMANCE OF THIS SOFTWARE.                                                │
 ╚─────────────────────────────────────────────────────────────────────────────*/
+#include "libc/assert.h"
+#include "libc/calls/blockcancel.internal.h"
 #include "libc/calls/calls.h"
+#include "libc/calls/cp.internal.h"
+#include "libc/calls/internal.h"
 #include "libc/calls/struct/sigaction.h"
 #include "libc/calls/struct/sigset.h"
 #include "libc/calls/syscall-sysv.internal.h"
 #include "libc/calls/syscall_support-nt.internal.h"
+#include "libc/calls/syscall_support-sysv.internal.h"
 #include "libc/dce.h"
 #include "libc/errno.h"
+#include "libc/intrin/asan.internal.h"
+#include "libc/intrin/asmflag.h"
 #include "libc/intrin/bits.h"
 #include "libc/intrin/strace.internal.h"
+#include "libc/intrin/weaken.h"
+#include "libc/macros.internal.h"
 #include "libc/nexgen32e/kcpuids.h"
 #include "libc/nexgen32e/rdtsc.h"
 #include "libc/nexgen32e/vendor.internal.h"
@@ -43,12 +52,120 @@
 #include "libc/sysv/errfuns.h"
 #include "libc/thread/thread.h"
 
+STATIC_YOINK("rdrand_init");
+
+int sys_getentropy(void *, size_t) asm("sys_getrandom");
+
 static bool have_getrandom;
 
-static ssize_t GetDevRandom(char *p, size_t n) {
+static bool GetRandomRdseed(uint64_t *out) {
+  int i;
+  char cf;
+  uint64_t x;
+  for (i = 0; i < 10; ++i) {
+    asm volatile(CFLAG_ASM("rdseed\t%1")
+                 : CFLAG_CONSTRAINT(cf), "=r"(x)
+                 : /* no inputs */
+                 : "cc");
+    if (cf) {
+      *out = x;
+      return true;
+    }
+    asm volatile("pause");
+  }
+  return false;
+}
+
+static bool GetRandomRdrand(uint64_t *out) {
+  int i;
+  char cf;
+  uint64_t x;
+  for (i = 0; i < 10; ++i) {
+    asm volatile(CFLAG_ASM("rdrand\t%1")
+                 : CFLAG_CONSTRAINT(cf), "=r"(x)
+                 : /* no inputs */
+                 : "cc");
+    if (cf) {
+      *out = x;
+      return true;
+    }
+    asm volatile("pause");
+  }
+  return false;
+}
+
+static ssize_t GetRandomCpu(char *p, size_t n, int f, bool impl(uint64_t *)) {
+  uint64_t x;
+  size_t i, j;
+  for (i = 0; i < n; i += j) {
+  TryAgain:
+    if (!impl(&x)) {
+      if (f || i >= 256) break;
+      goto TryAgain;
+    }
+    for (j = 0; j < 8 && i + j < n; ++j) {
+      p[i + j] = x;
+      x >>= 8;
+    }
+  }
+  return n;
+}
+
+static ssize_t GetRandomMetal(char *p, size_t n, int f) {
+  if (f & GRND_RANDOM) {
+    if (X86_HAVE(RDSEED)) {
+      return GetRandomCpu(p, n, f, GetRandomRdseed);
+    } else {
+      return enosys();
+    }
+  } else {
+    if (X86_HAVE(RDRND)) {
+      return GetRandomCpu(p, n, f, GetRandomRdrand);
+    } else {
+      return enosys();
+    }
+  }
+}
+
+static void GetRandomEntropy(char *p, size_t n) {
+  _unassert(n <= 256);
+  if (sys_getentropy(p, n)) notpossible;
+}
+
+static void GetRandomArnd(char *p, size_t n) {
+  size_t m;
+  int cmd[2];
+  cmd[0] = 1;                      // CTL_KERN
+  cmd[1] = IsFreebsd() ? 37 : 81;  // KERN_ARND
+  _unassert((m = n) <= 256);
+  if (sys_sysctl(cmd, 2, p, &n, 0, 0) == -1) notpossible;
+  if (m != n) notpossible;
+}
+
+static ssize_t GetRandomBsd(char *p, size_t n, void impl(char *, size_t)) {
+  errno_t e;
+  size_t m, i;
+  if (_weaken(pthread_testcancel_np) &&
+      (e = _weaken(pthread_testcancel_np)())) {
+    errno = e;
+    return -1;
+  }
+  for (i = 0;;) {
+    m = MIN(n - i, 256);
+    impl(p + i, m);
+    if ((i += m) == n) {
+      return n;
+    }
+    if (_weaken(pthread_testcancel)) {
+      _weaken(pthread_testcancel)();
+    }
+  }
+}
+
+static ssize_t GetDevUrandom(char *p, size_t n) {
   int fd;
   ssize_t rc;
-  fd = __sys_openat(AT_FDCWD, "/dev/urandom", O_RDONLY | O_CLOEXEC, 0);
+  fd = sys_openat(AT_FDCWD, "/dev/urandom", O_RDONLY | O_CLOEXEC, 0);
   if (fd == -1) return -1;
   pthread_cleanup_push((void *)sys_close, (void *)(intptr_t)fd);
   rc = sys_read(fd, p, n);
@@ -56,26 +173,29 @@ static ssize_t GetDevRandom(char *p, size_t n) {
   return rc;
 }
 
-static ssize_t GetKernArnd(char *p, size_t n) {
-  size_t m, i = 0;
-  int cmd[2];
-  if (IsFreebsd()) {
-    cmd[0] = 1;  /* CTL_KERN */
-    cmd[1] = 37; /* KERN_ARND */
-  } else {
-    cmd[0] = 1;  /* CTL_KERN */
-    cmd[1] = 81; /* KERN_ARND */
-  }
-  for (;;) {
-    m = n - i;
-    if (sys_sysctl(cmd, 2, p + i, &m, 0, 0) != -1) {
-      if ((i += m) == n) {
-        return n;
-      }
+ssize_t __getrandom(void *p, size_t n, unsigned f) {
+  ssize_t rc;
+  if (IsWindows()) {
+    if (_check_interrupts(true, 0)) return -1;
+    rc = RtlGenRandom(p, n) ? n : __winerr();
+  } else if (have_getrandom) {
+    if (IsXnu() || IsOpenbsd()) {
+      rc = GetRandomBsd(p, n, GetRandomEntropy);
     } else {
-      return i ? i : -1;
+      BEGIN_CANCELLATION_POINT;
+      rc = sys_getrandom(p, n, f);
+      END_CANCELLATION_POINT;
     }
+  } else if (IsFreebsd() || IsNetbsd()) {
+    rc = GetRandomBsd(p, n, GetRandomArnd);
+  } else if (IsMetal()) {
+    rc = GetRandomMetal(p, n, f);
+  } else {
+    BEGIN_CANCELLATION_POINT;
+    rc = GetDevUrandom(p, n);
+    END_CANCELLATION_POINT;
   }
+  return rc;
 }
 
 /**
@@ -83,27 +203,47 @@ static ssize_t GetKernArnd(char *p, size_t n) {
  *
  * This random number seed generator obtains information from:
  *
- * - getrandom() on Linux
  * - RtlGenRandom() on Windows
  * - getentropy() on XNU and OpenBSD
- * - sysctl(KERN_ARND) on FreeBSD and NetBSD
+ * - getrandom() on Linux, FreeBSD, and NetBSD
+ * - sysctl(KERN_ARND) on older versions of FreeBSD and NetBSD
  *
- * The following flags may be specified:
+ * Unlike getentropy() this function is interruptible. However EINTR
+ * shouldn't be possible if `f` is zero and `n` is no more than 256,
+ * noting that kernels are a bit vague with their promises here, and
+ * if you're willing to trade some performance for a more assurances
+ * that EINTR won't happen, then either consider using getentropy(),
+ * or using the `SA_RESTART` flag on your signal handlers.
  *
- * - `GRND_RANDOM`: Halt the entire system while I tap an entropy pool
- *   so small that it's hard to use statistics to test if it's random
- * - `GRND_NONBLOCK`: Do not wait for i/o events or me to jiggle my
- *   mouse, and instead return immediately the moment data isn't
- *   available, even if the result needs to be -1 w/ EAGAIN
+ * Unlike getentropy() you may specify an `n` greater than 256. When
+ * larger amounts are specified, the caller must be prepared for the
+ * case where fewer than `n` bytes are returned. In that case, it is
+ * likely that a signal delivery occured. Cancellations in mask mode
+ * also need to be suppressed while processing the bytes beyond 256.
+ * On BSD OSes, this entire process is uninterruptible so be careful
+ * when using large sizes if interruptibility is needed.
  *
- * This function is safe to use with fork() and vfork(). It will also
- * close any file descriptor it ends up needing before it returns.
+ * Unlike getentropy() this function is a cancellation point. But it
+ * shouldn't be a problem, unless you're using masked mode, in which
+ * case extra care must be taken to consider the result.
+ *
+ * It's recommended that `f` be set to zero, although it may include
+ * the following flags:
+ *
+ * - `GRND_NONBLOCK` when you want to elevate the insecurity of your
+ *   random data
+ *
+ * - `GRND_RANDOM` if you want to have the best possible chance your
+ *   program will freeze and the system operator is paged to address
+ *   the outage by driving to the data center and jiggling the mouse
  *
  * @note this function could block a nontrivial time on old computers
  * @note this function is indeed intended for cryptography
  * @note this function takes around 900 cycles
  * @raise EINVAL if `f` is invalid
- * @raise ENOSYS on bare metal
+ * @raise ECANCELED if thread was cancelled in masked mode
+ * @raise EFAULT if the `n` bytes at `p` aren't valid memory
+ * @raise EINTR if we needed to block and a signal was delivered instead
  * @cancellationpoint
  * @asyncsignalsafe
  * @restartable
@@ -111,39 +251,27 @@ static ssize_t GetKernArnd(char *p, size_t n) {
  */
 ssize_t getrandom(void *p, size_t n, unsigned f) {
   ssize_t rc;
-  const char *via;
-  if ((f & ~(GRND_RANDOM | GRND_NONBLOCK))) {
+  if ((!p && n) || (IsAsan() && !__asan_is_valid(p, n))) {
+    rc = efault();
+  } else if ((f & ~(GRND_RANDOM | GRND_NONBLOCK))) {
     rc = einval();
-    via = "n/a";
-  } else if (IsWindows()) {
-    via = "RtlGenRandom";
-    rc = RtlGenRandom(p, n) ? n : __winerr();
-  } else if (IsFreebsd() || IsNetbsd()) {
-    via = "KERN_ARND";
-    rc = GetKernArnd(p, n);
-  } else if (have_getrandom) {
-    via = "getrandom";
-    if ((rc = sys_getrandom(p, n, f & (GRND_RANDOM | GRND_NONBLOCK))) != -1) {
-      if (!rc && (IsXnu() || IsOpenbsd())) {
-        rc = n;
-      }
-    }
   } else {
-    via = "/dev/urandom";
-    rc = GetDevRandom(p, n);
+    rc = __getrandom(p, n, f);
   }
-  STRACE("getrandom(%p, %'zu, %#x) via %s → %'ld% m", p, n, f, via, rc);
+  STRACE("getrandom(%p, %'zu, %#x) → %'ld% m", p, n, f, rc);
   return rc;
 }
 
 __attribute__((__constructor__)) static textstartup void getrandom_init(void) {
   int e, rc;
-  if (IsWindows()) return;
+  if (IsWindows() || IsMetal()) return;
+  BLOCK_CANCELLATIONS;
   e = errno;
   if (!(rc = sys_getrandom(0, 0, 0))) {
     have_getrandom = true;
   } else {
     errno = e;
   }
+  ALLOW_CANCELLATIONS;
   STRACE("sys_getrandom(0,0,0) → %d% m", rc);
 }

libc/stdio/pclose.c

@@ -25,19 +25,45 @@
 
 /**
  * Closes stream created by popen().
+ *
+ * This function may be interrupted or cancelled, however it won't
+ * actually return until the child process has terminated. Thus we
+ * always release the resource, and errors are purely advisory.
+ *
  * @return termination status of subprocess, or -1 w/ ECHILD
+ * @raise ECANCELED if thread was cancelled in masked mode
+ * @raise ECHILD if child pid didn't exist
+ * @raise EINTR if signal was delivered
+ * @cancellationpoint
  */
 int pclose(FILE *f) {
-  int ws, pid;
+  int e, rc, ws, pid;
+  bool iscancelled, wasinterrupted;
   pid = f->pid;
   fclose(f);
   if (!pid) return 0;
-TryAgain:
-  if (wait4(pid, &ws, 0, 0) != -1) {
-    return ws;
-  } else if (errno == EINTR) {
-    goto TryAgain;
+  iscancelled = false;
+  wasinterrupted = false;
+  for (e = errno;;) {
+    if (wait4(pid, &ws, 0, 0) != -1) {
+      rc = ws;
+      break;
+    } else if (errno == ECANCELED) {
+      iscancelled = true;
+      errno = e;
+    } else if (errno == EINTR) {
+      wasinterrupted = true;
+      errno = e;
+    } else {
+      rc = echild();
+      break;
+    }
+  }
+  if (iscancelled) {
+    return ecanceled();
+  } else if (wasinterrupted) {
+    return eintr();
   } else {
-    return echild();
+    return rc;
   }
 }

libc/stdio/popen.c

@@ -33,10 +33,22 @@
 /**
  * Spawns subprocess and returns pipe stream.
  *
+ * The returned resource needs to be passed to pclose().
+ *
  * This embeds the Cosmopolitan Command Interpreter which provides
  * Bourne-like syntax on all platforms including Windows.
  *
- * @see pclose()
+ * @param cmdline is a unix shell script
+ * @param mode can be:
+ *     - `"r"` for reading from subprocess standard output
+ *     - `"w"` for writing to subprocess standard input
+ * @raise EINVAL if `mode` is invalid or specifies read+write
+ * @raise EMFILE if process `RLIMIT_NOFILE` has been reached
+ * @raise ENFILE if system-wide file limit has been reached
+ * @raise ECANCELED if thread was cancelled in masked mode
+ * @raise ENOMEM if we require more vespene gas
+ * @raise EAGAIN if `RLIMIT_NPROC` was exceeded
+ * @raise EINTR if signal was delivered
  * @cancellationpoint
  * @threadsafe
  */

libc/stdio/posix_spawn.c

@@ -68,7 +68,6 @@ static int RunFileActions(struct _posix_faction *a) {
  * @param envp is environment variables, or `environ` if null
  * @return 0 on success or error number on failure
  * @see posix_spawnp() for `$PATH` searching
- * @cancellationpoint
  * @tlsrequired
  * @threadsafe
  */
@@ -81,9 +80,6 @@ int posix_spawn(int *pid, const char *path,
   int s, child, policy;
   struct sched_param param;
   struct sigaction dfl = {0};
-  if (_weaken(pthread_testcancel)) {
-    _weaken(pthread_testcancel)();
-  }
   if (!(child = vfork())) {
     if (attrp && *attrp) {
       posix_spawnattr_getflags(attrp, &flags);

libc/stdio/system.c

@@ -16,6 +16,7 @@
 │ TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR             │
 │ PERFORMANCE OF THIS SOFTWARE.                                                │
 ╚─────────────────────────────────────────────────────────────────────────────*/
+#include "libc/calls/blockcancel.internal.h"
 #include "libc/calls/calls.h"
 #include "libc/calls/struct/rusage.h"
 #include "libc/calls/struct/sigaction.h"
@@ -36,10 +37,10 @@
  * This embeds the Cosmopolitan Command Interpreter which provides
  * Bourne-like syntax on all platforms including Windows.
  *
- * @param cmdline is an interpreted Turing-complete command
+ * @param cmdline is a unix shell script
  * @return -1 if child process couldn't be created, otherwise a wait
- *     status that can be accessed using macros like WEXITSTATUS(s)
- * @cancellationpoint
+ *     status that can be accessed using macros like WEXITSTATUS(s),
+ *     WIFSIGNALED(s), WTERMSIG(s), etc.
  * @threadsafe
  */
 int system(const char *cmdline) {
@@ -47,9 +48,7 @@ int system(const char *cmdline) {
   sigset_t chldmask, savemask;
   struct sigaction ignore, saveint, savequit;
   if (!cmdline) return 1;
-  if (_weaken(pthread_testcancel)) {
-    _weaken(pthread_testcancel)();
-  }
+  BLOCK_CANCELLATIONS;
   ignore.sa_flags = 0;
   ignore.sa_handler = SIG_IGN;
   sigemptyset(&ignore.sa_mask);
@@ -76,5 +75,6 @@ int system(const char *cmdline) {
   sigaction(SIGINT, &saveint, 0);
   sigaction(SIGQUIT, &savequit, 0);
   sigprocmask(SIG_SETMASK, &savemask, 0);
+  ALLOW_CANCELLATIONS;
   return wstatus;
 }

libc/stdio/tmpfile.c

@@ -54,6 +54,9 @@
  * is Linux-only and will cause open() failures on all other platforms.
  *
  * @see tmpfd() if you don't want to link stdio/malloc
+ * @raise ECANCELED if thread was cancelled in masked mode
+ * @raise EINTR if signal was delivered
+ * @cancellationpoint
  * @asyncsignalsafe
  * @threadsafe
  * @vforksafe