1# zx_channel_write
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7channel_write - write a message to a channel
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_channel_write(zx_handle_t handle,
17                             uint32_t options,
18                             const void* bytes,
19                             uint32_t num_bytes,
20                             const zx_handle_t* handles,
21                             uint32_t num_handles);
22```
23
24## DESCRIPTION
25
26`zx_channel_write()` attempts to write a message of *num_bytes*
27bytes and *num_handles* handles to the channel specified by
28*handle*.  The pointers *handles* and *bytes* may be NULL if their
29respective sizes are zero.
30
31On success, all *num_handles* of the handles in the *handles* array
32are no longer accessible to the caller's process -- they are attached
33to the message and will become available to the reader of that message
34from the opposite end of the channel.  On any failure, all handles
35are discarded rather than transferred.
36
37It is invalid to include *handle* (the handle of the channel being written
38to) in the *handles* array (the handles being sent in the message).
39
40The maximum number of handles which may be sent in a message is
41**ZX_CHANNEL_MAX_MSG_HANDLES**, which is 64.
42
43The maximum number of bytes which may be sent in a message is
44**ZX_CHANNEL_MAX_MSG_BYTES**, which is 65536.
45
46
47## RIGHTS
48
49<!-- Updated by update-docs-from-abigen, do not edit. -->
50
51*handle* must be of type **ZX_OBJ_TYPE_CHANNEL** and have **ZX_RIGHT_WRITE**.
52
53Every entry of *handles* must have **ZX_RIGHT_TRANSFER**.
54
55## RETURN VALUE
56
57`zx_channel_write()` returns **ZX_OK** on success.
58
59## ERRORS
60
61**ZX_ERR_BAD_HANDLE**  *handle* is not a valid handle, any element in
62*handles* is not a valid handle, or there are duplicates among the handles
63in the *handles* array.
64
65**ZX_ERR_WRONG_TYPE**  *handle* is not a channel handle.
66
67**ZX_ERR_INVALID_ARGS**  *bytes* is an invalid pointer, *handles*
68is an invalid pointer, or *options* is nonzero.
69
70**ZX_ERR_NOT_SUPPORTED**  *handle* was found in the *handles* array, or
71one of the handles in *handles* was *handle* (the handle to the
72channel being written to).
73
74**ZX_ERR_ACCESS_DENIED**  *handle* does not have **ZX_RIGHT_WRITE** or
75any element in *handles* does not have **ZX_RIGHT_TRANSFER**.
76
77**ZX_ERR_PEER_CLOSED**  The other side of the channel is closed.
78
79**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
80There is no good way for userspace to handle this (unlikely) error.
81In a future build this error will no longer occur.
82
83**ZX_ERR_OUT_OF_RANGE**  *num_bytes* or *num_handles* are larger than the
84largest allowable size for channel messages.
85
86## NOTES
87
88*num_handles* is a count of the number of elements in the *handles*
89array, not its size in bytes.
90
91The byte size limitation on messages is not yet finalized.
92
93## SEE ALSO
94
95 - [`zx_channel_call()`]
96 - [`zx_channel_create()`]
97 - [`zx_channel_read()`]
98 - [`zx_handle_close()`]
99 - [`zx_handle_duplicate()`]
100 - [`zx_handle_replace()`]
101 - [`zx_object_wait_async()`]
102 - [`zx_object_wait_many()`]
103 - [`zx_object_wait_one()`]
104
105<!-- References updated by update-docs-from-abigen, do not edit. -->
106
107[`zx_channel_call()`]: channel_call.md
108[`zx_channel_create()`]: channel_create.md
109[`zx_channel_read()`]: channel_read.md
110[`zx_handle_close()`]: handle_close.md
111[`zx_handle_duplicate()`]: handle_duplicate.md
112[`zx_handle_replace()`]: handle_replace.md
113[`zx_object_wait_async()`]: object_wait_async.md
114[`zx_object_wait_many()`]: object_wait_many.md
115[`zx_object_wait_one()`]: object_wait_one.md
116