Trait interprocess::os::unix::udsocket::ToUdSocketPath

pub trait ToUdSocketPath<'a> {
    fn to_socket_path(self) -> Result<UdSocketPath<'a>>;
}

Trait for types which can be converted to a path to a Unix domain socket.

The difference between this trait and TryInto<UdSocketPath> 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

On Linux (since it's the only platform which supports namespaced socket paths), an extra syntax feature is implemented for string types which don't have file path semantics, i.e. all standard string types except for Path and PathBuf. If the first character in a string is @, the path is interpreted as a namespaced socket path rather than a normal file path. Read the UdSocketPath documentation for more on what that means. There are several ways to opt out of that behavior if you're referring to a socket at a relative path which starts from a @:

• Use AsRef to convert the string slice type into a Path which has file path semantics and therefore does not have the @ syntax enabled, if your string type is str or OsStr
• Prefix the path with ./, which carries the same meaning from the perspective of the OS but bypasses the @ check
• If your string type is CStr or CString, explicitly construct UdSocketPath's File variant with a Cow wrapping your string value

Example

The following example uses the UdStreamListener::bind method, but UdStream::connect and UdSocket::bind/UdSocket::connect accept the same argument types too.

use interprocess::os::unix::udsocket::{UdStreamListener, UdSocketPath};
use std::{ffi::{CStr, CString}, path::{Path, PathBuf}, borrow::Cow};

// 1. Use a string literal
let listener = UdStreamListener::bind("/tmp/example1.sock")?;
// If we're on Linux, we can also use the abstract socket namespace which exists separately from
// the filesystem thanks to the special @ sign syntax which works with all string types
#[cfg(target_os = "linux")]
let listener_namespaced = UdStreamListener::bind("@namespaced_socket_1")?;

// 2. Use an owned string
let listener = UdStreamListener::bind("/tmp/example2.sock".to_string())?;
// Same story with the namespaced socket here
#[cfg(target_os = "linux")]
let listener_namespaced = UdStreamListener::bind("@namespaced_socket_2")?;

// 3. Use a path slice or an owned path
let listener_by_path = UdStreamListener::bind(Path::new("/tmp/exmaple3a.sock"))?;
let listener_by_pathbuf = UdStreamListener::bind(PathBuf::from("/tmp/example3b.sock"))?;
// The @ syntax doesn't work with Path and PathBuf, since those are explicitly paths at the type
// level, rather than strings with contextual meaning. Using AsRef to convert an &str slice or
// an &OsStr slice into a &Path slice is the recommended way to disable the @ syntax.

// 4. Use manual creation
let cstring = CString::new("/tmp/example4a.sock".to_string().into_bytes())?;
let path_to_socket = UdSocketPath::File(Cow::Owned(cstring));
let listener = UdStreamListener::bind(path_to_socket);

let cstr = CStr::from_bytes_with_nul("/tmp/example4b.sock\0".as_bytes())?;
let path_to_socket = UdSocketPath::File(Cow::Borrowed(cstr));
let listener = UdStreamListener::bind(path_to_socket);

Required methods

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

Performs the conversion from self to a Unix domain socket path.

Loading content...

Implementations on Foreign Types

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

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

Converts a borrowed CStr to a borrowed UdSocketPath with the same lifetime. On platforms which don't support namespaced socket paths, the variant is always File; on Linux, which supports namespaced sockets, an extra check for the @ character is performed. See the trait-level documentation for more.

impl ToUdSocketPath<'static> for CString

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

Converts an owned CString to a borrowed UdSocketPath with the same lifetime. On platforms which don't support namespaced socket paths, the variant is always File; on Linux, which supports namespaced sockets, an extra check for the @ character is performed. See the trait-level documentation for more.

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

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

Converts a borrowed OsStr to a borrowed UdSocketPath with the same lifetime. On platforms which don't support namespaced socket paths, the variant is always File; on Linux, which supports namespaced sockets, an extra check for the @ character is performed. See the trait-level documentation for more.

If the provided string is not nul-terminated, a nul terminator is automatically added by copying the string into owned storage and adding a nul byte on its end.

impl ToUdSocketPath<'static> for OsString

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

Converts a borrowed OsString to an owned UdSocketPath. On platforms which don't support namespaced socket paths, the variant is always File; on Linux, which supports namespaced sockets, an extra check for the @ character is performed. See the trait-level documentation for more.

If the provided string is not nul-terminated, a nul terminator is automatically added by copying the string into owned storage and adding a nul byte on its end.

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

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

Converts a borrowed Path to a borrowed UdSocketPath::File with the same lifetime.

If the provided string is not nul-terminated, a nul terminator is automatically added by copying the string into owned storage and adding a nul byte on its end.

impl ToUdSocketPath<'static> for PathBuf

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

Converts an owned PathBuf to an owned UdSocketPath::File.

If the provided string is not nul-terminated, a nul terminator is automatically added by copying the string into owned storage and adding a nul byte on its end.

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

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

Converts a borrowed str to a borrowed UdSocketPath with the same lifetime. On platforms which don't support namespaced socket paths, the variant is always File; on Linux, which supports namespaced sockets, an extra check for the @ character is performed. See the trait-level documentation for more.

If the provided string is not nul-terminated, a nul terminator is automatically added by copying the string into owned storage and adding a nul byte on its end. This is done to support normal string literals, since adding \0 at the end of every single socket name string is tedious and unappealing.

impl ToUdSocketPath<'static> for String

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

Converts an owned String to an owned UdSocketPath. On platforms which don't support namespaced socket paths, the variant is always File; on Linux, which supports namespaced sockets, an extra check for the @ character is performed. See the trait-level documentation for more.

If the provided string is not nul-terminated, a nul terminator is automatically added by copying the string into owned storage and adding a nul byte on its end.

Loading content...

Implementors

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

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

Accepts explicit UdSocketPaths in the bind constructor.

Loading content...