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