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