Struct uds::nonblocking::UnixSeqpacketConn

#[repr(transparent)]
pub struct UnixSeqpacketConn { /* private fields */ }

A non-blocking unix domain sequential-packet connection.

Differs from uds::UnixSeqpacketConn in that all operations that send or receive data will return an Error of kind ErrorKind::WouldBlock instead of blocking. This is done by creating the socket as non-blocking, and not by passing MSG_DONTWAIT. If creating this type from a raw file descriptor, ensure the fd is set to nonblocking before using it through this type.

This type can be used with mio if one of the mio features are enabled:

For mio version 0.6:

uds = { version = "x.y", features=["mio"] }

For mio version 0.7:

uds = { version = "x.y", features=["mio_07"] }

Examples

Sending or receiving when it would block a normal socket:

use uds::nonblocking::UnixSeqpacketConn;
use std::io::ErrorKind;

let (a, b) = UnixSeqpacketConn::pair().expect("create nonblocking seqpacket pair");

// trying to receive when there are no packets waiting
assert_eq!(a.recv(&mut[0]).unwrap_err().kind(), ErrorKind::WouldBlock);

// trying to send when the OS buffer for the connection is full
loop {
    if let Err(error) = a.send(&[0u8; 1000]) {
        assert_eq!(error.kind(), ErrorKind::WouldBlock);
        break;
    }
}

Registering with mio (v0.6):

use uds::nonblocking::UnixSeqpacketConn;
use mio::{Poll, Token, Ready, PollOpt, Events};
use std::io::ErrorKind;

let (a, b) = UnixSeqpacketConn::pair()
    .expect("create nonblocking seqpacket pair");

let poll = Poll::new().expect("create mio poll");
let mut events = Events::with_capacity(10);
poll.register(&a, Token(1), Ready::all(),  PollOpt::edge())
    .expect("register unix seqpacket connection with mio");

b.send(b"this is it").expect("send seqpacket");

poll.poll(&mut events, None).expect("receive mio notifications");
let current_events = events.iter().collect::<Vec<_>>();
assert!(current_events.len() > 0);
assert_eq!(current_events[0].token(), Token(1));
assert_eq!(a.recv(&mut [0; 8]).expect("receive packet"), (8, true/*truncated*/));

Implementations

impl NonblockingUnixSeqpacketConn

pub fn connect<P: AsRef<Path>>(path: P) -> Result<Self, Error>

Connects to an unix seqpacket server listening at path.

This is a wrapper around connect_unix_addr() for convenience and compatibility with std.

pub fn connect_unix_addr(addr: &UnixSocketAddr) -> Result<Self, Error>

Connects to an unix seqpacket server listening at addr.

pub fn connect_from_to_unix_addr(
    from: &UnixSocketAddr,
    to: &UnixSocketAddr
) -> Result<Self, Error>

Binds to an address before connecting to a listening seqpacket socket.

pub fn pair() -> Result<(Self, Self), Error>

Creates a pair of nonblocking unix-domain seqpacket conneections connected to each other.

Examples

let (a, b) = uds::nonblocking::UnixSeqpacketConn::pair().unwrap();
assert!(a.local_unix_addr().unwrap().is_unnamed());
assert!(b.local_unix_addr().unwrap().is_unnamed());
assert_eq!(b.recv(&mut[0; 20]).unwrap_err().kind(), std::io::ErrorKind::WouldBlock);
a.send(b"hello").unwrap();
assert_eq!(b.recv(&mut[0; 20]).unwrap(), (5, false));

pub fn local_unix_addr(&self) -> Result<UnixSocketAddr, Error>

Returns the address of this side of the connection.

pub fn peer_unix_addr(&self) -> Result<UnixSocketAddr, Error>

Returns the address of the other side of the connection.

pub fn initial_peer_credentials(&self) -> Result<ConnCredentials, Error>

Returns information about the process of the peer when the connection was established.

See documentation of the returned type for details.

pub fn initial_peer_selinux_context(
    &self,
    buf: &mut [u8]
) -> Result<usize, Error>

Returns the SELinux security context of the process that created the other end of this connection.

Will return an error on other operating systems than Linux or Android, and also if running inside kubernetes. On success the number of bytes used is returned. (like Read)

The default security context is unconfined, without any trailing NUL.
A buffor of 50 bytes is probably always big enough.

pub fn send(&self, packet: &[u8]) -> Result<usize, Error>

Sends a packet to the peer.

pub fn recv(&self, buffer: &mut [u8]) -> Result<(usize, bool), Error>

Receives a packet from the peer.

The returned bool indicates whether the packet was truncated due to too short buffer.

pub fn send_vectored(&self, slices: &[IoSlice<'_>]) -> Result<usize, Error>

Sends a packet assembled from multiple byte slices.

pub fn recv_vectored(
    &self,
    buffers: &mut [IoSliceMut<'_>]
) -> Result<(usize, bool), Error>

Reads a packet into multiple buffers.

The returned bool indicates whether the packet was truncated due to too short buffers.

pub fn send_fds(&self, bytes: &[u8], fds: &[RawFd]) -> Result<usize, Error>

Sends a packet with associated file descriptors.

pub fn recv_fds(
    &self,
    byte_buffer: &mut [u8],
    fd_buffer: &mut [RawFd]
) -> Result<(usize, bool, usize), Error>

Receives a packet and associated file descriptors.

pub fn peek(&self, buffer: &mut [u8]) -> Result<(usize, bool), Error>

Receives a packet without removing it from the incoming queue.

The returned bool indicates whether the packet was truncated due to the buffer being too small.

Examples

let (a, b) = uds::nonblocking::UnixSeqpacketConn::pair().unwrap();
let mut buf = [0u8; 10];
assert_eq!(b.peek(&mut buf).unwrap_err().kind(), WouldBlock);
a.send(b"hello").unwrap();
assert_eq!(b.peek(&mut buf).unwrap(), (5, false));
assert_eq!(&buf[..5], b"hello");
assert_eq!(b.recv(&mut buf).unwrap(), (5, false));
assert_eq!(&buf[..5], b"hello");
assert_eq!(b.peek(&mut buf).unwrap_err().kind(), WouldBlock);

pub fn peek_vectored(
    &self,
    buffers: &mut [IoSliceMut<'_>]
) -> Result<(usize, bool), Error>

Receives a packet without removing it from the incoming queue.

The returned bool indicates whether the packet was truncated due to the combined buffers being too small.

pub fn take_error(&self) -> Result<Option<Error>, Error>

Returns the value of the SO_ERROR option.

This might only provide errors generated from nonblocking connect()s, which this library doesn’t support. It is therefore unlikely to be useful, but is provided for parity with mios UnixStream.

Examples

let (a, _b) = uds::nonblocking::UnixSeqpacketConn::pair().unwrap();

assert!(a.recv(&mut[0u8; 1024]).is_err());
assert!(a.take_error().unwrap().is_none());

pub fn try_clone(&self) -> Result<Self, Error>

Creates a new file descriptor also pointing to this side of this connection.

Examples

let (a1, b) = UnixSeqpacketConn::pair().unwrap();
b.send(b"first come first serve").unwrap();
let a2 = a1.try_clone().unwrap();
a2.recv(&mut[0u8; 10]).unwrap();
assert_eq!(a1.recv(&mut[0u8; 10]).unwrap_err().kind(), ErrorKind::WouldBlock);

b.send(b"more").unwrap();
a1.recv(&mut[0u8; 10]).unwrap();
assert_eq!(a2.recv(&mut[0u8; 10]).unwrap_err().kind(), ErrorKind::WouldBlock);

pub fn shutdown(&self, how: Shutdown) -> Result<()>

Shuts down the read, write, or both halves of this connection.

Trait Implementations

impl AsRawFd for NonblockingUnixSeqpacketConn

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for NonblockingUnixSeqpacketConn

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

Formats the value using the given formatter.

impl Drop for NonblockingUnixSeqpacketConn

fn drop(&mut self)

Executes the destructor for this type.

impl FromRawFd for NonblockingUnixSeqpacketConn

unsafe fn from_raw_fd(fd: RawFd) -> Self

Constructs a new instance of Self from the given raw file descriptor.

impl IntoRawFd for NonblockingUnixSeqpacketConn

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.