1# zx_interrupt_bind
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7interrupt_bind - Bind an interrupt object to a port
8
9## SYNOPSIS
10
11<!-- Updated by update-docs-from-abigen, do not edit. -->
12
13```
14#include <zircon/syscalls.h>
15
16zx_status_t zx_interrupt_bind(zx_handle_t handle,
17                              zx_handle_t port_handle,
18                              uint64_t key,
19                              uint32_t options);
20```
21
22## DESCRIPTION
23
24`zx_interrupt_bind()` binds an interrupt object to a port.
25
26An interrupt object may only be bound to a single port and may only be bound once.
27The interrupt can only bind to a port which is created with **ZX_PORT_BIND_TO_INTERRUPT**
28option.
29
30When a bound interrupt object is triggered, a **ZX_PKT_TYPE_INTERRUPT** packet will
31be delivered to the port it is bound to, with the timestamp (relative to **ZX_CLOCK_MONOTONIC**)
32of when the interrupt was triggered in the `zx_packet_interrupt_t`.  The *key* used
33when binding the interrupt will be present in the `key` field of the `zx_port_packet_t`.
34
35Before another packet may be delivered, the bound interrupt must be re-armed using the
36[`zx_interrupt_ack()`] syscall.  This is (in almost all cases) best done after the interrupt
37packet has been fully processed.  Especially in the case of multiple threads reading
38packets from a port, if the processing thread re-arms the interrupt and it has triggered,
39a packet will immediately be delivered to a waiting thread.
40
41Interrupt packets are delivered via a dedicated queue on ports and are higher priority
42than non-interrupt packets.
43
44## RIGHTS
45
46<!-- Updated by update-docs-from-abigen, do not edit. -->
47
48*handle* must be of type **ZX_OBJ_TYPE_INTERRUPT** and have **ZX_RIGHT_READ**.
49
50*port_handle* must be of type **ZX_OBJ_TYPE_PORT** and have **ZX_RIGHT_WRITE**.
51
52## RETURN VALUE
53
54`zx_interrupt_bind()` returns **ZX_OK** on success. In the event
55of failure, a negative error value is returned.
56
57## ERRORS
58
59**ZX_ERR_BAD_HANDLE** *handle* or *port_handle* is not a valid handle.
60
61**ZX_ERR_WRONG_TYPE** *handle* is not an interrupt object or *port_handle* is not a port object.
62
63**ZX_ERR_CANCELED**  [`zx_interrupt_destroy()`] was called on *handle*.
64
65**ZX_ERR_BAD_STATE**  A thread is waiting on the interrupt using [`zx_interrupt_wait()`]
66
67**ZX_ERR_ACCESS_DENIED** the *handle* handle lacks **ZX_RIGHT_READ** or the *port_handle* handle
68lacks **ZX_RIGHT_WRITE**
69
70**ZX_ERR_ALREADY_BOUND** this interrupt object is already bound.
71
72**ZX_ERR_INVALID_ARGS** *options* contains a non-zero value.
73
74## SEE ALSO
75
76 - [`zx_handle_close()`]
77 - [`zx_interrupt_ack()`]
78 - [`zx_interrupt_create()`]
79 - [`zx_interrupt_destroy()`]
80 - [`zx_interrupt_trigger()`]
81 - [`zx_interrupt_wait()`]
82 - [`zx_port_wait()`]
83
84<!-- References updated by update-docs-from-abigen, do not edit. -->
85
86[`zx_handle_close()`]: handle_close.md
87[`zx_interrupt_ack()`]: interrupt_ack.md
88[`zx_interrupt_create()`]: interrupt_create.md
89[`zx_interrupt_destroy()`]: interrupt_destroy.md
90[`zx_interrupt_trigger()`]: interrupt_trigger.md
91[`zx_interrupt_wait()`]: interrupt_wait.md
92[`zx_port_wait()`]: port_wait.md
93