Struct uds::UnixSocketAddr

pub struct UnixSocketAddr { /* fields omitted */ }

A unix domain socket address.

Differences from std's unix::net::SocketAddr

This type fully supports abstract socket addresses, and can be created by user code and not returned by accept() and similar.

Examples

Creating an abstract address:

use uds::UnixSocketAddr;

let addr = UnixSocketAddr::new("@abstract").expect("too long");
assert!(addr.is_abstract());
assert_eq!(addr.to_string(), "@abstract");

Methods

impl UnixSocketAddr

pub fn new<A: AsRef<[u8]> + ?Sized>(addr: &A) -> Result<Self, Error>

Allows creating abstract, path or unspecified address based on an user-supplied string.

A leading '@' or '\0' signifies an abstract address, an empty slice is takes as the unnamed address, and anything else is a path address.
If a relative path address starts with '@', escape it by prepending "./".

Errors

• A path or abstract address is too long.
• A path address contains '\0'.

Examples

Abstract address:

assert!(UnixSocketAddr::new("@abstract").unwrap().is_abstract());
assert!(UnixSocketAddr::new("\0abstract").unwrap().is_abstract());

Escaped path address:

assert!(UnixSocketAddr::new("./@path").unwrap().is_relative_path());

Unnamed address:

assert!(UnixSocketAddr::new("").unwrap().is_unnamed());

pub fn unspecified() -> Self

Creates an unnamed address, which on Linux can be used for auto-bind.

Binding a socket to the unnamed address is different from not binding at all:

On Linux that binds the socket to an abstract address determined by the OS.

Examples

let addr = UnixSocketAddr::unspecified();
assert!(addr.is_unnamed());
let socket = UnixDatagram::unbound().unwrap();
socket.bind_to_unix_addr(&addr).unwrap();
assert!(socket.local_unix_addr().unwrap().is_abstract());

pub fn max_path_len() -> usize

The maximum size of pathname addesses supported by UnixSocketAddr.

Returns the size of the underlying sun_path field, minus 1 if the OS is known to require a trailing NUL ('\0') byte.

pub fn from_path<P: AsRef<Path> + ?Sized>(path: &P) -> Result<Self, Error>

Create a pathname unix socket address.

Errors

This function will return an error if the path is too long for the underlying sockaddr_un type, or contains NUL ('\0') bytes.

pub fn max_abstract_len() -> usize

The maximum size of abstract addesses supported by UnixSocketAddr.

Returns the size of the underlying sun_path field minus 1 for the leading '\0' byte.

pub const fn can_use_abstract_addresses() -> bool

Whether the operating system is known to support abstract socket addresses.

pub fn from_abstract<N: AsRef<[u8]> + ?Sized>(name: &N) -> Result<Self, Error>

Create an abstract unix socket address.

Abstract addresses is a non-standard feature which is only available on Linux and FreeBSD.
This function is always present, and abstract UnixSocketAddrs can be created even if the operating system doesn't support them. Actually using the address will hopefully fail when bind()ing or connect()ing it.

Abstract names can contain NUL bytes.

Errors

This function will return an error if the name is too long. Call max_abstract_len() get the limit.

pub fn from_std(addr: SocketAddr) -> Option<Self>

Try to convert a std::os::unix::net::SocketAddr into an UnixSocketAddr.

This can fail (produce None) if the std ``SocketAddr represents an abstract address, because it doesn't provide any method for viewing it. (other than parsing its Debug output, anyway.)

pub fn from_c_str(path: &CStr) -> Result<Self, Error>

This method can create unnamed and path addresses, but not abstract ones.

Creates unnamed addres for empty strings, and path addresses otherwise.

Errors

Returns ENAMETOOLONG if path (without the trailing '\0') is too long for sockaddr_un.sun_path.

pub fn is_unnamed(&self) -> bool

pub fn is_abstract(&self) -> bool

pub fn is_absolute_path(&self) -> bool

pub fn is_relative_path(&self) -> bool

pub fn is_path(&self) -> bool

pub fn as_ref(&self) -> UnixSocketAddrRef

Get a view that can be pattern matched to the differnt types of addresses.

pub fn new_from_ffi<R, F>(call: F) -> Result<(R, Self), Error> where
    F: FnOnce(&mut sockaddr, &mut socklen_t) -> Result<R, Error>, 

Prepare a struct sockaddr* and socklen_t* for passing to ffi (such as getsockname(), getpeername(), accept()), and sanitize and normalize the produced address afterwards.

Sanitizations:

• checking that the address family is AF_UNIX.
• checking that the address wasn't truncated (the socklen_t is too big).

Normalization:

• Path addresses have a trailing NUL byte appended if not already there and there is space.

pub unsafe fn from_raw(
    addr: *const sockaddr,
    len: socklen_t
) -> Result<Self, Error>

Create an UnixSocketAddr from a pointer to a generic sockaddr and a length.

Safety

• len must not be greater than the size of the memory addr points to.
• addr must point to valid memory if len is greater than zero, or be NULL.

pub unsafe fn from_raw_unchecked(addr: sockaddr_un, len: socklen_t) -> Self

Create an UnixSocketAddr without any validation.

Safety

• len must be <= size_of::<sockaddr_un>().
• addr.sun_family should be AF_UNIX or strange things could happen.
• addr.sun_len if it exists should be zero.

pub fn into_raw(self) -> (sockaddr_un, socklen_t)

Split the address into its inner, raw parts.

pub fn as_raw_general(&self) -> (&sockaddr, socklen_t)

Get a general sockaddr reference to the address and its length.

Useful for passing to bind(), connect(), sendto() or other FFI.

pub fn as_raw(&self) -> (&sockaddr_un, socklen_t)

Get a reference to the inner struct sockaddr_un, and length.

pub unsafe fn as_raw_mut_general(&mut self) -> (&mut sockaddr, &mut socklen_t)

Get mutable references to a general struct sockaddr and socklen_t.

If passing to getpeername(), accept() or similar, remember to set the length to the capacity, and consider using new_from_ffi() instead.

Safety

Assigning a value > sizeof(struct sockaddr_un) to the socklen_t reference might lead to out-of-bounds reads later.

pub unsafe fn as_raw_mut(&mut self) -> (&mut sockaddr_un, &mut socklen_t)

Get mutable references to the inner struct sockaddr_un and length.

Safety

Assigning a value > sizeof(struct sockaddr_un) to the socklen_t reference might lead to out-of-bounds reads later.

Trait Implementations

impl<'a> From<&'a UnixSocketAddr> for UnixSocketAddrRef<'a>

fn from(addr: &'a UnixSocketAddr) -> UnixSocketAddrRef<'a>

Performs the conversion.

impl Clone for UnixSocketAddr

fn clone(&self) -> UnixSocketAddr

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Copy for UnixSocketAddr

impl Default for UnixSocketAddr

fn default() -> Self

Returns the "default value" for a type.

impl Eq for UnixSocketAddr

impl PartialEq<UnixSocketAddr> for UnixSocketAddr

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<[u8]> for UnixSocketAddr

fn eq(&self, unescaped: &[u8]) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<UnixSocketAddr> for [u8]

fn eq(&self, addr: &UnixSocketAddr) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Display for UnixSocketAddr

fn fmt(&self, fmtr: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Debug for UnixSocketAddr

fn fmt(&self, fmtr: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Hash for UnixSocketAddr

fn hash<H: Hasher>(&self, hasher: &mut H)

Feeds this value into the given [Hasher].

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

Feeds a slice of this type into the given [Hasher].