Struct uds::UnixSocketAddr [−][src]
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
impl UnixSocketAddr
[src]
pub fn new<A: AsRef<[u8]> + ?Sized>(addr: &A) -> Result<Self, Error>
[src]
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());
pub fn new_unspecified() -> Self
[src]
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());
pub fn max_path_len() -> usize
[src]
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.
pub fn from_path<P: AsRef<Path> + ?Sized>(path: &P) -> Result<Self, Error>
[src]
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.
pub fn max_abstract_len() -> usize
[src]
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.
pub const fn has_abstract_addresses() -> bool
[src]
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.
pub fn from_abstract<N: AsRef<[u8]> + ?Sized>(name: &N) -> Result<Self, Error>
[src]
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)
pub fn from_std(addr: SocketAddr) -> Option<Self>
[src]
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.)
pub fn from_c_str(path: &CStr) -> Result<Self, Error>
[src]
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
.
pub fn is_unnamed(&self) -> bool
[src]
Checks whether the address is unnamed.
pub fn is_abstract(&self) -> bool
[src]
Checks whether the address is a name in the abstract namespace.
Always returns false
on operating systems that don’t support abstract
addresses.
pub fn is_absolute_path(&self) -> bool
[src]
Checks whether the address is a path that begins with ‘/’.
pub fn is_relative_path(&self) -> bool
[src]
Checks whether the address is a path that doesn’t begin with ‘/’.
pub fn is_path(&self) -> bool
[src]
Checks whether the address is a path.
pub fn name(&self) -> AddrName<'_>
[src]
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") ); }
pub fn as_pathname(&self) -> Option<&Path>
[src]
Returns the path of a path-based address.
pub fn as_abstract(&self) -> Option<&[u8]>
[src]
Returns the name of an address which is in the abstract namespace.
pub fn as_ref(&self) -> UnixSocketAddrRef<'_>
[src]
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);
pub fn from_raw_bytes(addr: &[u8]) -> Result<Self, Error>
[src]
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());
pub fn as_raw_bytes(&self) -> &[u8]ⓘ
[src]
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());
pub fn new_from_ffi<R, F>(call: F) -> Result<(R, Self), Error> where
F: FnOnce(&mut sockaddr, &mut socklen_t) -> Result<R, Error>,
[src]
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:
- Check that the address family is
AF_UNIX
. - Check that the address wasn’t truncated (the
socklen_t
is too big).
Normalization:
- Ensure path addresses have a trailing NUL byte if there is space.
pub unsafe fn from_raw(
addr: *const sockaddr,
len: socklen_t
) -> Result<Self, Error>
[src]
addr: *const sockaddr,
len: socklen_t
) -> Result<Self, Error>
Creates an UnixSocketAddr
from a pointer to a generic sockaddr
and
a length.
Safety
len
must not be greater than the size of the memoryaddr
points to.addr
must point to valid memory iflen
is greater than zero, or be NULL.
pub unsafe fn from_raw_unchecked(addr: sockaddr_un, len: socklen_t) -> Self
[src]
Creates an UnixSocketAddr
without any validation.
Safety
len
must be<= size_of::<sockaddr_un>()
.addr.sun_family
should beAF_UNIX
or strange things might happen.addr.sun_len
, if it exists, should be zero (but is probably ignored).
pub fn into_raw(self) -> (sockaddr_un, socklen_t)
[src]
Splits the address into its inner, raw parts.
pub fn as_raw_general(&self) -> (&sockaddr, socklen_t)
[src]
Returns 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)
[src]
Returns a reference to the inner struct sockaddr_un
, and length.
pub unsafe fn as_raw_mut_general(&mut self) -> (&mut sockaddr, &mut socklen_t)
[src]
Returns 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)
[src]
Returns 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 Clone for UnixSocketAddr
[src]
fn clone(&self) -> UnixSocketAddr
[src]
pub fn clone_from(&mut self, source: &Self)
1.0.0[src]
impl Copy for UnixSocketAddr
[src]
impl Debug for UnixSocketAddr
[src]
impl Default for UnixSocketAddr
[src]
impl Display for UnixSocketAddr
[src]
impl Eq for UnixSocketAddr
[src]
impl<'a> From<&'a UnixSocketAddr> for AddrName<'a>
[src]
fn from(addr: &'a UnixSocketAddr) -> AddrName<'a>
[src]
impl Hash for UnixSocketAddr
[src]
fn hash<H: Hasher>(&self, hasher: &mut H)
[src]
pub fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,
1.3.0[src]
H: Hasher,
impl PartialEq<[u8]> for UnixSocketAddr
[src]
fn eq(&self, unescaped: &[u8]) -> bool
[src]
#[must_use]pub fn ne(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialEq<UnixSocketAddr> for UnixSocketAddr
[src]
impl PartialEq<UnixSocketAddr> for [u8]
[src]
Auto Trait Implementations
impl RefUnwindSafe for UnixSocketAddr
impl Send for UnixSocketAddr
impl Sync for UnixSocketAddr
impl Unpin for UnixSocketAddr
impl UnwindSafe for UnixSocketAddr
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
pub fn to_owned(&self) -> T
[src]
pub fn clone_into(&self, target: &mut T)
[src]
impl<T> ToString for T where
T: Display + ?Sized,
[src]
T: Display + ?Sized,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,