Mercurial

comparison third_party/libuv/docs/src/tcp.rst @ 160:948de3f54cea

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ThirdParty] Added libuv
author June Park <parkjune1995@gmail.com>
date Wed, 14 Jan 2026 19:39:52 -0800
parents
children
comparison
equal deleted inserted replaced
159:05cf9467a1c3 160:948de3f54cea
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