std/os/unix/net/
datagram.rs

1#[cfg(any(
2    target_os = "linux",
3    target_os = "android",
4    target_os = "dragonfly",
5    target_os = "freebsd",
6    target_os = "openbsd",
7    target_os = "netbsd",
8    target_os = "solaris",
9    target_os = "illumos",
10    target_os = "haiku",
11    target_os = "nto",
12))]
13use libc::MSG_NOSIGNAL;
14
15use super::{SocketAddr, sockaddr_un};
16#[cfg(any(doc, target_os = "android", target_os = "linux"))]
17use super::{SocketAncillary, recv_vectored_with_ancillary_from, send_vectored_with_ancillary_to};
18#[cfg(any(doc, target_os = "android", target_os = "linux"))]
19use crate::io::{IoSlice, IoSliceMut};
20use crate::net::Shutdown;
21use crate::os::unix::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd};
22use crate::path::Path;
23use crate::sealed::Sealed;
24use crate::sys::cvt;
25use crate::sys::net::Socket;
26use crate::sys_common::{AsInner, FromInner, IntoInner};
27use crate::time::Duration;
28use crate::{fmt, io};
29#[cfg(not(any(
30    target_os = "linux",
31    target_os = "android",
32    target_os = "dragonfly",
33    target_os = "freebsd",
34    target_os = "openbsd",
35    target_os = "netbsd",
36    target_os = "solaris",
37    target_os = "illumos",
38    target_os = "haiku",
39    target_os = "nto",
40)))]
41const MSG_NOSIGNAL: core::ffi::c_int = 0x0;
42
43/// A Unix datagram socket.
44///
45/// # Examples
46///
47/// ```no_run
48/// use std::os::unix::net::UnixDatagram;
49///
50/// fn main() -> std::io::Result<()> {
51///     let socket = UnixDatagram::bind("/path/to/my/socket")?;
52///     socket.send_to(b"hello world", "/path/to/other/socket")?;
53///     let mut buf = [0; 100];
54///     let (count, address) = socket.recv_from(&mut buf)?;
55///     println!("socket {:?} sent {:?}", address, &buf[..count]);
56///     Ok(())
57/// }
58/// ```
59#[stable(feature = "unix_socket", since = "1.10.0")]
60pub struct UnixDatagram(Socket);
61
62/// Allows extension traits within `std`.
63#[unstable(feature = "sealed", issue = "none")]
64impl Sealed for UnixDatagram {}
65
66#[stable(feature = "unix_socket", since = "1.10.0")]
67impl fmt::Debug for UnixDatagram {
68    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
69        let mut builder = fmt.debug_struct("UnixDatagram");
70        builder.field("fd", self.0.as_inner());
71        if let Ok(addr) = self.local_addr() {
72            builder.field("local", &addr);
73        }
74        if let Ok(addr) = self.peer_addr() {
75            builder.field("peer", &addr);
76        }
77        builder.finish()
78    }
79}
80
81impl UnixDatagram {
82    /// Creates a Unix datagram socket bound to the given path.
83    ///
84    /// # Examples
85    ///
86    /// ```no_run
87    /// use std::os::unix::net::UnixDatagram;
88    ///
89    /// let sock = match UnixDatagram::bind("/path/to/the/socket") {
90    ///     Ok(sock) => sock,
91    ///     Err(e) => {
92    ///         println!("Couldn't bind: {e:?}");
93    ///         return
94    ///     }
95    /// };
96    /// ```
97    #[stable(feature = "unix_socket", since = "1.10.0")]
98    pub fn bind<P: AsRef<Path>>(path: P) -> io::Result<UnixDatagram> {
99        unsafe {
100            let socket = UnixDatagram::unbound()?;
101            let (addr, len) = sockaddr_un(path.as_ref())?;
102
103            cvt(libc::bind(socket.as_raw_fd(), (&raw const addr) as *const _, len as _))?;
104
105            Ok(socket)
106        }
107    }
108
109    /// Creates a Unix datagram socket bound to an address.
110    ///
111    /// # Examples
112    ///
113    /// ```no_run
114    /// use std::os::unix::net::{UnixDatagram};
115    ///
116    /// fn main() -> std::io::Result<()> {
117    ///     let sock1 = UnixDatagram::bind("path/to/socket")?;
118    ///     let addr = sock1.local_addr()?;
119    ///
120    ///     let sock2 = match UnixDatagram::bind_addr(&addr) {
121    ///         Ok(sock) => sock,
122    ///         Err(err) => {
123    ///             println!("Couldn't bind: {err:?}");
124    ///             return Err(err);
125    ///         }
126    ///     };
127    ///     Ok(())
128    /// }
129    /// ```
130    #[stable(feature = "unix_socket_abstract", since = "1.70.0")]
131    pub fn bind_addr(socket_addr: &SocketAddr) -> io::Result<UnixDatagram> {
132        unsafe {
133            let socket = UnixDatagram::unbound()?;
134            cvt(libc::bind(
135                socket.as_raw_fd(),
136                (&raw const socket_addr.addr) as *const _,
137                socket_addr.len as _,
138            ))?;
139            Ok(socket)
140        }
141    }
142
143    /// Creates a Unix Datagram socket which is not bound to any address.
144    ///
145    /// # Examples
146    ///
147    /// ```no_run
148    /// use std::os::unix::net::UnixDatagram;
149    ///
150    /// let sock = match UnixDatagram::unbound() {
151    ///     Ok(sock) => sock,
152    ///     Err(e) => {
153    ///         println!("Couldn't unbound: {e:?}");
154    ///         return
155    ///     }
156    /// };
157    /// ```
158    #[stable(feature = "unix_socket", since = "1.10.0")]
159    pub fn unbound() -> io::Result<UnixDatagram> {
160        let inner = Socket::new_raw(libc::AF_UNIX, libc::SOCK_DGRAM)?;
161        Ok(UnixDatagram(inner))
162    }
163
164    /// Creates an unnamed pair of connected sockets.
165    ///
166    /// Returns two `UnixDatagrams`s which are connected to each other.
167    ///
168    /// # Examples
169    ///
170    /// ```no_run
171    /// use std::os::unix::net::UnixDatagram;
172    ///
173    /// let (sock1, sock2) = match UnixDatagram::pair() {
174    ///     Ok((sock1, sock2)) => (sock1, sock2),
175    ///     Err(e) => {
176    ///         println!("Couldn't unbound: {e:?}");
177    ///         return
178    ///     }
179    /// };
180    /// ```
181    #[stable(feature = "unix_socket", since = "1.10.0")]
182    pub fn pair() -> io::Result<(UnixDatagram, UnixDatagram)> {
183        let (i1, i2) = Socket::new_pair(libc::AF_UNIX, libc::SOCK_DGRAM)?;
184        Ok((UnixDatagram(i1), UnixDatagram(i2)))
185    }
186
187    /// Connects the socket to the specified path address.
188    ///
189    /// The [`send`] method may be used to send data to the specified address.
190    /// [`recv`] and [`recv_from`] will only receive data from that address.
191    ///
192    /// [`send`]: UnixDatagram::send
193    /// [`recv`]: UnixDatagram::recv
194    /// [`recv_from`]: UnixDatagram::recv_from
195    ///
196    /// # Examples
197    ///
198    /// ```no_run
199    /// use std::os::unix::net::UnixDatagram;
200    ///
201    /// fn main() -> std::io::Result<()> {
202    ///     let sock = UnixDatagram::unbound()?;
203    ///     match sock.connect("/path/to/the/socket") {
204    ///         Ok(sock) => sock,
205    ///         Err(e) => {
206    ///             println!("Couldn't connect: {e:?}");
207    ///             return Err(e)
208    ///         }
209    ///     };
210    ///     Ok(())
211    /// }
212    /// ```
213    #[stable(feature = "unix_socket", since = "1.10.0")]
214    pub fn connect<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
215        unsafe {
216            let (addr, len) = sockaddr_un(path.as_ref())?;
217
218            cvt(libc::connect(self.as_raw_fd(), (&raw const addr) as *const _, len))?;
219        }
220        Ok(())
221    }
222
223    /// Connects the socket to an address.
224    ///
225    /// # Examples
226    ///
227    /// ```no_run
228    /// use std::os::unix::net::{UnixDatagram};
229    ///
230    /// fn main() -> std::io::Result<()> {
231    ///     let bound = UnixDatagram::bind("/path/to/socket")?;
232    ///     let addr = bound.local_addr()?;
233    ///
234    ///     let sock = UnixDatagram::unbound()?;
235    ///     match sock.connect_addr(&addr) {
236    ///         Ok(sock) => sock,
237    ///         Err(e) => {
238    ///             println!("Couldn't connect: {e:?}");
239    ///             return Err(e)
240    ///         }
241    ///     };
242    ///     Ok(())
243    /// }
244    /// ```
245    #[stable(feature = "unix_socket_abstract", since = "1.70.0")]
246    pub fn connect_addr(&self, socket_addr: &SocketAddr) -> io::Result<()> {
247        unsafe {
248            cvt(libc::connect(
249                self.as_raw_fd(),
250                (&raw const socket_addr.addr) as *const _,
251                socket_addr.len,
252            ))?;
253        }
254        Ok(())
255    }
256
257    /// Creates a new independently owned handle to the underlying socket.
258    ///
259    /// The returned `UnixDatagram` is a reference to the same socket that this
260    /// object references. Both handles can be used to accept incoming
261    /// connections and options set on one side will affect the other.
262    ///
263    /// # Examples
264    ///
265    /// ```no_run
266    /// use std::os::unix::net::UnixDatagram;
267    ///
268    /// fn main() -> std::io::Result<()> {
269    ///     let sock = UnixDatagram::bind("/path/to/the/socket")?;
270    ///     let sock_copy = sock.try_clone().expect("try_clone failed");
271    ///     Ok(())
272    /// }
273    /// ```
274    #[stable(feature = "unix_socket", since = "1.10.0")]
275    pub fn try_clone(&self) -> io::Result<UnixDatagram> {
276        self.0.duplicate().map(UnixDatagram)
277    }
278
279    /// Returns the address of this socket.
280    ///
281    /// # Examples
282    ///
283    /// ```no_run
284    /// use std::os::unix::net::UnixDatagram;
285    ///
286    /// fn main() -> std::io::Result<()> {
287    ///     let sock = UnixDatagram::bind("/path/to/the/socket")?;
288    ///     let addr = sock.local_addr().expect("Couldn't get local address");
289    ///     Ok(())
290    /// }
291    /// ```
292    #[stable(feature = "unix_socket", since = "1.10.0")]
293    pub fn local_addr(&self) -> io::Result<SocketAddr> {
294        SocketAddr::new(|addr, len| unsafe { libc::getsockname(self.as_raw_fd(), addr, len) })
295    }
296
297    /// Returns the address of this socket's peer.
298    ///
299    /// The [`connect`] method will connect the socket to a peer.
300    ///
301    /// [`connect`]: UnixDatagram::connect
302    ///
303    /// # Examples
304    ///
305    /// ```no_run
306    /// use std::os::unix::net::UnixDatagram;
307    ///
308    /// fn main() -> std::io::Result<()> {
309    ///     let sock = UnixDatagram::unbound()?;
310    ///     sock.connect("/path/to/the/socket")?;
311    ///
312    ///     let addr = sock.peer_addr().expect("Couldn't get peer address");
313    ///     Ok(())
314    /// }
315    /// ```
316    #[stable(feature = "unix_socket", since = "1.10.0")]
317    pub fn peer_addr(&self) -> io::Result<SocketAddr> {
318        SocketAddr::new(|addr, len| unsafe { libc::getpeername(self.as_raw_fd(), addr, len) })
319    }
320
321    fn recv_from_flags(
322        &self,
323        buf: &mut [u8],
324        flags: core::ffi::c_int,
325    ) -> io::Result<(usize, SocketAddr)> {
326        let mut count = 0;
327        let addr = SocketAddr::new(|addr, len| unsafe {
328            count = libc::recvfrom(
329                self.as_raw_fd(),
330                buf.as_mut_ptr() as *mut _,
331                buf.len(),
332                flags,
333                addr,
334                len,
335            );
336            if count > 0 {
337                1
338            } else if count == 0 {
339                0
340            } else {
341                -1
342            }
343        })?;
344
345        Ok((count as usize, addr))
346    }
347
348    /// Receives data from the socket.
349    ///
350    /// On success, returns the number of bytes read and the address from
351    /// whence the data came.
352    ///
353    /// # Examples
354    ///
355    /// ```no_run
356    /// use std::os::unix::net::UnixDatagram;
357    ///
358    /// fn main() -> std::io::Result<()> {
359    ///     let sock = UnixDatagram::unbound()?;
360    ///     let mut buf = vec![0; 10];
361    ///     let (size, sender) = sock.recv_from(buf.as_mut_slice())?;
362    ///     println!("received {size} bytes from {sender:?}");
363    ///     Ok(())
364    /// }
365    /// ```
366    #[stable(feature = "unix_socket", since = "1.10.0")]
367    pub fn recv_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> {
368        self.recv_from_flags(buf, 0)
369    }
370
371    /// Receives data from the socket.
372    ///
373    /// On success, returns the number of bytes read.
374    ///
375    /// # Examples
376    ///
377    /// ```no_run
378    /// use std::os::unix::net::UnixDatagram;
379    ///
380    /// fn main() -> std::io::Result<()> {
381    ///     let sock = UnixDatagram::bind("/path/to/the/socket")?;
382    ///     let mut buf = vec![0; 10];
383    ///     sock.recv(buf.as_mut_slice()).expect("recv function failed");
384    ///     Ok(())
385    /// }
386    /// ```
387    #[stable(feature = "unix_socket", since = "1.10.0")]
388    pub fn recv(&self, buf: &mut [u8]) -> io::Result<usize> {
389        self.0.read(buf)
390    }
391
392    /// Receives data and ancillary data from socket.
393    ///
394    /// On success, returns the number of bytes read, if the data was truncated and the address from whence the msg came.
395    ///
396    /// # Examples
397    ///
398    #[cfg_attr(any(target_os = "android", target_os = "linux"), doc = "```no_run")]
399    #[cfg_attr(not(any(target_os = "android", target_os = "linux")), doc = "```ignore")]
400    /// #![feature(unix_socket_ancillary_data)]
401    /// use std::os::unix::net::{UnixDatagram, SocketAncillary, AncillaryData};
402    /// use std::io::IoSliceMut;
403    ///
404    /// fn main() -> std::io::Result<()> {
405    ///     let sock = UnixDatagram::unbound()?;
406    ///     let mut buf1 = [1; 8];
407    ///     let mut buf2 = [2; 16];
408    ///     let mut buf3 = [3; 8];
409    ///     let mut bufs = &mut [
410    ///         IoSliceMut::new(&mut buf1),
411    ///         IoSliceMut::new(&mut buf2),
412    ///         IoSliceMut::new(&mut buf3),
413    ///     ][..];
414    ///     let mut fds = [0; 8];
415    ///     let mut ancillary_buffer = [0; 128];
416    ///     let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]);
417    ///     let (size, _truncated, sender) = sock.recv_vectored_with_ancillary_from(bufs, &mut ancillary)?;
418    ///     println!("received {size}");
419    ///     for ancillary_result in ancillary.messages() {
420    ///         if let AncillaryData::ScmRights(scm_rights) = ancillary_result.unwrap() {
421    ///             for fd in scm_rights {
422    ///                 println!("receive file descriptor: {fd}");
423    ///             }
424    ///         }
425    ///     }
426    ///     Ok(())
427    /// }
428    /// ```
429    #[cfg(any(doc, target_os = "android", target_os = "linux"))]
430    #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")]
431    pub fn recv_vectored_with_ancillary_from(
432        &self,
433        bufs: &mut [IoSliceMut<'_>],
434        ancillary: &mut SocketAncillary<'_>,
435    ) -> io::Result<(usize, bool, SocketAddr)> {
436        let (count, truncated, addr) = recv_vectored_with_ancillary_from(&self.0, bufs, ancillary)?;
437        let addr = addr?;
438
439        Ok((count, truncated, addr))
440    }
441
442    /// Receives data and ancillary data from socket.
443    ///
444    /// On success, returns the number of bytes read and if the data was truncated.
445    ///
446    /// # Examples
447    ///
448    #[cfg_attr(any(target_os = "android", target_os = "linux"), doc = "```no_run")]
449    #[cfg_attr(not(any(target_os = "android", target_os = "linux")), doc = "```ignore")]
450    /// #![feature(unix_socket_ancillary_data)]
451    /// use std::os::unix::net::{UnixDatagram, SocketAncillary, AncillaryData};
452    /// use std::io::IoSliceMut;
453    ///
454    /// fn main() -> std::io::Result<()> {
455    ///     let sock = UnixDatagram::unbound()?;
456    ///     let mut buf1 = [1; 8];
457    ///     let mut buf2 = [2; 16];
458    ///     let mut buf3 = [3; 8];
459    ///     let mut bufs = &mut [
460    ///         IoSliceMut::new(&mut buf1),
461    ///         IoSliceMut::new(&mut buf2),
462    ///         IoSliceMut::new(&mut buf3),
463    ///     ][..];
464    ///     let mut fds = [0; 8];
465    ///     let mut ancillary_buffer = [0; 128];
466    ///     let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]);
467    ///     let (size, _truncated) = sock.recv_vectored_with_ancillary(bufs, &mut ancillary)?;
468    ///     println!("received {size}");
469    ///     for ancillary_result in ancillary.messages() {
470    ///         if let AncillaryData::ScmRights(scm_rights) = ancillary_result.unwrap() {
471    ///             for fd in scm_rights {
472    ///                 println!("receive file descriptor: {fd}");
473    ///             }
474    ///         }
475    ///     }
476    ///     Ok(())
477    /// }
478    /// ```
479    #[cfg(any(doc, target_os = "android", target_os = "linux"))]
480    #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")]
481    pub fn recv_vectored_with_ancillary(
482        &self,
483        bufs: &mut [IoSliceMut<'_>],
484        ancillary: &mut SocketAncillary<'_>,
485    ) -> io::Result<(usize, bool)> {
486        let (count, truncated, addr) = recv_vectored_with_ancillary_from(&self.0, bufs, ancillary)?;
487        addr?;
488
489        Ok((count, truncated))
490    }
491
492    /// Sends data on the socket to the specified address.
493    ///
494    /// On success, returns the number of bytes written.
495    ///
496    /// # Examples
497    ///
498    /// ```no_run
499    /// use std::os::unix::net::UnixDatagram;
500    ///
501    /// fn main() -> std::io::Result<()> {
502    ///     let sock = UnixDatagram::unbound()?;
503    ///     sock.send_to(b"omelette au fromage", "/some/sock").expect("send_to function failed");
504    ///     Ok(())
505    /// }
506    /// ```
507    #[stable(feature = "unix_socket", since = "1.10.0")]
508    pub fn send_to<P: AsRef<Path>>(&self, buf: &[u8], path: P) -> io::Result<usize> {
509        unsafe {
510            let (addr, len) = sockaddr_un(path.as_ref())?;
511
512            let count = cvt(libc::sendto(
513                self.as_raw_fd(),
514                buf.as_ptr() as *const _,
515                buf.len(),
516                MSG_NOSIGNAL,
517                (&raw const addr) as *const _,
518                len,
519            ))?;
520            Ok(count as usize)
521        }
522    }
523
524    /// Sends data on the socket to the specified [SocketAddr].
525    ///
526    /// On success, returns the number of bytes written.
527    ///
528    /// [SocketAddr]: crate::os::unix::net::SocketAddr
529    ///
530    /// # Examples
531    ///
532    /// ```no_run
533    /// use std::os::unix::net::{UnixDatagram};
534    ///
535    /// fn main() -> std::io::Result<()> {
536    ///     let bound = UnixDatagram::bind("/path/to/socket")?;
537    ///     let addr = bound.local_addr()?;
538    ///
539    ///     let sock = UnixDatagram::unbound()?;
540    ///     sock.send_to_addr(b"bacon egg and cheese", &addr).expect("send_to_addr function failed");
541    ///     Ok(())
542    /// }
543    /// ```
544    #[stable(feature = "unix_socket_abstract", since = "1.70.0")]
545    pub fn send_to_addr(&self, buf: &[u8], socket_addr: &SocketAddr) -> io::Result<usize> {
546        unsafe {
547            let count = cvt(libc::sendto(
548                self.as_raw_fd(),
549                buf.as_ptr() as *const _,
550                buf.len(),
551                MSG_NOSIGNAL,
552                (&raw const socket_addr.addr) as *const _,
553                socket_addr.len,
554            ))?;
555            Ok(count as usize)
556        }
557    }
558
559    /// Sends data on the socket to the socket's peer.
560    ///
561    /// The peer address may be set by the `connect` method, and this method
562    /// will return an error if the socket has not already been connected.
563    ///
564    /// On success, returns the number of bytes written.
565    ///
566    /// # Examples
567    ///
568    /// ```no_run
569    /// use std::os::unix::net::UnixDatagram;
570    ///
571    /// fn main() -> std::io::Result<()> {
572    ///     let sock = UnixDatagram::unbound()?;
573    ///     sock.connect("/some/sock").expect("Couldn't connect");
574    ///     sock.send(b"omelette au fromage").expect("send_to function failed");
575    ///     Ok(())
576    /// }
577    /// ```
578    #[stable(feature = "unix_socket", since = "1.10.0")]
579    pub fn send(&self, buf: &[u8]) -> io::Result<usize> {
580        self.0.write(buf)
581    }
582
583    /// Sends data and ancillary data on the socket to the specified address.
584    ///
585    /// On success, returns the number of bytes written.
586    ///
587    /// # Examples
588    ///
589    #[cfg_attr(any(target_os = "android", target_os = "linux"), doc = "```no_run")]
590    #[cfg_attr(not(any(target_os = "android", target_os = "linux")), doc = "```ignore")]
591    /// #![feature(unix_socket_ancillary_data)]
592    /// use std::os::unix::net::{UnixDatagram, SocketAncillary};
593    /// use std::io::IoSlice;
594    ///
595    /// fn main() -> std::io::Result<()> {
596    ///     let sock = UnixDatagram::unbound()?;
597    ///     let buf1 = [1; 8];
598    ///     let buf2 = [2; 16];
599    ///     let buf3 = [3; 8];
600    ///     let bufs = &[
601    ///         IoSlice::new(&buf1),
602    ///         IoSlice::new(&buf2),
603    ///         IoSlice::new(&buf3),
604    ///     ][..];
605    ///     let fds = [0, 1, 2];
606    ///     let mut ancillary_buffer = [0; 128];
607    ///     let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]);
608    ///     ancillary.add_fds(&fds[..]);
609    ///     sock.send_vectored_with_ancillary_to(bufs, &mut ancillary, "/some/sock")
610    ///         .expect("send_vectored_with_ancillary_to function failed");
611    ///     Ok(())
612    /// }
613    /// ```
614    #[cfg(any(doc, target_os = "android", target_os = "linux"))]
615    #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")]
616    pub fn send_vectored_with_ancillary_to<P: AsRef<Path>>(
617        &self,
618        bufs: &[IoSlice<'_>],
619        ancillary: &mut SocketAncillary<'_>,
620        path: P,
621    ) -> io::Result<usize> {
622        send_vectored_with_ancillary_to(&self.0, Some(path.as_ref()), bufs, ancillary)
623    }
624
625    /// Sends data and ancillary data on the socket.
626    ///
627    /// On success, returns the number of bytes written.
628    ///
629    /// # Examples
630    ///
631    #[cfg_attr(any(target_os = "android", target_os = "linux"), doc = "```no_run")]
632    #[cfg_attr(not(any(target_os = "android", target_os = "linux")), doc = "```ignore")]
633    /// #![feature(unix_socket_ancillary_data)]
634    /// use std::os::unix::net::{UnixDatagram, SocketAncillary};
635    /// use std::io::IoSlice;
636    ///
637    /// fn main() -> std::io::Result<()> {
638    ///     let sock = UnixDatagram::unbound()?;
639    ///     let buf1 = [1; 8];
640    ///     let buf2 = [2; 16];
641    ///     let buf3 = [3; 8];
642    ///     let bufs = &[
643    ///         IoSlice::new(&buf1),
644    ///         IoSlice::new(&buf2),
645    ///         IoSlice::new(&buf3),
646    ///     ][..];
647    ///     let fds = [0, 1, 2];
648    ///     let mut ancillary_buffer = [0; 128];
649    ///     let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]);
650    ///     ancillary.add_fds(&fds[..]);
651    ///     sock.send_vectored_with_ancillary(bufs, &mut ancillary)
652    ///         .expect("send_vectored_with_ancillary function failed");
653    ///     Ok(())
654    /// }
655    /// ```
656    #[cfg(any(doc, target_os = "android", target_os = "linux"))]
657    #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")]
658    pub fn send_vectored_with_ancillary(
659        &self,
660        bufs: &[IoSlice<'_>],
661        ancillary: &mut SocketAncillary<'_>,
662    ) -> io::Result<usize> {
663        send_vectored_with_ancillary_to(&self.0, None, bufs, ancillary)
664    }
665
666    /// Sets the read timeout for the socket.
667    ///
668    /// If the provided value is [`None`], then [`recv`] and [`recv_from`] calls will
669    /// block indefinitely. An [`Err`] is returned if the zero [`Duration`]
670    /// is passed to this method.
671    ///
672    /// [`recv`]: UnixDatagram::recv
673    /// [`recv_from`]: UnixDatagram::recv_from
674    ///
675    /// # Examples
676    ///
677    /// ```
678    /// use std::os::unix::net::UnixDatagram;
679    /// use std::time::Duration;
680    ///
681    /// fn main() -> std::io::Result<()> {
682    ///     let sock = UnixDatagram::unbound()?;
683    ///     sock.set_read_timeout(Some(Duration::new(1, 0)))
684    ///         .expect("set_read_timeout function failed");
685    ///     Ok(())
686    /// }
687    /// ```
688    ///
689    /// An [`Err`] is returned if the zero [`Duration`] is passed to this
690    /// method:
691    ///
692    /// ```no_run
693    /// use std::io;
694    /// use std::os::unix::net::UnixDatagram;
695    /// use std::time::Duration;
696    ///
697    /// fn main() -> std::io::Result<()> {
698    ///     let socket = UnixDatagram::unbound()?;
699    ///     let result = socket.set_read_timeout(Some(Duration::new(0, 0)));
700    ///     let err = result.unwrap_err();
701    ///     assert_eq!(err.kind(), io::ErrorKind::InvalidInput);
702    ///     Ok(())
703    /// }
704    /// ```
705    #[stable(feature = "unix_socket", since = "1.10.0")]
706    pub fn set_read_timeout(&self, timeout: Option<Duration>) -> io::Result<()> {
707        self.0.set_timeout(timeout, libc::SO_RCVTIMEO)
708    }
709
710    /// Sets the write timeout for the socket.
711    ///
712    /// If the provided value is [`None`], then [`send`] and [`send_to`] calls will
713    /// block indefinitely. An [`Err`] is returned if the zero [`Duration`] is passed to this
714    /// method.
715    ///
716    /// [`send`]: UnixDatagram::send
717    /// [`send_to`]: UnixDatagram::send_to
718    ///
719    /// # Examples
720    ///
721    /// ```
722    /// use std::os::unix::net::UnixDatagram;
723    /// use std::time::Duration;
724    ///
725    /// fn main() -> std::io::Result<()> {
726    ///     let sock = UnixDatagram::unbound()?;
727    ///     sock.set_write_timeout(Some(Duration::new(1, 0)))
728    ///         .expect("set_write_timeout function failed");
729    ///     Ok(())
730    /// }
731    /// ```
732    ///
733    /// An [`Err`] is returned if the zero [`Duration`] is passed to this
734    /// method:
735    ///
736    /// ```no_run
737    /// use std::io;
738    /// use std::os::unix::net::UnixDatagram;
739    /// use std::time::Duration;
740    ///
741    /// fn main() -> std::io::Result<()> {
742    ///     let socket = UnixDatagram::unbound()?;
743    ///     let result = socket.set_write_timeout(Some(Duration::new(0, 0)));
744    ///     let err = result.unwrap_err();
745    ///     assert_eq!(err.kind(), io::ErrorKind::InvalidInput);
746    ///     Ok(())
747    /// }
748    /// ```
749    #[stable(feature = "unix_socket", since = "1.10.0")]
750    pub fn set_write_timeout(&self, timeout: Option<Duration>) -> io::Result<()> {
751        self.0.set_timeout(timeout, libc::SO_SNDTIMEO)
752    }
753
754    /// Returns the read timeout of this socket.
755    ///
756    /// # Examples
757    ///
758    /// ```
759    /// use std::os::unix::net::UnixDatagram;
760    /// use std::time::Duration;
761    ///
762    /// fn main() -> std::io::Result<()> {
763    ///     let sock = UnixDatagram::unbound()?;
764    ///     sock.set_read_timeout(Some(Duration::new(1, 0)))
765    ///         .expect("set_read_timeout function failed");
766    ///     assert_eq!(sock.read_timeout()?, Some(Duration::new(1, 0)));
767    ///     Ok(())
768    /// }
769    /// ```
770    #[stable(feature = "unix_socket", since = "1.10.0")]
771    pub fn read_timeout(&self) -> io::Result<Option<Duration>> {
772        self.0.timeout(libc::SO_RCVTIMEO)
773    }
774
775    /// Returns the write timeout of this socket.
776    ///
777    /// # Examples
778    ///
779    /// ```
780    /// use std::os::unix::net::UnixDatagram;
781    /// use std::time::Duration;
782    ///
783    /// fn main() -> std::io::Result<()> {
784    ///     let sock = UnixDatagram::unbound()?;
785    ///     sock.set_write_timeout(Some(Duration::new(1, 0)))
786    ///         .expect("set_write_timeout function failed");
787    ///     assert_eq!(sock.write_timeout()?, Some(Duration::new(1, 0)));
788    ///     Ok(())
789    /// }
790    /// ```
791    #[stable(feature = "unix_socket", since = "1.10.0")]
792    pub fn write_timeout(&self) -> io::Result<Option<Duration>> {
793        self.0.timeout(libc::SO_SNDTIMEO)
794    }
795
796    /// Moves the socket into or out of nonblocking mode.
797    ///
798    /// # Examples
799    ///
800    /// ```
801    /// use std::os::unix::net::UnixDatagram;
802    ///
803    /// fn main() -> std::io::Result<()> {
804    ///     let sock = UnixDatagram::unbound()?;
805    ///     sock.set_nonblocking(true).expect("set_nonblocking function failed");
806    ///     Ok(())
807    /// }
808    /// ```
809    #[stable(feature = "unix_socket", since = "1.10.0")]
810    pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> {
811        self.0.set_nonblocking(nonblocking)
812    }
813
814    /// Set the id of the socket for network filtering purpose
815    ///
816    #[cfg_attr(
817        any(target_os = "linux", target_os = "freebsd", target_os = "openbsd"),
818        doc = "```no_run"
819    )]
820    #[cfg_attr(
821        not(any(target_os = "linux", target_os = "freebsd", target_os = "openbsd")),
822        doc = "```ignore"
823    )]
824    /// #![feature(unix_set_mark)]
825    /// use std::os::unix::net::UnixDatagram;
826    ///
827    /// fn main() -> std::io::Result<()> {
828    ///     let sock = UnixDatagram::unbound()?;
829    ///     sock.set_mark(32)?;
830    ///     Ok(())
831    /// }
832    /// ```
833    #[cfg(any(doc, target_os = "linux", target_os = "freebsd", target_os = "openbsd",))]
834    #[unstable(feature = "unix_set_mark", issue = "96467")]
835    pub fn set_mark(&self, mark: u32) -> io::Result<()> {
836        self.0.set_mark(mark)
837    }
838
839    /// Returns the value of the `SO_ERROR` option.
840    ///
841    /// # Examples
842    ///
843    /// ```no_run
844    /// use std::os::unix::net::UnixDatagram;
845    ///
846    /// fn main() -> std::io::Result<()> {
847    ///     let sock = UnixDatagram::unbound()?;
848    ///     if let Ok(Some(err)) = sock.take_error() {
849    ///         println!("Got error: {err:?}");
850    ///     }
851    ///     Ok(())
852    /// }
853    /// ```
854    #[stable(feature = "unix_socket", since = "1.10.0")]
855    pub fn take_error(&self) -> io::Result<Option<io::Error>> {
856        self.0.take_error()
857    }
858
859    /// Shut down the read, write, or both halves of this connection.
860    ///
861    /// This function will cause all pending and future I/O calls on the
862    /// specified portions to immediately return with an appropriate value
863    /// (see the documentation of [`Shutdown`]).
864    ///
865    /// ```no_run
866    /// use std::os::unix::net::UnixDatagram;
867    /// use std::net::Shutdown;
868    ///
869    /// fn main() -> std::io::Result<()> {
870    ///     let sock = UnixDatagram::unbound()?;
871    ///     sock.shutdown(Shutdown::Both).expect("shutdown function failed");
872    ///     Ok(())
873    /// }
874    /// ```
875    #[stable(feature = "unix_socket", since = "1.10.0")]
876    pub fn shutdown(&self, how: Shutdown) -> io::Result<()> {
877        self.0.shutdown(how)
878    }
879
880    /// Receives data on the socket from the remote address to which it is
881    /// connected, without removing that data from the queue. On success,
882    /// returns the number of bytes peeked.
883    ///
884    /// Successive calls return the same data. This is accomplished by passing
885    /// `MSG_PEEK` as a flag to the underlying `recv` system call.
886    ///
887    /// # Examples
888    ///
889    /// ```no_run
890    /// #![feature(unix_socket_peek)]
891    ///
892    /// use std::os::unix::net::UnixDatagram;
893    ///
894    /// fn main() -> std::io::Result<()> {
895    ///     let socket = UnixDatagram::bind("/tmp/sock")?;
896    ///     let mut buf = [0; 10];
897    ///     let len = socket.peek(&mut buf).expect("peek failed");
898    ///     Ok(())
899    /// }
900    /// ```
901    #[unstable(feature = "unix_socket_peek", issue = "76923")]
902    pub fn peek(&self, buf: &mut [u8]) -> io::Result<usize> {
903        self.0.peek(buf)
904    }
905
906    /// Receives a single datagram message on the socket, without removing it from the
907    /// queue. On success, returns the number of bytes read and the origin.
908    ///
909    /// The function must be called with valid byte array `buf` of sufficient size to
910    /// hold the message bytes. If a message is too long to fit in the supplied buffer,
911    /// excess bytes may be discarded.
912    ///
913    /// Successive calls return the same data. This is accomplished by passing
914    /// `MSG_PEEK` as a flag to the underlying `recvfrom` system call.
915    ///
916    /// Do not use this function to implement busy waiting, instead use `libc::poll` to
917    /// synchronize IO events on one or more sockets.
918    ///
919    /// # Examples
920    ///
921    /// ```no_run
922    /// #![feature(unix_socket_peek)]
923    ///
924    /// use std::os::unix::net::UnixDatagram;
925    ///
926    /// fn main() -> std::io::Result<()> {
927    ///     let socket = UnixDatagram::bind("/tmp/sock")?;
928    ///     let mut buf = [0; 10];
929    ///     let (len, addr) = socket.peek_from(&mut buf).expect("peek failed");
930    ///     Ok(())
931    /// }
932    /// ```
933    #[unstable(feature = "unix_socket_peek", issue = "76923")]
934    pub fn peek_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> {
935        self.recv_from_flags(buf, libc::MSG_PEEK)
936    }
937}
938
939#[stable(feature = "unix_socket", since = "1.10.0")]
940impl AsRawFd for UnixDatagram {
941    #[inline]
942    fn as_raw_fd(&self) -> RawFd {
943        self.0.as_inner().as_raw_fd()
944    }
945}
946
947#[stable(feature = "unix_socket", since = "1.10.0")]
948impl FromRawFd for UnixDatagram {
949    #[inline]
950    unsafe fn from_raw_fd(fd: RawFd) -> UnixDatagram {
951        UnixDatagram(Socket::from_inner(FromInner::from_inner(OwnedFd::from_raw_fd(fd))))
952    }
953}
954
955#[stable(feature = "unix_socket", since = "1.10.0")]
956impl IntoRawFd for UnixDatagram {
957    #[inline]
958    fn into_raw_fd(self) -> RawFd {
959        self.0.into_inner().into_inner().into_raw_fd()
960    }
961}
962
963#[stable(feature = "io_safety", since = "1.63.0")]
964impl AsFd for UnixDatagram {
965    #[inline]
966    fn as_fd(&self) -> BorrowedFd<'_> {
967        self.0.as_inner().as_fd()
968    }
969}
970
971#[stable(feature = "io_safety", since = "1.63.0")]
972impl From<UnixDatagram> for OwnedFd {
973    /// Takes ownership of a [`UnixDatagram`]'s socket file descriptor.
974    #[inline]
975    fn from(unix_datagram: UnixDatagram) -> OwnedFd {
976        unsafe { OwnedFd::from_raw_fd(unix_datagram.into_raw_fd()) }
977    }
978}
979
980#[stable(feature = "io_safety", since = "1.63.0")]
981impl From<OwnedFd> for UnixDatagram {
982    #[inline]
983    fn from(owned: OwnedFd) -> Self {
984        unsafe { Self::from_raw_fd(owned.into_raw_fd()) }
985    }
986}
987
988impl AsInner<Socket> for UnixDatagram {
989    #[inline]
990    fn as_inner(&self) -> &Socket {
991        &self.0
992    }
993}