1# zx_port_queue
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7port_queue - queue a packet to an 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_queue(zx_handle_t handle, const zx_port_packet_t* packet);
18```
19
20## DESCRIPTION
21
22`zx_port_queue()` queues a *packet* to the port specified
23by *handle*.
24
25```
26typedef struct zx_port_packet {
27    uint64_t key;
28    uint32_t type;
29    zx_status_t status;
30    union {
31        zx_packet_user_t user;
32        zx_packet_signal_t signal;
33    };
34} zx_port_packet_t;
35
36```
37
38In *packet* *type* should be **ZX_PKT_TYPE_USER** and only the **user**
39union element is considered valid:
40
41```
42typedef union zx_packet_user {
43    uint64_t u64[4];
44    uint32_t u32[8];
45    uint16_t u16[16];
46    uint8_t   c8[32];
47} zx_packet_user_t;
48
49```
50
51## RIGHTS
52
53<!-- Updated by update-docs-from-abigen, do not edit. -->
54
55*handle* must be of type **ZX_OBJ_TYPE_PORT** and have **ZX_RIGHT_WRITE**.
56
57## RETURN VALUE
58
59`zx_port_queue()` returns **ZX_OK** on successful queue of a packet.
60
61## ERRORS
62
63**ZX_ERR_BAD_HANDLE** *handle* isn't a valid handle
64
65**ZX_ERR_INVALID_ARGS** *packet* is an invalid pointer.
66
67**ZX_ERR_WRONG_TYPE** *handle* is not a port handle.
68
69**ZX_ERR_ACCESS_DENIED** *handle* does not have **ZX_RIGHT_WRITE**.
70
71**ZX_ERR_SHOULD_WAIT** the port has too many pending packets. Once a thread
72has drained some packets a new `zx_port_queue()` call will likely succeed.
73
74## NOTES
75
76The queue is drained by calling [`zx_port_wait()`].
77
78
79## SEE ALSO
80
81 - [`zx_port_create()`]
82 - [`zx_port_wait()`]
83
84<!-- References updated by update-docs-from-abigen, do not edit. -->
85
86[`zx_port_create()`]: port_create.md
87[`zx_port_wait()`]: port_wait.md
88