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