1# Socket
2
3## NAME
4
5Socket - Bidirectional streaming IPC transport
6
7## SYNOPSIS
8
9Sockets are a bidirectional stream transport. Unlike channels, sockets
10only move data (not handles).
11
12## DESCRIPTION
13
14Data is written into one end of a socket via *zx_socket_write* and
15read from the opposing end via *zx_socket_read*.
16
17Upon creation, both ends of the socket are writable and readable. Via the
18**ZX_SOCKET_SHUTDOWN_READ** and **ZX_SOCKET_SHUTDOWN_WRITE** options to
19*zx_socket_shutdown*, one end of the socket can be closed for reading and/or
20writing.
21
22## PROPERTIES
23
24The following properties may be queried from a socket object:
25
26**ZX_PROP_SOCKET_RX_THRESHOLD** size of the read threshold of a socket, in
27bytes. When the bytes queued on the socket (available for reading) is equal to
28or greater than this value, the ZX_SOCKET_READ_THRESHOLD signal is asserted.
29Read threshold signalling is disabled by default (and when set, writing
30a value of 0 for this property disables it).
31
32**ZX_PROP_SOCKET_TX_THRESHOLD** size of the write threshold of a socket,
33in bytes. When the space available for writing on the socket is equal to or
34greater than this value, the ZX_SOCKET_WRITE_THRESHOLD signal is asserted.
35Write threshold signalling is disabled by default (and when set, writing a
36value of 0 for this property disables it).
37
38From the point of view of a socket handle, the receive buffer contains the data
39that is readable via **zx_socket_read**() from that handle (having been written
40from the opposing handle), and the transmit buffer contains the data that is
41written via **zx_socket_write**() to that handle (and readable from the opposing
42handle).
43
44## SIGNALS
45
46The following signals may be set for a socket object:
47
48**ZX_SOCKET_READABLE** data is available to read from the socket
49
50**ZX_SOCKET_WRITABLE** data may be written to the socket
51
52**ZX_SOCKET_PEER_CLOSED** the other endpoint of this socket has
53been closed.
54
55**ZX_SOCKET_PEER_WRITE_DISABLED** writing is disabled permanently for the other
56endpoint either because of passing **ZX_SOCKET_SHUTDOWN_READ** to this endpoint
57or passing **ZX_SOCKET_SHUTDOWN_WRITE** to the peer. Reads on a socket endpoint
58with this signal raised will succeed so long as there is data in the socket that
59was written before writing was disabled.
60
61**ZX_SOCKET_WRITE_DISABLED** writing is disabled permanently for this endpoint
62either because of passing **ZX_SOCKET_SHUTDOWN_WRITE** to this endpoint or
63passing **ZX_SOCKET_SHUTDOWN_READ** to the peer.
64
65**ZX_SOCKET_CONTROL_READABLE** data is available to read from the
66socket control plane.
67
68**ZX_SOCKET_CONTROL_WRITABLE** data may be written to the socket control plane.
69
70**ZX_SOCKET_SHARE** a socket may be sent via *zx_socket_share*.
71
72**ZX_SOCKET_ACCEPT** a socket may be received via *zx_socket_accept*.
73
74**ZX_SOCKET_READ_THRESHOLD** data queued up on socket for reading exceeds
75the read threshold.
76
77**ZX_SOCKET_WRITE_THRESHOLD** space available on the socket for writing exceeds
78the write threshold.
79
80## SYSCALLS
81
82+ [socket_accept](../syscalls/socket_accept.md) - receive a socket via a socket
83+ [socket_create](../syscalls/socket_create.md) - create a new socket
84+ [socket_read](../syscalls/socket_read.md) - read data from a socket
85+ [socket_share](../syscalls/socket_share.md) - share a socket via a socket
86+ [socket_shutdown](../syscalls/socket_shutdown.md) - prevent reading or writing
87+ [socket_write](../syscalls/socket_write.md) - write data to a socket
88