Struct UnixSeqpacketConn 

pub struct UnixSeqpacketConn { /* private fields */ }

An unix domain sequential packet connection.

Sequential-packet connections have an interface similar to streams, but behave more like connected datagram sockets.

They have guaranteed in-order and reliable delivery, which unix datagrams technically doesn’t.

Operating system support

Sequential-packet sockets are supported by Linux, FreeBSD, NetBSD and Illumos, but not by for example macOS or OpenBSD.

Zero-length packets

… are best avoided:
On Linux and FreeBSD zero-length packets can be sent and received, but there is no way to distinguish receiving one from reaching end of connection unless the packet has an ancillary payload. Also beware of trying to receive with a zero-length buffer, as that will on FreeBSD (and probably other BSDs with seqpacket sockets) always succeed even if there is no packet waiting.

Illumos and Solaris doesn’t support receiving zero-length packets at all: writes succeed but recv() will block.

Registering with Xio (xio-rs) a feature = “xio-rs”

A XioEventPipe is implemented on this function. During initial registration an attempt set nonblocking mode is performed during initial registration.

See examples below.

Registering with Mio (mio) a feature = “mio”

A Source is implemented on the instance.During initial registration an attempt set nonblocking mode is performed during initial registration.

Examples

What is sent separately is received separately:

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

a.send(b"first").unwrap();
a.send(b"second").unwrap();

let mut buffer_big_enough_for_both = [0; 20];
let len = b.recv(&mut buffer_big_enough_for_both).unwrap();
assert_eq!(&buffer_big_enough_for_both[..len], b"first");
let len = b.recv(&mut buffer_big_enough_for_both).unwrap();
assert_eq!(&buffer_big_enough_for_both[..len], b"second");

Connect to a listener on a socket file and write to it:

use uds_fork::{UnixSeqpacketListener, UnixSeqpacketConn};
use tempfile::TempDir;
 
let dir = tempfile::tempdir().unwrap();
let mut file_path = dir.path().join("seqpacket.socket");
 
let listener = UnixSeqpacketListener::bind(&file_path)
    .expect("create seqpacket listener");
let conn = UnixSeqpacketConn::connect(&file_path)
    .expect("connect to seqpacket listener");

let message = "Hello, listener";
let sent = conn.send(message.as_bytes()).unwrap();
assert_eq!(sent, message.len());

Connect to a listener on an abstract address:

use uds_fork::{UnixSeqpacketListener, UnixSeqpacketConn, UnixSocketAddr};

let addr = UnixSocketAddr::new("@seqpacket example").unwrap();
let listener = UnixSeqpacketListener::bind_unix_addr(&addr)
    .expect("create abstract seqpacket listener");
let _client = UnixSeqpacketConn::connect_unix_addr(&addr)
    .expect("connect to abstract seqpacket listener");
let (_server, _addr) = listener.accept_unix_addr().unwrap();

Xio

let (mut a, b) = UnixSeqpacketConn::pair().unwrap();
 
let mut reg = XioPollRegistry::<ESS>::new().unwrap();
let mut event_buf = XioPollRegistry::<ESS>::allocate_events(128.try_into().unwrap());
 
// either
let a_wrapped =
    reg.get_registry()
        .en_register_wrap(a, XioEventUid::manual(1), XioChannel::INPUT)
        .unwrap();
  
// or 
    reg.get_registry()
        .en_register&mut a, XioEventUid::manual(1), XioChannel::INPUT)
        .unwrap();
 
// so depending on the method, use either:
a_wrapped.inner();
 
// or continue using a directly

Mio:

let (mut a, b) = UnixSeqpacketConn::pair().unwrap();
 
let mut poll = Poll::new().expect("create mio poll");
let mut events = Events::with_capacity(10);
 
poll.registry()
    .register(&mut a, Token(1), Interest::READABLE)
    .unwrap();
// ...

Implementations

impl UnixSeqpacketConn

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 seqpacet socket.

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

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

Examples

let (a, b) = uds_fork::UnixSeqpacketConn::pair().unwrap();
assert!(a.local_unix_addr().unwrap().is_unnamed());
assert!(b.local_unix_addr().unwrap().is_unnamed());

a.send(b"hello").unwrap();
b.recv(&mut[0; 20]).unwrap();

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 send_flags(&self, packet: &[u8], flags: i32) -> Result<usize, Error>

Sends a packet to the peer.

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

Receives a packet from the peer.

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: Vec<OwnedFd>) -> Result<usize, Error>

Sends a packet with associated file descriptors.

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

Receives a packet and associated file descriptors. A legacy method which was in this crate since its author added it.

See a Self::recv_vectored_with_ancillary for a new stdlib approach.

Returns

• 0 - amount of bytes received

• 1 - is truncated

• 2 - a fd buffer length

pub fn recv_vectored_with_ancillary( &self, flags: i32, bufs: &mut [IoSliceMut<'_>], ancillary: &mut SocketAncillary<'_>, ) -> Result<(usize, bool), Error>

A new (provided by std) parser of the ancillary data

Unstable and extremely unsafe. Rust devs did not provide an access to the internal reference to the buffer in SocketAncillary, so there is no access to the buffer and its length. For this reason a very bad approach to overcome this is used.

Receives data and ancillary data from socket.

On success, returns the number of bytes read, if the data was truncated and the address from whence the msg came.

Returns

A Result is returned with tuple:

• 0 - a count of bytes.

• 1 - was msg truncated

Example

 let mut buf = [0_u8; 256];
let bufs = &mut [IoSliceMut::new(&mut buf[..])];
 
let mut ancillary_buffer = [0; 128];
let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]);
 
let (count, trunc) = 
    freya_side_b.recv_vectored_with_ancillary(bufs, &mut ancillary).unwrap();

pub fn recv_vectored_with_ancillary_from( &self, flags: i32, bufs: &mut [IoSliceMut<'_>], ancillary: &mut SocketAncillary<'_>, ) -> Result<(usize, bool, UnixSocketAddr), Error>

A new (provided by std) parser of the ancillary data

Unstable and extremely unsafe. Rust devs did not provide an access to the internal reference to the buffer in SocketAncillary, so there is no access to the buffer and its length. For this reason a very bad approach to overcome this is used.

Receives data and ancillary data providing the source of msg.

On success, returns the number of bytes read, if the data was truncated and the address from whence the msg came.

Returns

A Result is returned with tuple:

• 0 - a count of bytes.

• 1 - was msg truncated

• 2 - a source address

Example

let mut buf = [0_u8; 256];
let bufs = &mut [IoSliceMut::new(&mut buf[..])];
 
let mut ancillary_buffer = [0; 128];
let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]);
 
let (count, trunc, from) = 
    freya_side_b.recv_vectored_with_ancillary(bufs, &mut ancillary).unwrap();

pub fn send_vectored_with_ancillary( &self, flags: i32, bufs: &[IoSlice<'_>], ancillary: &mut SocketAncillary<'_>, ) -> Result<usize>

A new (provided by std) parser of the ancillary data.

Rust #![feature(unix_socket_ancillary_data)]

Unstable and extremely unsafe. Rust devs did not provide an access to the internal reference to the buffer in SocketAncillary, so there is no access to the buffer and its length. For this reason a very bad approach to overcome this is used.

Sends data and ancillary data on the current socket.

On success, returns the number of bytes written.

Crate: feature = unsatable_preview

Arguments

• flags - a flags which are passed to libc::recvmsg.

• bufs - an IoSlice buffers.

• ancillary - packed ancillary data

Example

let buf0 = b"Here I come";
let mut ancillary_buffer = [0; 128];
let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]);
 
let fds = [OwnedFd::from(a).into_raw_fd(), OwnedFd::from(b).into_raw_fd(), OwnedFd::from(aa).into_raw_fd()];
 
ancillary.add_fds(&fds[..]);
 
freya_side_a.send_vectored_with_ancillary(&[IoSlice::new(buf0.as_slice())], &mut ancillary)
    .expect("send stdin, stdout and stderr");
 

pub fn send_vectored_with_ancillary_to( &self, flags: i32, to: &UnixSocketAddr, bufs: &[IoSlice<'_>], ancillary: &mut SocketAncillary<'_>, ) -> Result<usize>

A new (provided by std) parser of the ancillary data.

Rust #![feature(unix_socket_ancillary_data)]

Unstable and extremely unsafe. Rust devs did not provide an access to the internal reference to the buffer in SocketAncillary, so there is no access to the buffer and its length. For this reason a very bad approach to overcome this is used.

Sends data and ancillary data on the socket to the specified address.

On success, returns the number of bytes written.

Crate: feature = unsatable_preview

Arguments

• flags - a flags which are passed to libc::recvmsg.

• to - a destination.

• bufs - an IoSlice buffers.

• ancillary - packed ancillary data

Example

let buf0 = b"Here I come";
let mut ancillary_buffer = [0; 128];
let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]);
 
let fds = 
    [OwnedFd::from(a).into_raw_fd(), OwnedFd::from(b).into_raw_fd(), OwnedFd::from(aa).into_raw_fd()];
 
ancillary.add_fds(&fds[..]);
 
let dst = UnixSocketAddr::from_abstract("@test");
 
freya_side_a
    .send_vectored_with_ancillary_to(0, &dst, &[IoSlice::new(buf0.as_slice())], &mut ancillary)
    .expect("send stdin, stdout and stderr");
 

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

Receives a packet without removing it from the incoming queue.

Examples

let (a, b) = uds_fork::UnixSeqpacketConn::pair().unwrap();
a.send(b"hello").unwrap();
let mut buf = [0u8; 10];
assert_eq!(b.peek(&mut buf[..1]).unwrap(), 1);
assert_eq!(&buf[..2], &[b'h', 0]);
assert_eq!(b.peek(&mut buf).unwrap(), 5);
assert_eq!(&buf[..5], b"hello");
assert_eq!(b.recv(&mut buf).unwrap(), 5);
assert_eq!(&buf[..5], b"hello");

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 stream counterpart in std.

Examples

let (a, b) = uds_fork::UnixSeqpacketConn::pair().unwrap();
drop(b);

assert!(a.send(b"anyone there?").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

Both new and old can send and receive, and share queues:

let (a1, b) = uds_fork::nonblocking::UnixSeqpacketConn::pair().unwrap();
let a2 = a1.try_clone().unwrap();

a1.send(b"first").unwrap();
a2.send(b"second").unwrap();

let mut buf = [0u8; 20];
let len = b.recv(&mut buf).unwrap();
assert_eq!(&buf[..len], b"first");
b.send(b"hello first").unwrap();
let len = b.recv(&mut buf).unwrap();
assert_eq!(&buf[..len], b"second");
b.send(b"hello second").unwrap();

let len = a2.recv(&mut buf).unwrap();
assert_eq!(&buf[..len], b"hello first");
let len = a1.recv(&mut buf).unwrap();
assert_eq!(&buf[..len], b"hello second");

Clone can still be used after the first one has been closed:

let (a, b1) = uds_fork::nonblocking::UnixSeqpacketConn::pair().unwrap();
a.send(b"hello").unwrap();

let b2 = b1.try_clone().unwrap();
drop(b1);
assert_eq!(b2.recv(&mut[0; 10]).unwrap(), "hello".len());

pub fn set_read_timeout(&self, timeout: Option<Duration>) -> Result<(), Error>

Sets the read timeout to the duration specified.

If the value specified is None, then recv() and its variants will block indefinitely.
An error is returned if the duration is zero.

The duration is rounded to microsecond precission. Currently it’s rounded down except if that would make it all zero.

Operating System Support

On Illumos (and pressumably also Solaris) timeouts appears not to work for unix domain sockets.

Examples

use std::io::ErrorKind;
use std::time::Duration;
use uds_fork::UnixSeqpacketConn;

let (a, b) = UnixSeqpacketConn::pair().unwrap();
a.set_read_timeout(Some(Duration::new(0, 2_000_000))).unwrap();
let error = a.recv(&mut[0; 1024]).unwrap_err();
assert_eq!(error.kind(), ErrorKind::WouldBlock);

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

Returns the read timeout of this socket.

None is returned if there is no timeout.

Note that subsecond parts might have been be rounded by the OS (in addition to the rounding to microsecond in set_read_timeout()).

Examples

use uds_fork::UnixSeqpacketConn;
use std::time::Duration;

let timeout = Some(Duration::new(2, 0));
let conn = UnixSeqpacketConn::pair().unwrap().0;
conn.set_read_timeout(timeout).unwrap();
assert_eq!(conn.read_timeout().unwrap(), timeout);

pub fn set_write_timeout(&self, timeout: Option<Duration>) -> Result<(), Error>

Sets the write timeout to the duration specified.

If the value specified is None, then send() and its variants will block indefinitely.
An error is returned if the duration is zero.

Operating System Support

On Illumos (and pressumably also Solaris) timeouts appears not to work for unix domain sockets.

Examples

let (conn, _other) = UnixSeqpacketConn::pair().unwrap();
conn.set_write_timeout(Some(Duration::new(0, 500 * 1000))).unwrap();
loop {
    if let Err(e) = conn.send(&[0; 1000]) {
        assert_eq!(e.kind(), ErrorKind::WouldBlock, "{}", e);
        break
    }
}

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

Returns the write timeout of this socket.

None is returned if there is no timeout.

Examples

let conn = uds_fork::UnixSeqpacketConn::pair().unwrap().0;
assert!(conn.write_timeout().unwrap().is_none());

pub fn set_nonblocking(&self, nonblocking: bool) -> Result<(), Error>

Enables or disables nonblocking mode.

Consider using the nonblocking variant of this type instead. This method mainly exists for feature parity with std’s UnixStream.

Examples

Trying to receive when there are no packets waiting:

let (a, b) = UnixSeqpacketConn::pair().expect("create seqpacket pair");
a.set_nonblocking(true).unwrap();
assert_eq!(a.recv(&mut[0; 20]).unwrap_err().kind(), ErrorKind::WouldBlock);

Trying to send when the OS buffer for the connection is full:

let (a, b) = UnixSeqpacketConn::pair().expect("create seqpacket pair");
a.set_nonblocking(true).unwrap();
loop {
    if let Err(error) = a.send(&[b'#'; 1000]) {
        assert_eq!(error.kind(), ErrorKind::WouldBlock);
        break;
    }
}

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

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

Trait Implementations

impl AsFd for UnixSeqpacketConn

fn as_fd(&self) -> BorrowedFd<'_>

Borrows the file descriptor.

impl AsRawFd for UnixSeqpacketConn

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for UnixSeqpacketConn

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

Formats the value using the given formatter.

impl From<OwnedFd> for UnixSeqpacketConn

fn from(ofd: OwnedFd) -> Self

Converts to this type from the input type.

impl From<UnixSeqpacketConn> for OwnedFd

fn from(value: UnixSeqpacketConn) -> Self

Converts to this type from the input type.

impl FromRawFd for UnixSeqpacketConn

unsafe fn from_raw_fd(fd: RawFd) -> Self

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

impl IntoRawFd for UnixSeqpacketConn

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.

impl<'a> Read for &'a UnixSeqpacketConn

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

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

Like read, except that it reads into a slice of buffers.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize>

Reads all bytes until EOF in this source, appending them to buf.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

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

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

fn read_array<const N: usize>(&mut self) -> Result<[u8; N], Error>

where Self: Sized,

🔬This is a nightly-only experimental API. (read_array)

Read and return a fixed array of bytes from this source.

impl Read for UnixSeqpacketConn

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

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

Like read, except that it reads into a slice of buffers.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize>

Reads all bytes until EOF in this source, appending them to buf.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

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

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

fn read_array<const N: usize>(&mut self) -> Result<[u8; N], Error>

where Self: Sized,

🔬This is a nightly-only experimental API. (read_array)

Read and return a fixed array of bytes from this source.

impl Write for UnixSeqpacketConn

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

Writes a buffer into this writer, returning how many bytes were written.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>

Like write, except that it writes from a slice of buffers.

fn flush(&mut self) -> Result<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

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

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.

impl<ESSR: EsInterfaceRegistry> XioEventPipe<ESSR> for UnixSeqpacketConn

fn connect_event_pipe( &mut self, ess: &XioRegistry<ESSR>, ev_uid: XioEventUid, channel: XioChannel, ) -> XioResult<()>

Should connect the self to the endpoint which is provided by the argument ess.

fn modify_event_pipe( &mut self, ess: &XioRegistry<ESSR>, ev_uid: XioEventUid, channel: XioChannel, ) -> XioResult<()>

This interface function should be reimplemented soon.

fn disconnect_event_pipe(&mut self, ess: &XioRegistry<ESSR>) -> XioResult<()>

Should disconnect self from the ess provided endpoint. An instance which implements the logic should check that the ess matches the ess used when self was initially registered (if available).