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 `IPV6_TCLASS` option for this socket.
493 ///
494 /// For more information about this option, see [`set_tclass_v6`].
495 ///
496 /// [`set_tclass_v6`]: Self::set_tclass_v6
497 // https://docs.rs/socket2/0.6.1/src/socket2/sys/unix.rs.html#2541
498 #[cfg(any(
499 target_os = "android",
500 target_os = "dragonfly",
501 target_os = "freebsd",
502 target_os = "fuchsia",
503 target_os = "linux",
504 target_os = "macos",
505 target_os = "netbsd",
506 target_os = "openbsd",
507 target_os = "cygwin",
508 ))]
509 #[cfg_attr(
510 docsrs,
511 doc(cfg(any(
512 target_os = "android",
513 target_os = "dragonfly",
514 target_os = "freebsd",
515 target_os = "fuchsia",
516 target_os = "linux",
517 target_os = "macos",
518 target_os = "netbsd",
519 target_os = "openbsd",
520 target_os = "cygwin",
521 )))
522 )]
523 pub fn tclass_v6(&self) -> io::Result<u32> {
524 self.inner.tclass_v6()
525 }
526
527 /// Sets the value for the `IPV6_TCLASS` option on this socket.
528 ///
529 /// Specifies the traffic class field that is used in every packet
530 /// sent from this socket.
531 ///
532 /// # Note
533 ///
534 /// This may not have any effect on IPv4 sockets.
535 // https://docs.rs/socket2/0.6.1/src/socket2/sys/unix.rs.html#2566
536 #[cfg(any(
537 target_os = "android",
538 target_os = "dragonfly",
539 target_os = "freebsd",
540 target_os = "fuchsia",
541 target_os = "linux",
542 target_os = "macos",
543 target_os = "netbsd",
544 target_os = "openbsd",
545 target_os = "cygwin",
546 ))]
547 #[cfg_attr(
548 docsrs,
549 doc(cfg(any(
550 target_os = "android",
551 target_os = "dragonfly",
552 target_os = "freebsd",
553 target_os = "fuchsia",
554 target_os = "linux",
555 target_os = "macos",
556 target_os = "netbsd",
557 target_os = "openbsd",
558 target_os = "cygwin",
559 )))
560 )]
561 pub fn set_tclass_v6(&self, tclass: u32) -> io::Result<()> {
562 self.inner.set_tclass_v6(tclass)
563 }
564
565 /// Gets the value of the `IP_TOS` option for this socket.
566 ///
567 /// For more information about this option, see [`set_tos_v4`].
568 ///
569 /// [`set_tos_v4`]: Self::set_tos_v4
570 // https://docs.rs/socket2/0.6.1/src/socket2/socket.rs.html#1585
571 #[cfg(not(any(
572 target_os = "fuchsia",
573 target_os = "redox",
574 target_os = "solaris",
575 target_os = "illumos",
576 target_os = "haiku"
577 )))]
578 #[cfg_attr(
579 docsrs,
580 doc(cfg(not(any(
581 target_os = "fuchsia",
582 target_os = "redox",
583 target_os = "solaris",
584 target_os = "illumos",
585 target_os = "haiku"
586 ))))
587 )]
588 pub fn tos_v4(&self) -> io::Result<u32> {
589 self.inner.tos_v4()
590 }
591
592 /// Deprecated. Use [`tos_v4()`] instead.
593 ///
594 /// [`tos_v4()`]: Self::tos_v4
595 #[deprecated(
596 note = "`tos` related methods have been renamed `tos_v4` since they are IPv4-specific."
597 )]
598 #[doc(hidden)]
599 #[cfg(not(any(
600 target_os = "fuchsia",
601 target_os = "redox",
602 target_os = "solaris",
603 target_os = "illumos",
604 target_os = "haiku"
605 )))]
606 #[cfg_attr(
607 docsrs,
608 doc(cfg(not(any(
609 target_os = "fuchsia",
610 target_os = "redox",
611 target_os = "solaris",
612 target_os = "illumos",
613 target_os = "haiku"
614 ))))
615 )]
616 pub fn tos(&self) -> io::Result<u32> {
617 self.tos_v4()
618 }
619
620 /// Sets the value for the `IP_TOS` option on this socket.
621 ///
622 /// This value sets the type-of-service field that is used in every packet
623 /// sent from this socket.
624 ///
625 /// # Note
626 ///
627 /// - This may not have any effect on IPv6 sockets.
628 /// - On Windows, `IP_TOS` is only supported on [Windows 8+ or
629 /// Windows Server 2012+.](https://docs.microsoft.com/en-us/windows/win32/winsock/ipproto-ip-socket-options)
630 // https://docs.rs/socket2/0.6.1/src/socket2/socket.rs.html#1566
631 #[cfg(not(any(
632 target_os = "fuchsia",
633 target_os = "redox",
634 target_os = "solaris",
635 target_os = "illumos",
636 target_os = "haiku"
637 )))]
638 #[cfg_attr(
639 docsrs,
640 doc(cfg(not(any(
641 target_os = "fuchsia",
642 target_os = "redox",
643 target_os = "solaris",
644 target_os = "illumos",
645 target_os = "haiku"
646 ))))
647 )]
648 pub fn set_tos_v4(&self, tos: u32) -> io::Result<()> {
649 self.inner.set_tos_v4(tos)
650 }
651
652 /// Deprecated. Use [`set_tos_v4()`] instead.
653 ///
654 /// [`set_tos_v4()`]: Self::set_tos_v4
655 #[deprecated(
656 note = "`tos` related methods have been renamed `tos_v4` since they are IPv4-specific."
657 )]
658 #[doc(hidden)]
659 #[cfg(not(any(
660 target_os = "fuchsia",
661 target_os = "redox",
662 target_os = "solaris",
663 target_os = "illumos",
664 target_os = "haiku"
665 )))]
666 #[cfg_attr(
667 docsrs,
668 doc(cfg(not(any(
669 target_os = "fuchsia",
670 target_os = "redox",
671 target_os = "solaris",
672 target_os = "illumos",
673 target_os = "haiku"
674 ))))
675 )]
676 pub fn set_tos(&self, tos: u32) -> io::Result<()> {
677 self.set_tos_v4(tos)
678 }
679
680 /// Gets the value for the `SO_BINDTODEVICE` option on this socket
681 ///
682 /// This value gets the socket binded device's interface name.
683 #[cfg(any(target_os = "android", target_os = "fuchsia", target_os = "linux",))]
684 #[cfg_attr(
685 docsrs,
686 doc(cfg(any(target_os = "android", target_os = "fuchsia", target_os = "linux",)))
687 )]
688 pub fn device(&self) -> io::Result<Option<Vec<u8>>> {
689 self.inner.device()
690 }
691
692 /// Sets the value for the `SO_BINDTODEVICE` option on this socket
693 ///
694 /// If a socket is bound to an interface, only packets received from that
695 /// particular interface are processed by the socket. Note that this only
696 /// works for some socket types, particularly `AF_INET` sockets.
697 ///
698 /// If `interface` is `None` or an empty string it removes the binding.
699 #[cfg(any(target_os = "android", target_os = "fuchsia", target_os = "linux"))]
700 #[cfg_attr(
701 docsrs,
702 doc(cfg(all(any(target_os = "android", target_os = "fuchsia", target_os = "linux"))))
703 )]
704 pub fn bind_device(&self, interface: Option<&[u8]>) -> io::Result<()> {
705 self.inner.bind_device(interface)
706 }
707
708 /// Gets the local address of this socket.
709 ///
710 /// Will fail on windows if called before `bind`.
711 ///
712 /// # Examples
713 ///
714 /// ```no_run
715 /// use tokio::net::TcpSocket;
716 ///
717 /// use std::io;
718 ///
719 /// #[tokio::main]
720 /// async fn main() -> io::Result<()> {
721 /// let addr = "127.0.0.1:8080".parse().unwrap();
722 ///
723 /// let socket = TcpSocket::new_v4()?;
724 /// socket.bind(addr)?;
725 /// assert_eq!(socket.local_addr().unwrap().to_string(), "127.0.0.1:8080");
726 /// let listener = socket.listen(1024)?;
727 /// Ok(())
728 /// }
729 /// ```
730 pub fn local_addr(&self) -> io::Result<SocketAddr> {
731 self.inner.local_addr().and_then(convert_address)
732 }
733
734 /// Returns the value of the `SO_ERROR` option.
735 pub fn take_error(&self) -> io::Result<Option<io::Error>> {
736 self.inner.take_error()
737 }
738
739 /// Binds the socket to the given address.
740 ///
741 /// This calls the `bind(2)` operating-system function. Behavior is
742 /// platform specific. Refer to the target platform's documentation for more
743 /// details.
744 ///
745 /// # Examples
746 ///
747 /// Bind a socket before listening.
748 ///
749 /// ```no_run
750 /// use tokio::net::TcpSocket;
751 ///
752 /// use std::io;
753 ///
754 /// #[tokio::main]
755 /// async fn main() -> io::Result<()> {
756 /// let addr = "127.0.0.1:8080".parse().unwrap();
757 ///
758 /// let socket = TcpSocket::new_v4()?;
759 /// socket.bind(addr)?;
760 ///
761 /// let listener = socket.listen(1024)?;
762 /// # drop(listener);
763 ///
764 /// Ok(())
765 /// }
766 /// ```
767 pub fn bind(&self, addr: SocketAddr) -> io::Result<()> {
768 self.inner.bind(&addr.into())
769 }
770
771 /// Establishes a TCP connection with a peer at the specified socket address.
772 ///
773 /// The `TcpSocket` is consumed. Once the connection is established, a
774 /// connected [`TcpStream`] is returned. If the connection fails, the
775 /// encountered error is returned.
776 ///
777 /// [`TcpStream`]: TcpStream
778 ///
779 /// This calls the `connect(2)` operating-system function. Behavior is
780 /// platform specific. Refer to the target platform's documentation for more
781 /// details.
782 ///
783 /// # Examples
784 ///
785 /// Connecting to a peer.
786 ///
787 /// ```no_run
788 /// use tokio::net::TcpSocket;
789 ///
790 /// use std::io;
791 ///
792 /// #[tokio::main]
793 /// async fn main() -> io::Result<()> {
794 /// let addr = "127.0.0.1:8080".parse().unwrap();
795 ///
796 /// let socket = TcpSocket::new_v4()?;
797 /// let stream = socket.connect(addr).await?;
798 /// # drop(stream);
799 ///
800 /// Ok(())
801 /// }
802 /// ```
803 pub async fn connect(self, addr: SocketAddr) -> io::Result<TcpStream> {
804 if let Err(err) = self.inner.connect(&addr.into()) {
805 #[cfg(unix)]
806 if err.raw_os_error() != Some(libc::EINPROGRESS) {
807 return Err(err);
808 }
809 #[cfg(windows)]
810 if err.kind() != io::ErrorKind::WouldBlock {
811 return Err(err);
812 }
813 }
814 #[cfg(unix)]
815 let mio = {
816 use std::os::unix::io::{FromRawFd, IntoRawFd};
817
818 let raw_fd = self.inner.into_raw_fd();
819 unsafe { mio::net::TcpStream::from_raw_fd(raw_fd) }
820 };
821
822 #[cfg(windows)]
823 let mio = {
824 use std::os::windows::io::{FromRawSocket, IntoRawSocket};
825
826 let raw_socket = self.inner.into_raw_socket();
827 unsafe { mio::net::TcpStream::from_raw_socket(raw_socket) }
828 };
829
830 TcpStream::connect_mio(mio).await
831 }
832
833 /// Converts the socket into a `TcpListener`.
834 ///
835 /// `backlog` defines the maximum number of pending connections are queued
836 /// by the operating system at any given time. Connection are removed from
837 /// the queue with [`TcpListener::accept`]. When the queue is full, the
838 /// operating-system will start rejecting connections.
839 ///
840 /// [`TcpListener::accept`]: TcpListener::accept
841 ///
842 /// This calls the `listen(2)` operating-system function, marking the socket
843 /// as a passive socket. Behavior is platform specific. Refer to the target
844 /// platform's documentation for more details.
845 ///
846 /// # Examples
847 ///
848 /// Create a `TcpListener`.
849 ///
850 /// ```no_run
851 /// use tokio::net::TcpSocket;
852 ///
853 /// use std::io;
854 ///
855 /// #[tokio::main]
856 /// async fn main() -> io::Result<()> {
857 /// let addr = "127.0.0.1:8080".parse().unwrap();
858 ///
859 /// let socket = TcpSocket::new_v4()?;
860 /// socket.bind(addr)?;
861 ///
862 /// let listener = socket.listen(1024)?;
863 /// # drop(listener);
864 ///
865 /// Ok(())
866 /// }
867 /// ```
868 pub fn listen(self, backlog: u32) -> io::Result<TcpListener> {
869 self.inner.listen(backlog as i32)?;
870 #[cfg(unix)]
871 let mio = {
872 use std::os::unix::io::{FromRawFd, IntoRawFd};
873
874 let raw_fd = self.inner.into_raw_fd();
875 unsafe { mio::net::TcpListener::from_raw_fd(raw_fd) }
876 };
877
878 #[cfg(windows)]
879 let mio = {
880 use std::os::windows::io::{FromRawSocket, IntoRawSocket};
881
882 let raw_socket = self.inner.into_raw_socket();
883 unsafe { mio::net::TcpListener::from_raw_socket(raw_socket) }
884 };
885
886 TcpListener::new(mio)
887 }
888
889 /// Converts a [`std::net::TcpStream`] into a `TcpSocket`. The provided
890 /// socket must not have been connected prior to calling this function. This
891 /// function is typically used together with crates such as [`socket2`] to
892 /// configure socket options that are not available on `TcpSocket`.
893 ///
894 /// [`std::net::TcpStream`]: struct@std::net::TcpStream
895 /// [`socket2`]: https://docs.rs/socket2/
896 ///
897 /// # Notes
898 ///
899 /// The caller is responsible for ensuring that the socket is in
900 /// non-blocking mode. Otherwise all I/O operations on the socket
901 /// will block the thread, which will cause unexpected behavior.
902 /// Non-blocking mode can be set using [`set_nonblocking`].
903 ///
904 /// [`set_nonblocking`]: std::net::TcpStream::set_nonblocking
905 ///
906 /// # Examples
907 ///
908 /// ```
909 /// use tokio::net::TcpSocket;
910 /// use socket2::{Domain, Socket, Type};
911 ///
912 /// #[tokio::main]
913 /// async fn main() -> std::io::Result<()> {
914 /// # if cfg!(miri) { return Ok(()); } // No `socket` in miri.
915 /// let socket2_socket = Socket::new(Domain::IPV4, Type::STREAM, None)?;
916 /// socket2_socket.set_nonblocking(true)?;
917 ///
918 /// let socket = TcpSocket::from_std_stream(socket2_socket.into());
919 ///
920 /// Ok(())
921 /// }
922 /// ```
923 pub fn from_std_stream(std_stream: std::net::TcpStream) -> TcpSocket {
924 #[cfg(unix)]
925 {
926 use std::os::unix::io::{FromRawFd, IntoRawFd};
927
928 let raw_fd = std_stream.into_raw_fd();
929 unsafe { TcpSocket::from_raw_fd(raw_fd) }
930 }
931
932 #[cfg(windows)]
933 {
934 use std::os::windows::io::{FromRawSocket, IntoRawSocket};
935
936 let raw_socket = std_stream.into_raw_socket();
937 unsafe { TcpSocket::from_raw_socket(raw_socket) }
938 }
939 }
940}
941
942fn convert_address(address: socket2::SockAddr) -> io::Result<SocketAddr> {
943 match address.as_socket() {
944 Some(address) => Ok(address),
945 None => Err(io::Error::new(
946 io::ErrorKind::InvalidInput,
947 "invalid address family (not IPv4 or IPv6)",
948 )),
949 }
950}
951
952impl fmt::Debug for TcpSocket {
953 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
954 self.inner.fmt(fmt)
955 }
956}
957
958// These trait implementations can't be build on Windows, so we completely
959// ignore them, even when building documentation.
960#[cfg(unix)]
961cfg_unix! {
962 impl AsRawFd for TcpSocket {
963 fn as_raw_fd(&self) -> RawFd {
964 self.inner.as_raw_fd()
965 }
966 }
967
968 impl AsFd for TcpSocket {
969 fn as_fd(&self) -> BorrowedFd<'_> {
970 unsafe { BorrowedFd::borrow_raw(self.as_raw_fd()) }
971 }
972 }
973
974 impl FromRawFd for TcpSocket {
975 /// Converts a `RawFd` to a `TcpSocket`.
976 ///
977 /// # Notes
978 ///
979 /// The caller is responsible for ensuring that the socket is in
980 /// non-blocking mode.
981 unsafe fn from_raw_fd(fd: RawFd) -> TcpSocket {
982 // Safety: exactly the same safety requirements as the
983 // `FromRawFd::from_raw_fd` trait method.
984 let inner = unsafe { socket2::Socket::from_raw_fd(fd) };
985 TcpSocket { inner }
986 }
987 }
988
989 impl IntoRawFd for TcpSocket {
990 fn into_raw_fd(self) -> RawFd {
991 self.inner.into_raw_fd()
992 }
993 }
994}
995
996cfg_windows! {
997 impl IntoRawSocket for TcpSocket {
998 fn into_raw_socket(self) -> RawSocket {
999 self.inner.into_raw_socket()
1000 }
1001 }
1002
1003 impl AsRawSocket for TcpSocket {
1004 fn as_raw_socket(&self) -> RawSocket {
1005 self.inner.as_raw_socket()
1006 }
1007 }
1008
1009 impl AsSocket for TcpSocket {
1010 fn as_socket(&self) -> BorrowedSocket<'_> {
1011 unsafe { BorrowedSocket::borrow_raw(self.as_raw_socket()) }
1012 }
1013 }
1014
1015 impl FromRawSocket for TcpSocket {
1016 /// Converts a `RawSocket` to a `TcpStream`.
1017 ///
1018 /// # Notes
1019 ///
1020 /// The caller is responsible for ensuring that the socket is in
1021 /// non-blocking mode.
1022 unsafe fn from_raw_socket(socket: RawSocket) -> TcpSocket {
1023 let inner = unsafe { socket2::Socket::from_raw_socket(socket) };
1024 TcpSocket { inner }
1025 }
1026 }
1027}