1# zx_socket_write
2
3## NAME
4
5socket_write - write data to a socket
6
7## SYNOPSIS
8
9```
10#include <zircon/syscalls.h>
11
12zx_status_t zx_socket_write(zx_handle_t handle, uint32_t options,
13                            const void* buffer, size_t buffer_size,
14                            size_t* actual) {
15```
16
17## DESCRIPTION
18
19**socket_write**() attempts to write *buffer_size* bytes to the socket specified
20by *handle*. The pointer to *bytes* may be NULL if *buffer_size* is zero.
21
22If *buffer_size* is zero, a bitwise combination of **ZX_SOCKET_SHUTDOWN_READ** and
23**ZX_SOCKET_SHUTDOWN_WRITE** can be passed to *options* to disable reading or
24writing from a socket endpoint:
25
26 * If **ZX_SOCKET_SHUTDOWN_READ** is passed to *options*, and *buffer_size* is
27   0, then reading is disabled for the socket endpoint at *handle*. All data
28   buffered in the socket at the time of the call can be read, but further reads
29   from this endpoint or writes to the other endpoint of the socket will fail
30   with **ZX_ERR_BAD_STATE**.
31
32 * If **ZX_SOCKET_SHUTDOWN_WRITE** is passed to *options*, and *buffer_size* is
33   0, then writing is disabled for the socket endpoint at *handle*. Further
34   writes to this endpoint or reads from the other endpoint of the socket will
35   fail with **ZX_ERR_BAD_STATE**.
36
37If **ZX_SOCKET_CONTROL** is passed to *options*, then **socket_write**()
38attempts to write into the socket control plane. A write to the control plane is
39never short. If the socket control plane has insufficient space for *buffer*, it
40writes nothing and returns **ZX_ERR_OUT_OF_RANGE**.
41
42If a NULL *actual* is passed in, it will be ignored.
43
44A **ZX_SOCKET_STREAM** socket write can be short if the socket does not have
45enough space for all of *buffer*. If a non-zero amount of data was written to
46the socket, the amount written is returned via *actual* and the call succeeds.
47Otherwise, if the socket was already full, the call returns
48**ZX_ERR_SHOULD_WAIT** and the client should wait (e.g., with
49[object_wait_one](object_wait_one.md) or
50[object_wait_async](object_wait_async.md)). For datagram sockets, attempting to
51write a packet larger than the socket's capacity will fail with
52**ZX_ERR_OUT_OF_RANGE**.
53
54A **ZX_SOCKET_DATAGRAM** socket write is never short. If the socket has
55insufficient space for *buffer*, it writes nothing and returns
56**ZX_ERR_SHOULD_WAIT**. If the write succeeds, *buffer_size* is returned via
57*actual*.
58
59## RIGHTS
60
61TODO(ZX-2399)
62
63## RETURN VALUE
64
65**socket_write**() returns **ZX_OK** on success.
66
67## ERRORS
68
69**ZX_ERR_BAD_HANDLE**  *handle* is not a valid handle.
70
71**ZX_ERR_BAD_STATE**  *options* includes **ZX_SOCKET_CONTROL** and the
72socket was not created with **ZX_SOCKET_HAS_CONTROL**.
73
74**ZX_ERR_WRONG_TYPE**  *handle* is not a socket handle.
75
76**ZX_ERR_INVALID_ARGS**  *buffer* is an invalid pointer,
77**ZX_SOCKET_SHUTDOWN_READ** and/or **ZX_SOCKET_SHUTDOWN_WRITE** was passed to
78*options* but *buffer_size* was not 0, or *options* was not 0 or a combination
79or **ZX_SOCKET_SHUTDOWN_READ** and/or **ZX_SOCKET_SHUTDOWN_WRITE**.
80
81**ZX_ERR_ACCESS_DENIED**  *handle* does not have **ZX_RIGHT_WRITE**.
82
83**ZX_ERR_SHOULD_WAIT**  The buffer underlying the socket is full.
84
85**ZX_ERR_OUT_OF_RANGE**  The socket was created with **ZX_SOCKET_DATAGRAM** and
86*buffer* is larger than the remaining space in the socket.
87
88**ZX_ERR_BAD_STATE**  Writing has been disabled for this socket endpoint.
89
90**ZX_ERR_PEER_CLOSED**  The other side of the socket is closed.
91
92**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
93There is no good way for userspace to handle this (unlikely) error.
94In a future build this error will no longer occur.
95
96## SEE ALSO
97
98[socket_create](socket_create.md),
99[socket_read](socket_read.md).
100