WAIT(3)

okay bestie, welcome to WAIT(3) from the Library Functions Manual — the page where Unix makes you wait for your child processes to exit, and honestly? iconic. 💅

✨ NAME ✨

The whole squad on this page is await, awaitnohang, awaitfor, wait, waitnohang, waitfor, and waitpid — and their whole job is literally: wait for a process to exit. 🫶

🦋 SYNOPSIS 🦋

#include <u.h>
#include <libc.h>

Waitmsg*  wait(void)

Waitmsg*  waitnohang(void)

Waitmsg*  waitfor(int pid)

int       waitpid(void)

int       await(char *s, int n)

int       awaitnohang(char *s, int n)

int       awaitfor(int pid, char *s, int n)

💅 DESCRIPTION 💅

Wait — yes, capitalized in the prose, but bestie the function is wait — causes a process to wait for any child process (see fork(2) and rfork(3)) to exit. It returns a Waitmsg holding information about the exited child. A Waitmsg has this structure:

typedef
struct Waitmsg
{
      int pid;              /* of loved one */
      ulong time[3];        /* of loved one & descendants */
      char *msg;
} Waitmsg;

• pid — the child’s process id.
• time — the time array contains the time the child and its descendants spent in user code, the time spent in system calls, and the child’s elapsed real time, all in units of milliseconds.
• msg — contains the message that the child specified in exits(3). For a normal exit, msg[0] is zero, otherwise msg is the exit string prefixed by the process name, a blank, the process id, and a colon.

If there are no more children to wait for, wait returns immediately, with return value nil.

The Waitmsg structure is allocated by malloc(3) and should be freed after use. For programs that only need the pid of the exiting program, waitpid returns just the pid and discards the rest of the information.

Waitnohang is like wait but does not block if there are no more children to wait for. Instead it returns immediately and sets errstr.

Waitfor is like wait but waits for a particular pid.

The underlying calls are await, awaitnohang, and awaitfor, which fill in the n-byte buffer s with a textual representation of the pid, times, and exit string. There is no terminal NUL. The return value is the length, in bytes, of the data.

The filled-in buffer may be parsed (after appending a NUL) using tokenize (see getfields(3)); the resulting fields are, in order, pid, the three times, and the exit string, which will be '' for normal exit.

lowkey important: if the representation is longer than n bytes, it is truncated but, if possible, properly formatted. The information that does not fit in the buffer is discarded, so a subsequent call to await will return the information about the next exiting child, not the remainder of the truncated message. In other words, each call to await returns the information about one child, blocking if necessary if no child has exited. If the calling process has no living children, await returns -1. 💀

🍓 SOURCE 🍓

• /src/lib9/wait.c
• /src/lib9/await.c

🌈 SEE ALSO 🌈

• rfork(3)
• exits(3),

go read those next, bestie — the comma on exits(3), is canon, periodt. 🎀

🩺 DIAGNOSTICS 🩺

These routines set errstr. that’s the diagnostic vibe, no cap. 🩺

💀 BUGS 💀

To avoid name conflicts with the underlying system, wait, waitpid, and waitfor are preprocessor macros defined as p9wait, p9waitpid, and p9waitfor; see intro(3).

so if you’re out here looking for plain wait, don’t be shocked when the preprocessor is doing main character energy. 🙈

---

mwah 💖 — this is page WAIT(3) from the Library Functions Manual, with source files /src/lib9/wait.c and /src/lib9/await.c; the footer doesn’t show a date, just WAIT(3), and that’s the whole cute sign-off. slay. 🎀✨