Struct UnixSocket

pub struct UnixSocket { /* private fields */ }

Available on Unix and crate feature net only.

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.