1# zx_socket_write
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7socket_write - write data to a socket
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_socket_write(zx_handle_t handle,
17                            uint32_t options,
18                            const void* buffer,
19                            size_t buffer_size,
20                            size_t* actual);
21```
22
23## DESCRIPTION
24
25`zx_socket_write()` attempts to write *buffer_size* bytes to the socket specified
26by *handle*. The pointer to *bytes* may be NULL if *buffer_size* is zero.
27
28If **ZX_SOCKET_CONTROL** is passed to *options*, then `zx_socket_write()`
29attempts to write into the socket control plane. A write to the control plane is
30never short. If the socket control plane has insufficient space for *buffer*, it
31writes nothing and returns **ZX_ERR_OUT_OF_RANGE**.
32
33If a NULL *actual* is passed in, it will be ignored.
34
35A **ZX_SOCKET_STREAM** socket write can be short if the socket does not have
36enough space for all of *buffer*. If a non-zero amount of data was written to
37the socket, the amount written is returned via *actual* and the call succeeds.
38Otherwise, if the socket was already full, the call returns
39**ZX_ERR_SHOULD_WAIT** and the client should wait (e.g., with
40[object_wait_one](object_wait_one.md) or
41[object_wait_async](object_wait_async.md)). For datagram sockets, attempting to
42write a packet larger than the socket's capacity will fail with
43**ZX_ERR_OUT_OF_RANGE**.
44
45A **ZX_SOCKET_DATAGRAM** socket write is never short. If the socket has
46insufficient space for *buffer*, it writes nothing and returns
47**ZX_ERR_SHOULD_WAIT**. If the write succeeds, *buffer_size* is returned via
48*actual*.
49
50## RIGHTS
51
52<!-- Updated by update-docs-from-abigen, do not edit. -->
53
54*handle* must be of type **ZX_OBJ_TYPE_SOCKET** and have **ZX_RIGHT_WRITE**.
55
56## RETURN VALUE
57
58`zx_socket_write()` returns **ZX_OK** on success.
59
60## ERRORS
61
62**ZX_ERR_BAD_HANDLE**  *handle* is not a valid handle.
63
64**ZX_ERR_BAD_STATE**  *options* includes **ZX_SOCKET_CONTROL** and the
65socket was not created with **ZX_SOCKET_HAS_CONTROL**.
66
67**ZX_ERR_WRONG_TYPE**  *handle* is not a socket handle.
68
69**ZX_ERR_INVALID_ARGS**  *buffer* is an invalid pointer.
70
71**ZX_ERR_ACCESS_DENIED**  *handle* does not have **ZX_RIGHT_WRITE**.
72
73**ZX_ERR_SHOULD_WAIT**  The buffer underlying the socket is full.
74
75**ZX_ERR_OUT_OF_RANGE**  The socket was created with **ZX_SOCKET_DATAGRAM** and
76*buffer* is larger than the remaining space in the socket.
77
78**ZX_ERR_BAD_STATE**  Writing has been disabled for this socket endpoint.
79
80**ZX_ERR_PEER_CLOSED**  The other side of the socket is closed.
81
82**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
83There is no good way for userspace to handle this (unlikely) error.
84In a future build this error will no longer occur.
85
86## SEE ALSO
87
88 - [`zx_socket_accept()`]
89 - [`zx_socket_create()`]
90 - [`zx_socket_read()`]
91 - [`zx_socket_share()`]
92 - [`zx_socket_shutdown()`]
93
94<!-- References updated by update-docs-from-abigen, do not edit. -->
95
96[`zx_socket_accept()`]: socket_accept.md
97[`zx_socket_create()`]: socket_create.md
98[`zx_socket_read()`]: socket_read.md
99[`zx_socket_share()`]: socket_share.md
100[`zx_socket_shutdown()`]: socket_shutdown.md
101