tokio/net/tcp/socket.rs
1use crate::net::{TcpListener, TcpStream};
2
3use std::fmt;
4use std::io;
5use std::net::SocketAddr;
6
7#[cfg(unix)]
8use std::os::unix::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, RawFd};
9use std::time::Duration;
10
11cfg_windows! {
12 use crate::os::windows::io::{AsRawSocket, FromRawSocket, IntoRawSocket, RawSocket, AsSocket, BorrowedSocket};
13}
14
15cfg_net! {
16 /// A TCP socket that has not yet been converted to a `TcpStream` or
17 /// `TcpListener`.
18 ///
19 /// `TcpSocket` wraps an operating system socket and enables the caller to
20 /// configure the socket before establishing a TCP connection or accepting
21 /// inbound connections. The caller is able to set socket option and explicitly
22 /// bind the socket with a socket address.
23 ///
24 /// The underlying socket is closed when the `TcpSocket` value is dropped.
25 ///
26 /// `TcpSocket` should only be used directly if the default configuration used
27 /// by `TcpStream::connect` and `TcpListener::bind` does not meet the required
28 /// use case.
29 ///
30 /// Calling `TcpStream::connect("127.0.0.1:8080")` is equivalent to:
31 ///
32 /// ```no_run
33 /// use tokio::net::TcpSocket;
34 ///
35 /// use std::io;
36 ///
37 /// #[tokio::main]
38 /// async fn main() -> io::Result<()> {
39 /// let addr = "127.0.0.1:8080".parse().unwrap();
40 ///
41 /// let socket = TcpSocket::new_v4()?;
42 /// let stream = socket.connect(addr).await?;
43 /// # drop(stream);
44 ///
45 /// Ok(())
46 /// }
47 /// ```
48 ///
49 /// Calling `TcpListener::bind("127.0.0.1:8080")` is equivalent to:
50 ///
51 /// ```no_run
52 /// use tokio::net::TcpSocket;
53 ///
54 /// use std::io;
55 ///
56 /// #[tokio::main]
57 /// async fn main() -> io::Result<()> {
58 /// let addr = "127.0.0.1:8080".parse().unwrap();
59 ///
60 /// let socket = TcpSocket::new_v4()?;
61 /// // On platforms with Berkeley-derived sockets, this allows to quickly
62 /// // rebind a socket, without needing to wait for the OS to clean up the
63 /// // previous one.
64 /// //
65 /// // On Windows, this allows rebinding sockets which are actively in use,
66 /// // which allows "socket hijacking", so we explicitly don't set it here.
67 /// // https://docs.microsoft.com/en-us/windows/win32/winsock/using-so-reuseaddr-and-so-exclusiveaddruse
68 /// socket.set_reuseaddr(true)?;
69 /// socket.bind(addr)?;
70 ///
71 /// // Note: the actual backlog used by `TcpListener::bind` is platform-dependent,
72 /// // as Tokio relies on Mio's default backlog value configuration. The `1024` here is only
73 /// // illustrative and does not reflect the real value used.
74 /// let listener = socket.listen(1024)?;
75 /// # drop(listener);
76 ///
77 /// Ok(())
78 /// }
79 /// ```
80 ///
81 /// Setting socket options not explicitly provided by `TcpSocket` may be done by
82 /// accessing the `RawFd`/`RawSocket` using [`AsRawFd`]/[`AsRawSocket`] and
83 /// setting the option with a crate like [`socket2`].
84 ///
85 /// [`RawFd`]: https://doc.rust-lang.org/std/os/fd/type.RawFd.html
86 /// [`RawSocket`]: https://doc.rust-lang.org/std/os/windows/io/type.RawSocket.html
87 /// [`AsRawFd`]: https://doc.rust-lang.org/std/os/fd/trait.AsRawFd.html
88 /// [`AsRawSocket`]: https://doc.rust-lang.org/std/os/windows/io/trait.AsRawSocket.html
89 /// [`socket2`]: https://docs.rs/socket2/
90 #[cfg_attr(docsrs, doc(alias = "connect_std"))]
91 pub struct TcpSocket {
92 inner: socket2::Socket,
93 }
94}
95
96impl TcpSocket {
97 /// Creates a new socket configured for IPv4.
98 ///
99 /// Calls `socket(2)` with `AF_INET` and `SOCK_STREAM`.
100 ///
101 /// # Returns
102 ///
103 /// On success, the newly created `TcpSocket` is returned. If an error is
104 /// encountered, it is returned instead.
105 ///
106 /// # Examples
107 ///
108 /// Create a new IPv4 socket and start listening.
109 ///
110 /// ```no_run
111 /// use tokio::net::TcpSocket;
112 ///
113 /// use std::io;
114 ///
115 /// #[tokio::main]
116 /// async fn main() -> io::Result<()> {
117 /// let addr = "127.0.0.1:8080".parse().unwrap();
118 /// let socket = TcpSocket::new_v4()?;
119 /// socket.bind(addr)?;
120 ///
121 /// let listener = socket.listen(128)?;
122 /// # drop(listener);
123 /// Ok(())
124 /// }
125 /// ```
126 pub fn new_v4() -> io::Result<TcpSocket> {
127 TcpSocket::new(socket2::Domain::IPV4)
128 }
129
130 /// Creates a new socket configured for IPv6.
131 ///
132 /// Calls `socket(2)` with `AF_INET6` and `SOCK_STREAM`.
133 ///
134 /// # Returns
135 ///
136 /// On success, the newly created `TcpSocket` is returned. If an error is
137 /// encountered, it is returned instead.
138 ///
139 /// # Examples
140 ///
141 /// Create a new IPv6 socket and start listening.
142 ///
143 /// ```no_run
144 /// use tokio::net::TcpSocket;
145 ///
146 /// use std::io;
147 ///
148 /// #[tokio::main]
149 /// async fn main() -> io::Result<()> {
150 /// let addr = "[::1]:8080".parse().unwrap();
151 /// let socket = TcpSocket::new_v6()?;
152 /// socket.bind(addr)?;
153 ///
154 /// let listener = socket.listen(128)?;
155 /// # drop(listener);
156 /// Ok(())
157 /// }
158 /// ```
159 pub fn new_v6() -> io::Result<TcpSocket> {
160 TcpSocket::new(socket2::Domain::IPV6)
161 }
162
163 fn new(domain: socket2::Domain) -> io::Result<TcpSocket> {
164 let ty = socket2::Type::STREAM;
165 #[cfg(any(
166 target_os = "android",
167 target_os = "dragonfly",
168 target_os = "freebsd",
169 target_os = "fuchsia",
170 target_os = "illumos",
171 target_os = "linux",
172 target_os = "netbsd",
173 target_os = "openbsd"
174 ))]
175 let ty = ty.nonblocking();
176 let inner = socket2::Socket::new(domain, ty, Some(socket2::Protocol::TCP))?;
177 #[cfg(not(any(
178 target_os = "android",
179 target_os = "dragonfly",
180 target_os = "freebsd",
181 target_os = "fuchsia",
182 target_os = "illumos",
183 target_os = "linux",
184 target_os = "netbsd",
185 target_os = "openbsd"
186 )))]
187 inner.set_nonblocking(true)?;
188 Ok(TcpSocket { inner })
189 }
190
191 /// Sets value for the `SO_KEEPALIVE` option on this socket.
192 pub fn set_keepalive(&self, keepalive: bool) -> io::Result<()> {
193 self.inner.set_keepalive(keepalive)
194 }
195
196 /// Gets the value of the `SO_KEEPALIVE` option on this socket.
197 pub fn keepalive(&self) -> io::Result<bool> {
198 self.inner.keepalive()
199 }
200
201 /// Allows the socket to bind to an in-use address.
202 ///
203 /// Behavior is platform specific. Refer to the target platform's
204 /// documentation for more details.
205 ///
206 /// # Examples
207 ///
208 /// ```no_run
209 /// use tokio::net::TcpSocket;
210 ///
211 /// use std::io;
212 ///
213 /// #[tokio::main]
214 /// async fn main() -> io::Result<()> {
215 /// let addr = "127.0.0.1:8080".parse().unwrap();
216 ///
217 /// let socket = TcpSocket::new_v4()?;
218 /// socket.set_reuseaddr(true)?;
219 /// socket.bind(addr)?;
220 ///
221 /// let listener = socket.listen(1024)?;
222 /// # drop(listener);
223 ///
224 /// Ok(())
225 /// }
226 /// ```
227 pub fn set_reuseaddr(&self, reuseaddr: bool) -> io::Result<()> {
228 self.inner.set_reuse_address(reuseaddr)
229 }
230
231 /// Retrieves the value set for `SO_REUSEADDR` on this socket.
232 ///
233 /// # Examples
234 ///
235 /// ```no_run
236 /// use tokio::net::TcpSocket;
237 ///
238 /// use std::io;
239 ///
240 /// #[tokio::main]
241 /// async fn main() -> io::Result<()> {
242 /// let addr = "127.0.0.1:8080".parse().unwrap();
243 ///
244 /// let socket = TcpSocket::new_v4()?;
245 /// socket.set_reuseaddr(true)?;
246 /// assert!(socket.reuseaddr().unwrap());
247 /// socket.bind(addr)?;
248 ///
249 /// let listener = socket.listen(1024)?;
250 /// Ok(())
251 /// }
252 /// ```
253 pub fn reuseaddr(&self) -> io::Result<bool> {
254 self.inner.reuse_address()
255 }
256
257 /// Allows the socket to bind to an in-use port. Only available for unix systems
258 /// (excluding Solaris, Illumos, and Cygwin).
259 ///
260 /// Behavior is platform specific. Refer to the target platform's
261 /// documentation for more details.
262 ///
263 /// # Examples
264 ///
265 /// ```no_run
266 /// use tokio::net::TcpSocket;
267 ///
268 /// use std::io;
269 ///
270 /// #[tokio::main]
271 /// async fn main() -> io::Result<()> {
272 /// let addr = "127.0.0.1:8080".parse().unwrap();
273 ///
274 /// let socket = TcpSocket::new_v4()?;
275 /// socket.set_reuseport(true)?;
276 /// socket.bind(addr)?;
277 ///
278 /// let listener = socket.listen(1024)?;
279 /// Ok(())
280 /// }
281 /// ```
282 #[cfg(all(
283 unix,
284 not(target_os = "solaris"),
285 not(target_os = "illumos"),
286 not(target_os = "cygwin"),
287 ))]
288 #[cfg_attr(
289 docsrs,
290 doc(cfg(all(
291 unix,
292 not(target_os = "solaris"),
293 not(target_os = "illumos"),
294 not(target_os = "cygwin"),
295 )))
296 )]
297 pub fn set_reuseport(&self, reuseport: bool) -> io::Result<()> {
298 self.inner.set_reuse_port(reuseport)
299 }
300
301 /// Allows the socket to bind to an in-use port. Only available for unix systems
302 /// (excluding Solaris, Illumos, and Cygwin).
303 ///
304 /// Behavior is platform specific. Refer to the target platform's
305 /// documentation for more details.
306 ///
307 /// # Examples
308 ///
309 /// ```no_run
310 /// use tokio::net::TcpSocket;
311 ///
312 /// use std::io;
313 ///
314 /// #[tokio::main]
315 /// async fn main() -> io::Result<()> {
316 /// let addr = "127.0.0.1:8080".parse().unwrap();
317 ///
318 /// let socket = TcpSocket::new_v4()?;
319 /// socket.set_reuseport(true)?;
320 /// assert!(socket.reuseport().unwrap());
321 /// socket.bind(addr)?;
322 ///
323 /// let listener = socket.listen(1024)?;
324 /// Ok(())
325 /// }
326 /// ```
327 #[cfg(all(
328 unix,
329 not(target_os = "solaris"),
330 not(target_os = "illumos"),
331 not(target_os = "cygwin"),
332 ))]
333 #[cfg_attr(
334 docsrs,
335 doc(cfg(all(
336 unix,
337 not(target_os = "solaris"),
338 not(target_os = "illumos"),
339 not(target_os = "cygwin"),
340 )))
341 )]
342 pub fn reuseport(&self) -> io::Result<bool> {
343 self.inner.reuse_port()
344 }
345
346 /// Sets the size of the TCP send buffer on this socket.
347 ///
348 /// On most operating systems, this sets the `SO_SNDBUF` socket option.
349 pub fn set_send_buffer_size(&self, size: u32) -> io::Result<()> {
350 self.inner.set_send_buffer_size(size as usize)
351 }
352
353 /// Returns the size of the TCP send buffer for this socket.
354 ///
355 /// On most operating systems, this is the value of the `SO_SNDBUF` socket
356 /// option.
357 ///
358 /// Note that if [`set_send_buffer_size`] has been called on this socket
359 /// previously, the value returned by this function may not be the same as
360 /// the argument provided to `set_send_buffer_size`. This is for the
361 /// following reasons:
362 ///
363 /// * Most operating systems have minimum and maximum allowed sizes for the
364 /// send buffer, and will clamp the provided value if it is below the
365 /// minimum or above the maximum. The minimum and maximum buffer sizes are
366 /// OS-dependent.
367 /// * Linux will double the buffer size to account for internal bookkeeping
368 /// data, and returns the doubled value from `getsockopt(2)`. As per `man
369 /// 7 socket`:
370 /// > Sets or gets the maximum socket send buffer in bytes. The
371 /// > kernel doubles this value (to allow space for bookkeeping
372 /// > overhead) when it is set using `setsockopt(2)`, and this doubled
373 /// > value is returned by `getsockopt(2)`.
374 ///
375 /// [`set_send_buffer_size`]: #method.set_send_buffer_size
376 pub fn send_buffer_size(&self) -> io::Result<u32> {
377 self.inner.send_buffer_size().map(|n| n as u32)
378 }
379
380 /// Sets the size of the TCP receive buffer on this socket.
381 ///
382 /// On most operating systems, this sets the `SO_RCVBUF` socket option.
383 pub fn set_recv_buffer_size(&self, size: u32) -> io::Result<()> {
384 self.inner.set_recv_buffer_size(size as usize)
385 }
386
387 /// Returns the size of the TCP receive buffer for this socket.
388 ///
389 /// On most operating systems, this is the value of the `SO_RCVBUF` socket
390 /// option.
391 ///
392 /// Note that if [`set_recv_buffer_size`] has been called on this socket
393 /// previously, the value returned by this function may not be the same as
394 /// the argument provided to `set_recv_buffer_size`. This is for the
395 /// following reasons:
396 ///
397 /// * Most operating systems have minimum and maximum allowed sizes for the
398 /// receive buffer, and will clamp the provided value if it is below the
399 /// minimum or above the maximum. The minimum and maximum buffer sizes are
400 /// OS-dependent.
401 /// * Linux will double the buffer size to account for internal bookkeeping
402 /// data, and returns the doubled value from `getsockopt(2)`. As per `man
403 /// 7 socket`:
404 /// > Sets or gets the maximum socket send buffer in bytes. The
405 /// > kernel doubles this value (to allow space for bookkeeping
406 /// > overhead) when it is set using `setsockopt(2)`, and this doubled
407 /// > value is returned by `getsockopt(2)`.
408 ///
409 /// [`set_recv_buffer_size`]: #method.set_recv_buffer_size
410 pub fn recv_buffer_size(&self) -> io::Result<u32> {
411 self.inner.recv_buffer_size().map(|n| n as u32)
412 }
413
414 /// Sets the linger duration of this socket by setting the `SO_LINGER` option.
415 ///
416 /// This option controls the action taken when a stream has unsent messages and the stream is
417 /// closed. If `SO_LINGER` is set, the system shall block the process until it can transmit the
418 /// data or until the time expires.
419 ///
420 /// If `SO_LINGER` is not specified, and the socket is closed, the system handles the call in a
421 /// way that allows the process to continue as quickly as possible.
422 ///
423 /// This option is deprecated because setting `SO_LINGER` on a socket used with Tokio is always
424 /// incorrect as it leads to blocking the thread when the socket is closed. For more details,
425 /// please see:
426 ///
427 /// > Volumes of communications have been devoted to the intricacies of `SO_LINGER` versus
428 /// > non-blocking (`O_NONBLOCK`) sockets. From what I can tell, the final word is: don't do
429 /// > it. Rely on the `shutdown()`-followed-by-`read()`-eof technique instead.
430 /// >
431 /// > From [The ultimate `SO_LINGER` page, or: why is my tcp not reliable](https://blog.netherlabs.nl/articles/2009/01/18/the-ultimate-so_linger-page-or-why-is-my-tcp-not-reliable)
432 #[deprecated = "`SO_LINGER` causes the socket to block the thread on drop"]
433 pub fn set_linger(&self, dur: Option<Duration>) -> io::Result<()> {
434 self.inner.set_linger(dur)
435 }
436
437 /// Reads the linger duration for this socket by getting the `SO_LINGER`
438 /// option.
439 ///
440 /// For more information about this option, see [`set_linger`].
441 ///
442 /// [`set_linger`]: TcpSocket::set_linger
443 pub fn linger(&self) -> io::Result<Option<Duration>> {
444 self.inner.linger()
445 }
446
447 /// Sets the value of the `TCP_NODELAY` option on this socket.
448 ///
449 /// If set, this option disables the Nagle algorithm. This means that segments are always
450 /// sent as soon as possible, even if there is only a small amount of data. When not set,
451 /// data is buffered until there is a sufficient amount to send out, thereby avoiding
452 /// the frequent sending of small packets.
453 ///
454 /// # Examples
455 ///
456 /// ```no_run
457 /// use tokio::net::TcpSocket;
458 ///
459 /// # async fn dox() -> Result<(), Box<dyn std::error::Error>> {
460 /// let socket = TcpSocket::new_v4()?;
461 ///
462 /// socket.set_nodelay(true)?;
463 /// # Ok(())
464 /// # }
465 /// ```
466 pub fn set_nodelay(&self, nodelay: bool) -> io::Result<()> {
467 self.inner.set_tcp_nodelay(nodelay)
468 }
469
470 /// Gets the value of the `TCP_NODELAY` option on this socket.
471 ///
472 /// For more information about this option, see [`set_nodelay`].
473 ///
474 /// [`set_nodelay`]: TcpSocket::set_nodelay
475 ///
476 /// # Examples
477 ///
478 /// ```no_run
479 /// use tokio::net::TcpSocket;
480 ///
481 /// # async fn dox() -> Result<(), Box<dyn std::error::Error>> {
482 /// let socket = TcpSocket::new_v4()?;
483 ///
484 /// println!("{:?}", socket.nodelay()?);
485 /// # Ok(())
486 /// # }
487 /// ```
488 pub fn nodelay(&self) -> io::Result<bool> {
489 self.inner.tcp_nodelay()
490 }
491
492 /// Gets the value of the `IP_TOS` option for this socket.
493 ///
494 /// For more information about this option, see [`set_tos`].
495 ///
496 /// **NOTE:** On Windows, `IP_TOS` is only supported on [Windows 8+ or
497 /// Windows Server 2012+.](https://docs.microsoft.com/en-us/windows/win32/winsock/ipproto-ip-socket-options)
498 ///
499 /// [`set_tos`]: Self::set_tos
500 // https://docs.rs/socket2/0.5.3/src/socket2/socket.rs.html#1464
501 #[cfg(not(any(
502 target_os = "fuchsia",
503 target_os = "redox",
504 target_os = "solaris",
505 target_os = "illumos",
506 target_os = "haiku"
507 )))]
508 #[cfg_attr(
509 docsrs,
510 doc(cfg(not(any(
511 target_os = "fuchsia",
512 target_os = "redox",
513 target_os = "solaris",
514 target_os = "illumos",
515 target_os = "haiku"
516 ))))
517 )]
518 pub fn tos(&self) -> io::Result<u32> {
519 self.inner.tos_v4()
520 }
521
522 /// Sets the value for the `IP_TOS` option on this socket.
523 ///
524 /// This value sets the type-of-service field that is used in every packet
525 /// sent from this socket.
526 ///
527 /// **NOTE:** On Windows, `IP_TOS` is only supported on [Windows 8+ or
528 /// Windows Server 2012+.](https://docs.microsoft.com/en-us/windows/win32/winsock/ipproto-ip-socket-options)
529 // https://docs.rs/socket2/0.5.3/src/socket2/socket.rs.html#1446
530 #[cfg(not(any(
531 target_os = "fuchsia",
532 target_os = "redox",
533 target_os = "solaris",
534 target_os = "illumos",
535 target_os = "haiku"
536 )))]
537 #[cfg_attr(
538 docsrs,
539 doc(cfg(not(any(
540 target_os = "fuchsia",
541 target_os = "redox",
542 target_os = "solaris",
543 target_os = "illumos",
544 target_os = "haiku"
545 ))))
546 )]
547 pub fn set_tos(&self, tos: u32) -> io::Result<()> {
548 self.inner.set_tos_v4(tos)
549 }
550
551 /// Gets the value for the `SO_BINDTODEVICE` option on this socket
552 ///
553 /// This value gets the socket binded device's interface name.
554 #[cfg(any(target_os = "android", target_os = "fuchsia", target_os = "linux",))]
555 #[cfg_attr(
556 docsrs,
557 doc(cfg(any(target_os = "android", target_os = "fuchsia", target_os = "linux",)))
558 )]
559 pub fn device(&self) -> io::Result<Option<Vec<u8>>> {
560 self.inner.device()
561 }
562
563 /// Sets the value for the `SO_BINDTODEVICE` option on this socket
564 ///
565 /// If a socket is bound to an interface, only packets received from that
566 /// particular interface are processed by the socket. Note that this only
567 /// works for some socket types, particularly `AF_INET` sockets.
568 ///
569 /// If `interface` is `None` or an empty string it removes the binding.
570 #[cfg(any(target_os = "android", target_os = "fuchsia", target_os = "linux"))]
571 #[cfg_attr(
572 docsrs,
573 doc(cfg(all(any(target_os = "android", target_os = "fuchsia", target_os = "linux"))))
574 )]
575 pub fn bind_device(&self, interface: Option<&[u8]>) -> io::Result<()> {
576 self.inner.bind_device(interface)
577 }
578
579 /// Gets the local address of this socket.
580 ///
581 /// Will fail on windows if called before `bind`.
582 ///
583 /// # Examples
584 ///
585 /// ```no_run
586 /// use tokio::net::TcpSocket;
587 ///
588 /// use std::io;
589 ///
590 /// #[tokio::main]
591 /// async fn main() -> io::Result<()> {
592 /// let addr = "127.0.0.1:8080".parse().unwrap();
593 ///
594 /// let socket = TcpSocket::new_v4()?;
595 /// socket.bind(addr)?;
596 /// assert_eq!(socket.local_addr().unwrap().to_string(), "127.0.0.1:8080");
597 /// let listener = socket.listen(1024)?;
598 /// Ok(())
599 /// }
600 /// ```
601 pub fn local_addr(&self) -> io::Result<SocketAddr> {
602 self.inner.local_addr().and_then(convert_address)
603 }
604
605 /// Returns the value of the `SO_ERROR` option.
606 pub fn take_error(&self) -> io::Result<Option<io::Error>> {
607 self.inner.take_error()
608 }
609
610 /// Binds the socket to the given address.
611 ///
612 /// This calls the `bind(2)` operating-system function. Behavior is
613 /// platform specific. Refer to the target platform's documentation for more
614 /// details.
615 ///
616 /// # Examples
617 ///
618 /// Bind a socket before listening.
619 ///
620 /// ```no_run
621 /// use tokio::net::TcpSocket;
622 ///
623 /// use std::io;
624 ///
625 /// #[tokio::main]
626 /// async fn main() -> io::Result<()> {
627 /// let addr = "127.0.0.1:8080".parse().unwrap();
628 ///
629 /// let socket = TcpSocket::new_v4()?;
630 /// socket.bind(addr)?;
631 ///
632 /// let listener = socket.listen(1024)?;
633 /// # drop(listener);
634 ///
635 /// Ok(())
636 /// }
637 /// ```
638 pub fn bind(&self, addr: SocketAddr) -> io::Result<()> {
639 self.inner.bind(&addr.into())
640 }
641
642 /// Establishes a TCP connection with a peer at the specified socket address.
643 ///
644 /// The `TcpSocket` is consumed. Once the connection is established, a
645 /// connected [`TcpStream`] is returned. If the connection fails, the
646 /// encountered error is returned.
647 ///
648 /// [`TcpStream`]: TcpStream
649 ///
650 /// This calls the `connect(2)` operating-system function. Behavior is
651 /// platform specific. Refer to the target platform's documentation for more
652 /// details.
653 ///
654 /// # Examples
655 ///
656 /// Connecting to a peer.
657 ///
658 /// ```no_run
659 /// use tokio::net::TcpSocket;
660 ///
661 /// use std::io;
662 ///
663 /// #[tokio::main]
664 /// async fn main() -> io::Result<()> {
665 /// let addr = "127.0.0.1:8080".parse().unwrap();
666 ///
667 /// let socket = TcpSocket::new_v4()?;
668 /// let stream = socket.connect(addr).await?;
669 /// # drop(stream);
670 ///
671 /// Ok(())
672 /// }
673 /// ```
674 pub async fn connect(self, addr: SocketAddr) -> io::Result<TcpStream> {
675 if let Err(err) = self.inner.connect(&addr.into()) {
676 #[cfg(unix)]
677 if err.raw_os_error() != Some(libc::EINPROGRESS) {
678 return Err(err);
679 }
680 #[cfg(windows)]
681 if err.kind() != io::ErrorKind::WouldBlock {
682 return Err(err);
683 }
684 }
685 #[cfg(unix)]
686 let mio = {
687 use std::os::unix::io::{FromRawFd, IntoRawFd};
688
689 let raw_fd = self.inner.into_raw_fd();
690 unsafe { mio::net::TcpStream::from_raw_fd(raw_fd) }
691 };
692
693 #[cfg(windows)]
694 let mio = {
695 use std::os::windows::io::{FromRawSocket, IntoRawSocket};
696
697 let raw_socket = self.inner.into_raw_socket();
698 unsafe { mio::net::TcpStream::from_raw_socket(raw_socket) }
699 };
700
701 TcpStream::connect_mio(mio).await
702 }
703
704 /// Converts the socket into a `TcpListener`.
705 ///
706 /// `backlog` defines the maximum number of pending connections are queued
707 /// by the operating system at any given time. Connection are removed from
708 /// the queue with [`TcpListener::accept`]. When the queue is full, the
709 /// operating-system will start rejecting connections.
710 ///
711 /// [`TcpListener::accept`]: TcpListener::accept
712 ///
713 /// This calls the `listen(2)` operating-system function, marking the socket
714 /// as a passive socket. Behavior is platform specific. Refer to the target
715 /// platform's documentation for more details.
716 ///
717 /// # Examples
718 ///
719 /// Create a `TcpListener`.
720 ///
721 /// ```no_run
722 /// use tokio::net::TcpSocket;
723 ///
724 /// use std::io;
725 ///
726 /// #[tokio::main]
727 /// async fn main() -> io::Result<()> {
728 /// let addr = "127.0.0.1:8080".parse().unwrap();
729 ///
730 /// let socket = TcpSocket::new_v4()?;
731 /// socket.bind(addr)?;
732 ///
733 /// let listener = socket.listen(1024)?;
734 /// # drop(listener);
735 ///
736 /// Ok(())
737 /// }
738 /// ```
739 pub fn listen(self, backlog: u32) -> io::Result<TcpListener> {
740 self.inner.listen(backlog as i32)?;
741 #[cfg(unix)]
742 let mio = {
743 use std::os::unix::io::{FromRawFd, IntoRawFd};
744
745 let raw_fd = self.inner.into_raw_fd();
746 unsafe { mio::net::TcpListener::from_raw_fd(raw_fd) }
747 };
748
749 #[cfg(windows)]
750 let mio = {
751 use std::os::windows::io::{FromRawSocket, IntoRawSocket};
752
753 let raw_socket = self.inner.into_raw_socket();
754 unsafe { mio::net::TcpListener::from_raw_socket(raw_socket) }
755 };
756
757 TcpListener::new(mio)
758 }
759
760 /// Converts a [`std::net::TcpStream`] into a `TcpSocket`. The provided
761 /// socket must not have been connected prior to calling this function. This
762 /// function is typically used together with crates such as [`socket2`] to
763 /// configure socket options that are not available on `TcpSocket`.
764 ///
765 /// [`std::net::TcpStream`]: struct@std::net::TcpStream
766 /// [`socket2`]: https://docs.rs/socket2/
767 ///
768 /// # Notes
769 ///
770 /// The caller is responsible for ensuring that the socket is in
771 /// non-blocking mode. Otherwise all I/O operations on the socket
772 /// will block the thread, which will cause unexpected behavior.
773 /// Non-blocking mode can be set using [`set_nonblocking`].
774 ///
775 /// [`set_nonblocking`]: std::net::TcpStream::set_nonblocking
776 ///
777 /// # Examples
778 ///
779 /// ```
780 /// use tokio::net::TcpSocket;
781 /// use socket2::{Domain, Socket, Type};
782 ///
783 /// #[tokio::main]
784 /// async fn main() -> std::io::Result<()> {
785 /// # if cfg!(miri) { return Ok(()); } // No `socket` in miri.
786 /// let socket2_socket = Socket::new(Domain::IPV4, Type::STREAM, None)?;
787 /// socket2_socket.set_nonblocking(true)?;
788 ///
789 /// let socket = TcpSocket::from_std_stream(socket2_socket.into());
790 ///
791 /// Ok(())
792 /// }
793 /// ```
794 pub fn from_std_stream(std_stream: std::net::TcpStream) -> TcpSocket {
795 #[cfg(unix)]
796 {
797 use std::os::unix::io::{FromRawFd, IntoRawFd};
798
799 let raw_fd = std_stream.into_raw_fd();
800 unsafe { TcpSocket::from_raw_fd(raw_fd) }
801 }
802
803 #[cfg(windows)]
804 {
805 use std::os::windows::io::{FromRawSocket, IntoRawSocket};
806
807 let raw_socket = std_stream.into_raw_socket();
808 unsafe { TcpSocket::from_raw_socket(raw_socket) }
809 }
810 }
811}
812
813fn convert_address(address: socket2::SockAddr) -> io::Result<SocketAddr> {
814 match address.as_socket() {
815 Some(address) => Ok(address),
816 None => Err(io::Error::new(
817 io::ErrorKind::InvalidInput,
818 "invalid address family (not IPv4 or IPv6)",
819 )),
820 }
821}
822
823impl fmt::Debug for TcpSocket {
824 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
825 self.inner.fmt(fmt)
826 }
827}
828
829// These trait implementations can't be build on Windows, so we completely
830// ignore them, even when building documentation.
831#[cfg(unix)]
832cfg_unix! {
833 impl AsRawFd for TcpSocket {
834 fn as_raw_fd(&self) -> RawFd {
835 self.inner.as_raw_fd()
836 }
837 }
838
839 impl AsFd for TcpSocket {
840 fn as_fd(&self) -> BorrowedFd<'_> {
841 unsafe { BorrowedFd::borrow_raw(self.as_raw_fd()) }
842 }
843 }
844
845 impl FromRawFd for TcpSocket {
846 /// Converts a `RawFd` to a `TcpSocket`.
847 ///
848 /// # Notes
849 ///
850 /// The caller is responsible for ensuring that the socket is in
851 /// non-blocking mode.
852 unsafe fn from_raw_fd(fd: RawFd) -> TcpSocket {
853 // Safety: exactly the same safety requirements as the
854 // `FromRawFd::from_raw_fd` trait method.
855 let inner = unsafe { socket2::Socket::from_raw_fd(fd) };
856 TcpSocket { inner }
857 }
858 }
859
860 impl IntoRawFd for TcpSocket {
861 fn into_raw_fd(self) -> RawFd {
862 self.inner.into_raw_fd()
863 }
864 }
865}
866
867cfg_windows! {
868 impl IntoRawSocket for TcpSocket {
869 fn into_raw_socket(self) -> RawSocket {
870 self.inner.into_raw_socket()
871 }
872 }
873
874 impl AsRawSocket for TcpSocket {
875 fn as_raw_socket(&self) -> RawSocket {
876 self.inner.as_raw_socket()
877 }
878 }
879
880 impl AsSocket for TcpSocket {
881 fn as_socket(&self) -> BorrowedSocket<'_> {
882 unsafe { BorrowedSocket::borrow_raw(self.as_raw_socket()) }
883 }
884 }
885
886 impl FromRawSocket for TcpSocket {
887 /// Converts a `RawSocket` to a `TcpStream`.
888 ///
889 /// # Notes
890 ///
891 /// The caller is responsible for ensuring that the socket is in
892 /// non-blocking mode.
893 unsafe fn from_raw_socket(socket: RawSocket) -> TcpSocket {
894 let inner = unsafe { socket2::Socket::from_raw_socket(socket) };
895 TcpSocket { inner }
896 }
897 }
898}