Trait interprocess::local_socket::ToLocalSocketName

source · 
pub trait ToLocalSocketName<'a> {
    fn to_local_socket_name(self) -> Result<LocalSocketName<'a>>;
}
Expand description

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:

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

Performs the conversion to a local socket name.

Implementations on Foreign Types

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

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

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.

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.

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.

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.

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.

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.

Implementors