Struct UdSocket

pub struct UdSocket { /* private fields */ }

Available on Unix only.

A datagram socket in the Unix domain.

All such sockets have the SOCK_DGRAM socket type; in other words, this is the Unix domain version of a UDP socket.

Implementations

impl UdSocket

pub fn bind<'a>(path: impl ToUdSocketPath<'a>) -> Result<Self>

Creates a new socket that can be referred to by the specified path.

If the socket path exceeds the maximum socket path length (which includes the first 0 byte when using the socket namespace), an error is returned. Errors can also be produced for different reasons, i.e. errors should always be handled regardless of whether the path is known to be short enough or not.

After the socket is dropped, the socket file will be left over. Use bind_with_drop_guard() to mitigate this automatically, even during panics (if unwinding is enabled).

Example

See ToUdSocketPath for an example of using various string types to specify socket paths.

System calls

• socket
• bind

pub fn bind_with_drop_guard<'a>(path: impl ToUdSocketPath<'a>) -> Result<Self>

Creates a new socket that can be referred to by the specified path, remembers the address, and installs a drop guard that will delete the socket file once the socket is dropped.

See the documentation of bind().

pub fn set_destination<'a>(&self, path: impl ToUdSocketPath<'a>) -> Result<()>

Selects the Unix domain socket to send packets to. You can also just use .send_to() instead, but supplying the address to the kernel once is more efficient.

Example

use interprocess::os::unix::udsocket::UdSocket;

let conn = UdSocket::bind("/tmp/side_a.sock")?;
conn.set_destination("/tmp/side_b.sock")?;
// Communicate with datagrams here!

See ToUdSocketPath for an example of using various string types to specify socket paths.

System calls

• connect

pub fn connect<'a>(path: impl ToUdSocketPath<'a>) -> Result<Self>

👎Deprecated: creates unusable socket that is not bound to any address, use .set_destination() instead

Incorrect API; do not use.

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

Receives a single datagram from the socket, returning the size of the received datagram.

Note: there is an additional meaningless boolean return value which is always false. It used to signify whether the datagram was truncated or not, but the functionality was implemented incorrectly and only on Linux, leading to its removal in version 1.2.0. In the next breaking release, 2.0.0, the return value will be changed to just io::Result<usize>.

System calls

• read

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

Receives a single datagram from the socket, making use of scatter input and returning the size of the received datagram.

Note: there is an additional meaningless boolean return value which is always false. It used to signify whether the datagram was truncated or not, but the functionality was implemented incorrectly and only on Linux, leading to its removal in version 1.2.0. In the next breaking release, 2.0.0, the return value will be changed to just io::Result<usize>.

System calls

• readv

pub fn recv_ancillary<'a: 'b, 'b>( &self, buf: &mut [u8], abuf: &'b mut AncillaryDataBuf<'a>, ) -> Result<(usize, bool, usize, bool)>

Receives a single datagram and ancillary data from the socket. The return value is in the following order:

• How many bytes of the datagram were received
• Deprecated bool field (always false), see note
• How many bytes of ancillary data were received
• Another deprecated bool field (always false), see note

Note: there are two additional meaningless boolean return values which are always false. They used to signify whether the datagram, and the ancillary data respectively, were truncated or not, but the functionality was implemented incorrectly and only on Linux, leading to its removal in version 1.2.0. In the next breaking release, 2.0.0, the return value will be changed to just io::Result<usize>.

System calls

• recvmsg

pub fn recv_ancillary_vectored<'a: 'b, 'b>( &self, bufs: &mut [IoSliceMut<'_>], abuf: &'b mut AncillaryDataBuf<'a>, ) -> Result<(usize, bool, usize, bool)>

Receives a single datagram and ancillary data from the socket, making use of scatter input. The return value is in the following order:

• How many bytes of the datagram were received
• Deprecated bool field (always false), see note
• How many bytes of ancillary data were received
• Another deprecated bool field (always false), see note

Note: there are two additional meaningless boolean return values which are always false. They used to signify whether the datagram, and the ancillary data respectively, were truncated or not, but the functionality was implemented incorrectly and only on Linux, leading to its removal in version 1.2.0. In the next breaking release, 2.0.0, the return value will be changed to just io::Result<(usize, usize)>.

System calls

• recvmsg

pub fn recv_from<'a: 'b, 'b>( &self, buf: &mut [u8], addr_buf: &'b mut UdSocketPath<'a>, ) -> Result<(usize, bool)>

Receives a single datagram and the source address from the socket, returning how much of the buffer was filled out and whether a part of the datagram was discarded because the buffer was too small.

System calls

• recvmsg
  • Future versions of interprocess may use recvfrom instead; for now, this method is a wrapper around recv_from_vectored.

pub fn recv_from_vectored<'a: 'b, 'b>( &self, bufs: &mut [IoSliceMut<'_>], addr_buf: &'b mut UdSocketPath<'a>, ) -> Result<(usize, bool)>

Receives a single datagram and the source address from the socket, making use of scatter input and returning how much of the buffer was filled out and whether a part of the datagram was discarded because the buffer was too small.

System calls

• recvmsg

pub fn recv_from_ancillary<'a: 'b, 'b, 'c: 'd, 'd>( &self, buf: &mut [u8], abuf: &'b mut AncillaryDataBuf<'a>, addr_buf: &'d mut UdSocketPath<'c>, ) -> Result<(usize, bool, usize, bool)>

Receives a single datagram, ancillary data and the source address from the socket. The return value is in the following order:

• How many bytes of the datagram were received
• Deprecated bool field (always false), see note
• How many bytes of ancillary data were received
• Another deprecated bool field (always false), see note

Note: there are two additional meaningless boolean return values which are always false. They used to signify whether the datagram, and the ancillary data respectively, were truncated or not, but the functionality was implemented incorrectly and only on Linux, leading to its removal in version 1.2.0. In the next breaking release, 2.0.0, the return value will be changed to just io::Result<(usize, usize)>.

System calls

• recvmsg

pub fn recv_from_ancillary_vectored<'a: 'b, 'b, 'c: 'd, 'd>( &self, bufs: &mut [IoSliceMut<'_>], abuf: &'b mut AncillaryDataBuf<'a>, addr_buf: &'d mut UdSocketPath<'c>, ) -> Result<(usize, bool, usize, bool)>

Receives a single datagram, ancillary data and the source address from the socket, making use of scatter input. The return value is in the following order:

• How many bytes of the datagram were received
• Whether a part of the datagram was discarded because the buffer was too small
• How many bytes of ancillary data were received
• Whether some ancillary data was discarded because the buffer was too small

System calls

• recvmsg

pub fn peek_msg_size(&self) -> Result<usize>

Available on Linux only.

Returns the size of the next datagram available on the socket without discarding it.

This method is only available on Linux since kernel version 2.2. On lower kernel versions, it will fail; on other platforms, it’s absent and thus any usage of it will result in a compile-time error.

System calls

• recv

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

Sends a datagram into the socket.

System calls

• write

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

Sends a datagram into the socket, making use of gather output for the main data.

System calls

• sendmsg
  • Future versions of interprocess may use writev instead; for now, this method is a wrapper around send_ancillary_vectored.

pub fn send_ancillary<'a>( &self, buf: &[u8], ancillary_data: impl IntoIterator<Item = AncillaryData<'a>>, ) -> Result<(usize, usize)>

Sends a datagram and ancillary data into the socket.

The ancillary data buffer is automatically converted from the supplied value, if possible. For that reason, slices and Vecs of AncillaryData can be passed directly.

System calls

• sendmsg

pub fn send_ancillary_vectored<'a>( &self, bufs: &[IoSlice<'_>], ancillary_data: impl IntoIterator<Item = AncillaryData<'a>>, ) -> Result<(usize, usize)>

Sends a datagram and ancillary data into the socket, making use of gather output for the main data.

The ancillary data buffer is automatically converted from the supplied value, if possible. For that reason, slices and Vecs of AncillaryData can be passed directly.

System calls

• sendmsg

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

Enables or disables the nonblocking mode for the socket. By default, it is disabled.

In nonblocking mode, calls to the recv… methods and the Read trait methods will never wait for at least one message to become available; calls to send… methods and the Write trait methods will never wait for the other side to remove enough bytes from the buffer for the write operation to be performed. Those operations will instead return a WouldBlock error immediately, allowing the thread to perform other useful operations in the meantime.

pub fn is_nonblocking(&self) -> Result<bool>

Checks whether the socket is currently in nonblocking mode or not.

pub fn get_peer_credentials(&self) -> Result<ucred>

Available on Linux and (GNU or musl or target_env="musleabi" or target_env="musleabihf"), or Emscripten, or Redox, or Haiku only.

Fetches the credentials of the other end of the connection without using ancillary data. The returned structure contains the process identifier, user identifier and group identifier of the peer.

Trait Implementations

impl AsRawFd for UdSocket

fn as_raw_fd(&self) -> c_int

Extracts the raw file descriptor.

impl Debug for UdSocket

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

Formats the value using the given formatter.

impl FromRawFd for UdSocket

unsafe fn from_raw_fd(fd: c_int) -> Self

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

impl IntoRawFd for UdSocket

fn into_raw_fd(self) -> c_int

Consumes this object, returning the raw underlying file descriptor.

impl ReliableReadMsg for UdSocket

Available on Linux only.

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

Reads one message from the stream into the specified buffer, returning either the size of the message written, a bigger buffer if the one provided was too small, or an error in the outermost Result if the operation could not be completed for OS reasons.

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

Attempts to read one message from the stream into the specified buffer, returning the size of the message, which, depending on whether it was in the Ok or Err variant, either did fit or did not fit into the provided buffer, respectively; if the operation could not be completed for OS reasons, an error from the outermost Result is returned.

impl TryFrom<UdSocket> for UdSocket

Available on crate feature tokio_support only.

type Error = Error

The type returned in the event of a conversion error.

fn try_from(x: UdSocket) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<UdSocket> for UdSocket

Available on crate feature tokio_support only.

type Error = Error

The type returned in the event of a conversion error.

fn try_from(sync: SyncUdSocket) -> Result<Self, Self::Error>

Performs the conversion.