Trait ToLocalSocketName

pub trait ToLocalSocketName<'a> {
    // Required method
    fn to_local_socket_name(self) -> Result<LocalSocketName<'a>>;
}

Types which can be converted to a local socket name.

The difference between this trait and TryInto<LocalSocketName> is that the latter does not constrain the error type to be io::Error and thus is not compatible with many types from the standard library which are widely expected to be convertible to Unix domain socket paths. Additionally, this makes the special syntax for namespaced sockets possible (see below).

@ syntax for namespaced paths

As mentioned in the LocalSocketName documentation, there are two types of which local socket names can be: filesystem paths and namespaced names. Those are isolated from each other – there’s no portable way to represent one using another, though certain OSes might provide ways to do so – Windows does, for example. To be able to represent both in a platform-independent fashion, a special syntax was implemented in implementations of this trait on types from the standard library: “@ syntax”.

The feature, in its core, is extremely simple: if the first character in a string is the @ character, the value of the string is interpreted and stored as a namespaced name (otherwise, it’s treated as a filesystem path); the @ character is then removed from the string (by taking a subslice which dosen’t include it if a string slice is being used; for owned strings, it’s simply removed from the string by shifting the entire string towards the beginning). Path and PathBuf are not affected at all – those have explicit path semantics and therefore cannot logically represent namespaced names.

This feature is extremely useful both when using hardcoded literals and accepting user input for the path, but sometimes you might want to prevent this behavior. In such a case, you have the following possible approaches:

• If the string is a OsStr/OsString, it can be cheaply converted to a Path/PathBuf, which do not support the @ syntax
• If the string is a str/String, it can be cheaply converted to OsStr/OsString; then the above method can be applied
• If the string is a CStr/CString, it can be converted to str/String using the following code:

fn cstr_to_str(val: &CStr) -> Result<&str, Utf8Error> {
    std::str::from_utf8(val.to_bytes_with_nul())
}
fn cstring_to_string(val: CString) -> String {
    String::from_utf8_lossy(&val.into_bytes_with_nul()).into()
}

Then, the method for str/String can be applied.

None of the above conversions perform memory allocations – the only expensive one is CStr/CString which performs a check for valid UTF-8.

Required Methods

fn to_local_socket_name(self) -> Result<LocalSocketName<'a>>

Performs the conversion to a local socket name.

Implementations on Foreign Types

impl ToLocalSocketName<'static> for CString

Converts an owned CString to an owned LocalSocketName. UTF-8 is assumed and the nul terminator is preserved during conversion. On platforms which don’t support namespaced socket names, the result is always a file-type name; on platforms that do, prefixing the name with the @ character will trim it away and yield a namespaced name instead. See the trait-level documentation for more.

fn to_local_socket_name(self) -> Result<LocalSocketName<'static>>

impl ToLocalSocketName<'static> for String

Converts an owned String to an owned LocalSocketName. On platforms which don’t support namespaced socket names, the result is always a file-type name; on platforms that do, prefixing the name with the @ character will trim it away and yield a namespaced name instead. See the trait-level documentation for more.

fn to_local_socket_name(self) -> Result<LocalSocketName<'static>>

impl ToLocalSocketName<'static> for OsString

Converts an owned OsString to an owned LocalSocketName. On platforms which don’t support namespaced socket names, the result is always a file-type name; on platforms that do, prefixing the name with the @ character will trim it away and yield a namespaced name instead. See the trait-level documentation for more.

fn to_local_socket_name(self) -> Result<LocalSocketName<'static>>

impl ToLocalSocketName<'static> for PathBuf

Converts an owned PathBuf to an owned file-type LocalSocketName.

fn to_local_socket_name(self) -> Result<LocalSocketName<'static>>

impl<'a> ToLocalSocketName<'a> for &'a str

Converts a borrowed str to a borrowed LocalSocketName with the same lifetime. On platforms which don’t support namespaced socket names, the result is always a file-type name; on platforms that do, prefixing the name with the @ character will trim it away and yield a namespaced name instead. See the trait-level documentation for more.

fn to_local_socket_name(self) -> Result<LocalSocketName<'a>>

impl<'a> ToLocalSocketName<'a> for &'a CStr

Converts a borrowed CStr to a borrowed LocalSocketName with the same lifetime. UTF-8 is assumed and the nul terminator is preserved during conversion. On platforms which don’t support namespaced socket names, the result is always a file-type name; on platforms that do, prefixing the name with the @ character will trim it away and yield a namespaced name instead. See the trait-level documentation for more.

fn to_local_socket_name(self) -> Result<LocalSocketName<'a>>

impl<'a> ToLocalSocketName<'a> for &'a OsStr

Converts a borrowed OsStr to a borrowed LocalSocketName with the same lifetime. On platforms which don’t support namespaced socket names, the result is always a file-type name; on platforms that do, prefixing the name with the @ character will trim it away and yield a namespaced name instead. See the trait-level documentation for more.

fn to_local_socket_name(self) -> Result<LocalSocketName<'a>>

impl<'a> ToLocalSocketName<'a> for &'a Path

Converts a borrowed Path to a borrowed file-type LocalSocketName with the same lifetime.

fn to_local_socket_name(self) -> Result<LocalSocketName<'a>>

Implementors