blob: b2101cce83fcaf3f62e396f681dfa7f438922091 [file] [log] [blame] [view]
# Socket
## NAME
Socket - Bidirectional streaming IPC transport
## SYNOPSIS
Sockets are a bidirectional stream transport. Unlike channels, sockets
only move data (not handles).
## DESCRIPTION
Data is written into one end of a socket via [`zx_socket_write()`] and
read from the opposing end via [`zx_socket_read()`].
Upon creation, both ends of the socket are writable and readable. Via the
**ZX_SOCKET_SHUTDOWN_READ** and **ZX_SOCKET_SHUTDOWN_WRITE** options to
[`zx_socket_shutdown()`], one end of the socket can be closed for reading and/or
writing.
## PROPERTIES
The following properties may be queried from a socket object:
**ZX_PROP_SOCKET_RX_THRESHOLD** size of the read threshold of a socket, in
bytes. When the bytes queued on the socket (available for reading) is equal to
or greater than this value, the **ZX_SOCKET_READ_THRESHOLD** signal is asserted.
Read threshold signalling is disabled by default (and when set, writing
a value of 0 for this property disables it).
**ZX_PROP_SOCKET_TX_THRESHOLD** size of the write threshold of a socket,
in bytes. When the space available for writing on the socket is equal to or
greater than this value, the **ZX_SOCKET_WRITE_THRESHOLD** signal is asserted.
Write threshold signalling is disabled by default (and when set, writing a
value of 0 for this property disables it).
From the point of view of a socket handle, the receive buffer contains the data
that is readable via [`zx_socket_read()`] from that handle (having been written
from the opposing handle), and the transmit buffer contains the data that is
written via [`zx_socket_write()`] to that handle (and readable from the opposing
handle).
## SIGNALS
The following signals may be set for a socket object:
**ZX_SOCKET_READABLE** data is available to read from the socket
**ZX_SOCKET_WRITABLE** data may be written to the socket
**ZX_SOCKET_PEER_CLOSED** the other endpoint of this socket has
been closed.
**ZX_SOCKET_PEER_WRITE_DISABLED** writing is disabled permanently for the other
endpoint either because of passing **ZX_SOCKET_SHUTDOWN_READ** to this endpoint
or passing **ZX_SOCKET_SHUTDOWN_WRITE** to the peer. Reads on a socket endpoint
with this signal raised will succeed so long as there is data in the socket that
was written before writing was disabled.
**ZX_SOCKET_WRITE_DISABLED** writing is disabled permanently for this endpoint
either because of passing **ZX_SOCKET_SHUTDOWN_WRITE** to this endpoint or
passing **ZX_SOCKET_SHUTDOWN_READ** to the peer.
**ZX_SOCKET_READ_THRESHOLD** data queued up on socket for reading exceeds
the read threshold.
**ZX_SOCKET_WRITE_THRESHOLD** space available on the socket for writing exceeds
the write threshold.
## SYSCALLS
- [`zx_socket_create()`] - create a new socket
- [`zx_socket_read()`] - read data from a socket
- [`zx_socket_shutdown()`] - prevent reading or writing
- [`zx_socket_write()`] - write data to a socket
[`zx_socket_create()`]: /docs/reference/syscalls/socket_create.md
[`zx_socket_read()`]: /docs/reference/syscalls/socket_read.md
[`zx_socket_shutdown()`]: /docs/reference/syscalls/socket_shutdown.md
[`zx_socket_write()`]: /docs/reference/syscalls/socket_write.md