---
name: "iv_wait"
section: "3"
platform: "linux"
package: "libivykis-dev"
version: "0.43.2-1+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/iv_wait"
---

# iv\_wait(3)

ivykis wait4(2) wrapper

## NAME

IV\_WAIT\_INTEREST\_INIT, iv\_wait\_interest\_register, iv\_wait\_interest\_register\_spawn, iv\_wait\_interest\_unregister, iv\_wait\_interest\_kill - ivykis [**wait4**(2)](/wait4/2.md) wrapper

## SYNOPSIS

**#include \<iv\_wait.h\>**

```
struct iv_wait_interest {
        pid_t           pid;
        void            *cookie;
        void            (*handler)(void *cookie, int status,
                                   const struct rusage *rusage);
};
```

**void IV\_WAIT\_INTEREST\_INIT(struct iv\_wait\_interest \****this***);**\
 **int iv\_wait\_interest\_register(struct iv\_wait\_interest \****this***);**\
 **int iv\_wait\_interest\_register\_spawn(struct iv\_wait\_interest \****this***, void (\****fn***)(void \*), void \****cookie***);**\
 **void iv\_wait\_interest\_unregister(struct iv\_wait\_interest \****this***);**\
 **int iv\_wait\_interest\_kill(const struct iv\_wait\_interest \****this***, int** *sig***);**\

## DESCRIPTION

**iv\_wait** is an [**ivykis**(3)](/ivykis/3.md) wrapper around [**wait4**(2)](/wait4/2.md), integrating process state change notification with the ivykis event loop.

An ivykis application desiring process state change notifications registers a **struct iv\_wait\_interest** object by calling **iv\_wait\_interest\_register,** after having initialised it with **IV\_WAIT\_INTEREST\_INIT** and subsequently having filled in the **-\>pid,** **-\>cookie** and **-\>handler** members.

Alternatively, an ivykis application can use **iv\_wait\_interest\_register\_spawn** to atomically fork off a child process and register a **struct iv\_wait\_interest** for it.  In this context, 'atomically' means that the call to **iv\_wait\_interest\_register\_spawn** will be serialised with respect to invocations of [**wait4**(2)](/wait4/2.md), which closes the race where process state change notifications can occur and be delivered between forking off the child process and registering a **struct iv\_wait\_interest** for the child's pid.  The child process will run the function given by the **iv\_wait\_interest\_register\_spawn** argument **fn,** with argument **cookie** as its argument.

Once a process state change occurs (as indicated by delivery of a SIGCHLD signal to the current process), **iv\_wait** calls [**wait4**(2)](/wait4/2.md) to return information about the process state change, looks up the returned process ID in the set of registered **struct iv\_wait\_interest** objects, and if there is a registered interest with a matching **-\>pid** field, arranges for that object's callback function to be called in the thread that the object was registered in.

Process state change notifications will continue to be delivered to the object's callback function until **iv\_wait\_interest\_unregister** is called on the object or until a WIFEXITED or WIFSIGNALED status for this pid is returned by [**wait4**(2)](/wait4/2.md).

Delivery of a WIFEXITED or WIFSIGNALED status does not automatically unregister the object, this always needs to be done explicitly.

Unregistering a **struct iv\_wait\_interest** object can only be done from the thread that that object was registered in, but within that thread, can safely be done from (and its underlying memory allocation can safely be freed from) its own callback function.

Registering multiple **struct iv\_wait\_interest** objects for the same process ID will produce undefined behavior.

To send a signal to a child process, use **iv\_wait\_interest\_kill.** This function will internally serialise with invocations of **[wait4(2)](/wait4/2.md),** to avoid the race between sending a signal to a process and collecting a termination notification for that process (which makes its pid available for reuse).

Internally, **iv\_wait** is implemented using [**iv\_signal**(3)](/iv_signal/3.md) and [**iv\_event**(3)](/iv_event/3.md).

## SEE ALSO

[**ivykis**(3)](/ivykis/3.md), [**iv\_signal**(3)](/iv_signal/3.md), [**iv\_event**(3)](/iv_event/3.md), [**wait4**(2)](/wait4/2.md)