1 2.. _tcp: 3 4:c:type:`uv_tcp_t` --- TCP handle 5================================= 6 7TCP handles are used to represent both TCP streams and servers. 8 9:c:type:`uv_tcp_t` is a 'subclass' of :c:type:`uv_stream_t`. 10 11 12Data types 13---------- 14 15.. c:type:: uv_tcp_t 16 17 TCP handle type. 18 19 20Public members 21^^^^^^^^^^^^^^ 22 23N/A 24 25.. seealso:: The :c:type:`uv_stream_t` members also apply. 26 27 28API 29--- 30 31.. c:function:: int uv_tcp_init(uv_loop_t* loop, uv_tcp_t* handle) 32 33 Initialize the handle. No socket is created as of yet. 34 35.. c:function:: int uv_tcp_init_ex(uv_loop_t* loop, uv_tcp_t* handle, unsigned int flags) 36 37 Initialize the handle with the specified flags. At the moment only the lower 8 bits 38 of the `flags` parameter are used as the socket domain. A socket will be created 39 for the given domain. If the specified domain is ``AF_UNSPEC`` no socket is created, 40 just like :c:func:`uv_tcp_init`. 41 42 .. versionadded:: 1.7.0 43 44.. c:function:: int uv_tcp_open(uv_tcp_t* handle, uv_os_sock_t sock) 45 46 Open an existing file descriptor or SOCKET as a TCP handle. 47 48 .. versionchanged:: 1.2.1 the file descriptor is set to non-blocking mode. 49 50 .. note:: 51 The passed file descriptor or SOCKET is not checked for its type, but 52 it's required that it represents a valid stream socket. 53 54.. c:function:: int uv_tcp_nodelay(uv_tcp_t* handle, int enable) 55 56 Enable `TCP_NODELAY`, which disables Nagle's algorithm. 57 58.. c:function:: int uv_tcp_keepalive(uv_tcp_t* handle, int enable, unsigned int delay) 59 60 Enable / disable TCP keep-alive. `delay` is the initial delay in seconds, 61 ignored when `enable` is zero. 62 63 After `delay` has been reached, 10 successive probes, each spaced 1 second 64 from the previous one, will still happen. If the connection is still lost 65 at the end of this procedure, then the handle is destroyed with a 66 ``UV_ETIMEDOUT`` error passed to the corresponding callback. 67 68 If `delay` is less than 1 then ``UV_EINVAL`` is returned. 69 70 .. versionchanged:: 1.49.0 If `delay` is less than 1 then ``UV_EINVAL``` is returned. 71 72.. c:function:: int uv_tcp_simultaneous_accepts(uv_tcp_t* handle, int enable) 73 74 Enable / disable simultaneous asynchronous accept requests that are 75 queued by the operating system when listening for new TCP connections. 76 77 This setting is used to tune a TCP server for the desired performance. 78 Having simultaneous accepts can significantly improve the rate of accepting 79 connections (which is why it is enabled by default) but may lead to uneven 80 load distribution in multi-process setups. 81 82.. c:function:: int uv_tcp_bind(uv_tcp_t* handle, const struct sockaddr* addr, unsigned int flags) 83 84 Bind the handle to an address and port. `addr` should point to an 85 initialized ``struct sockaddr_in`` or ``struct sockaddr_in6``. 86 87 When the port is already taken, you can expect to see an ``UV_EADDRINUSE`` 88 error from :c:func:`uv_listen` or :c:func:`uv_tcp_connect`. That is, 89 a successful call to this function does not guarantee that the call 90 to :c:func:`uv_listen` or :c:func:`uv_tcp_connect` will succeed as well. 91 92 `flags` can contain ``UV_TCP_IPV6ONLY``, in which case dual-stack support 93 is disabled and only IPv6 is used. 94 95.. c:function:: int uv_tcp_getsockname(const uv_tcp_t* handle, struct sockaddr* name, int* namelen) 96 97 Get the current address to which the handle is bound. `name` must point to 98 a valid and big enough chunk of memory, ``struct sockaddr_storage`` is 99 recommended for IPv4 and IPv6 support. 100 101.. c:function:: int uv_tcp_getpeername(const uv_tcp_t* handle, struct sockaddr* name, int* namelen) 102 103 Get the address of the peer connected to the handle. `name` must point to 104 a valid and big enough chunk of memory, ``struct sockaddr_storage`` is 105 recommended for IPv4 and IPv6 support. 106 107.. c:function:: int uv_tcp_connect(uv_connect_t* req, uv_tcp_t* handle, const struct sockaddr* addr, uv_connect_cb cb) 108 109 Establish an IPv4 or IPv6 TCP connection. Provide an initialized TCP handle 110 and an uninitialized :c:type:`uv_connect_t`. `addr` should point to an 111 initialized ``struct sockaddr_in`` or ``struct sockaddr_in6``. 112 113 On Windows if the `addr` is initialized to point to an unspecified address 114 (``0.0.0.0`` or ``::``) it will be changed to point to ``localhost``. 115 This is done to match the behavior of Linux systems. 116 117 The callback is made when the connection has been established or when a 118 connection error happened. 119 120 .. versionchanged:: 1.19.0 added ``0.0.0.0`` and ``::`` to ``localhost`` 121 mapping 122 123.. seealso:: The :c:type:`uv_stream_t` API functions also apply. 124 125.. c:function:: int uv_tcp_close_reset(uv_tcp_t* handle, uv_close_cb close_cb) 126 127 Resets a TCP connection by sending a RST packet. This is accomplished by 128 setting the `SO_LINGER` socket option with a linger interval of zero and 129 then calling :c:func:`uv_close`. 130 Due to some platform inconsistencies, mixing of :c:func:`uv_shutdown` and 131 :c:func:`uv_tcp_close_reset` calls is not allowed. 132 133 .. versionadded:: 1.32.0 134 135.. c:function:: int uv_socketpair(int type, int protocol, uv_os_sock_t socket_vector[2], int flags0, int flags1) 136 137 Create a pair of connected sockets with the specified properties. 138 The resulting handles can be passed to `uv_tcp_open`, used with `uv_spawn`, 139 or for any other purpose. 140 141 Valid values for `flags0` and `flags1` are: 142 143 - UV_NONBLOCK_PIPE: Opens the specified socket handle for `OVERLAPPED` 144 or `FIONBIO`/`O_NONBLOCK` I/O usage. 145 This is recommended for handles that will be used by libuv, 146 and not usually recommended otherwise. 147 148 Equivalent to :man:`socketpair(2)` with a domain of AF_UNIX. 149 150 .. versionadded:: 1.41.0 151
