# zx_interrupt_destroy

## Summary

Destroys an interrupt object.

## Declaration

    #include <zircon/syscalls.h>

    zx_status_t zx_interrupt_destroy(zx_handle_t handle);

## Description

`zx_interrupt_destroy()` "destroys" an interrupt object, putting it in a state
where any [`zx_interrupt_wait()`](https://fuchsia.dev/reference/syscalls/interrupt_wait) operations on it will return `ZX_ERR_CANCELED`,
and it is unbound from any ports it was bound to.

This provides a clean shut down mechanism. Closing the last handle to the
interrupt object results in similar cancellation but could result in use-after-close
of the handle.

If the interrupt object is bound to a port when cancellation happens, if it
has not yet triggered, or it has triggered but the packet has not yet been
received by a caller of [`zx_port_wait()`](https://fuchsia.dev/reference/syscalls/port_wait), success is returned and any packets
in flight are removed. Otherwise, `ZX_ERR_NOT_FOUND` is returned, indicating
that the packet has been read but the interrupt has not been re-armed by calling
[`zx_interrupt_ack()`](https://fuchsia.dev/reference/syscalls/interrupt_ack).

## Rights

TODO(https://fxbug.dev/42107318)

## Return value

`zx_interrupt_destroy()` returns `ZX_OK` on success. In the event
of failure, a negative error value is returned.

## Errors

`ZX_ERR_BAD_HANDLE` *handle* is an invalid handle.

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

`ZX_ERR_NOT_FOUND` *handle* was bound (and now no longer is) but was not
being waited for.

`ZX_ERR_ACCESS_DENIED` *handle* lacks `ZX_RIGHT_WRITE`.

## 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_trigger()`](https://fuchsia.dev/reference/syscalls/interrupt_trigger)
- [`zx_interrupt_wait()`](https://fuchsia.dev/reference/syscalls/interrupt_wait)
- [`zx_port_wait()`](https://fuchsia.dev/reference/syscalls/port_wait)