Struct uds::UnixSocketAddr

source · [−]

pub struct UnixSocketAddr { /* private fields */ }

Expand description

A unix domain socket address.

Differences from `std`’s `unix::net::SocketAddr`

This type fully supports Linux’s abstract socket addresses, and can be created by user code instead of just returned by accept() and similar.

Examples

Creating an abstract address (fails if the OS doesn’t support them):

use uds::UnixSocketAddr;

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

Implementations

source

impl UnixSocketAddr

source

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 taken as the unnamed address, and anything else is a path address.
If a relative path address starts with @, escape it by prepending "./". To avoid surprises, abstract addresses will be detected regargsless of wheither the OS supports them, and result in an error if it doesn’t.

Errors

A path or abstract address is too long.
A path address contains '\0'.
An abstract name was supplied on an OS that doesn’t support them.

Examples

Abstract address:

if UnixSocketAddr::has_abstract_addresses() {
    assert!(UnixSocketAddr::new("@abstract").unwrap().is_abstract());
    assert!(UnixSocketAddr::new("\0abstract").unwrap().is_abstract());
} else {
    assert!(UnixSocketAddr::new("@abstract").is_err());
    assert!(UnixSocketAddr::new("\0abstract").is_err());
}

Escaped path address:

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

Unnamed address:

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

source

pub fn new_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 doing so binds the socket to a random abstract address determined by the OS.

Examples

let addr = UnixSocketAddr::new_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());

source

pub fn max_path_len() -> usize

Returns the maximum size of pathname addresses supported by UnixSocketAddr.

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

source

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

Creates 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.

source

pub fn max_abstract_len() -> usize

Returns maximum size of abstract addesses supported by UnixSocketAddr.

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

This value is also returned on operating systems that doesn’t support abstract addresses.

source

pub const fn has_abstract_addresses() -> bool

Returns whether the operating system is known to support abstract unix domain socket addresses.

Is true for Linux & Android, and false for all other OSes.

source

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

Creates an abstract unix domain socket address.

Abstract addresses use a namespace separate from the file system, that doesn’t have directories (ie. is flat) or permissions. The advandage of it is that the address disappear when the socket bound to it is closed, which frees one from dealing with removing it when shutting down cleanly.

They are a Linux-only feature though, and this function will fail if abstract addresses are not supported.

Errors

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

It will also fail on operating systems that don’t support abstract addresses. (ie. anything other than Linux and Android)

source

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

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

This can fail (produce None) on Linux and Android if the std SocketAddr represents an abstract address, as it provides no method for viewing abstract addresses. (other than parsing its Debug output, anyway.)

source

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

Returns 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.

source

pub fn is_unnamed(&self) -> bool

Checks whether the address is unnamed.

source

pub fn is_abstract(&self) -> bool

Checks whether the address is a name in the abstract namespace.

Always returns false on operating systems that don’t support abstract addresses.

source

pub fn is_absolute_path(&self) -> bool

Checks whether the address is a path that begins with ‘/’.

source

pub fn is_relative_path(&self) -> bool

Checks whether the address is a path that doesn’t begin with ‘/’.

source

pub fn is_path(&self) -> bool

Checks whether the address is a path.

source

pub fn name(&self) -> AddrName<'_>

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

Examples

use uds::{UnixSocketAddr, AddrName};
use std::path::Path;

assert_eq!(
    UnixSocketAddr::new_unspecified().name(),
    AddrName::Unnamed
);
assert_eq!(
    UnixSocketAddr::from_path("/var/run/socket.sock").unwrap().name(),
    AddrName::Path(Path::new("/var/run/socket.sock"))
);
if UnixSocketAddr::has_abstract_addresses() {
    assert_eq!(
        UnixSocketAddr::from_abstract("tcartsba").unwrap().name(),
        AddrName::Abstract(b"tcartsba")
    );
}

source

pub fn as_pathname(&self) -> Option<&Path>

Returns the path of a path-based address.

source

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

Returns the name of an address which is in the abstract namespace.

source

pub fn as_ref(&self) -> UnixSocketAddrRef<'_>

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

Examples

use uds::{UnixDatagramExt, UnixSocketAddr, UnixSocketAddrRef};
use std::os::unix::net::UnixDatagram;
use std::path::Path;

let receiver = UnixDatagram::bind("dgram.socket").expect("create datagram socket");
assert_eq!(
    receiver.local_unix_addr().unwrap().as_ref(),
    UnixSocketAddrRef::Path(Path::new("dgram.socket"))
);

let sender = UnixDatagram::unbound().expect("create unbound datagram socket");
sender.send_to(b"I can't hear you", "dgram.socket").expect("send");

let mut buf = [0; 100];
let (len, addr) = receiver.recv_from_unix_addr(&mut buf).unwrap();
assert_eq!(addr.as_ref(), UnixSocketAddrRef::Unnamed);

source

pub fn from_raw_bytes(addr: &[u8]) -> Result<Self, Error>

Creates an address from a slice of bytes to place in sun_path.

This is a low-level but simple interface for creating addresses by other unix socket wrappers without exposing any libc types.
The meaning of a slice can vary between operating systems.

addr should point to thes start of the “path” part of a socket address, with length being the number of valid bytes of the path. (Trailing NULs are not stripped by this function.)

Errors

If the slice is longer than sun_path, an error of kind Other is returned. No other validation of the bytes is performed.

Examples

A normal path-based address

let addr = UnixSocketAddr::from_raw_bytes(b"/var/run/a.sock\0").unwrap();
assert_eq!(addr.as_pathname(), Some(Path::new("/var/run/a.sock")));
assert_eq!(addr.as_raw_bytes(), b"/var/run/a.sock\0");

On Linux:

let addr = UnixSocketAddr::from_raw_bytes(b"\0a").unwrap();
assert_eq!(addr.as_abstract(), Some(&b"a"[..]));
assert_eq!(addr.as_raw_bytes(), b"\0a");

Elsewhere:

let addr = UnixSocketAddr::from_raw_bytes(b"\0a").unwrap();
assert!(addr.is_unnamed());
assert_eq!(addr.as_raw_bytes().len(), 2);

A portable unnamed address:

let addr = UnixSocketAddr::from_raw_bytes(&[]).expect("not too long");
assert!(addr.is_unnamed());
assert!(addr.as_raw_bytes().is_empty());

source

pub fn as_raw_bytes(&self) -> &[u8]ⓘNotable traits for &[u8]`impl Read for &[u8]impl Write for &mut [u8]`

Returns a low-level but view of the address without using any libc types.

The returned slice points to the start of sun_addr of the contained sockaddr_un, and the length is the number of bytes of sun_addr that were filled out by the OS. Any trailing NUL(s) will be preserved.

Examples

A normal path-based address

let pathname = "a file";
let socket = UnixDatagram::bind(pathname).expect("create datagram socket");
let addr = socket.local_unix_addr().expect("get its address");
assert!(addr.as_raw_bytes().starts_with(pathname.as_bytes()));
assert!(addr.as_raw_bytes()[pathname.len()..].iter().all(|&b| b == b'\0' ));
assert_eq!(addr.as_pathname(), Some(Path::new(pathname)));

Abstract address:

let addr = UnixSocketAddr::new("@someone@").unwrap();
assert_eq!(addr.as_raw_bytes(), b"\0someone@");

Unnamed address on macOS, OpenBSD and maybe others:

let socket = UnixDatagram::unbound().expect("create datagram socket");
let addr = socket.local_unix_addr().expect("get its unbound address");
let bytes = addr.as_raw_bytes();
assert!(bytes.len() > 0);
assert!(bytes.iter().all(|&b| b == b'\0' ));
assert!(addr.is_unnamed());

source

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

Prepares a struct sockaddr* and socklen_t* for passing to FFI (such as getsockname(), getpeername(), or accept()), and validate and normalize the produced address afterwards.

Validation: