Struct UnixAddr 

pub struct UnixAddr<'a> { /* private fields */ }

A UNIX domain socket (UDS) address.

Three types of address are distinguished:

1. pathname: a non-empty bytes slice without any interior null bytes.
2. unnamed: an empty bytes slice.
3. abstract: a bytes slice that starts with b'\0'.

The maximum length of the address bytes is SUN_LEN, which is 108 on most Unix-like platforms.

Notes

It should be noted that the abstract namespace is a Linux-specific extension. While creating an abstract address on other platforms is allowed, converting an UnixAddr to the standard library type SocketAddr is a hard error (compilation error).

Additionally, any bytes slice that starts with b'\0' is a valid abstract address, which means that an abstract address with interior null bytes or even an empty abstract address is a “legal” abstract address. Such address may lead to some unexpected behaviors and is rejected here by default. You can use the from_abstract_name method with LOOSE_MODE set to true to manually construct such abstract addresses if you really need them.

Currently, the lifetime parameter 'a is not actually used and the inner bytes type is Arc<[u8]>. We will change the inner bytes type to a more flexible one in the future, which accepts any borrowed, inlined or owned atomic-ref-counted bytes.

Implementations

impl<'a> UnixAddr<'a>

pub fn from_str(string: &'a str) -> Result<UnixAddr<'a>, ParseError>

Parses (deserializes) the given string to a UnixAddr.

This method accepts the following two serialization formats:

1. unix:{unix-socket-address};
2. unix://{unix-socket-address}.

One {unix-socket-address} may be a file system path (for pathname addresses), or a string starting with @ or \0 (for abstract addresses), or an empty string (for unnamed addresses).

Examples

use uaddr::unix::UnixAddr;

let addr = UnixAddr::from_str("unix:/path/to/your/file.socket").unwrap();
assert!(addr.is_pathname());
assert_eq!(addr.as_pathname(), Some(&b"/path/to/your/file.socket"[..]));

let addr = UnixAddr::from_str("unix:@abstract-socket").unwrap();
assert!(addr.is_abstract_name());
assert_eq!(addr.as_abstract_name(), Some(&b"abstract-socket"[..]));

let addr = UnixAddr::from_str("unix:\0abstract-socket").unwrap();
assert!(addr.is_abstract_name());
assert_eq!(addr.as_abstract_name(), Some(&b"abstract-socket"[..]));

// By default, we don't accept abstract socket names with interior null bytes.
let _ = UnixAddr::from_str("unix:@abstract-socket\0").unwrap_err();

let addr = UnixAddr::from_str("unix:").unwrap();
assert!(addr.is_unnamed());

pub fn from_bytes(bytes: &'a [u8]) -> Result<UnixAddr<'a>, ParseError>

Creates a new UnixAddr directly from the given bytes slice.

Notes

@ is a valid character for pathname, we just use it to replace b'\0' during serialization. Unlike from_str, @ is not treated as the indicator of an abstract UDS address here.

Examples

use uaddr::unix::UnixAddr;

let addr = UnixAddr::from_bytes(b"/path/to/your/file.socket").unwrap();
assert!(addr.is_pathname());
assert_eq!(addr.as_pathname(), Some(&b"/path/to/your/file.socket"[..]));

let addr = UnixAddr::from_bytes(b"@abstract-socket").unwrap();
assert!(addr.is_pathname());
assert_eq!(addr.as_pathname(), Some(&b"@abstract-socket"[..]));

let addr = UnixAddr::from_bytes(b"\0abstract-socket").unwrap();
assert!(addr.is_abstract_name());
assert_eq!(addr.as_abstract_name(), Some(&b"abstract-socket"[..]));

// By default, we don't accept abstract socket names with interior null bytes.
let _ = UnixAddr::from_bytes(b"@abstract-socket\0").unwrap_err();
let _ = UnixAddr::from_bytes(b"\0abstract-socket\0").unwrap_err();

let addr = UnixAddr::from_bytes(b"").unwrap();
assert!(addr.is_unnamed());

pub fn from_pathname(path: &'a [u8]) -> Result<UnixAddr<'a>, ParseError>

Creates a new UnixAddr from the given pathname.

Notes

@ is a valid character for pathname, we just use it to replace b'\0' during serialization. Unlike from_str, @ is not treated as the indicator of an abstract UDS address here.

Examples

use uaddr::unix::UnixAddr;

let addr = UnixAddr::from_pathname(b"/path/to/your/file.socket").unwrap();
assert!(addr.is_pathname());
assert_eq!(addr.as_pathname(), Some(&b"/path/to/your/file.socket"[..]));

// Note: this is a special case.
let addr = UnixAddr::from_pathname(b"@abstract-socket").unwrap();
assert!(addr.is_pathname());
assert_eq!(addr.as_pathname(), Some(&b"@abstract-socket"[..]));

let _ = UnixAddr::from_pathname(b"\0abstract-socket").unwrap_err();
let _ = UnixAddr::from_pathname(b"").unwrap_err();

pub fn from_pathname_until_nul( path: &'a [u8], ) -> Result<UnixAddr<'a>, ParseError>

from_pathname, but terminates the bytes at the first null byte.

Examples

use uaddr::unix::UnixAddr;

let addr = UnixAddr::from_pathname_until_nul(b"/path/to/your/file.socket").unwrap();
assert!(addr.is_pathname());
assert_eq!(addr.as_pathname(), Some(&b"/path/to/your/file.socket"[..]));

let addr = UnixAddr::from_pathname_until_nul(b"/path/to/your/file.sock\0et\0").unwrap();
assert!(addr.is_pathname());
assert_eq!(addr.as_pathname(), Some(&b"/path/to/your/file.sock"[..]));

let addr = UnixAddr::from_pathname_until_nul(b"@abstract-socket").unwrap();
assert!(addr.is_pathname());
assert_eq!(addr.as_pathname(), Some(&b"@abstract-socket"[..]));

let _ = UnixAddr::from_pathname_until_nul(b"").unwrap_err();
let _ = UnixAddr::from_pathname_until_nul(b"\0").unwrap_err();

pub fn is_pathname(&self) -> bool

Checks if the address is a pathname one.

pub fn as_pathname(&self) -> Option<&[u8]>

Returns the pathname bytes if this is a pathname address, or None otherwise.

pub fn from_abstract_name<const LOOSE_MODE: bool>( name: &'a [u8], ) -> Result<UnixAddr<'a>, ParseError>

Creates a new abstract UnixAddr.

Notes

Don’t include the leading b'\0' in the name, as it will be automatically added by this method.

As mentioned in the documentation of this type, any bytes slice that starts with b'\0' is a valid abstract address, including those with interior null bytes or even an empty one. Such addresses may lead to some unexpected behaviors and are rejected by default. You can set LOOSE_MODE to true to manually construct such abstract addresses if you really need them.

Examples

use uaddr::unix::UnixAddr;

let addr = UnixAddr::from_abstract_name::<false>(b"abstract-socket").unwrap();
assert!(addr.is_abstract_name());
assert_eq!(addr.as_abstract_name(), Some(&b"abstract-socket"[..]));

let _ = UnixAddr::from_abstract_name::<false>(b"").unwrap_err();
let addr = UnixAddr::from_abstract_name::<true>(b"").unwrap();
assert!(addr.is_abstract_name());
assert_eq!(addr.as_abstract_name(), Some(&b""[..]));

let _ = UnixAddr::from_abstract_name::<false>(b"abstract\0socket").unwrap_err();
let addr = UnixAddr::from_abstract_name::<true>(b"abstract\0socket").unwrap();
assert!(addr.is_abstract_name());
assert_eq!(addr.as_abstract_name(), Some(&b"abstract\0socket"[..]));

pub fn from_abstract_name_until_nul<const LOOSE_MODE: bool>( name: &'a [u8], ) -> Result<UnixAddr<'a>, ParseError>

from_abstract_name, but terminates the name at the first null byte.

use uaddr::unix::UnixAddr;

let addr = UnixAddr::from_abstract_name_until_nul::<false>(b"abstract-socket").unwrap();
assert!(addr.is_abstract_name());
assert_eq!(addr.as_abstract_name(), Some(&b"abstract-socket"[..]));

let addr = UnixAddr::from_abstract_name_until_nul::<false>(b"abstract\0socket").unwrap();
assert!(addr.is_abstract_name());
assert_eq!(addr.as_abstract_name(), Some(&b"abstract"[..]));

let _ = UnixAddr::from_abstract_name_until_nul::<false>(b"").unwrap_err();
let addr = UnixAddr::from_abstract_name_until_nul::<true>(b"").unwrap();
assert!(addr.is_abstract_name());
assert_eq!(addr.as_abstract_name(), Some(&b""[..]));

pub fn is_abstract_name(&self) -> bool

Checks if the UDS address is an abstract one.

pub fn as_abstract_name(&self) -> Option<&[u8]>

Returns the abstract name bytes if this is an abstract UDS address, or None otherwise.

The returned bytes slice does not include the leading b'\0'.

pub fn new_unnamed() -> UnixAddr<'a>

Creates an new unnamed UnixAddr.

pub fn is_unnamed(&self) -> bool

Checks if the UDS address is an unnamed one.

pub fn to_owned(self) -> UnixAddr<'static>

Converts this UnixAddr into an owned version.

This is a no-op for now since the inner bytes type is already owned, but it will be useful in the future when we change the inner bytes type to a more flexible one and accept borrowed bytes.

Trait Implementations

impl<'a> AsRef<[u8]> for UnixAddr<'a>

fn as_ref(&self) -> &[u8]

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

impl<'a> Clone for UnixAddr<'a>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for UnixAddr<'_>

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for UnixAddr<'de>

fn deserialize<D>( deserializer: D, ) -> Result<UnixAddr<'de>, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for UnixAddr<'_>

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

Formats the value using the given formatter.

impl<'a> From<&UnixAddr<'a>> for UniAddr<'a>

fn from(addr: &UnixAddr<'a>) -> UniAddr<'a>

Converts to this type from the input type.

impl<'a> From<UnixAddr<'a>> for UniAddr<'a>

fn from(addr: UnixAddr<'a>) -> UniAddr<'a>

Converts to this type from the input type.

impl FromStr for UnixAddr<'static>

fn from_str( s: &str, ) -> Result<UnixAddr<'static>, <UnixAddr<'static> as FromStr>::Err>

See UnixAddr::from_str.

type Err = ParseError

The associated error which can be returned from parsing.

impl<'a> Hash for UnixAddr<'a>

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> PartialEq for UnixAddr<'a>

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

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

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 Serialize for UnixAddr<'_>

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<'a> TryFrom<&'a SocketAddr> for UnixAddr<'a>

type Error = ParseError

The type returned in the event of a conversion error.

fn try_from( value: &'a SocketAddr, ) -> Result<UnixAddr<'a>, <UnixAddr<'a> as TryFrom<&'a SocketAddr>>::Error>

Performs the conversion.

impl TryFrom<SocketAddr> for UnixAddr<'static>

type Error = ParseError

The type returned in the event of a conversion error.

fn try_from( value: SocketAddr, ) -> Result<UnixAddr<'static>, <UnixAddr<'static> as TryFrom<SocketAddr>>::Error>

Performs the conversion.

impl<'a> Eq for UnixAddr<'a>

impl<'a> StructuralPartialEq for UnixAddr<'a>