1# zx_port_create
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7port_create - create an IO 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_port_create(uint32_t options, zx_handle_t* out);
17```
18
19## DESCRIPTION
20
21`zx_port_create()` creates a port: a waitable object that can be used to read
22packets queued by kernel or by user-mode.
23
24If you need this port to be bound to an interrupt, pass **ZX_PORT_BIND_TO_INTERRUPT** to *options*,
25otherwise it should be **0**.
26
27In the case where a port is bound to an interrupt, the interrupt packets are delivered via a
28dedicated queue on ports and are higher priority than other non-interrupt packets.
29
30The returned handle will have:
31  * `ZX_RIGHT_TRANSFER`: allowing them to be sent to another process via channel write.
32  * `ZX_RIGHT_WRITE`: allowing packets to be *queued*.
33  * `ZX_RIGHT_READ`: allowing packets to be *read*.
34  * `ZX_RIGHT_DUPLICATE`: allowing them to be *duplicated*.
35
36## RIGHTS
37
38<!-- Updated by update-docs-from-abigen, do not edit. -->
39
40TODO(ZX-2399)
41
42## RETURN VALUE
43
44`zx_port_create()` returns **ZX_OK** and a valid IO port handle via *out* on
45success. In the event of failure, an error value is returned.
46
47## ERRORS
48
49**ZX_ERR_INVALID_ARGS** *options* has an invalid value, or *out* is an
50invalid pointer or NULL.
51
52**ZX_ERR_NO_MEMORY** Failure due to lack of memory.
53There is no good way for userspace to handle this (unlikely) error.
54In a future builds this error will no longer occur.
55
56## SEE ALSO
57
58 - [`zx_handle_close()`]
59 - [`zx_handle_duplicate()`]
60 - [`zx_handle_replace()`]
61 - [`zx_object_wait_async()`]
62 - [`zx_port_queue()`]
63 - [`zx_port_wait()`]
64
65<!-- References updated by update-docs-from-abigen, do not edit. -->
66
67[`zx_handle_close()`]: handle_close.md
68[`zx_handle_duplicate()`]: handle_duplicate.md
69[`zx_handle_replace()`]: handle_replace.md
70[`zx_object_wait_async()`]: object_wait_async.md
71[`zx_port_queue()`]: port_queue.md
72[`zx_port_wait()`]: port_wait.md
73