# zx_interrupt_wait

## Summary

Wait for an interrupt.

## Declaration

    #include <zircon/syscalls.h>

    zx_status_t zx_interrupt_wait(zx_handle_t handle, zx_time_t* out_timestamp);

## Description

`zx_interrupt_wait()` is a blocking syscall that causes the caller to wait until an
interrupt is triggered. It can only be used on interrupt objects that have not been bound
to a port with [`zx_interrupt_bind()`](https://fuchsia.dev/reference/syscalls/interrupt_bind).

If a thread was notified of an interrupt becoming triggered by returning from a call to
`zx_interrupt_wait()`, then the next call to `zx_interrupt_wait()` will also acknowledge
the interrupt object, in addition to waiting for the next trigger event. Please note that
waiting on the interrupt object again is the *only* way to acknowledge a non-port-bound
interrupt object. [`zx_interrupt_ack()`](https://fuchsia.dev/reference/syscalls/interrupt_ack) does not change the state of non-port bound
interrupts. Please see (here)[Interrupts#synchronous-waiting-and-acknowledgement](https://fuchsia.dev/docs/reference/kernel_objects/interrupts#synchronous-waiting-and-acknowledgement)
for details about how to properly wait for and acknowledge interrupts when using
`zx_interrupt_wait()`.

The wait may be aborted with [`zx_interrupt_destroy()`](https://fuchsia.dev/reference/syscalls/interrupt_destroy) or by closing the final handle to
the interrupt object.

## Rights

*handle* must be of type `ZX_OBJ_TYPE_INTERRUPT` and have `ZX_RIGHT_WAIT`.

## Return value

`zx_interrupt_wait()` returns `ZX_OK` on success, and *out_timestamp* , if
non-NULL, returns the timestamp of when the interrupt was triggered. By default,
this timestamp is relative to `ZX_CLOCK_BOOT`. However, if the interrupt was
created using the `ZX_INTERRUPT_TIMESTAMP_MONO` flag, this timestamp will be
relative to `ZX_CLOCK_MONOTONIC`.

## Errors

`ZX_ERR_BAD_HANDLE` *handle* is an invalid handle.

`ZX_ERR_WRONG_TYPE` *handle* is not a handle to an interrupt object.

`ZX_ERR_BAD_STATE` the interrupt object is bound to a port.

`ZX_ERR_ACCESS_DENIED` *handle* lacks `ZX_RIGHT_WAIT`.

`ZX_ERR_CANCELED` *handle* was closed while waiting or [`zx_interrupt_destroy()`](https://fuchsia.dev/reference/syscalls/interrupt_destroy) was called
on it.

`ZX_ERR_INVALID_ARGS` the *out_timestamp* parameter is an invalid pointer.

## See also

- [Interrupts](https://fuchsia.dev/docs/reference/kernel_objects/interrupts)
- [`zx_handle_close()`](https://fuchsia.dev/reference/syscalls/handle_close)
- [`zx_interrupt_ack()`](https://fuchsia.dev/reference/syscalls/interrupt_ack)
- [`zx_interrupt_bind()`](https://fuchsia.dev/reference/syscalls/interrupt_bind)
- [`zx_interrupt_create()`](https://fuchsia.dev/reference/syscalls/interrupt_create)
- [`zx_interrupt_destroy()`](https://fuchsia.dev/reference/syscalls/interrupt_destroy)
- [`zx_interrupt_trigger()`](https://fuchsia.dev/reference/syscalls/interrupt_trigger)
- [`zx_port_wait()`](https://fuchsia.dev/reference/syscalls/port_wait)