1# zx_socket_read
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7socket_read - read data from 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_read(zx_handle_t handle,
17                           uint32_t options,
18                           void* buffer,
19                           size_t buffer_size,
20                           size_t* actual);
21```
22
23## DESCRIPTION
24
25`zx_socket_read()` attempts to read *buffer_size* bytes into *buffer*. If
26successful, the number of bytes actually read are return via
27*actual*.
28
29If a NULL *actual* is passed in, it will be ignored.
30
31If the socket was created with **ZX_SOCKET_DATAGRAM**, this syscall reads
32only the first available datagram in the socket (if one is present).
33If *buffer* is too small for the datagram, then the read will be
34truncated, and any remaining bytes in the datagram will be discarded.
35
36If *options* is set to **ZX_SOCKET_CONTROL**, then `zx_socket_read()`
37attempts to read from the socket control plane.
38
39To determine how many bytes are available to read, use the **rx_buf_available**
40field of the resulting `zx_info_socket_t`, which you can obtain using the
41**ZX_INFO_SOCKET** topic for [`zx_object_get_info()`].
42
43## RIGHTS
44
45<!-- Updated by update-docs-from-abigen, do not edit. -->
46
47*handle* must be of type **ZX_OBJ_TYPE_SOCKET** and have **ZX_RIGHT_READ**.
48
49## RETURN VALUE
50
51`zx_socket_read()` returns **ZX_OK** on success, and writes into
52*actual* (if non-NULL) the exact number of bytes read.
53
54## ERRORS
55
56**ZX_ERR_BAD_HANDLE**  *handle* is not a valid handle.
57
58**ZX_ERR_BAD_STATE** Either (a) *options* includes **ZX_SOCKET_CONTROL** and the
59socket was not created with **ZX_SOCKET_HAS_CONTROL**, or (b) reading has been
60disabled for this socket endpoint.
61
62**ZX_ERR_WRONG_TYPE**  *handle* is not a socket handle.
63
64**ZX_ERR_INVALID_ARGS** If any of *buffer* or *actual* are non-NULL
65but invalid pointers, or if *buffer* is NULL, or if *options* is not either zero
66or **ZX_SOCKET_CONTROL**.
67
68**ZX_ERR_ACCESS_DENIED**  *handle* does not have **ZX_RIGHT_READ**.
69
70**ZX_ERR_SHOULD_WAIT**  The socket contained no data to read.
71
72**ZX_ERR_PEER_CLOSED**  The other side of the socket is closed and no data is
73readable.
74
75## SEE ALSO
76
77 - [`zx_socket_accept()`]
78 - [`zx_socket_create()`]
79 - [`zx_socket_share()`]
80 - [`zx_socket_shutdown()`]
81 - [`zx_socket_write()`]
82
83<!-- References updated by update-docs-from-abigen, do not edit. -->
84
85[`zx_object_get_info()`]: object_get_info.md
86[`zx_socket_accept()`]: socket_accept.md
87[`zx_socket_create()`]: socket_create.md
88[`zx_socket_share()`]: socket_share.md
89[`zx_socket_shutdown()`]: socket_shutdown.md
90[`zx_socket_write()`]: socket_write.md
91