Struct UnixSocket

pub struct UnixSocket { /* private fields */ }

A Unix socket that has not yet been converted to a UnixStream, UnixDatagram, or UnixListener.

UnixSocket wraps an operating system socket and enables the caller to configure the socket before establishing a connection or accepting inbound connections. The caller is able to set socket option and explicitly bind the socket with a socket address.

The underlying socket is closed when the UnixSocket value is dropped.

UnixSocket should only be used directly if the default configuration used by UnixStream::connect, UnixDatagram::bind, and UnixListener::bind does not meet the required use case.

Calling UnixStream::connect(path) effectively performs the same function as:

use tokio::net::UnixSocket;
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("bind_path");
    let socket = UnixSocket::new_stream()?;

    let stream = socket.connect(path).await?;

    Ok(())
}

Calling UnixDatagram::bind(path) effectively performs the same function as:

use tokio::net::UnixSocket;
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("bind_path");
    let socket = UnixSocket::new_datagram()?;
    socket.bind(path)?;

    let datagram = socket.datagram()?;

    Ok(())
}

Calling UnixListener::bind(path) effectively performs the same function as:

use tokio::net::UnixSocket;
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("bind_path");
    let socket = UnixSocket::new_stream()?;
    socket.bind(path)?;

    let listener = socket.listen(1024)?;

    Ok(())
}

Setting socket options not explicitly provided by UnixSocket may be done by accessing the RawFd/RawSocket using AsRawFd/AsRawSocket and setting the option with a crate like socket2.

Implementations

impl UnixSocket

pub fn new_datagram() -> Result<UnixSocket>

Creates a new Unix datagram socket.

Calls socket(2) with AF_UNIX and SOCK_DGRAM.

Returns

On success, the newly created UnixSocket is returned. If an error is encountered, it is returned instead.

pub fn new_stream() -> Result<UnixSocket>

Creates a new Unix stream socket.

Calls socket(2) with AF_UNIX and SOCK_STREAM.

Returns

On success, the newly created UnixSocket is returned. If an error is encountered, it is returned instead.

pub fn bind(&self, path: impl AsRef<Path>) -> Result<()>

Binds the socket to the given address.

This calls the bind(2) operating-system function.

pub fn listen(self, backlog: u32) -> Result<UnixListener>

Converts the socket into a UnixListener.

backlog defines the maximum number of pending connections are queued by the operating system at any given time. Connection are removed from the queue with UnixListener::accept. When the queue is full, the operating-system will start rejecting connections.

Calling this function on a socket created by new_datagram will return an error.

This calls the listen(2) operating-system function, marking the socket as a passive socket.

pub async fn connect(self, path: impl AsRef<Path>) -> Result<UnixStream>

Establishes a Unix connection with a peer at the specified socket address.

The UnixSocket is consumed. Once the connection is established, a connected UnixStream is returned. If the connection fails, the encountered error is returned.

Calling this function on a socket created by new_datagram will return an error.

This calls the connect(2) operating-system function.

pub fn datagram(self) -> Result<UnixDatagram>

Converts the socket into a UnixDatagram.

Calling this function on a socket created by new_stream will return an error.

Trait Implementations

impl AsFd for UnixSocket

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

Borrows the file descriptor.

impl AsRawFd for UnixSocket

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for UnixSocket

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

Formats the value using the given formatter.

impl FromRawFd for UnixSocket

unsafe fn from_raw_fd(fd: RawFd) -> UnixSocket

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

impl IntoRawFd for UnixSocket

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.