interprocess_docfix/os/unix/udsocket/
mod.rs

1//! Support for Unix domain sockets, abbreviated here as "Ud-sockets".
2//!
3//! Ud-sockets are a special kind of sockets which work in the scope of only one system and use file paths instead of IPv4/IPv6 addresses and 16-bit socket numbers. Aside from their high reliability and convenience for the purposes of IPC (such as filesystem-level privelege management and the similarity to named pipes), they have a unique feature which cannot be replaced by any other form of IPC: **ancillary data**.
4//!
5//! # Ancillary data
6//! Thanks to this feature, Ud-sockets can transfer ownership of a file descriptor to another process, even if it doesn't have a parent-child relationship with the file descriptor owner and thus does not inherit anything via `fork()`. Aside from that, ancillary data can contain credentials of a process, which are validated by the kernel unless the sender is the superuser, meaning that this way of retrieving credentials can be used for authentification.
7//!
8//! # Usage
9//! The [`UdStreamListener`] and [`UdSocket`] types are two starting points, depending on whether you intend to use UDP-like datagrams or TCP-like byte streams.
10//!
11//! [`UdStreamListener`]: struct.UdStreamListener.html " "
12//! [`UdSocket`]: struct.UdSocket.html " "
13
14#[cfg(any(doc, feature = "tokio_support"))]
15#[cfg_attr(feature = "doc_cfg", doc(cfg(feature = "tokio_support")))]
16pub mod tokio;
17
18mod ancillary;
19mod listener;
20mod path;
21mod socket;
22mod stream;
23mod util;
24pub use {ancillary::*, listener::*, path::*, socket::*, stream::*};
25
26mod path_drop_guard;
27use path_drop_guard::*;
28
29#[cfg(uds_supported)]
30mod c_wrappers;
31
32use super::imports;
33use cfg_if::cfg_if;
34
35cfg_if! {
36    if #[cfg(not(unix))] {
37        const _MAX_UDSOCKET_PATH_LEN: usize = 0;
38    } else if #[cfg(uds_sockaddr_un_len_108)] {
39        const _MAX_UDSOCKET_PATH_LEN: usize = 108;
40    } else if #[cfg(uds_sockaddr_un_len_104)] {
41        const _MAX_UDSOCKET_PATH_LEN: usize = 104;
42    } else if #[cfg(uds_sockaddr_un_len_126)] {
43        const _MAX_UDSOCKET_PATH_LEN: usize = 126;
44    } else {
45        compile_error!("\
46Please fill out MAX_UDSOCKET_PATH_LEN in interprocess/src/os/unix/udsocket/mod.rs for your \
47platform if you wish to enable Unix domain socket support for it"
48        );
49    }
50}
51
52/// The maximum path length for Unix domain sockets. [`UdStreamListener::bind`] panics if the specified path exceeds this value.
53///
54/// When using the [socket namespace], this value is reduced by 1, since enabling the usage of that namespace takes up one character.
55///
56/// ## Value
57/// The following platforms define the value of this constant as **108**:
58/// - Linux
59///     - includes Android
60/// - Emscripten
61/// - Redox
62/// - HermitCore
63/// - Solaris
64///     - Illumos
65///
66/// The following platforms define the value of this constant as **104**:
67/// - FreeBSD
68/// - OpenBSD
69/// - NetBSD
70/// - DragonflyBSD
71/// - macOS
72/// - iOS
73///
74/// The following platforms define the value of this constant as **126**:
75/// - Haiku
76///
77/// [`UdStreamListener::bind`]: struct.UdStreamListener.html#method.bind " "
78/// [socket namespace]: enum.UdSocketPath.html#namespaced " "
79// The reason why this constant wraps the underscored one instead of being defined directly is
80// because that'd require documenting both branches separately. This way, the user-faced
81// constant has only one definition and one documentation comment block.
82pub const MAX_UDSOCKET_PATH_LEN: usize = _MAX_UDSOCKET_PATH_LEN;
interprocess_docfix/os/unix/udsocket/mod.rs

interprocess_docfix/os/unix/udsocket/
mod.rs
