Enum interprocess::os::unix::udsocket::UdSocketPath

pub enum UdSocketPath<'a> {
    Unnamed,
    File(Cow<'a, CStr>),
    Namespaced(Cow<'a, CStr>),
}

Represents a name for a Unix domain socket.

The main purpose for this enumeration is to conditionally support the dedicated socket namespace on systems which implement it — for that, the Namespaced variant is used. Depending on your system, you might not be seeing it, which is when you'd need the File fallback variant, which works on all POSIX-compliant systems.

Namespaced

This variant refers to sockets in a dedicated socket namespace, which is fully isolated from the main filesystem and closes sockets automatically when the server which opened the socket shuts down. This variant is only implemented on Linux, which is why it is not available on other POSIX-conformant systems at compile time, resulting in a compile-time error if usage is attempted.

File

All sockets identified this way are located on the main filesystem and exist as persistent files until deletion, preventing servers from using the same socket without deleting it from the filesystem first. This variant is available on all POSIX-compilant systems.

Variants

Unnamed

An unnamed socket, identified only by its file descriptor. This is an invalid path value for creating sockets — all attempts to use such a value will result in an error.

File(Cow<'a, CStr>)

Identifies a socket which is located in the filesystem tree, existing as a file. See the enum-level documentation for more.

Namespaced(Cow<'a, CStr>)

Identifies a socket in the dedicated socket namespace, where it exists until the server closes it rather than persisting as a file. See the enum-level documentation for more.

Implementations

impl<'a> UdSocketPath<'a>

pub fn as_cstr(&'a self) -> &'a CStr

Returns the path as a CStr. The resulting value does not include any indication of whether it's a namespaced socket name or a filesystem path.

pub fn into_cstring(self) -> CString

Returns the path as a CString. The resulting value does not include any indication of whether it's a namespaced socket name or a filesystem path.

pub fn make_owned(&mut self) -> bool

Ensures that the path is stored as an owned CString in place, and returns whether that required cloning or not. If self was not referring to any socket (Unnamed variant), the value is set to an empty CString (only nul terminator) of type File.

pub fn get_cstring_mut(&mut self) -> &mut CString

Returns a mutable reference to the underlying CString, cloning the borrowed path if it wasn't owned before.

pub fn try_get_cstring_mut(&mut self) -> Option<&mut CString>

Returns a mutable reference to the underlying CString if it's available as owned, otherwise returns None.

pub fn is_owned(&self) -> bool

Returns true if the path to the socket is stored as an owned CString, i.e. if into_cstring doesn't require cloning the path; false otherwise.

impl UdSocketPath<'static>

pub fn buffer() -> Self

Creates a buffer suitable for usage with recv_from (_ancillary/_vectored/_ancillary_vectored). The capacity is equal to the MAX_UDSOCKET_PATH_LEN constant (the nul terminator in the CString is included). The contained value is unspecified — results of reading from the buffer should not be relied upon.

Example

use interprocess::os::unix::udsocket::{UdSocketPath, MAX_UDSOCKET_PATH_LEN};
use std::borrow::Cow;

let path_buffer = UdSocketPath::buffer();
match path_buffer {
    UdSocketPath::File(cow) => match cow {
        Cow::Owned(cstring)
    => assert_eq!(cstring.into_bytes_with_nul().capacity(), MAX_UDSOCKET_PATH_LEN),
        Cow::Borrowed(..) => unreachable!(),
    }
    #[cfg(target_os = "linux")]
    UdSocketPath::Namespaced(..) => unreachable!(),
    UdSocketPath::Unnamed => unreachable!(),
}

pub fn file_from_vec(vec: Vec<u8>) -> Result<Self, NulError>

Constructs a UdSocketPath::File value from a Vec of bytes, wrapping CString::new.

pub fn namespaced_from_vec(vec: Vec<u8>) -> Result<Self, NulError>

Constructs a UdSocketPath::Namespaced value from a Vec of bytes, wrapping CString::new.

Trait Implementations

impl<'a> Clone for UdSocketPath<'a>

fn clone(&self) -> UdSocketPath<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for UdSocketPath<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Eq for UdSocketPath<'a>

impl<'a> PartialEq<UdSocketPath<'a>> for UdSocketPath<'a>

fn eq(&self, other: &UdSocketPath<'a>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &UdSocketPath<'a>) -> bool

This method tests for !=.

impl<'a> StructuralEq for UdSocketPath<'a>

impl<'a> StructuralPartialEq for UdSocketPath<'a>

impl<'a> ToUdSocketPath<'a> for UdSocketPath<'a>

fn to_socket_path(self) -> Result<UdSocketPath<'a>>

Accepts explicit UdSocketPaths in the bind constructor.