Enum UdSocketPath

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

Available on Unix only.

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>)

Available on Linux or Android only.

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 as_osstr(&'a self) -> &'a OsStr

Returns the path as an OsStr. 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 into_osstring(self) -> OsString

Returns the path as an OsString. 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 to_owned(&self) -> UdSocketPath<'static>

Converts to a UdSocketPath<'static> which stores the path as an owned CString, cloning if necessary.

pub fn borrow(&self) -> UdSocketPath<'_>

Borrows into another UdSocketPath<'_> instance. If borrowed here, reborrows; if owned here, returns a fresh borrow.

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 const 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!(),
    }
    _ => 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>

Available on Linux or Android only.

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

Trait Implementations

impl AsRef<CStr> for UdSocketPath<'_>

fn as_ref(&self) -> &CStr

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<OsStr> for UdSocketPath<'_>

fn as_ref(&self) -> &OsStr

Converts this type into a shared reference of the (usually inferred) input type.

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

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

Returns a duplicate of the value.

const 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 From<UdSocketPath<'_>> for CString

fn from(path: UdSocketPath<'_>) -> Self

Converts to this type from the input type.

impl From<UdSocketPath<'_>> for OsString

fn from(path: UdSocketPath<'_>) -> Self

Converts to this type from the input type.

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

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

Tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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

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

Reborrows an explicit UdSocketPath for a smaller lifetime.

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

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

Accepts explicit UdSocketPaths in relevant constructors.

impl TryFrom<UdSocketPath<'_>> for sockaddr_un

type Error = Error

The type returned in the event of a conversion error.

fn try_from(path: UdSocketPath<'_>) -> Result<Self>

Performs the conversion.

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

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