1# zx_port_wait
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7port_wait - wait for a packet arrival in a port
8
9## SYNOPSIS
10
11<!-- Updated by update-docs-from-abigen, do not edit. -->
12
13```
14#include <zircon/syscalls.h>
15#include <zircon/syscalls/port.h>
16
17zx_status_t zx_port_wait(zx_handle_t handle,
18                         zx_time_t deadline,
19                         zx_port_packet_t* packet);
20```
21
22## DESCRIPTION
23
24`zx_port_wait()` is a blocking syscall which causes the caller to wait until at least
25one packet is available.
26
27Upon return, if successful *packet* will contain the earliest (in FIFO order)
28available packet data.
29
30The *deadline* indicates when to stop waiting for a packet (with respect to
31**ZX_CLOCK_MONOTONIC**).  If no packet has arrived by the deadline,
32**ZX_ERR_TIMED_OUT** is returned.  The value **ZX_TIME_INFINITE** will
33result in waiting forever.  A value in the past will result in an immediate
34timeout, unless a packet is already available for reading.
35
36Unlike [`zx_object_wait_one()`] and [`zx_object_wait_many()`] only one
37waiting thread is released (per available packet) which makes ports
38amenable to be serviced by thread pools.
39
40There are two classes of packets: packets queued by userspace with [`zx_port_queue()`]
41and packets queued by the kernel when objects a port is registered with change state. In both
42cases the packet is always of type `zx_port_packet_t`:
43
44```
45struct zx_port_packet_t {
46    uint64_t key;
47    uint32_t type;
48    zx_status_t status;
49    union {
50        zx_packet_user_t user;
51        zx_packet_signal_t signal;
52        zx_packet_exception_t exception;
53        zx_packet_guest_bell_t guest_bell;
54        zx_packet_guest_mem_t guest_mem;
55        zx_packet_guest_io_t guest_io;
56        zx_packet_guest_vcpu_t guest_vcpu;
57        zx_packet_interrupt_t interrupt;
58    };
59};
60```
61
62In the case of packets generated via [`zx_port_queue()`], *type* will be set to
63**ZX_PKT_TYPE_USER**, and the caller of [`zx_port_queue()`] controls all other values in the
64`zx_port_packet_t` structure. Access to the packet data is provided by the *user* member, with
65type `zx_packet_user_t`:
66
67```
68typedef union zx_packet_user {
69    uint64_t u64[4];
70    uint32_t u32[8];
71    uint16_t u16[16];
72    uint8_t   c8[32];
73} zx_packet_user_t;
74```
75
76For packets generated by the kernel, type can be one of the following values:
77
78**ZX_PKT_TYPE_SIGNAL_ONE** or **ZX_PKT_TYPE_SIGNAL_REP** - generated by objects registered
79via [`zx_object_wait_async()`].
80
81**ZX_PKT_TYPE_EXCEPTION(n)** - generated by objects registered via
82[`zx_task_bind_exception_port()`].
83
84**ZX_PKT_TYPE_GUEST_BELL**, **ZX_PKT_TYPE_GUEST_MEM**, **ZX_PKT_TYPE_GUEST_IO**,
85or **ZX_PKT_TYPE_GUEST_VCPU** - generated by objects registered via [`zx_guest_set_trap()`].
86
87**ZX_PKT_TYPE_INTERRUPT** - generated by objects registered via [`zx_interrupt_bind()`].
88
89All kernel queued packets will have *status* set to **ZX_OK** and *key* set to the
90value provided to the registration syscall. For details on how to interpret the union, see
91the corresponding registration syscall.
92
93## RIGHTS
94
95<!-- Updated by update-docs-from-abigen, do not edit. -->
96
97*handle* must be of type **ZX_OBJ_TYPE_PORT** and have **ZX_RIGHT_READ**.
98
99## RETURN VALUE
100
101`zx_port_wait()` returns **ZX_OK** on successful packet dequeuing.
102
103## ERRORS
104
105**ZX_ERR_BAD_HANDLE** *handle* is not a valid handle.
106
107**ZX_ERR_INVALID_ARGS** *packet* isn't a valid pointer
108
109**ZX_ERR_ACCESS_DENIED** *handle* does not have **ZX_RIGHT_READ** and may
110not be waited upon.
111
112**ZX_ERR_TIMED_OUT** *deadline* passed and no packet was available.
113
114## SEE ALSO
115
116 - [`zx_object_wait_async()`]
117 - [`zx_port_create()`]
118 - [`zx_port_queue()`]
119
120<!-- References updated by update-docs-from-abigen, do not edit. -->
121
122[`zx_guest_set_trap()`]: guest_set_trap.md
123[`zx_interrupt_bind()`]: interrupt_bind.md
124[`zx_object_wait_async()`]: object_wait_async.md
125[`zx_object_wait_many()`]: object_wait_many.md
126[`zx_object_wait_one()`]: object_wait_one.md
127[`zx_port_create()`]: port_create.md
128[`zx_port_queue()`]: port_queue.md
129[`zx_task_bind_exception_port()`]: task_bind_exception_port.md
130