[−][src]Struct uds::UnixSeqpacketConn
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.
Examples
What is sent separately is received separately:
let (a, b) = uds::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, _truncated) = b.recv(&mut buffer_big_enough_for_both).unwrap(); assert_eq!(&buffer_big_enough_for_both[..len], b"first"); let (len, _truncated) = 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::{UnixSeqpacketListener, UnixSeqpacketConn}; let listener = UnixSeqpacketListener::bind("seqpacket.socket") .expect("create seqpacket listener"); let conn = UnixSeqpacketConn::connect("seqpacket.socket") .expect("connect to seqpacket listener"); let message = "Hello, listener"; let sent = conn.send(message.as_bytes()).unwrap(); assert_eq!(sent, message.len()); std::fs::remove_file("seqpacket.socket").unwrap(); // clean up after ourselves
Connect to a listener on an abstract address:
use uds::{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();
Implementations
impl UnixSeqpacketConn
[src]
pub fn connect<P: AsRef<Path>>(path: P) -> Result<Self, Error>
[src]
Connect 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>
[src]
Connect to an unix seqpacket server listening at addr
.
pub fn connect_from_to_unix_addr(
from: &UnixSocketAddr,
to: &UnixSocketAddr
) -> Result<Self, Error>
[src]
from: &UnixSocketAddr,
to: &UnixSocketAddr
) -> Result<Self, Error>
Bind to an address before connecting to a listening sequplacet socket.
pub fn pair() -> Result<(Self, Self), Error>
[src]
Create a pair of unix-domain seqpacket conneections connected to each other.
Examples
let (a, b) = uds::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>
[src]
Get the address of this side of the connection.
pub fn peer_unix_addr(&self) -> Result<UnixSocketAddr, Error>
[src]
Get the address of the other side of the connection.
pub fn initial_peer_credentials(&self) -> Result<ConnCredentials, Error>
[src]
Get information about the process of the peer when the connection was established.
See documentation of the returned type for details.
pub fn send(&self, packet: &[u8]) -> Result<usize, Error>
[src]
Send a packet to the peer.
pub fn recv(&self, buffer: &mut [u8]) -> Result<(usize, bool), Error>
[src]
Receive 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>
[src]
Send a packet assembled from multiple byte slices.
pub fn recv_vectored(
&self,
buffers: &mut [IoSliceMut<'_>]
) -> Result<(usize, bool), Error>
[src]
&self,
buffers: &mut [IoSliceMut<'_>]
) -> Result<(usize, bool), Error>
Read 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>
[src]
Send a packet with associated file descriptors.
pub fn recv_fds(
&self,
byte_buffer: &mut [u8],
fd_buffer: &mut [RawFd]
) -> Result<(usize, bool, usize), Error>
[src]
&self,
byte_buffer: &mut [u8],
fd_buffer: &mut [RawFd]
) -> Result<(usize, bool, usize), Error>
Receive a packet and associated file descriptors.
pub fn try_clone(&self) -> Result<Self, Error>
[src]
Create 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::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, _truncated) = b.recv(&mut buf).unwrap(); assert_eq!(&buf[..len], b"first"); b.send(b"hello first").unwrap(); let (len, _truncated) = b.recv(&mut buf).unwrap(); assert_eq!(&buf[..len], b"second"); b.send(b"hello second").unwrap(); let (len, _truncated) = a2.recv(&mut buf).unwrap(); assert_eq!(&buf[..len], b"hello first"); let (len, _truncated) = 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::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().0, "hello".len());
pub fn set_nonblocking(&self, nonblocking: bool) -> Result<(), Error>
[src]
Enable or disable 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<()>
[src]
Shuts down the read, write, or both halves of this connection.
Trait Implementations
impl AsRawFd for UnixSeqpacketConn
[src]
impl Debug for UnixSeqpacketConn
[src]
impl Drop for UnixSeqpacketConn
[src]
impl FromRawFd for UnixSeqpacketConn
[src]
unsafe fn from_raw_fd(fd: RawFd) -> Self
[src]
impl IntoRawFd for UnixSeqpacketConn
[src]
fn into_raw_fd(self) -> RawFd
[src]
Auto Trait Implementations
impl RefUnwindSafe for UnixSeqpacketConn
impl Send for UnixSeqpacketConn
impl Sync for UnixSeqpacketConn
impl Unpin for UnixSeqpacketConn
impl UnwindSafe for UnixSeqpacketConn
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,
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, 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.
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>,