uv_tcp_t
— TCP handle#
TCP handles are used to represent both TCP streams and servers.
uv_tcp_t
is a ‘subclass’ of uv_stream_t
.
Data types#
-
type uv_tcp_t#
TCP handle type.
-
enum uv_tcp_flags#
Flags used in
uv_tcp_bind()
.enum uv_tcp_flags { /* Used with uv_tcp_bind, when an IPv6 address is used. */ UV_TCP_IPV6ONLY = 1, /* Enable SO_REUSEPORT socket option when binding the handle. * This allows completely duplicate bindings by multiple processes * or threads if they all set SO_REUSEPORT before binding the port. * Incoming connections are distributed across the participating * listener sockets. * * This flag is available only on Linux 3.9+, DragonFlyBSD 3.6+, * FreeBSD 12.0+, Solaris 11.4, and AIX 7.2.5+ for now. */ UV_TCP_REUSEPORT = 2, };
Public members#
N/A
See also
The uv_stream_t
members also apply.
API#
-
int uv_tcp_init(uv_loop_t *loop, uv_tcp_t *handle)#
Initialize the handle. No socket is created as of yet.
-
int uv_tcp_init_ex(uv_loop_t *loop, uv_tcp_t *handle, unsigned int flags)#
Initialize the handle with the specified flags. At the moment only the lower 8 bits of the flags parameter are used as the socket domain. A socket will be created for the given domain. If the specified domain is
AF_UNSPEC
no socket is created, just likeuv_tcp_init()
.New in version 1.7.0.
-
int uv_tcp_open(uv_tcp_t *handle, uv_os_sock_t sock)#
Open an existing file descriptor or SOCKET as a TCP handle.
Changed in version 1.2.1: the file descriptor is set to non-blocking mode.
Note
The passed file descriptor or SOCKET is not checked for its type, but it’s required that it represents a valid stream socket.
-
int uv_tcp_nodelay(uv_tcp_t *handle, int enable)#
Enable TCP_NODELAY, which disables Nagle’s algorithm.
-
int uv_tcp_keepalive(uv_tcp_t *handle, int enable, unsigned int delay)#
Enable / disable TCP keep-alive. delay is the initial delay in seconds, ignored when enable is zero.
After delay has been reached, 10 successive probes, each spaced 1 second from the previous one, will still happen. If the connection is still lost at the end of this procedure, then the handle is destroyed with a
UV_ETIMEDOUT
error passed to the corresponding callback.If delay is less than 1 then
UV_EINVAL
is returned.Changed in version 1.49.0: If delay is less than 1 then
UV_EINVAL`
is returned.
-
int uv_tcp_simultaneous_accepts(uv_tcp_t *handle, int enable)#
Enable / disable simultaneous asynchronous accept requests that are queued by the operating system when listening for new TCP connections.
This setting is used to tune a TCP server for the desired performance. Having simultaneous accepts can significantly improve the rate of accepting connections (which is why it is enabled by default) but may lead to uneven load distribution in multi-process setups.
-
int uv_tcp_bind(uv_tcp_t *handle, const struct sockaddr *addr, unsigned int flags)#
Bind the handle to an address and port.
When the port is already taken, you can expect to see an
UV_EADDRINUSE
error fromuv_listen()
oruv_tcp_connect()
unless you specifyUV_TCP_REUSEPORT
in flags for all the binding sockets. That is, a successful call to this function does not guarantee that the call touv_listen()
oruv_tcp_connect()
will succeed as well.- Parameters:
handle – TCP handle. It should have been initialized with
uv_tcp_init()
.addr – Address to bind to. It should point to an initialized
struct sockaddr_in
orstruct sockaddr_in6
.flags – Flags that control the behavior of binding the socket.
UV_TCP_IPV6ONLY
can be contained in flags to disable dual-stack support and only use IPv6.UV_TCP_REUSEPORT
can be contained in flags to enable the socket option SO_REUSEPORT with the capability of load balancing that distribute incoming connections across all listening sockets in multiple processes or threads.
- Returns:
0 on success, or an error code < 0 on failure.
Changed in version 1.49.0: added the
UV_TCP_REUSEPORT
flag.Note
UV_TCP_REUSEPORT
flag is available only on Linux 3.9+, DragonFlyBSD 3.6+, FreeBSD 12.0+, Solaris 11.4, and AIX 7.2.5+ at the moment. On other platforms this function will return an UV_ENOTSUP error.
-
int uv_tcp_getsockname(const uv_tcp_t *handle, struct sockaddr *name, int *namelen)#
Get the current address to which the handle is bound. name must point to a valid and big enough chunk of memory,
struct sockaddr_storage
is recommended for IPv4 and IPv6 support.
-
int uv_tcp_getpeername(const uv_tcp_t *handle, struct sockaddr *name, int *namelen)#
Get the address of the peer connected to the handle. name must point to a valid and big enough chunk of memory,
struct sockaddr_storage
is recommended for IPv4 and IPv6 support.
-
int uv_tcp_connect(uv_connect_t *req, uv_tcp_t *handle, const struct sockaddr *addr, uv_connect_cb cb)#
Establish an IPv4 or IPv6 TCP connection. Provide an initialized TCP handle and an uninitialized
uv_connect_t
. addr should point to an initializedstruct sockaddr_in
orstruct sockaddr_in6
.On Windows if the addr is initialized to point to an unspecified address (
0.0.0.0
or::
) it will be changed to point tolocalhost
. This is done to match the behavior of Linux systems.The callback is made when the connection has been established or when a connection error happened.
Changed in version 1.19.0: added
0.0.0.0
and::
tolocalhost
mapping
See also
The uv_stream_t
API functions also apply.
-
int uv_tcp_close_reset(uv_tcp_t *handle, uv_close_cb close_cb)#
Resets a TCP connection by sending a RST packet. This is accomplished by setting the SO_LINGER socket option with a linger interval of zero and then calling
uv_close()
. Due to some platform inconsistencies, mixing ofuv_shutdown()
anduv_tcp_close_reset()
calls is not allowed.New in version 1.32.0.
-
int uv_socketpair(int type, int protocol, uv_os_sock_t socket_vector[2], int flags0, int flags1)#
Create a pair of connected sockets with the specified properties. The resulting handles can be passed to uv_tcp_open, used with uv_spawn, or for any other purpose.
Valid values for flags0 and flags1 are:
UV_NONBLOCK_PIPE: Opens the specified socket handle for OVERLAPPED or FIONBIO/O_NONBLOCK I/O usage. This is recommended for handles that will be used by libuv, and not usually recommended otherwise.
Equivalent to socketpair(2) with a domain of AF_UNIX.
New in version 1.41.0.