1# zx_task_bind_exception_port
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7task_bind_exception_port - Bind to, or unbind from, the exception port corresponding to a given job, process, or thread.
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_task_bind_exception_port(zx_handle_t handle,
17                                        zx_handle_t port,
18                                        uint64_t key,
19                                        uint32_t options);
20```
21
22## DESCRIPTION
23
24`zx_task_bind_exception_port()` is used to bind (or unbind) a port to
25the exception port of a job, process, or thread.
26
27*port* is an IO port created by [`zx_port_create()`]. The same
28IO port can be bound to multiple objects.
29
30*key* is passed back in exception reports, and is part of the port
31message protocol.
32
33When a port is bound to the exception port of an object it participates
34in exception processing. See below for how exceptions are processed.
35
36### Unbinding
37
38To unbind from an exception port pass **ZX_HANDLE_INVALID** for *port*.
39This will remove the exception port from *handle* and *port* will no
40longer participate in exception processing for *handle*.
41
42The exception port will unbind automatically if all handles to *port*
43are closed while it is still bound.
44
45A thread may be currently waiting for a response from the program that
46bound *port* when it is unbound. Exception processing will continue as if
47*port* had never been bound.
48
49## RIGHTS
50
51<!-- Updated by update-docs-from-abigen, do not edit. -->
52
53*port* must be of type **ZX_OBJ_TYPE_PORT**.
54
55## RETURN VALUE
56
57`zx_task_bind_exception_port()` returns **ZX_OK** on success.
58In the event of failure, a negative error value is returned.
59
60## ERRORS
61
62**ZX_ERR_ALREADY_BOUND** *handle* already has its exception port bound.
63
64**ZX_ERR_BAD_HANDLE** *handle* is not a valid handle,
65or *port* is not a valid handle. Note that when unbinding from an exception
66port *port* is **ZX_HANDLE_INVALID**.
67
68**ZX_ERR_BAD_STATE** Unbinding a port that is not currently bound.
69
70**ZX_ERR_WRONG_TYPE**  *handle* is not that of a job, process, or thread,
71and is not **ZX_HANDLE_INVALID**,
72or *port* is not that of a port and is not **ZX_HANDLE_INVALID**.
73
74**ZX_ERR_INVALID_ARGS** A bad value has been passed in *options*.
75
76**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
77There is no good way for userspace to handle this (unlikely) error.
78In a future build this error will no longer occur.
79
80## SEE ALSO
81
82 - [exceptions](../exceptions.md)
83 - [`zx_port_create()`]
84 - [`zx_port_wait()`]
85 - [`zx_task_resume_from_exception()`]
86
87<!-- References updated by update-docs-from-abigen, do not edit. -->
88
89[`zx_port_create()`]: port_create.md
90[`zx_port_wait()`]: port_wait.md
91[`zx_task_resume_from_exception()`]: task_resume_from_exception.md
92