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}