std/net/
tcp.rs

1#![deny(unsafe_op_in_unsafe_fn)]
2
3#[cfg(all(
4    test,
5    not(any(
6        target_os = "emscripten",
7        all(target_os = "wasi", target_env = "p1"),
8        target_os = "xous",
9        target_os = "trusty",
10    ))
11))]
12mod tests;
13
14use crate::fmt;
15use crate::io::prelude::*;
16use crate::io::{self, BorrowedCursor, IoSlice, IoSliceMut};
17use crate::iter::FusedIterator;
18use crate::net::{Shutdown, SocketAddr, ToSocketAddrs};
19use crate::sys::net as net_imp;
20use crate::sys_common::{AsInner, FromInner, IntoInner};
21use crate::time::Duration;
22
23/// A TCP stream between a local and a remote socket.
24///
25/// After creating a `TcpStream` by either [`connect`]ing to a remote host or
26/// [`accept`]ing a connection on a [`TcpListener`], data can be transmitted
27/// by [reading] and [writing] to it.
28///
29/// The connection will be closed when the value is dropped. The reading and writing
30/// portions of the connection can also be shut down individually with the [`shutdown`]
31/// method.
32///
33/// The Transmission Control Protocol is specified in [IETF RFC 793].
34///
35/// [`accept`]: TcpListener::accept
36/// [`connect`]: TcpStream::connect
37/// [IETF RFC 793]: https://tools.ietf.org/html/rfc793
38/// [reading]: Read
39/// [`shutdown`]: TcpStream::shutdown
40/// [writing]: Write
41///
42/// # Examples
43///
44/// ```no_run
45/// use std::io::prelude::*;
46/// use std::net::TcpStream;
47///
48/// fn main() -> std::io::Result<()> {
49///     let mut stream = TcpStream::connect("127.0.0.1:34254")?;
50///
51///     stream.write(&[1])?;
52///     stream.read(&mut [0; 128])?;
53///     Ok(())
54/// } // the stream is closed here
55/// ```
56#[stable(feature = "rust1", since = "1.0.0")]
57pub struct TcpStream(net_imp::TcpStream);
58
59/// A TCP socket server, listening for connections.
60///
61/// After creating a `TcpListener` by [`bind`]ing it to a socket address, it listens
62/// for incoming TCP connections. These can be accepted by calling [`accept`] or by
63/// iterating over the [`Incoming`] iterator returned by [`incoming`][`TcpListener::incoming`].
64///
65/// The socket will be closed when the value is dropped.
66///
67/// The Transmission Control Protocol is specified in [IETF RFC 793].
68///
69/// [`accept`]: TcpListener::accept
70/// [`bind`]: TcpListener::bind
71/// [IETF RFC 793]: https://tools.ietf.org/html/rfc793
72///
73/// # Examples
74///
75/// ```no_run
76/// use std::net::{TcpListener, TcpStream};
77///
78/// fn handle_client(stream: TcpStream) {
79///     // ...
80/// }
81///
82/// fn main() -> std::io::Result<()> {
83///     let listener = TcpListener::bind("127.0.0.1:80")?;
84///
85///     // accept connections and process them serially
86///     for stream in listener.incoming() {
87///         handle_client(stream?);
88///     }
89///     Ok(())
90/// }
91/// ```
92#[stable(feature = "rust1", since = "1.0.0")]
93pub struct TcpListener(net_imp::TcpListener);
94
95/// An iterator that infinitely [`accept`]s connections on a [`TcpListener`].
96///
97/// This `struct` is created by the [`TcpListener::incoming`] method.
98/// See its documentation for more.
99///
100/// [`accept`]: TcpListener::accept
101#[must_use = "iterators are lazy and do nothing unless consumed"]
102#[stable(feature = "rust1", since = "1.0.0")]
103#[derive(Debug)]
104pub struct Incoming<'a> {
105    listener: &'a TcpListener,
106}
107
108/// An iterator that infinitely [`accept`]s connections on a [`TcpListener`].
109///
110/// This `struct` is created by the [`TcpListener::into_incoming`] method.
111/// See its documentation for more.
112///
113/// [`accept`]: TcpListener::accept
114#[derive(Debug)]
115#[unstable(feature = "tcplistener_into_incoming", issue = "88373")]
116pub struct IntoIncoming {
117    listener: TcpListener,
118}
119
120impl TcpStream {
121    /// Opens a TCP connection to a remote host.
122    ///
123    /// `addr` is an address of the remote host. Anything which implements
124    /// [`ToSocketAddrs`] trait can be supplied for the address; see this trait
125    /// documentation for concrete examples.
126    ///
127    /// If `addr` yields multiple addresses, `connect` will be attempted with
128    /// each of the addresses until a connection is successful. If none of
129    /// the addresses result in a successful connection, the error returned from
130    /// the last connection attempt (the last address) is returned.
131    ///
132    /// # Examples
133    ///
134    /// Open a TCP connection to `127.0.0.1:8080`:
135    ///
136    /// ```no_run
137    /// use std::net::TcpStream;
138    ///
139    /// if let Ok(stream) = TcpStream::connect("127.0.0.1:8080") {
140    ///     println!("Connected to the server!");
141    /// } else {
142    ///     println!("Couldn't connect to server...");
143    /// }
144    /// ```
145    ///
146    /// Open a TCP connection to `127.0.0.1:8080`. If the connection fails, open
147    /// a TCP connection to `127.0.0.1:8081`:
148    ///
149    /// ```no_run
150    /// use std::net::{SocketAddr, TcpStream};
151    ///
152    /// let addrs = [
153    ///     SocketAddr::from(([127, 0, 0, 1], 8080)),
154    ///     SocketAddr::from(([127, 0, 0, 1], 8081)),
155    /// ];
156    /// if let Ok(stream) = TcpStream::connect(&addrs[..]) {
157    ///     println!("Connected to the server!");
158    /// } else {
159    ///     println!("Couldn't connect to server...");
160    /// }
161    /// ```
162    #[stable(feature = "rust1", since = "1.0.0")]
163    pub fn connect<A: ToSocketAddrs>(addr: A) -> io::Result<TcpStream> {
164        super::each_addr(addr, net_imp::TcpStream::connect).map(TcpStream)
165    }
166
167    /// Opens a TCP connection to a remote host with a timeout.
168    ///
169    /// Unlike `connect`, `connect_timeout` takes a single [`SocketAddr`] since
170    /// timeout must be applied to individual addresses.
171    ///
172    /// It is an error to pass a zero `Duration` to this function.
173    ///
174    /// Unlike other methods on `TcpStream`, this does not correspond to a
175    /// single system call. It instead calls `connect` in nonblocking mode and
176    /// then uses an OS-specific mechanism to await the completion of the
177    /// connection request.
178    #[stable(feature = "tcpstream_connect_timeout", since = "1.21.0")]
179    pub fn connect_timeout(addr: &SocketAddr, timeout: Duration) -> io::Result<TcpStream> {
180        net_imp::TcpStream::connect_timeout(addr, timeout).map(TcpStream)
181    }
182
183    /// Returns the socket address of the remote peer of this TCP connection.
184    ///
185    /// # Examples
186    ///
187    /// ```no_run
188    /// use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4, TcpStream};
189    ///
190    /// let stream = TcpStream::connect("127.0.0.1:8080")
191    ///                        .expect("Couldn't connect to the server...");
192    /// assert_eq!(stream.peer_addr().unwrap(),
193    ///            SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080)));
194    /// ```
195    #[stable(feature = "rust1", since = "1.0.0")]
196    pub fn peer_addr(&self) -> io::Result<SocketAddr> {
197        self.0.peer_addr()
198    }
199
200    /// Returns the socket address of the local half of this TCP connection.
201    ///
202    /// # Examples
203    ///
204    /// ```no_run
205    /// use std::net::{IpAddr, Ipv4Addr, TcpStream};
206    ///
207    /// let stream = TcpStream::connect("127.0.0.1:8080")
208    ///                        .expect("Couldn't connect to the server...");
209    /// assert_eq!(stream.local_addr().unwrap().ip(),
210    ///            IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)));
211    /// ```
212    #[stable(feature = "rust1", since = "1.0.0")]
213    pub fn local_addr(&self) -> io::Result<SocketAddr> {
214        self.0.socket_addr()
215    }
216
217    /// Shuts down the read, write, or both halves of this connection.
218    ///
219    /// This function will cause all pending and future I/O on the specified
220    /// portions to return immediately with an appropriate value (see the
221    /// documentation of [`Shutdown`]).
222    ///
223    /// # Platform-specific behavior
224    ///
225    /// Calling this function multiple times may result in different behavior,
226    /// depending on the operating system. On Linux, the second call will
227    /// return `Ok(())`, but on macOS, it will return `ErrorKind::NotConnected`.
228    /// This may change in the future.
229    ///
230    /// # Examples
231    ///
232    /// ```no_run
233    /// use std::net::{Shutdown, TcpStream};
234    ///
235    /// let stream = TcpStream::connect("127.0.0.1:8080")
236    ///                        .expect("Couldn't connect to the server...");
237    /// stream.shutdown(Shutdown::Both).expect("shutdown call failed");
238    /// ```
239    #[stable(feature = "rust1", since = "1.0.0")]
240    pub fn shutdown(&self, how: Shutdown) -> io::Result<()> {
241        self.0.shutdown(how)
242    }
243
244    /// Creates a new independently owned handle to the underlying socket.
245    ///
246    /// The returned `TcpStream` is a reference to the same stream that this
247    /// object references. Both handles will read and write the same stream of
248    /// data, and options set on one stream will be propagated to the other
249    /// stream.
250    ///
251    /// # Examples
252    ///
253    /// ```no_run
254    /// use std::net::TcpStream;
255    ///
256    /// let stream = TcpStream::connect("127.0.0.1:8080")
257    ///                        .expect("Couldn't connect to the server...");
258    /// let stream_clone = stream.try_clone().expect("clone failed...");
259    /// ```
260    #[stable(feature = "rust1", since = "1.0.0")]
261    pub fn try_clone(&self) -> io::Result<TcpStream> {
262        self.0.duplicate().map(TcpStream)
263    }
264
265    /// Sets the read timeout to the timeout specified.
266    ///
267    /// If the value specified is [`None`], then [`read`] calls will block
268    /// indefinitely. An [`Err`] is returned if the zero [`Duration`] is
269    /// passed to this method.
270    ///
271    /// # Platform-specific behavior
272    ///
273    /// Platforms may return a different error code whenever a read times out as
274    /// a result of setting this option. For example Unix typically returns an
275    /// error of the kind [`WouldBlock`], but Windows may return [`TimedOut`].
276    ///
277    /// [`read`]: Read::read
278    /// [`WouldBlock`]: io::ErrorKind::WouldBlock
279    /// [`TimedOut`]: io::ErrorKind::TimedOut
280    ///
281    /// # Examples
282    ///
283    /// ```no_run
284    /// use std::net::TcpStream;
285    ///
286    /// let stream = TcpStream::connect("127.0.0.1:8080")
287    ///                        .expect("Couldn't connect to the server...");
288    /// stream.set_read_timeout(None).expect("set_read_timeout call failed");
289    /// ```
290    ///
291    /// An [`Err`] is returned if the zero [`Duration`] is passed to this
292    /// method:
293    ///
294    /// ```no_run
295    /// use std::io;
296    /// use std::net::TcpStream;
297    /// use std::time::Duration;
298    ///
299    /// let stream = TcpStream::connect("127.0.0.1:8080").unwrap();
300    /// let result = stream.set_read_timeout(Some(Duration::new(0, 0)));
301    /// let err = result.unwrap_err();
302    /// assert_eq!(err.kind(), io::ErrorKind::InvalidInput)
303    /// ```
304    #[stable(feature = "socket_timeout", since = "1.4.0")]
305    pub fn set_read_timeout(&self, dur: Option<Duration>) -> io::Result<()> {
306        self.0.set_read_timeout(dur)
307    }
308
309    /// Sets the write timeout to the timeout specified.
310    ///
311    /// If the value specified is [`None`], then [`write`] calls will block
312    /// indefinitely. An [`Err`] is returned if the zero [`Duration`] is
313    /// passed to this method.
314    ///
315    /// # Platform-specific behavior
316    ///
317    /// Platforms may return a different error code whenever a write times out
318    /// as a result of setting this option. For example Unix typically returns
319    /// an error of the kind [`WouldBlock`], but Windows may return [`TimedOut`].
320    ///
321    /// [`write`]: Write::write
322    /// [`WouldBlock`]: io::ErrorKind::WouldBlock
323    /// [`TimedOut`]: io::ErrorKind::TimedOut
324    ///
325    /// # Examples
326    ///
327    /// ```no_run
328    /// use std::net::TcpStream;
329    ///
330    /// let stream = TcpStream::connect("127.0.0.1:8080")
331    ///                        .expect("Couldn't connect to the server...");
332    /// stream.set_write_timeout(None).expect("set_write_timeout call failed");
333    /// ```
334    ///
335    /// An [`Err`] is returned if the zero [`Duration`] is passed to this
336    /// method:
337    ///
338    /// ```no_run
339    /// use std::io;
340    /// use std::net::TcpStream;
341    /// use std::time::Duration;
342    ///
343    /// let stream = TcpStream::connect("127.0.0.1:8080").unwrap();
344    /// let result = stream.set_write_timeout(Some(Duration::new(0, 0)));
345    /// let err = result.unwrap_err();
346    /// assert_eq!(err.kind(), io::ErrorKind::InvalidInput)
347    /// ```
348    #[stable(feature = "socket_timeout", since = "1.4.0")]
349    pub fn set_write_timeout(&self, dur: Option<Duration>) -> io::Result<()> {
350        self.0.set_write_timeout(dur)
351    }
352
353    /// Returns the read timeout of this socket.
354    ///
355    /// If the timeout is [`None`], then [`read`] calls will block indefinitely.
356    ///
357    /// # Platform-specific behavior
358    ///
359    /// Some platforms do not provide access to the current timeout.
360    ///
361    /// [`read`]: Read::read
362    ///
363    /// # Examples
364    ///
365    /// ```no_run
366    /// use std::net::TcpStream;
367    ///
368    /// let stream = TcpStream::connect("127.0.0.1:8080")
369    ///                        .expect("Couldn't connect to the server...");
370    /// stream.set_read_timeout(None).expect("set_read_timeout call failed");
371    /// assert_eq!(stream.read_timeout().unwrap(), None);
372    /// ```
373    #[stable(feature = "socket_timeout", since = "1.4.0")]
374    pub fn read_timeout(&self) -> io::Result<Option<Duration>> {
375        self.0.read_timeout()
376    }
377
378    /// Returns the write timeout of this socket.
379    ///
380    /// If the timeout is [`None`], then [`write`] calls will block indefinitely.
381    ///
382    /// # Platform-specific behavior
383    ///
384    /// Some platforms do not provide access to the current timeout.
385    ///
386    /// [`write`]: Write::write
387    ///
388    /// # Examples
389    ///
390    /// ```no_run
391    /// use std::net::TcpStream;
392    ///
393    /// let stream = TcpStream::connect("127.0.0.1:8080")
394    ///                        .expect("Couldn't connect to the server...");
395    /// stream.set_write_timeout(None).expect("set_write_timeout call failed");
396    /// assert_eq!(stream.write_timeout().unwrap(), None);
397    /// ```
398    #[stable(feature = "socket_timeout", since = "1.4.0")]
399    pub fn write_timeout(&self) -> io::Result<Option<Duration>> {
400        self.0.write_timeout()
401    }
402
403    /// Receives data on the socket from the remote address to which it is
404    /// connected, without removing that data from the queue. On success,
405    /// returns the number of bytes peeked.
406    ///
407    /// Successive calls return the same data. This is accomplished by passing
408    /// `MSG_PEEK` as a flag to the underlying `recv` system call.
409    ///
410    /// # Examples
411    ///
412    /// ```no_run
413    /// use std::net::TcpStream;
414    ///
415    /// let stream = TcpStream::connect("127.0.0.1:8000")
416    ///                        .expect("Couldn't connect to the server...");
417    /// let mut buf = [0; 10];
418    /// let len = stream.peek(&mut buf).expect("peek failed");
419    /// ```
420    #[stable(feature = "peek", since = "1.18.0")]
421    pub fn peek(&self, buf: &mut [u8]) -> io::Result<usize> {
422        self.0.peek(buf)
423    }
424
425    /// Sets the value of the `SO_LINGER` option on this socket.
426    ///
427    /// This value controls how the socket is closed when data remains
428    /// to be sent. If `SO_LINGER` is set, the socket will remain open
429    /// for the specified duration as the system attempts to send pending data.
430    /// Otherwise, the system may close the socket immediately, or wait for a
431    /// default timeout.
432    ///
433    /// # Examples
434    ///
435    /// ```no_run
436    /// #![feature(tcp_linger)]
437    ///
438    /// use std::net::TcpStream;
439    /// use std::time::Duration;
440    ///
441    /// let stream = TcpStream::connect("127.0.0.1:8080")
442    ///                        .expect("Couldn't connect to the server...");
443    /// stream.set_linger(Some(Duration::from_secs(0))).expect("set_linger call failed");
444    /// ```
445    #[unstable(feature = "tcp_linger", issue = "88494")]
446    pub fn set_linger(&self, linger: Option<Duration>) -> io::Result<()> {
447        self.0.set_linger(linger)
448    }
449
450    /// Gets the value of the `SO_LINGER` option on this socket.
451    ///
452    /// For more information about this option, see [`TcpStream::set_linger`].
453    ///
454    /// # Examples
455    ///
456    /// ```no_run
457    /// #![feature(tcp_linger)]
458    ///
459    /// use std::net::TcpStream;
460    /// use std::time::Duration;
461    ///
462    /// let stream = TcpStream::connect("127.0.0.1:8080")
463    ///                        .expect("Couldn't connect to the server...");
464    /// stream.set_linger(Some(Duration::from_secs(0))).expect("set_linger call failed");
465    /// assert_eq!(stream.linger().unwrap(), Some(Duration::from_secs(0)));
466    /// ```
467    #[unstable(feature = "tcp_linger", issue = "88494")]
468    pub fn linger(&self) -> io::Result<Option<Duration>> {
469        self.0.linger()
470    }
471
472    /// Sets the value of the `TCP_NODELAY` option on this socket.
473    ///
474    /// If set, this option disables the Nagle algorithm. This means that
475    /// segments are always sent as soon as possible, even if there is only a
476    /// small amount of data. When not set, data is buffered until there is a
477    /// sufficient amount to send out, thereby avoiding the frequent sending of
478    /// small packets.
479    ///
480    /// # Examples
481    ///
482    /// ```no_run
483    /// use std::net::TcpStream;
484    ///
485    /// let stream = TcpStream::connect("127.0.0.1:8080")
486    ///                        .expect("Couldn't connect to the server...");
487    /// stream.set_nodelay(true).expect("set_nodelay call failed");
488    /// ```
489    #[stable(feature = "net2_mutators", since = "1.9.0")]
490    pub fn set_nodelay(&self, nodelay: bool) -> io::Result<()> {
491        self.0.set_nodelay(nodelay)
492    }
493
494    /// Gets the value of the `TCP_NODELAY` option on this socket.
495    ///
496    /// For more information about this option, see [`TcpStream::set_nodelay`].
497    ///
498    /// # Examples
499    ///
500    /// ```no_run
501    /// use std::net::TcpStream;
502    ///
503    /// let stream = TcpStream::connect("127.0.0.1:8080")
504    ///                        .expect("Couldn't connect to the server...");
505    /// stream.set_nodelay(true).expect("set_nodelay call failed");
506    /// assert_eq!(stream.nodelay().unwrap_or(false), true);
507    /// ```
508    #[stable(feature = "net2_mutators", since = "1.9.0")]
509    pub fn nodelay(&self) -> io::Result<bool> {
510        self.0.nodelay()
511    }
512
513    /// Sets the value for the `IP_TTL` option on this socket.
514    ///
515    /// This value sets the time-to-live field that is used in every packet sent
516    /// from this socket.
517    ///
518    /// # Examples
519    ///
520    /// ```no_run
521    /// use std::net::TcpStream;
522    ///
523    /// let stream = TcpStream::connect("127.0.0.1:8080")
524    ///                        .expect("Couldn't connect to the server...");
525    /// stream.set_ttl(100).expect("set_ttl call failed");
526    /// ```
527    #[stable(feature = "net2_mutators", since = "1.9.0")]
528    pub fn set_ttl(&self, ttl: u32) -> io::Result<()> {
529        self.0.set_ttl(ttl)
530    }
531
532    /// Gets the value of the `IP_TTL` option for this socket.
533    ///
534    /// For more information about this option, see [`TcpStream::set_ttl`].
535    ///
536    /// # Examples
537    ///
538    /// ```no_run
539    /// use std::net::TcpStream;
540    ///
541    /// let stream = TcpStream::connect("127.0.0.1:8080")
542    ///                        .expect("Couldn't connect to the server...");
543    /// stream.set_ttl(100).expect("set_ttl call failed");
544    /// assert_eq!(stream.ttl().unwrap_or(0), 100);
545    /// ```
546    #[stable(feature = "net2_mutators", since = "1.9.0")]
547    pub fn ttl(&self) -> io::Result<u32> {
548        self.0.ttl()
549    }
550
551    /// Gets the value of the `SO_ERROR` option on this socket.
552    ///
553    /// This will retrieve the stored error in the underlying socket, clearing
554    /// the field in the process. This can be useful for checking errors between
555    /// calls.
556    ///
557    /// # Examples
558    ///
559    /// ```no_run
560    /// use std::net::TcpStream;
561    ///
562    /// let stream = TcpStream::connect("127.0.0.1:8080")
563    ///                        .expect("Couldn't connect to the server...");
564    /// stream.take_error().expect("No error was expected...");
565    /// ```
566    #[stable(feature = "net2_mutators", since = "1.9.0")]
567    pub fn take_error(&self) -> io::Result<Option<io::Error>> {
568        self.0.take_error()
569    }
570
571    /// Moves this TCP stream into or out of nonblocking mode.
572    ///
573    /// This will result in `read`, `write`, `recv` and `send` system operations
574    /// becoming nonblocking, i.e., immediately returning from their calls.
575    /// If the IO operation is successful, `Ok` is returned and no further
576    /// action is required. If the IO operation could not be completed and needs
577    /// to be retried, an error with kind [`io::ErrorKind::WouldBlock`] is
578    /// returned.
579    ///
580    /// On Unix platforms, calling this method corresponds to calling `fcntl`
581    /// `FIONBIO`. On Windows calling this method corresponds to calling
582    /// `ioctlsocket` `FIONBIO`.
583    ///
584    /// # Examples
585    ///
586    /// Reading bytes from a TCP stream in non-blocking mode:
587    ///
588    /// ```no_run
589    /// use std::io::{self, Read};
590    /// use std::net::TcpStream;
591    ///
592    /// let mut stream = TcpStream::connect("127.0.0.1:7878")
593    ///     .expect("Couldn't connect to the server...");
594    /// stream.set_nonblocking(true).expect("set_nonblocking call failed");
595    ///
596    /// # fn wait_for_fd() { unimplemented!() }
597    /// let mut buf = vec![];
598    /// loop {
599    ///     match stream.read_to_end(&mut buf) {
600    ///         Ok(_) => break,
601    ///         Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
602    ///             // wait until network socket is ready, typically implemented
603    ///             // via platform-specific APIs such as epoll or IOCP
604    ///             wait_for_fd();
605    ///         }
606    ///         Err(e) => panic!("encountered IO error: {e}"),
607    ///     };
608    /// };
609    /// println!("bytes: {buf:?}");
610    /// ```
611    #[stable(feature = "net2_mutators", since = "1.9.0")]
612    pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> {
613        self.0.set_nonblocking(nonblocking)
614    }
615}
616
617// In addition to the `impl`s here, `TcpStream` also has `impl`s for
618// `AsFd`/`From<OwnedFd>`/`Into<OwnedFd>` and
619// `AsRawFd`/`IntoRawFd`/`FromRawFd`, on Unix and WASI, and
620// `AsSocket`/`From<OwnedSocket>`/`Into<OwnedSocket>` and
621// `AsRawSocket`/`IntoRawSocket`/`FromRawSocket` on Windows.
622
623#[stable(feature = "rust1", since = "1.0.0")]
624impl Read for TcpStream {
625    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
626        self.0.read(buf)
627    }
628
629    fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> io::Result<()> {
630        self.0.read_buf(buf)
631    }
632
633    fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
634        self.0.read_vectored(bufs)
635    }
636
637    #[inline]
638    fn is_read_vectored(&self) -> bool {
639        self.0.is_read_vectored()
640    }
641}
642#[stable(feature = "rust1", since = "1.0.0")]
643impl Write for TcpStream {
644    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
645        self.0.write(buf)
646    }
647
648    fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
649        self.0.write_vectored(bufs)
650    }
651
652    #[inline]
653    fn is_write_vectored(&self) -> bool {
654        self.0.is_write_vectored()
655    }
656
657    #[inline]
658    fn flush(&mut self) -> io::Result<()> {
659        Ok(())
660    }
661}
662#[stable(feature = "rust1", since = "1.0.0")]
663impl Read for &TcpStream {
664    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
665        self.0.read(buf)
666    }
667
668    fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> io::Result<()> {
669        self.0.read_buf(buf)
670    }
671
672    fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
673        self.0.read_vectored(bufs)
674    }
675
676    #[inline]
677    fn is_read_vectored(&self) -> bool {
678        self.0.is_read_vectored()
679    }
680}
681#[stable(feature = "rust1", since = "1.0.0")]
682impl Write for &TcpStream {
683    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
684        self.0.write(buf)
685    }
686
687    fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
688        self.0.write_vectored(bufs)
689    }
690
691    #[inline]
692    fn is_write_vectored(&self) -> bool {
693        self.0.is_write_vectored()
694    }
695
696    #[inline]
697    fn flush(&mut self) -> io::Result<()> {
698        Ok(())
699    }
700}
701
702impl AsInner<net_imp::TcpStream> for TcpStream {
703    #[inline]
704    fn as_inner(&self) -> &net_imp::TcpStream {
705        &self.0
706    }
707}
708
709impl FromInner<net_imp::TcpStream> for TcpStream {
710    fn from_inner(inner: net_imp::TcpStream) -> TcpStream {
711        TcpStream(inner)
712    }
713}
714
715impl IntoInner<net_imp::TcpStream> for TcpStream {
716    fn into_inner(self) -> net_imp::TcpStream {
717        self.0
718    }
719}
720
721#[stable(feature = "rust1", since = "1.0.0")]
722impl fmt::Debug for TcpStream {
723    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
724        self.0.fmt(f)
725    }
726}
727
728impl TcpListener {
729    /// Creates a new `TcpListener` which will be bound to the specified
730    /// address.
731    ///
732    /// The returned listener is ready for accepting connections.
733    ///
734    /// Binding with a port number of 0 will request that the OS assigns a port
735    /// to this listener. The port allocated can be queried via the
736    /// [`TcpListener::local_addr`] method.
737    ///
738    /// The address type can be any implementor of [`ToSocketAddrs`] trait. See
739    /// its documentation for concrete examples.
740    ///
741    /// If `addr` yields multiple addresses, `bind` will be attempted with
742    /// each of the addresses until one succeeds and returns the listener. If
743    /// none of the addresses succeed in creating a listener, the error returned
744    /// from the last attempt (the last address) is returned.
745    ///
746    /// # Examples
747    ///
748    /// Creates a TCP listener bound to `127.0.0.1:80`:
749    ///
750    /// ```no_run
751    /// use std::net::TcpListener;
752    ///
753    /// let listener = TcpListener::bind("127.0.0.1:80").unwrap();
754    /// ```
755    ///
756    /// Creates a TCP listener bound to `127.0.0.1:80`. If that fails, create a
757    /// TCP listener bound to `127.0.0.1:443`:
758    ///
759    /// ```no_run
760    /// use std::net::{SocketAddr, TcpListener};
761    ///
762    /// let addrs = [
763    ///     SocketAddr::from(([127, 0, 0, 1], 80)),
764    ///     SocketAddr::from(([127, 0, 0, 1], 443)),
765    /// ];
766    /// let listener = TcpListener::bind(&addrs[..]).unwrap();
767    /// ```
768    ///
769    /// Creates a TCP listener bound to a port assigned by the operating system
770    /// at `127.0.0.1`.
771    ///
772    /// ```no_run
773    /// use std::net::TcpListener;
774    ///
775    /// let socket = TcpListener::bind("127.0.0.1:0").unwrap();
776    /// ```
777    #[stable(feature = "rust1", since = "1.0.0")]
778    pub fn bind<A: ToSocketAddrs>(addr: A) -> io::Result<TcpListener> {
779        super::each_addr(addr, net_imp::TcpListener::bind).map(TcpListener)
780    }
781
782    /// Returns the local socket address of this listener.
783    ///
784    /// # Examples
785    ///
786    /// ```no_run
787    /// use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4, TcpListener};
788    ///
789    /// let listener = TcpListener::bind("127.0.0.1:8080").unwrap();
790    /// assert_eq!(listener.local_addr().unwrap(),
791    ///            SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080)));
792    /// ```
793    #[stable(feature = "rust1", since = "1.0.0")]
794    pub fn local_addr(&self) -> io::Result<SocketAddr> {
795        self.0.socket_addr()
796    }
797
798    /// Creates a new independently owned handle to the underlying socket.
799    ///
800    /// The returned [`TcpListener`] is a reference to the same socket that this
801    /// object references. Both handles can be used to accept incoming
802    /// connections and options set on one listener will affect the other.
803    ///
804    /// # Examples
805    ///
806    /// ```no_run
807    /// use std::net::TcpListener;
808    ///
809    /// let listener = TcpListener::bind("127.0.0.1:8080").unwrap();
810    /// let listener_clone = listener.try_clone().unwrap();
811    /// ```
812    #[stable(feature = "rust1", since = "1.0.0")]
813    pub fn try_clone(&self) -> io::Result<TcpListener> {
814        self.0.duplicate().map(TcpListener)
815    }
816
817    /// Accept a new incoming connection from this listener.
818    ///
819    /// This function will block the calling thread until a new TCP connection
820    /// is established. When established, the corresponding [`TcpStream`] and the
821    /// remote peer's address will be returned.
822    ///
823    /// # Examples
824    ///
825    /// ```no_run
826    /// use std::net::TcpListener;
827    ///
828    /// let listener = TcpListener::bind("127.0.0.1:8080").unwrap();
829    /// match listener.accept() {
830    ///     Ok((_socket, addr)) => println!("new client: {addr:?}"),
831    ///     Err(e) => println!("couldn't get client: {e:?}"),
832    /// }
833    /// ```
834    #[stable(feature = "rust1", since = "1.0.0")]
835    pub fn accept(&self) -> io::Result<(TcpStream, SocketAddr)> {
836        // On WASM, `TcpStream` is uninhabited (as it's unsupported) and so
837        // the `a` variable here is technically unused.
838        #[cfg_attr(target_arch = "wasm32", allow(unused_variables))]
839        self.0.accept().map(|(a, b)| (TcpStream(a), b))
840    }
841
842    /// Returns an iterator over the connections being received on this
843    /// listener.
844    ///
845    /// The returned iterator will never return [`None`] and will also not yield
846    /// the peer's [`SocketAddr`] structure. Iterating over it is equivalent to
847    /// calling [`TcpListener::accept`] in a loop.
848    ///
849    /// # Examples
850    ///
851    /// ```no_run
852    /// use std::net::{TcpListener, TcpStream};
853    ///
854    /// fn handle_connection(stream: TcpStream) {
855    ///    //...
856    /// }
857    ///
858    /// fn main() -> std::io::Result<()> {
859    ///     let listener = TcpListener::bind("127.0.0.1:80")?;
860    ///
861    ///     for stream in listener.incoming() {
862    ///         match stream {
863    ///             Ok(stream) => {
864    ///                 handle_connection(stream);
865    ///             }
866    ///             Err(e) => { /* connection failed */ }
867    ///         }
868    ///     }
869    ///     Ok(())
870    /// }
871    /// ```
872    #[stable(feature = "rust1", since = "1.0.0")]
873    pub fn incoming(&self) -> Incoming<'_> {
874        Incoming { listener: self }
875    }
876
877    /// Turn this into an iterator over the connections being received on this
878    /// listener.
879    ///
880    /// The returned iterator will never return [`None`] and will also not yield
881    /// the peer's [`SocketAddr`] structure. Iterating over it is equivalent to
882    /// calling [`TcpListener::accept`] in a loop.
883    ///
884    /// # Examples
885    ///
886    /// ```no_run
887    /// #![feature(tcplistener_into_incoming)]
888    /// use std::net::{TcpListener, TcpStream};
889    ///
890    /// fn listen_on(port: u16) -> impl Iterator<Item = TcpStream> {
891    ///     let listener = TcpListener::bind(("127.0.0.1", port)).unwrap();
892    ///     listener.into_incoming()
893    ///         .filter_map(Result::ok) /* Ignore failed connections */
894    /// }
895    ///
896    /// fn main() -> std::io::Result<()> {
897    ///     for stream in listen_on(80) {
898    ///         /* handle the connection here */
899    ///     }
900    ///     Ok(())
901    /// }
902    /// ```
903    #[must_use = "`self` will be dropped if the result is not used"]
904    #[unstable(feature = "tcplistener_into_incoming", issue = "88373")]
905    pub fn into_incoming(self) -> IntoIncoming {
906        IntoIncoming { listener: self }
907    }
908
909    /// Sets the value for the `IP_TTL` option on this socket.
910    ///
911    /// This value sets the time-to-live field that is used in every packet sent
912    /// from this socket.
913    ///
914    /// # Examples
915    ///
916    /// ```no_run
917    /// use std::net::TcpListener;
918    ///
919    /// let listener = TcpListener::bind("127.0.0.1:80").unwrap();
920    /// listener.set_ttl(100).expect("could not set TTL");
921    /// ```
922    #[stable(feature = "net2_mutators", since = "1.9.0")]
923    pub fn set_ttl(&self, ttl: u32) -> io::Result<()> {
924        self.0.set_ttl(ttl)
925    }
926
927    /// Gets the value of the `IP_TTL` option for this socket.
928    ///
929    /// For more information about this option, see [`TcpListener::set_ttl`].
930    ///
931    /// # Examples
932    ///
933    /// ```no_run
934    /// use std::net::TcpListener;
935    ///
936    /// let listener = TcpListener::bind("127.0.0.1:80").unwrap();
937    /// listener.set_ttl(100).expect("could not set TTL");
938    /// assert_eq!(listener.ttl().unwrap_or(0), 100);
939    /// ```
940    #[stable(feature = "net2_mutators", since = "1.9.0")]
941    pub fn ttl(&self) -> io::Result<u32> {
942        self.0.ttl()
943    }
944
945    #[stable(feature = "net2_mutators", since = "1.9.0")]
946    #[deprecated(since = "1.16.0", note = "this option can only be set before the socket is bound")]
947    #[allow(missing_docs)]
948    pub fn set_only_v6(&self, only_v6: bool) -> io::Result<()> {
949        self.0.set_only_v6(only_v6)
950    }
951
952    #[stable(feature = "net2_mutators", since = "1.9.0")]
953    #[deprecated(since = "1.16.0", note = "this option can only be set before the socket is bound")]
954    #[allow(missing_docs)]
955    pub fn only_v6(&self) -> io::Result<bool> {
956        self.0.only_v6()
957    }
958
959    /// Gets the value of the `SO_ERROR` option on this socket.
960    ///
961    /// This will retrieve the stored error in the underlying socket, clearing
962    /// the field in the process. This can be useful for checking errors between
963    /// calls.
964    ///
965    /// # Examples
966    ///
967    /// ```no_run
968    /// use std::net::TcpListener;
969    ///
970    /// let listener = TcpListener::bind("127.0.0.1:80").unwrap();
971    /// listener.take_error().expect("No error was expected");
972    /// ```
973    #[stable(feature = "net2_mutators", since = "1.9.0")]
974    pub fn take_error(&self) -> io::Result<Option<io::Error>> {
975        self.0.take_error()
976    }
977
978    /// Moves this TCP stream into or out of nonblocking mode.
979    ///
980    /// This will result in the `accept` operation becoming nonblocking,
981    /// i.e., immediately returning from their calls. If the IO operation is
982    /// successful, `Ok` is returned and no further action is required. If the
983    /// IO operation could not be completed and needs to be retried, an error
984    /// with kind [`io::ErrorKind::WouldBlock`] is returned.
985    ///
986    /// On Unix platforms, calling this method corresponds to calling `fcntl`
987    /// `FIONBIO`. On Windows calling this method corresponds to calling
988    /// `ioctlsocket` `FIONBIO`.
989    ///
990    /// # Examples
991    ///
992    /// Bind a TCP listener to an address, listen for connections, and read
993    /// bytes in nonblocking mode:
994    ///
995    /// ```no_run
996    /// use std::io;
997    /// use std::net::TcpListener;
998    ///
999    /// let listener = TcpListener::bind("127.0.0.1:7878").unwrap();
1000    /// listener.set_nonblocking(true).expect("Cannot set non-blocking");
1001    ///
1002    /// # fn wait_for_fd() { unimplemented!() }
1003    /// # fn handle_connection(stream: std::net::TcpStream) { unimplemented!() }
1004    /// for stream in listener.incoming() {
1005    ///     match stream {
1006    ///         Ok(s) => {
1007    ///             // do something with the TcpStream
1008    ///             handle_connection(s);
1009    ///         }
1010    ///         Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
1011    ///             // wait until network socket is ready, typically implemented
1012    ///             // via platform-specific APIs such as epoll or IOCP
1013    ///             wait_for_fd();
1014    ///             continue;
1015    ///         }
1016    ///         Err(e) => panic!("encountered IO error: {e}"),
1017    ///     }
1018    /// }
1019    /// ```
1020    #[stable(feature = "net2_mutators", since = "1.9.0")]
1021    pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> {
1022        self.0.set_nonblocking(nonblocking)
1023    }
1024}
1025
1026// In addition to the `impl`s here, `TcpListener` also has `impl`s for
1027// `AsFd`/`From<OwnedFd>`/`Into<OwnedFd>` and
1028// `AsRawFd`/`IntoRawFd`/`FromRawFd`, on Unix and WASI, and
1029// `AsSocket`/`From<OwnedSocket>`/`Into<OwnedSocket>` and
1030// `AsRawSocket`/`IntoRawSocket`/`FromRawSocket` on Windows.
1031
1032#[stable(feature = "rust1", since = "1.0.0")]
1033impl<'a> Iterator for Incoming<'a> {
1034    type Item = io::Result<TcpStream>;
1035    fn next(&mut self) -> Option<io::Result<TcpStream>> {
1036        Some(self.listener.accept().map(|p| p.0))
1037    }
1038}
1039
1040#[stable(feature = "tcp_listener_incoming_fused_iterator", since = "1.64.0")]
1041impl FusedIterator for Incoming<'_> {}
1042
1043#[unstable(feature = "tcplistener_into_incoming", issue = "88373")]
1044impl Iterator for IntoIncoming {
1045    type Item = io::Result<TcpStream>;
1046    fn next(&mut self) -> Option<io::Result<TcpStream>> {
1047        Some(self.listener.accept().map(|p| p.0))
1048    }
1049}
1050
1051#[unstable(feature = "tcplistener_into_incoming", issue = "88373")]
1052impl FusedIterator for IntoIncoming {}
1053
1054impl AsInner<net_imp::TcpListener> for TcpListener {
1055    #[inline]
1056    fn as_inner(&self) -> &net_imp::TcpListener {
1057        &self.0
1058    }
1059}
1060
1061impl FromInner<net_imp::TcpListener> for TcpListener {
1062    fn from_inner(inner: net_imp::TcpListener) -> TcpListener {
1063        TcpListener(inner)
1064    }
1065}
1066
1067impl IntoInner<net_imp::TcpListener> for TcpListener {
1068    fn into_inner(self) -> net_imp::TcpListener {
1069        self.0
1070    }
1071}
1072
1073#[stable(feature = "rust1", since = "1.0.0")]
1074impl fmt::Debug for TcpListener {
1075    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1076        self.0.fmt(f)
1077    }
1078}