# zx_interrupt_trigger

## Summary

Triggers a virtual interrupt object.

## Declaration

    #include <zircon/syscalls.h>

    zx_status_t zx_interrupt_trigger(zx_handle_t handle,
                                     uint32_t options,
                                     zx_time_t timestamp);

## Description

`zx_interrupt_trigger()` is used to trigger a virtual interrupt interrupt object,
causing an interrupt message packet to arrive on the bound port, if it is bound
to a port, or [`zx_interrupt_wait()`](https://fuchsia.dev/reference/syscalls/interrupt_wait) to return if it is waiting on this interrupt.

*options* must be zero.

*timestamp* is by default interpreted as a timestamp on `ZX_CLOCK_BOOT`. However, if
the interrupt was created with the `ZX_INTERRUPT_TIMESTAMP_MONO` option, then this
timestamp will be interpreted as a timestamp on `ZX_CLOCK_MONOTONIC`.

`zx_interrupt_trigger()` is only valid when the underlying object is a virtual interrupt
created explicitly using the `ZX_INTERRUPT_VIRTUAL` option, and may not be used to
force-trigger a physical interrupt.

Virtual interrupts also support a Zircon signal, `ZX_VIRTUAL_INTERRUPT_UNTRIGGERED`, which
can be used along with the standard Zircon signal waiting mechanisms (*not*
[`zx_interrupt_wait()`](https://fuchsia.dev/reference/syscalls/interrupt_wait)) to inform the triggering driver of when the interrupt consumer has
processed and acknowledged the interrupt trigger event. Please see
(here)[Interrupts#virtual-interrupts-and-the-untriggered-signal](https://fuchsia.dev/docs/reference/kernel_objects/interrupts#virtual-interrupts-and-the-untriggered-signal) for the details of how to
use the `ZX_VIRTUAL_INTERRUPT_UNTRIGGERED` signal.

## Rights

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

## Return value

`zx_interrupt_trigger()` 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_BAD_STATE` *handle* is not a virtual interrupt.

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

`ZX_ERR_ACCESS_DENIED` *handle* lacks `ZX_RIGHT_SIGNAL`.

`ZX_ERR_INVALID_ARGS` *options* is non-zero.

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