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.

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.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 4 bytes